sir_cachealot 0.5 → 0.6.4

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NmUyMGY5NzdhN2NmNjI2ZTAxYjcwMjM5N2RiYTg5ZmMyOTI0YTZiYg==
+    OTNmODJhZjRhODc5OGMyOTllMDE0MzQ2NmQ0ZWEzZTgzYmQ2NTMwZA==
   data.tar.gz: !binary |-
-    MjRhYjBlYmE0ZDQ4MDQ4MDE2MzE3MTU5NzNhNzZhM2I4ODRiNmRmMw==
+    NzY0NjQ1ZTZmMWM5ZDhlYmI2MGMyNjhiNjkyOTZlNTY1NDE1MDY5Mg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    M2JhMGZiYzc3NGFjMmY4OWUzOWJhMTZjYTc5ODU3NmQ0ZjI1ZjRmMDAxMjM3
-    NjM4NGU4MWVhNzc3YjQ1MmIyNWQ1OGYxYzBmMGFhZGI2M2E3ODEwNDI3NDQz
-    MmFjOWEwODk3ZTIwYzE0YzNiZjIzMWZjNjRlOTBhMjc4MTczYmI=
+    ODgzYWQ0MDViZDkyN2UwMjYwMTAxZTAzZTc3OGMxODU5YmEwODQ2ZDY2Njhh
+    YTNjNmU4NDcyZGQzNDIzYmZhODM1MjI4N2Y2YzA3YzA1MTRhNmYyYzA0YmVm
+    ZGMxYWVlNzRlNDA3MmE1MTM2MDNiYTE1ODZlMTNhOGEwY2IzODk=
   data.tar.gz: !binary |-
-    Mjc5NjRlZGY0ZjU1M2M5YThkZGE0YWVlNmU0NzViMjE2ZGI1ODQ4YzZmZDYy
-    N2RhMjE1ZjZiZGI4NGRkMDI0MTZlM2U2MTI1MDE4MjY5ZjM4NWVjYWU1ZWVh
-    MjQ1MDA1Y2UyMWJlOTIxMWVhOTdjMjIxNzU2Nzc3MDdlZTBkZjk=
+    ZmUxNWJiMGRkNGZiNTQwZjBjNjFiOGJiNjllNTQ0NGMxNWFiZDQxZjIwZWNm
+    ODExYTM2OGIxZDQ2ZDYzM2RkZjVjMTc2YzY1MWVhOTE4NzA5ZmIxYmExN2Ez
+    NDc4MDNkY2ZiODgwNWM4YmI5YTg2MGFhMDQwNWYxZWI4OGQ2ZDY=

data/.gitignore

@@ -16,3 +16,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+*.rdb

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in sir_cachealot.gemspec
+# Specify your gem's dependencies in sir.gemspec
 gemspec

data/LICENSE.txt

