Path: | README.rdoc |
Last Update: | Sun Dec 25 14:20:03 +0000 2011 |
require 'syncache' @cache = SynCache::Cache.new @cache.fetch_or_add('key:1') do # expensive operation end @cache.flush(/^key:/)
SynCache::Cache stores cached objects in a Hash that is protected by an advanced two-level locking mechanism. Two-level locking ensures that:
When number of cache entries exceeds the size limit, the least recently accessed entries are replaced with new data. This replacement strategy is controlled by the SynCache::CacheEntry class and can be changed by overriding its replacement_index method.
Cache entries are automatically invalidated when their ttl (time to live) is exceeded. Entries can be explicitly invalidated by flush method. The method can use === operator to compare cache keys against flush base (so that base can be e.g. a Regexp). When invoked without the base parameter, it invalidates all entries.
The flush_delay initialization option allows to limit cache‘s flush rate. When this option is set, SynCache will make sure that at least this many seconds (it can also be a fraction) pass between two flushes. When extra flushes are requested, invalidation of flushed entries is postponed until earliest time when next flush is allowed.
SynCache::Cache object can be shared between multiple Ruby processes, even across different computers. All you need is the syncache-drb script shipped with this module. This script will start a daemon that serves a SynCache::Cache object over dRuby protocol, with $SAFE set to 1 for security.
To access a remote cache, you will need to use DRb library:
require 'drb' # connect to the remote cache @cache = DRbObject.new_with_uri('druby://localhost:9000') # allow remote cache to access local objects from fetch_or_add blocks DRb.start_service('druby://localhost:0')
For the above to work properly, all your fetch_or_add blocks should be thread-safe, because DRb will run them in their own threads. Also, if a Ruby process crashes is the middle of such block, the key will remain locked in the remote cache until its ttl runs out.
To work around these limitations, you can wrap access to a remote cache using a SynCache::RemoteCache object:
require 'syncache' # connect to the remote cache @cache = SynCache::RemoteCache.new('druby://localhost:9000')
SynCache::RemoteCache implements its own version of fetch_or_add that runs the supplied block locally in the current thread and would give up and take over a locked key if the client that originally locked it takes too long to free it up.
Copyright (c) 2002-2011 Dmitry Borodaenko <angdraug@debian.org> This program is free software. You can distribute/modify this program under the terms of the GNU General Public License version 3 or later.