syncache 1.0.0 → 1.2

data/lib/syncache/syncache.rb

@@ -0,0 +1,283 @@
+# SynCache: thread-safe time-limited cache with flexible replacement policy
+# (originally written for Samizdat project)
+#
+#   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.
+#
+# vim: et sw=2 sts=2 ts=8 tw=0
+
+module SynCache
+
+FOREVER = 60 * 60 * 24 * 365 * 5   # 5 years
+
+class CacheError < RuntimeError; end
+
+class CacheEntry
+  def initialize(ttl = nil, value = nil)
+    @value = value
+    @ttl = ttl
+    @dirty = false
+    record_access
+
+    @sync = Mutex.new
+  end
+
+  # stores the value object
+  attr_accessor :value
+
+  # change this to make the entry expire sooner
+  attr_accessor :ttl
+
+  # use this to synchronize access to +value+
+  attr_reader :sync
+
+  # record the fact that the entry was accessed
+  #
+  def record_access
+    return if @dirty
+    @expires = Time.now + (@ttl or FOREVER)
+  end
+
+  # entries with lowest index will be replaced first
+  #
+  def replacement_index
+    @expires
+  end
+
+  # check if entry is stale
+  #
+  def stale?
+    @expires < Time.now
+  end
+
+  # mark entry as dirty and schedule it to expire at given time
+  #
+  def expire_at(time)
+    @expires = time if @expires > time
+    @dirty = true
+  end
+end
+
+class Cache
+
+  # a float number of seconds to sleep when a race condition is detected
+  # (actual delay is randomized to avoid live lock situation)
+  #
+  LOCK_SLEEP = 0.2
+
+  # _ttl_ (time to live) is time in seconds from the last access until cache
+  # entry is expired (set to _nil_ to disable time limit)
+  # 
+  # _max_size_ is max number of objects in cache
+  #
+  # _flush_delay_ is used to rate-limit flush operations: if less than that
+  # number of seconds has passed since last flush, next flush will be delayed;
+  # default is no rate limit
+  #
+  def initialize(ttl = 60*60, max_size = 5000, flush_delay = nil)
+    @ttl = ttl
+    @max_size = max_size
+    @debug = false
+
+    if @flush_delay = flush_delay
+      @last_flush = Time.now
+    end
+
+    @sync = Mutex.new
+    @cache = {}
+  end
+
+  # set to _true_ to report every single cache operation
+  #
+  attr_accessor :debug
+
+  # remove all values from cache
+  #
+  # if _base_ is given, only values with keys matching the base (using
+  # <tt>===</tt> operator) are removed
+  #
+  def flush(base = nil)
+    debug { 'flush ' << base.to_s }
+
+    @sync.synchronize do
+
+      if @flush_delay
+        next_flush = @last_flush + @flush_delay
+
+        if next_flush > Time.now
+          flush_at(next_flush, base)
+        else
+          flush_now(base)
+          @last_flush = Time.now
+        end
+
+      else
+        flush_now(base)
+      end
+    end
+  end
+
+  # remove single value from cache
+  #
+  def delete(key)
+    debug { 'delete ' << key.to_s }
+
+    @sync.synchronize do
+      @cache.delete(key)
+    end
+  end
+
+  # store new value in cache
+  #
+  # see also Cache#fetch_or_add
+  #
+  def []=(key, value)
+    debug { '[]= ' << key.to_s }
+
+    entry = get_locked_entry(key)
+    begin
+      return entry.value = value
+    ensure
+      entry.sync.unlock
+    end
+  end
+
+  # retrieve value from cache if it's still fresh
+  #
+  # see also Cache#fetch_or_add
+  #
+  def [](key)
+    debug { '[] ' << key.to_s }
+
+    entry = get_locked_entry(key, false)
+    unless entry.nil?
+      begin
+        return entry.value
+      ensure
+        entry.sync.unlock
+      end
+    end
+  end
+
+  # initialize missing cache entry from supplied block
+  #
+  # this is the preferred method of adding values to the cache as it locks the
+  # key for the duration of computation of the supplied block to prevent
+  # parallel execution of resource-intensive actions
+  #
+  def fetch_or_add(key)
+    debug { 'fetch_or_add ' << key.to_s }
+
+    entry = get_locked_entry(key)
+    begin
+      if entry.value.nil?
+        entry.value = yield
+      end
+      return entry.value
+    ensure
+      entry.sync.unlock
+    end
+  end
+
+  private
+
+  # immediate flush (delete all entries matching _base_)
+  #
+  # must be run from inside global lock, see #flush
+  #
+  def flush_now(base = nil)
+    if base
+      @cache.delete_if {|key, entry| base === key }
+    else
+      @cache = {}
+    end
+  end
+
+  # delayed flush (ensure all entries matching _base_ expire no later than _next_flush_)
+  #
+  # must be run from inside global lock, see #flush
+  #
+  def flush_at(next_flush, base = nil)
+    @cache.each do |key, entry|
+      next if base and not base === key
+      entry.expire_at(next_flush)
+    end
+  end
+
+  def add_blank_entry(key)
+    @sync.locked? or raise CacheError,
+      'add_entry called while @sync is not locked'
+
+    had_same_key = @cache.has_key?(key)
+    entry = @cache[key] = CacheEntry.new(@ttl)
+    check_size unless had_same_key
+    entry
+  end
+
+  def get_locked_entry(key, add_if_missing=true)
+    debug { "get_locked_entry #{key}, #{add_if_missing}" }
+
+    entry = nil   # scope fix
+    entry_locked = false
+    until entry_locked do
+      @sync.synchronize do
+        entry = @cache[key]
+
+        if entry.nil? or entry.stale?
+          if add_if_missing
+            entry = add_blank_entry(key)
+          else
+            @cache.delete(key) unless entry.nil?
+            return nil
+          end
+        end
+
+        entry_locked = entry.sync.try_lock
+      end
+      sleep(rand * LOCK_SLEEP) unless entry_locked
+    end
+
+    entry.record_access
+    entry
+  end
+
+  # remove oldest item from cache if size limit reached
+  #
+  def check_size
+    debug { 'check_size' }
+
+    return unless @max_size.kind_of? Numeric
+
+    if @sync.locked?
+      check_size_internal
+    else
+      @sync.synchronize { check_size_internal }
+    end
+  end
+
+  def check_size_internal
+    while @cache.size > @max_size do
+      # optimize: supplement hash with queue
+      oldest = @cache.keys.min {|a, b| @cache[a].replacement_index <=> @cache[b].replacement_index }
+      @cache.delete(oldest)
+    end
+  end
+
+  # send debug output to syslog if enabled
+  #
+  def debug
+    return unless @debug
+    message = Thread.current.to_s + ' ' + yield
+    if defined?(Syslog) and Syslog.opened?
+      Syslog.debug(message)
+    else
+      STDERR << 'syncache: ' + message + "\n"
+      STDERR.flush
+    end
+  end
+end
+
+end   # module SynCache

