diff --git a/CHANGELOG.md b/CHANGELOG.md
index a146819..8fb3082 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 1.5.5
+
+- Add more detailed documentation/comments.
+
## 1.5.4
- Some minor wording updates.
diff --git a/lib/caddy.rb b/lib/caddy.rb
index 6c8c769..73cea55 100644
--- a/lib/caddy.rb
+++ b/lib/caddy.rb
@@ -13,14 +13,22 @@ class << self
@started_pid = nil
@caches = Hash.new { |h, k| h[k] = Caddy::Cache.new(k) }
+ ##
+ # Returns the cache object for key +k+.
+ #
+ # If the cache at +k+ does not exist yet, Caddy will initialize an empty one.
def self.[](k)
@caches[k]
end
- def self.caches
- @caches
- end
-
+ ##
+ # Starts the Caddy refresh processes for all caches.
+ #
+ # If the refresh process was started pre-fork, Caddy will error out, as this means
+ # the refresh process would have been killed by the fork.
+ #
+ # Caddy freezes the hash of caches at this point, so no more further caches can be
+ # added after start.
def self.start
if !@started_pid
@started_pid = $$
@@ -33,10 +41,14 @@ def self.start
@caches.values.each(&:start).all?
end
+ ##
+ # Cleanly shut down all currently running refreshers.
def self.stop
@caches.values.each(&:stop).all?
end
+ ##
+ # Start and then stop again all refreshers. Useful for triggering an immediate refresh of all caches.
def self.restart
stop
start
diff --git a/lib/caddy/cache.rb b/lib/caddy/cache.rb
index 6fabd8c..6b43325 100644
--- a/lib/caddy/cache.rb
+++ b/lib/caddy/cache.rb
@@ -6,6 +6,8 @@ class Cache
attr_accessor :refresher, :refresh_interval, :error_handler
+ ##
+ # Create a new cache with key +key+.
def initialize(key)
@task = nil
@refresh_interval = DEFAULT_REFRESH_INTERVAL
@@ -13,10 +15,17 @@ def initialize(key)
@key = key
end
+ ##
+ # Convenience method for getting the value of the refresher-returned object at path +k+,
+ # assuming the refresher-returned value responds to [].
+ #
+ # If not, #cache can be used instead to access the refresher-returned object.
def [](k)
cache[k]
end
+ ##
+ # Returns the refresher-produced value that is used as the cache.
def cache
raise "Please run `Caddy.start` before attempting to access the cache" unless @task && @task.running?
raise "Caddy cache access of :#{@key} before initial load; allow some more time for your app to start up" unless @cache
@@ -24,6 +33,13 @@ def cache
@cache
end
+ ##
+ # Starts the period refresh cycle.
+ #
+ # Every +refresh_interval+ seconds -- smoothed by a jitter amount (a random amount +/- +REFRESH_INTERVAL_JITTER_PCT+) --
+ # the refresher lambda is called and the results stored in +cache+.
+ #
+ # Note that the result of the refresh is frozen to avoid multithreading mutations.
def start
unless refresher && refresher.respond_to?(:call)
raise "Please set your cache refresher via `Caddy[:#{@key}].refresher = -> { }`"
@@ -52,6 +68,10 @@ def start
@task.running?
end
+ ##
+ # Stops the current executing refresher.
+ #
+ # The current cache value is persisted even if the task is stopped.
def stop
@task.shutdown if @task && @task.running?
end
diff --git a/lib/caddy/version.rb b/lib/caddy/version.rb
index fbf1632..daf1455 100644
--- a/lib/caddy/version.rb
+++ b/lib/caddy/version.rb
@@ -1,4 +1,4 @@
# frozen_string_literal: true
module Caddy
- VERSION = "1.5.4".freeze
+ VERSION = "1.5.5".freeze
end