@@ -1,166 +1,26 @@
-                   GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-  This version of the GNU Lesser General Public License incorporates
-the terms and conditions of version 3 of the GNU General Public
-License, supplemented by the additional permissions listed below.
-
-  0. Additional Definitions.
-
-  As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the GNU
-General Public License.
-
-  "The Library" refers to a covered work governed by this License,
-other than an Application or a Combined Work as defined below.
-
-  An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-  A "Combined Work" is a work produced by combining or linking an
-Application with the Library.  The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-  The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-  The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-  1. Exception to Section 3 of the GNU GPL.
-
-  You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-  2. Conveying Modified Versions.
-
-  If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
-   a) under this License, provided that you make a good faith effort to
-   ensure that, in the event an Application does not supply the
-   function or data, the facility still operates, and performs
-   whatever part of its purpose remains meaningful, or
-
-   b) under the GNU GPL, with none of the additional permissions of
-   this License applicable to that copy.
-
-  3. Object Code Incorporating Material from Library Header Files.
-
-  The object code form of an Application may incorporate material from
-a header file that is part of the Library.  You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
-   a) Give prominent notice with each copy of the object code that the
-   Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the object code with a copy of the GNU GPL and this license
-   document.
-
-  4. Combined Works.
-
-  You may convey a Combined Work under terms of your choice that,
-taken together, effectively do not restrict modification of the
-portions of the Library contained in the Combined Work and reverse
-engineering for debugging such modifications, if you also do each of
-the following:
-
-   a) Give prominent notice with each copy of the Combined Work that
-   the Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
-   document.
-
-   c) For a Combined Work that displays copyright notices during
-   execution, include the copyright notice for the Library among
-   these notices, as well as a reference directing the user to the
-   copies of the GNU GPL and this license document.
-
-   d) Do one of the following:
-
-       0) Convey the Minimal Corresponding Source under the terms of this
-       License, and the Corresponding Application Code in a form
-       suitable for, and under terms that permit, the user to
-       recombine or relink the Application with a modified version of
-       the Linked Version to produce a modified Combined Work, in the
-       manner specified by section 6 of the GNU GPL for conveying
-       Corresponding Source.
-
-       1) Use a suitable shared library mechanism for linking with the
-       Library.  A suitable mechanism is one that (a) uses at run time
-       a copy of the Library already present on the user's computer
-       system, and (b) will operate properly with a modified version
-       of the Library that is interface-compatible with the Linked
-       Version.
-
-   e) Provide Installation Information, but only if you would otherwise
-   be required to provide such information under section 6 of the
-   GNU GPL, and only to the extent that such information is
-   necessary to install and execute a modified version of the
-   Combined Work produced by recombining or relinking the
-   Application with a modified version of the Linked Version. (If
-   you use option 4d0, the Installation Information must accompany
-   the Minimal Corresponding Source and Corresponding Application
-   Code. If you use option 4d1, you must provide the Installation
-   Information in the manner specified by section 6 of the GNU GPL
-   for conveying Corresponding Source.)
-
-  5. Combined Libraries.
-
-  You may place library facilities that are a work based on the
-Library side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
-   a) Accompany the combined library with a copy of the same work based
-   on the Library, uncombined with any other library facilities,
-   conveyed under the terms of this License.
-
-   b) Give prominent notice with the combined library that part of it
-   is a work based on the Library, and explaining where to find the
-   accompanying uncombined form of the same work.
-
-  6. Revised Versions of the GNU Lesser General Public License.
-
-  The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-  Each version is given a distinguishing version number. If the
-Library as you received it specifies that a certain numbered version
-of the GNU Lesser General Public License "or any later version"
-applies to it, you have the option of following the terms and
-conditions either of that published version or of any later version
-published by the Free Software Foundation. If the Library as you
-received it does not specify a version number of the GNU Lesser
-General Public License, you may choose any version of the GNU Lesser
-General Public License ever published by the Free Software Foundation.
-
-  If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
-.
+Copyright (c) 2014 Lyjia
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met: 
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer. 
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies, 
+either expressed or implied, of the FreeBSD Project.

data/README.md

