Module: MCollective::Cache

- - - -

- -

-A class to manage a number of named caches. Each cache can have a unique -timeout for keys in it and each cache has an independent Mutex protecting -access to it. -

-This cache is setup early in the process -of loading the mcollective libraries, before any threads are created etc -making it suitable as a cross thread cache or just a store for Mutexes you -need to use across threads like in an Agent or -something. -

-   # sets up a new cache, noop if it already exist
-   Cache.setup(:ddl, 600)
-   => true
-
-   # writes an item to the :ddl cache, this item will
-   # be valid on the cache for 600 seconds
-   Cache.write(:ddl, :something, "value")
-   => "value"
-
-   # reads from the cache, read failures due to non existing
-   # data or expired data will raise an exception
-   Cache.read(:ddl, :something)
-   => "value"
-
-   # time left till expiry, raises if nothing is found
-   Cache.ttl(:ddl, :something)
-   => 500
-
-   # forcibly evict something from the cache
-   Cache.invalidate!(:ddl, :something)
-   => "value"
-
-   # deletes an entire named cache and its mutexes
-   Cache.delete!(:ddl)
-   => true
-
-   # you can also just use this cache as a global mutex store
-   Cache.setup(:mylock)
-
-   Cache.synchronize(:mylock) do
-     do_something()
-   end
-

- -

- - -

- -

Methods

- -

- check_cache! - delete! - has_cache? - invalidate! - read - setup - synchronize - ttl - write -

- -

- - - - - - - - - -

Public Class methods

- -

- - -

- - check_cache!(cache_name) - -

- -

[Source]

-    # File lib/mcollective/cache.rb, line 70
-70:     def self.check_cache!(cache_name)
-71:       raise_code(:PLMC13, "Could not find a cache called '%{cache_name}'", :debug, :cache_name => cache_name) unless has_cache?(cache_name)
-72:     end
-

- -

- - -

- - delete!(cache_name) - -

- -

[Source]

-    # File lib/mcollective/cache.rb, line 80
-80:     def self.delete!(cache_name)
-81:       check_cache!(cache_name)
-82: 
-83:       @locks_mutex.synchronize do
-84:         @cache_locks.delete(cache_name)
-85:         @cache.delete(cache_name)
-86:       end
-87: 
-88:       true
-89:     end
-

- -

- - -

- - has_cache?(cache_name) - -

- -

[Source]

-    # File lib/mcollective/cache.rb, line 74
-74:     def self.has_cache?(cache_name)
-75:       @locks_mutex.synchronize do
-76:         @cache.include?(cache_name)
-77:       end
-78:     end
-

- -

- - -

- - invalidate!(cache_name, key) - -

- -

[Source]

-     # File lib/mcollective/cache.rb, line 139
-139:     def self.invalidate!(cache_name, key)
-140:       check_cache!(cache_name)
-141: 
-142:       @cache_locks[cache_name].synchronize do
-143:         return false unless @cache[cache_name].include?(key)
-144: 
-145:         @cache[cache_name].delete(key)
-146:       end
-147:     end
-

- -

- - -

- - read(cache_name, key) - -

- -

[Source]

-     # File lib/mcollective/cache.rb, line 103
-103:     def self.read(cache_name, key)
-104:       check_cache!(cache_name)
-105: 
-106:       unless ttl(cache_name, key) > 0
-107:         raise_code(:PLMC11, "Cache expired on '%{cache_name}' key '%{item}'", :debug, :cache_name => cache_name, :item => key)
-108:       end
-109: 
-110:       log_code(:PLMC12, "Cache hit on '%{cache_name}' key '%{item}'", :debug, :cache_name => cache_name, :item => key)
-111: 
-112:       @cache_locks[cache_name].synchronize do
-113:         @cache[cache_name][key][:value]
-114:       end
-115:     end
-

- -

- - -

- - setup(cache_name, ttl=300) - -

- -

[Source]

-    # File lib/mcollective/cache.rb, line 56
-56:     def self.setup(cache_name, ttl=300)
-57:       @locks_mutex.synchronize do
-58:         break if @cache_locks.include?(cache_name)
-59: 
-60:         @cache_locks[cache_name] = Mutex.new
-61: 
-62:         @cache_locks[cache_name].synchronize do
-63:           @cache[cache_name] = {:max_age => Float(ttl)}
-64:         end
-65:       end
-66: 
-67:       true
-68:     end
-

- -

- - -

- - synchronize(cache_name) {|| ...} - -

- -

[Source]

-     # File lib/mcollective/cache.rb, line 129
-129:     def self.synchronize(cache_name)
-130:       check_cache!(cache_name)
-131: 
-132:       raise_code(:PLMC14, "No block supplied to synchronize on cache '%{cache_name}'", :debug, :cache_name => cache_name) unless block_given?
-133: 
-134:       @cache_locks[cache_name].synchronize do
-135:         yield
-136:       end
-137:     end
-

- -

- - -

- - ttl(cache_name, key) - -

- -

[Source]

-     # File lib/mcollective/cache.rb, line 117
-117:     def self.ttl(cache_name, key)
-118:       check_cache!(cache_name)
-119: 
-120:       @cache_locks[cache_name].synchronize do
-121:         unless @cache[cache_name].include?(key)
-122:           raise_code(:PLMC15, "No item called '%{item}' for cache '%{cache_name}'", :debug, :cache_name => cache_name, :item => key)
-123:         end
-124: 
-125:         @cache[cache_name][:max_age] - (Time.now - @cache[cache_name][key][:cache_create_time])
-126:       end
-127:     end
-

- -

- - -

- - write(cache_name, key, value) - -

- -

[Source]

-     # File lib/mcollective/cache.rb, line 91
- 91:     def self.write(cache_name, key, value)
- 92:       check_cache!(cache_name)
- 93: 
- 94:       @cache_locks[cache_name].synchronize do
- 95:         @cache[cache_name][key] ||= {}
- 96:         @cache[cache_name][key][:cache_create_time] = Time.now
- 97:         @cache[cache_name][key][:value] = value
- 98:       end
- 99: 
-100:       value
-101:     end
-

- - -