data/lib/syncache.rb

@@ -1,7 +1,7 @@
 # SynCache: thread-safe time-limited cache with flexible replacement policy
 # (originally written for Samizdat project)
 #
-#   Copyright (c) 2002-2009  Dmitry Borodaenko <angdraug@debian.org>
+#   Copyright (c) 2002-2011  Dmitry Borodaenko <angdraug@debian.org>
 #
 #   This program is free software.
 #   You can distribute/modify this program under the terms of
@@ -9,250 +9,5 @@
 #
 # vim: et sw=2 sts=2 ts=8 tw=0
 
-require 'sync'
-require 'syncache_sync_patch'
-
-module SynCache
-
-FOREVER = 60 * 60 * 24 * 365 * 5   # 5 years
-
-class CacheEntry
-  def initialize(ttl = nil, value = nil)
-    @value = value
-    @ttl = ttl
-    @dirty = false
-    record_access
-
-    @sync = Sync.new
-  end
-
-  # stores the value object
-  attr_accessor :value
-
-  # change this to make the entry expire sooner
-  attr_accessor :ttl
-
-  # use this to synchronize access to +value+
-  attr_reader :sync
-
-  # record the fact that the entry was accessed
-  #
-  def record_access
-    return if @dirty
-    @expires = Time.now + (@ttl or FOREVER)
-  end
-
-  # entries with lowest index will be replaced first
-  #
-  def replacement_index
-    @expires
-  end
-
-  # check if entry is stale
-  #
-  def stale?
-    @expires < Time.now
-  end
-
-  # mark entry as dirty and schedule it to expire at given time
-  #
-  def expire_at(time)
-    @expires = time if @expires > time
-    @dirty = true
-  end
-end
-
-class Cache
-
-  # set to _true_ to report every single cache operation to syslog
-  #
-  DEBUG = false
-
-  # a float number of seconds to sleep when a race condition is detected
-  # (actual delay is randomized to avoid live lock situation)
-  #
-  LOCK_SLEEP = 0.2
-
-  # _ttl_ (time to live) is time in seconds from the last access until cache
-  # entry is expired (set to _nil_ to disable time limit)
-  # 
-  # _max_size_ is max number of objects in cache
-  #
-  # _flush_delay_ is used to rate-limit flush operations: if less than that
-  # number of seconds has passed since last flush, next flush will be delayed;
-  # default is no rate limit
-  #
-  def initialize(ttl = 60*60, max_size = 5000, flush_delay = nil)
-    @ttl = ttl
-    @max_size = max_size
-
-    if @flush_delay = flush_delay
-      @last_flush = Time.now
-    end
-
-    @sync = Sync.new
-    @cache = {}
-  end
-
-  # remove all values from cache
-  #
-  # if _base_ is given, only values with keys matching the base (using
-  # <tt>===</tt> operator) are removed
-  #
-  def flush(base = nil)
-    debug('flush ' << base.to_s)
-
-    @sync.synchronize do
-
-      if @flush_delay
-        next_flush = @last_flush + @flush_delay
-
-        if next_flush > Time.now
-          flush_at(next_flush, base)
-        else
-          flush_now(base)
-          @last_flush = Time.now
-        end
-
-      else
-        flush_now(base)
-      end
-    end
-  end
-
-  # remove single value from cache
-  #
-  def delete(key)
-    debug('delete ' << key.to_s)
-
-    @sync.synchronize do
-      @cache.delete(key)
-    end
-  end
-
-  # store new value in cache
-  #
-  # see also Cache#fetch_or_add
-  #
-  def []=(key, value)
-    debug('[]= ' << key.to_s)
-
-    entry = get_entry(key)
-    entry.sync.synchronize do
-      entry.value = value
-    end
-    value
-  end
-
-  # retrieve value from cache if it's still fresh
-  #
-  # see also Cache#fetch_or_add
-  #
-  def [](key)
-    debug('[] ' << key.to_s)
-
-    entry = get_entry(key)
-    entry.sync.synchronize(:SH) do
-      entry.value
-    end
-  end
-
-  # initialize missing cache entry from supplied block
-  #
-  # this is the preferred method of adding values to the cache as it locks the
-  # key for the duration of computation of the supplied block to prevent
-  # parallel execution of resource-intensive actions
-  #
-  def fetch_or_add(key)
-    debug('fetch_or_add ' << key.to_s)
-
-    entry = nil   # scope fix
-    entry_locked = false
-    until entry_locked do
-      @sync.synchronize do
-        entry = get_entry(key)
-        entry_locked = entry.sync.try_lock   # fixme
-      end
-      sleep(rand * LOCK_SLEEP) unless entry_locked
-    end
-
-    begin
-      entry.record_access
-      entry.value ||= yield
-    ensure
-      entry.sync.unlock
-    end
-  end
-
-  private
-
-  # immediate flush (delete all entries matching _base_)
-  #
-  # must be run from inside global lock, see #flush
-  #
-  def flush_now(base = nil)
-    if base
-      @cache.delete_if {|key, entry| base === key }
-    else
-      @cache = {}
-    end
-  end
-
-  # delayed flush (ensure all entries matching _base_ expire no later than _next_flush_)
-  #
-  # must be run from inside global lock, see #flush
-  #
-  def flush_at(next_flush, base = nil)
-    @cache.each do |key, entry|
-      next if base and not base === key
-      entry.expire_at(next_flush)
-    end
-  end
-
-  def get_entry(key)
-    debug('get_entry ' << key.to_s)
-
-    @sync.synchronize do
-      entry = @cache[key]
-
-      if entry.kind_of?(CacheEntry)
-        if entry.stale?
-          @cache[key] = entry = CacheEntry.new(@ttl)
-        end
-      else
-        @cache[key] = entry = CacheEntry.new(@ttl)
-        check_size
-      end
-
-      entry.record_access
-      entry
-    end
-  end
-
-  # remove oldest item from cache if size limit reached
-  #
-  def check_size
-    debug('check_size')
-
-    return unless @max_size.kind_of? Numeric
-
-    @sync.synchronize do
-      while @cache.size > @max_size do
-        # optimize: supplement hash with queue
-        oldest = @cache.keys.min {|a, b| @cache[a].replacement_index <=> @cache[b].replacement_index }
-
-        @cache.delete(oldest)
-      end
-    end
-  end
-
-  # send debug output to syslog if enabled
-  #
-  def debug(message)
-    if DEBUG and defined?(Syslog) and Syslog.opened?
-      Syslog.debug(Thread.current.to_s << ' ' << message)
-    end
-  end
-end
-
-end   # module SynCache
+require 'syncache/syncache'
+require 'syncache/remote'