@@ -1,10 +1,32 @@
 # SirCachealot
 ![Sir Cachealot graphic](https://github.com/lyjia/sircachealot/blob/master/sircachealot.png?raw=true "Sir Cachealot graphic")
 
-SirCachealot is a very simple memcache-like keystore, licensed under LGPLv3. It is built to be modular and present a consistent API.
+SirCachealot is an easy-to-use, in-memory, pluggable key-value store, available under the 2-clause BSD license. It is built for:
 
-Future plans for 1.0:
-* Rails cache, Redis, and memcache storage modes.
+* Simple, swappable, modular backends. Cache server down? Swap another one in and keep chuggin'. Currently supports Redis and an in-memory store.
+* Shared memory between processes. Multi-process environments (such as in Passenger) make shared state difficult.
+* Unified API supporting a selected, shared subset of each backend's features.
+* Easily and seamlessly deal with cache misses.
+* Lets you cache stuff the Ruby way!
+
+Here's a quick example, which caches a user object to avoid fetching it from the database:
+
+    def login(id, password_hash)
+
+        user = Sir.get(keyname) do |key|               #Doesn't execute the block is key is found
+            Sir.put(key, User.find_by_id(id), 1.day)   #Cache miss! So let's fetch the User and store it for a day
+        end                                                 (note: 1.day comes from Rails, not included)
+
+        # your code here
+        user.authenticate?(password_hash)              #returns true if match, false is not
+
+    end
+
+Roadmap for 1.0:
+* More storage backends: RailsCache, Postgres HSTORE, Mysql memtable, memcache, internal
+* Add redis incr/decr and extra datatypes (emulate features on ramcache if necessary)
+* Explore clustering applications
+* Add convenience methods to ActiveRecord
 
 ## Installation
 
@@ -22,7 +44,9 @@ Or install it yourself as:
 
 ## Usage
 
-SirCachealot exposes a new module named `Sir`. This module is designed to be available globally in both Rails apps and vanilla Ruby scripts (don't forget `require 'sir_cachealot'`!)
+SirCachealot exposes a new module named `Sir`. This module is designed to be available globally in both Rails apps and vanilla Ruby scripts (don't forget `require 'sir'`!)
+
+This section is a quick tour through some of SirCachealot's best features. For a comprehensive API reference, please refer to the comments in `Sir::Backends::Base`.
 
 **You can use SirCachealot immediately, using either:**
 
@@ -35,44 +59,116 @@ If `config(:delete_on_nil) == true` and `value == nil`, `put()` will return `tru
 
 **You can retreive the value later, if it hasn't expired, with:**
 
-    my_var = Sir.get(keyname) # for a shallow copy
-    my_var = Sir.get(keyname, true) # for a deep copy (crude way, Marshal.load(Marshal.dump(obj)) )
+    my_var = Sir.get(keyname)
 
 or
 
     # A convenient way to rectify a cache miss!
     # put() returns the object you give it
-    my_var = Sir.get(keyname) do 
-        Sir.put(keyname, User.find_by_id(id))
+    my_var = Sir.get(keyname) do |key|
+        Sir.put(key, User.find_by_id(id))
     end
 
 If the key does not exist, or if it has expired:
+
 * `get()` returns `nil` if not given a block to execute.
 * `get()` yields to code block, if one is supplied.
 
 **To delete a cache entry, you can:**
 
-	Sir.delete(key)
+	Sir.kill(key)
 
 **If you want to clear the cache, you can:**
 
-    Sir.clear
+    Sir.nuke
 
 **If you want to sweep and purge all expired entries, you can:**
 
-    Sir.clean
+    Sir.sweep
 
 **There are a few configuration options available. You can configure SirCachealot with:**
 
+    cache_opts = Sir::Backends::RamCache::DEFAULTS #Change RamCache to RedisCache for redis
+
     Sir.configure do |config|
         config[:default_expiry] = 3600 # default expiration timeout in seconds
-        config[:mode]           = :ram_cache # cache storage mode. Currently only :ram_cache is supported. Others may be added at a later date.
+        config[:mode]           = :ram_cache # cache storage mode. Currently: :ram_cache, :redis_cache
         config[:debug]          = true|false # show some debug messages
         config[:annoy]          = true|false # show even more debug messages
-		config[:delete_on_nil]  = true|false # auto-deletes stale cache entries on if value == nil
+        config[:options]        = cache_opts # optional, depending on backend
     end
     
-*Note: Config keynames are always `.downcase.to_sym`!*
+Note: Backends may have additional configuration parameters that need to be satisfied. The default configuration can be retreived from the `DEFAULTS` constant in the backend class, as shown above. These values may then be modified and passed back to `Sir.configure()`
+
+## API Reference
+
+See `Sir::Backends::Base`
+
+## Available Backends
+
+### RAM Cache (for testing)
+The RAM Cache stores cache entries in a Ruby hash, and is the default cache store that SirCachealot will use if left unconfigured.
+
+RAM Cache does not support automatic expiration, and so it must be periodically #swept(). RAM Cache's thread safety depends on your interpreter: 'green thread' implementations are safe, while true multi-threaded environments (such as JRuby) remain untested at this time.
+
+This backend module is intentionally left simple, and is of limited usefulness. It is designed to be an example for implementing additional backends, and to satisfy basic turn-key functionality.
+
+#### Configuration
+Note that #configure is not necessary if you wish to use RAM cache with its default settings.
+
+    Sir.configure do |config|
+        config[:default_expiry] = 3600
+        config[:mode]           = :ram_cache
+    end
+
+### Redis Cache
+Redis cache supports a subset of full Redis functionality.
+
+#### Configuration
+
+    redis_obj = Redis.new(:path => "/tmp/redis.sock")
+
+    cache_opts = Sir::Backends::RedisCache::DEFAULTS
+    cache_opts[:redis_obj] = redis_obj                   #supply a preconfigured Redis instance
+    cache_opts[:namespace] = "MyCacheStore"              #override the default "SirCachealot" namespace
+    cache_opts[:serializer] = :marshal                   #all requests to put() are serialized. :marshal or :json are available
+
+    Sir.configure do |config|
+        config[:default_expiry] = 3600
+        config[:mode]           = :redis_cache
+        config[:options]        = cache_opts
+    end
+
+##### Options
+
+* `:redis_obj`: Store your pre-configured `Redis` instance in here
+* `:namespace`: Internally, all keys are prefixed with "SirCachealot" while stored in Redis. You can change that string with this option.
+* `:serializer`: `:marhsal` to serialize all values with `Marshal.load()`, or :json to serialize all values with `.to_json`
+    * Note: Do not switch to a different serializer without first calling `Sir.nuke()`!
+
+## Testing
+A test suite is available through `rspec`.
+
+sir_cachealot 0.6.0 was tested against ruby 1.9.3, 2.0, and 2.1 and passed 27/27 tests.
+
+### Testing SirCachealot
+
+    $> cd $GEM_PATH             # cd into your gem path. The shown command, as written, will fail if you use rvm.
+    $> cd gems/sir_cachealot-0.6.0
+    $> bundle install
+    $> rspec
+
+## Change Log
+
+### 0.6.0
+
+* Modularized backends.
+* Implemented Redis Cache features: FLUSHDB (`nuke()`, KEYS (`keys()`), DBSIZE (`length()`), BGSAVE (`flush()`)
+* Renamed clean, clear functions to sweep, nuke (to be easier to visually differentiate)
+
+## Known issues
+
+* `Marshal.load()`, which is used by RedisCache's `:marshal` serializer, has been known to throw exceptions when it is called repeatedly (like in a tight loop)
 
 ## Contributing
 
@@ -84,5 +180,5 @@ If the key does not exist, or if it has expired:
 
 ## License
 
-Use of SirCachealot is permitted under the terms of [LGPLv3](http://www.gnu.org/licenses/lgpl-3.0.txt).
-For more information see LICENSE.txt.
+Use of SirCachealot is permitted under the terms of the [2-clause BSD License](http://directory.fsf.org/wiki?title=License:FreeBSD).
+For more information see LICENSE.txt.

data/Rakefile

@@ -7,5 +7,5 @@ task :default => [:spec]
 
 desc "Open an irb session preloaded with this library"
 task :console do
-  sh "irb -rubygems -I lib -r sir_cachealot.rb"
+  sh "irb -rubygems -I lib -r sir.rb"
 end

data/lib/sir.rb

@@ -0,0 +1,145 @@
+require "rubygems"
+
+def required(str)
+  require File.dirname(__FILE__) + "/" + str
+end
+
+required "sir/version"
+required "sir/backends"
+
+module Sir
+
+  BACKENDS = {
+      ram_cache:   Sir::Backends::RamCache,
+      redis_cache: Sir::Backends::RedisCache
+  }
+
+  @@backend = Sir::Backends::RamCache
+
+  @@configuration = {
+      mode:           :ram_cache,
+      debug:          false, #debug messages (prints to stderr)
+      annoy:          false, #super annoying debug messages (prints to stderr)
+      default_expiry: 3600,  #Integer(1.hour)
+      options:        {}
+  }
+
+
+  # Configuration function
+  # yields a config block, see README
+  # @returns true
+  def self.configure(&block)
+
+    if block_given?
+      yield(@@configuration)
+    end
+
+    #ap @@configuration
+
+    @@backend = BACKENDS[@@configuration[:mode]]
+    @@backend.configure(@@configuration[:options])
+
+    # this doesnt work right
+    #Sir::Backends::Base::EXPORTS.each do |func|
+    #  Sir.send :define_singleton_method, func do |*params|
+    #    @@backend.send(func, *params)
+    #  end
+    #  self.annoy("Attached #{func}")
+    #end
+
+    self.debug("SirCachealot #{Sir::VERSION} loaded configuration for #{@@configuration[:mode]}, watching #{Sir::Backends::Base::EXPORTS.length} methods")
+    self.annoy("Annoy activated! Bwahaha!")
+    return true
+
+  end
+
+
+  # Tests is debug flag is set
+  # @returns [boolean] debug status
+  def self.debug?
+    return @@configuration[:debug]
+  end
+
+
+  # Tests if annoy flag is set
+  # @returns [boolean] annoy status
+  def self.annoy?
+    return @@configuration[:annoy]
+  end
+
+
+  # Send message to debug stream
+  def self.debug(msg)
+    $stderr.puts("<=S=I=R=[==] !! #{msg}") if self.debug?
+  end
+
+
+  # Send message to annoy stream
+  def self.annoy(msg)
+    $stderr.puts("<=S=I=R=[==] - #{msg}") if self.annoy?
+  end
+
+
+  # look up value of single configuration option
+  def self.config(key)
+    return @@configuration[key]
+  end
+
+
+  def self.dump_config
+    p @@configuration
+    return nil
+  end
+
+
+  # TODO: define all these methods on configure(), we should only go here if the user hasnt configured Sir
+  # catch on use if unconfigured
+  def self.method_missing(meth, *args, &block)
+
+    if Sir::Backends::Base::EXPORTS.include?(meth)
+      self.configure! if @@configuration.nil?
+      return @@backend.send(meth, *args, &block)
+    else
+      super
+    end
+
+  end
+
+  #remove me
+  #
+  # @todo Remove me
+  def self.conredis
+    require 'redis'
+    redis_obj        = Redis.new(:host => "127.0.0.1", :port => "6379")
+    opts             = Sir::Backends::RedisCache::DEFAULTS
+    opts[:redis_obj] = redis_obj
+
+
+    Sir.configure do |config|
+      config[:mode]           = :redis_cache
+      config[:debug]          = true
+      config[:options]        = opts
+    end
+
+  end
+
+
+  private
+
+  def self.puke
+    raise TypeError, "Invalid config(:mode). Check the inputs sent to Sir.configure()"
+  end
+
+
+  def self.crude_clone(obj)
+    return Marshal.load(Marshal.dump(obj))
+  end
+
+
+# returns a namespaced key
+  def self.nsed_key(key)
+    return "SirCachealot-#{key}"
+  end
+
+
+end