data/man/syncache-drb.1

@@ -0,0 +1,44 @@
+.TH "SYNCACHE-DRB" "1" 
+.SH "NAME" 
+syncache-drb - SynCache dRuby object cache server
+.SH "SYNOPSIS" 
+.PP 
+\fBsyncache-drb\fP [ \fBoptions\fP ] [ \fBURI\fP ]
+.SH "DESCRIPTION" 
+.PP 
+\fBsyncache-drb\fP starts a Distributed Ruby server providing a
+SynCache::Cache object.
+.PP 
+SynCache::Cache is a thread-safe time-limited object cache with flexible
+replacement strategy.
+.SH "OPTIONS" 
+.IP "\fBURI\fP" 4
+A URI with druby: schema that the DRb server binds to, default is
+\fBdruby://localhost:9000\fP
+.IP "\fB--help\fP" 4
+Display usage information and quit.
+.IP "\fB--ttl\fP SECONDS" 4
+Time-to-live value for cache entries, default is 24 hours.
+.IP "\fB--size\fP ENTRIES" 4
+Maximum number of objects in cache, default is 10000.
+.IP "\fB--flush-delay\fP SECONDS" 4
+Rate-limit flush operations. If less than that number of seconds has passed
+since last flush, next flush will be delayed. Default is no rate limit.
+.IP "\fB--user\fP USER" 4
+Run as USER if started as root. Default is nobody.
+.IP "\fB--error-log\fP ERROR_LOG_PATH" 4
+File to write errors to. Default is /dev/null. When run as root,
+the file is chowned to USER:adm.
+.IP "\fB--debug\fP" 4
+Enable debug mode. If an error log is specified with --error-log, all
+messages will be sent there instead of syslog.
+.IP "\fB--pidfile\fP PATH" 4
+Path to pidfile. By default, pidfile is created under /var/run/syncache-drb/
+when run as root, or under $TMPDIR otherwise. Location should be writeable by
+USER.
+
+.SH "AUTHOR" 
+.PP 
+This manual page was written by Dmitry Borodaenko <angdraug@debian.org>.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU GPL version 3 or later.