instantcache 0.1.0a1 → 0.1.1

data/History.txt

@@ -1,4 +1,11 @@
-=== 0.0.1 2011-08-25
+=== 0.1.1 2011-09-09
+
+* 1 major enhancement:
+  * Added check for the cache object having been set up.
+- Minor enhancements
+  - Much documentation updating.
+
+=== 0.1.0a1 2011-09-08
 
 * 1 major enhancement:
   * Initial release

data/README.txt

@@ -1,28 +1,65 @@
 = InstantCache - Variables in memcached
 
-* http://github.com/RoUS/rubygem-instantcache
+* http://instantcache.rubyforge.org/
+
+* github:    http://github.com/RoUS/rubygem-instantcache
+* rubyforge: http://rubyforge.org/scm/?group_id=10054
 
 == DESCRIPTION:
 
-rubygem-instantcache provides the InstantCache module, a mixin
+*rubygem-instantcache* provides the InstantCache module, a mixin
 which has accessors that allow you to declare 'instance variables'
 that are actually stored in a memcached cluster rather than
 local memory.
 
+== GLOSSARY:
+
+* <b><i>blob</i></b>, <b><i>blob object</i></b>, or <b><i>blob instance</i></b>: An instrumented InstantCache::Blob or InstantCache::Counter object that has been instantiated and stored in an <i>instance variable</i>.
+* <b><i>cached value</i></b>: The value actually stored in the memcached cluster.
+* <b><i>cache</i></b> (or <b><i>cached</i></b>) <b><i>variable</i></b>: an instance variable declared with one of the <tt>memcached_<i>xxx</i></tt> declarators and holding a <i>blob instance</i>.
+* <b><i>cell</i></b> or <b><i>cache cell</i></b>: The named location in the memcached cluster where a <i>cached value</i> is stored.
+* <b><i>instance variable</i></b>: This has its canonical meaning: a named cell local to an object.  <i>Blob objects</i> are stored in <i>instance variables</i> to form <i>cached variables</i>.
+
 == FEATURES:
 
-* Provides ''memcached_reader'', ''memcached_accessor'', and ''memcached_counter'' accessor declarations.
-* Variables declared with ''memcached_counter'' are restricted to integer values, and are incrementable/decrementable atomically.
-* Variables may be shared, using cells in memcache named by the user, or may be private, with opaque names unique to each instance.
-* Variables may be locked and unlocked for atomic operations.
+* Provides <tt>memcached_reader</tt>, <tt>memcached_accessor</tt>, and <tt>memcached_counter</tt> accessor declarations.
+* Cached variables declared with <tt>memcached_counter</tt> are restricted to integer values, and are incrementable/decrementable atomically.
+* Cached variables may be shared, using cells in memcache named by the user, or may be private, with opaque names unique to each instance.
+* Cached variables may be locked and unlocked for atomic operations.
+* If an instance variable is inadvertently overwritten, a new connexion to the cached value will be created (a new blob object will be instantiated) the next time one of InstantCache's methods is used to access it.
+
+== CAVEATS AND WARNINGS
 
-== PROBLEMS:
+* InstantCache works by storing a specially-instrumented object in the actual instance variable.  References from within the class to an instance variable declared as a cached variable should use the "<tt>self.</tt>" prefix (<i>e.g.</i>, <tt>self.ivar</tt>) or the blob object's methods directly (<i>e.g.</i>, <tt>@ivar.get</tt> or <tt>@ivar.set(17)</tt>).
+* Direct assignment to an instance variable (<i>e.g.</i>, <tt>@ivar = 17</tt>) will lose the instrumented object and result in a new one being created.
 
-* Multiple references to a cached variable can get out of sync, leading to confusion if they are updated independently.
+== KNOWN PROBLEMS:
+
+* If an cached variable is locked, and is then re-instantiated/reconnected, the variable will <b>remain</b> locked and cannot be unlocked.
+* Multiple references to a cached variable can get out of sync, leading to confusion if they are updated independently.  That is,
+    class Foo
+      include InstantCache
+      memcached_accessor(:ivar)
+    end
+
+    f = Foo.new
+    f.ivar = [1,2,3]
+    copy = f.ivar
+    f.ivar = 17
+    copy
+    => [1,2,3]
+    f.ivar
+    => 17
+    copy << 4
+    => [1,2,3,4]
+    f.ivar
+    => [1,2,3,4]
 
 == SYNOPSIS:
 
+  require 'memcache'
   require 'instantcache'
+
   class Foo
     include InstantCache
     memcached_counter(:c1)          # defaults to 0 if not already existant
@@ -56,8 +93,8 @@ local memory.
 
 == REQUIREMENTS:
 
-* Gem ''versionomy''
-* Gem ''memcache-client''
+* Gem <tt>{versionomy}[https://rubygems.org/gems/versionomy]</tt>
+* Gem <tt>{memcache-client}[https://rubygems.org/gems/memcache-client]</tt>
 
 == INSTALL:
 

data/instantcache.gemspec

@@ -1,29 +1,25 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{instantcache}
-  s.version = "0.1.0a1"
+  s.name = "instantcache"
+  s.version = "0.1.1"
 
-  s.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.3.1") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ken Coar"]
-  s.date = %q{2011-09-08}
-  s.description = %q{rubygem-instantcache provides the InstantCache module, a mixin
-which has accessors that allow you to declare 'instance variables'
-that are actually stored in a memcached cluster rather than
-local memory.}
+  s.date = "2011-09-09"
+  s.description = "rubygem-instantcache provides the InstantCache module, a mixin\nwhich has accessors that allow you to declare 'instance variables'\nthat are actually stored in a memcached cluster rather than\nlocal memory."
   s.email = ["coar@rubyforge.org"]
   s.extra_rdoc_files = ["History.txt", "LICENCE.txt", "Manifest.txt", "README.txt"]
-  s.files = ["History.txt", "LICENCE.txt", "Manifest.txt", "README.txt", "Rakefile", "instantcache.gemspec", "lib/instantcache.rb", "lib/instantcache/exceptions.rb", "script/console", "script/destroy", "script/generate", "test/test_helper.rb", "test/test_instantcache.rb", "test/test_sharing_complex.rb", "test/test_sharing_simple.rb"]
-  s.homepage = %q{http://github.com/RoUS/rubygem-instantcache}
+  s.files = ["History.txt", "LICENCE.txt", "Manifest.txt", "README.txt", "Rakefile", "instantcache.gemspec", "lib/instantcache.rb", "lib/instantcache/exceptions.rb", "script/console", "script/destroy", "script/generate", "test/test_helper.rb", "test/test_instantcache.rb", "test/test_sharing_complex.rb", "test/test_sharing_simple.rb", ".gemtest"]
+  s.homepage = "http://instantcache.rubyforge.org/"
   s.rdoc_options = ["--main", "README.txt"]
   s.require_paths = ["lib"]
-  s.rubyforge_project = %q{instantcache}
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{rubygem-instantcache provides the InstantCache module, a mixin which has accessors that allow you to declare 'instance variables' that are actually stored in a memcached cluster rather than local memory.}
+  s.rubyforge_project = "instantcache"
+  s.rubygems_version = "1.8.10"
+  s.summary = "rubygem-instantcache provides the InstantCache module, a mixin which has accessors that allow you to declare 'instance variables' that are actually stored in a memcached cluster rather than local memory."
   s.test_files = ["test/test_instantcache.rb", "test/test_helper.rb", "test/test_sharing_simple.rb", "test/test_sharing_complex.rb"]
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then

data/lib/instantcache.rb

@@ -73,7 +73,7 @@ module InstantCache
   #
   # The base Versionomy representation of the package version.
   #
-  Version = Versionomy.parse('0.1.0a1')
+  Version = Versionomy.parse('0.1.1')
 
   #
   # The package version-as-a-string.
@@ -102,6 +102,27 @@ module InstantCache
 
     #
     # === Description
+    # Wrapper for the @cache_object class variable.
+    #
+    # :call-seq:
+    # InstantCache.cache.<i>method</i>
+    #
+    # === Arguments
+    # <i>None.</i>
+    #
+    # === Exceptions
+    # [<tt>InstantCache::NoCache</tt>] Cache object unset or misset.
+    #
+    def cache                   # :nodoc
+      mco = (InstantCache.cache_object ||= nil)
+      return mco if (mco.kind_of?(MemCache))
+      raise NoCache
+    end
+
+    #
+    # === Description
+    # Add singleton wrapper methods to a copy of the cached value.
+    #
     # :call-seq:
     # InstantCache.enwrap(<i>cacheval</i>) => nil
     #
@@ -451,7 +472,7 @@ module InstantCache
       #
       # TODO: This can mess with subclassing; need better way to find the cache
       #
-      InstantCache.cache_object.set(self.name, rval, self.expiry, self.rawmode)
+      InstantCache.cache.set(self.name, rval, self.expiry, self.rawmode)
       return rval
     end
 
@@ -570,7 +591,7 @@ module InstantCache
       #
       # TODO: Another instance of poor-man's-cache-location; see #reset
       #
-      sts = InstantCache.cache_object.add(self.lock_name, @identity)
+      sts = InstantCache.cache.add(self.lock_name, @identity)
       @locked_by_us = (sts.to_s =~ %r!^STORED!) ? true : false
       return @locked_by_us
     end
@@ -610,7 +631,7 @@ module InstantCache
       #
       # TODO: Another instance of poor-man's-cache-location; see #reset
       #
-      sts = InstantCache.cache_object.get(self.lock_name) || false
+      sts = InstantCache.cache.get(self.lock_name) || false
       if (@locked_by_us && (sts != @identity))
         #
         # If we show we have the lock, but the lock cell doesn't exist
@@ -626,7 +647,7 @@ module InstantCache
       #
       # TODO: Another instance of poor-man's-cache-location; see #reset
       #
-      sts = InstantCache.cache_object.delete(self.lock_name)
+      sts = InstantCache.cache.delete(self.lock_name)
       if (sts !~ %r!^DELETED!)
         e = LockInconsistency.new(self.lock_name,
                                   '/DELETED/',
@@ -656,7 +677,7 @@ module InstantCache
       #
       # TODO: Another instance of poor-man's-cache-location; see #reset
       #
-      value = InstantCache.cache_object.get(self.name, self.rawmode)
+      value = InstantCache.cache.get(self.name, self.rawmode)
       begin
         #
         # Make a copy of the thing we fetched out of the cache.
@@ -717,8 +738,8 @@ module InstantCache
       #
       # We use both memcache#add and memcache#set for completeness.
       #
-      InstantCache.cache_object.add(self.name, val, self.expiry, self.rawmode)
-      InstantCache.cache_object.set(self.name, val, self.expiry, self.rawmode)
+      InstantCache.cache.add(self.name, val, self.expiry, self.rawmode)
+      InstantCache.cache.set(self.name, val, self.expiry, self.rawmode)
       #
       # Return the value as fetched through our accessor; this ensures
       # the proper annotation.
@@ -746,27 +767,6 @@ module InstantCache
       return self.get.__send__(:to_s, *args)
     end
 
-=begin
-    #
-    # === Description
-    # :call-seq:
-    # === Arguments
-    # === Exceptions
-    # <i>None.</i>
-    #
-    def method_missing(meth, *args)
-      methsym = meth.to_sym
-      return self.__send__(methsym, *args) if (self.respond_to?(methsym))
-      curval = self.get
-      lastval = curval.clone
-      opresult = curval.__send__(methsym, *args)
-      if (curval != lastval)
-        self.set(curval)
-      end
-      return opresult
-    end
-=end
-
   end                           # End of class Blob
 
   #
@@ -965,7 +965,7 @@ module InstantCache
       #
       # TODO: Another instance of poor-man's-cache-location; see #reset
       #
-      return InstantCache.cache_object.incr(self.name, amt)
+      return InstantCache.cache.incr(self.name, amt)
     end
     alias_method(:incr, :increment)
 
@@ -999,7 +999,7 @@ module InstantCache
       #
       # TODO: Another instance of poor-man's-cache-location; see #reset
       #
-      return InstantCache.cache_object.decr(self.name, amt)
+      return InstantCache.cache.decr(self.name, amt)
     end
     alias_method(:decr, :decrement)
 
@@ -1018,6 +1018,23 @@ module InstantCache
     # String constant used to set up most of the background magic
     # common to all of our types of cached variables.
     #
+    # TODO: Resolve what to do if the instance variable is zapped
+    #
+    # One of the fortunate side-effects of all of the methods calling
+    # this first is that if the instance variable gets zapped somehow,
+    # the next access to it through of of our methods will create a
+    # new Blob or Counter object and put it into the instance variable
+    # before proceeding.
+    #
+    # One of the UNfortunate side effects of *that* is that if the
+    # object that was lost was locked, it cannot be unlocked through
+    # the normal paths -- only the blob object itself is supposed to
+    # lock and unlock itself.  It can be worked around, but that's for
+    # another day.
+    #
+    # If we decide against instantiating a new object, the ConnexionLost
+    # exception is ready to be pressed into service.
+    #
     Setup =<<-'EOT'             # :nodoc:
       def _initialise_%s
         unless (self.instance_variables.include?('@%s') \
@@ -1046,8 +1063,8 @@ module InstantCache
           unless (shared)
             mvar.reset
             finaliser = Proc.new {
-              InstantCache.cache_object.delete(mvar.name)
-              InstantCache.cache_object.delete(mvar.send(:lock_name))
+              InstantCache.cache.delete(mvar.name)
+              InstantCache.cache.delete(mvar.send(:lock_name))
             }
             ObjectSpace.define_finalizer(owner, finaliser)
           end

data/lib/instantcache/exceptions.rb

@@ -137,6 +137,24 @@ module InstantCache
                     ]
   end                           # End of class IncompleteException
 
+  #
+  # Obviously this package is dependent upon memcache being available
+  # and configured.  Gritch otherwise.
+  #
+  class NoCache < InstantCache::Exception
+    #
+    # ==== <tt>raise NoCache</tt>
+    #   => InstantCache::NoCache: InstantCache.cache_object not initialised
+    #
+    # ==== <tt>raise Destroyed.new('<i>arg</i>')</tt>
+    #   => InstantCache::NoCache: InstantCache.cache_object not initialised for "arg"
+    #   
+    MessageFormat = [
+                     'InstantCache.cache_object not initialised',
+                     'InstantCache.cache_object not initialised for "%s"',
+                    ]
+  end                           # End of class NoCache
+
   #
   # Once a variable has been hit by the 'destroy!' method, it
   # becomes inaccessible to the instance.
@@ -155,6 +173,25 @@ module InstantCache
                     ]
   end                           # End of class Destroyed
 
+  #
+  # If the instance variable is somehow overwritten, the methods that
+  # try to treat it as a Blob or Counter will fail.  This exception
+  # tries to make that failure less mysterious.
+  #
+  class ConnexionLost < InstantCache::Exception
+    #
+    # ==== <tt>raise ConnexionLost</tt>
+    #   => InstantCache::ConnexionLost: instance variable no longer connected to cache
+    #
+    # ==== <tt>raise Destroyed.new('<i>arg</i>')</tt>
+    #   => InstantCache::ConnexionLost: instance variable "@arg" no longer connected to cache
+    #   
+    MessageFormat = [
+                     'instance variable no longer connected to cache',
+                     'instance variable "@%s" no longer connected to cache',
+                    ]
+  end                           # End of class ConnexionLost
+
   #
   # Our record of the locked status of a cell differs from the information
   # stored in the memcache about it.  This Is Not Good.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: instantcache
 version: !ruby/object:Gem::Version 
-  hash: 415506520
-  prerelease: true
+  hash: 25
+  prerelease: 
   segments: 
   - 0
   - 1
-  - 0a1
-  version: 0.1.0a1
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Ken Coar
@@ -15,8 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-08 00:00:00 -04:00
-default_executable: 
+date: 2011-09-09 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: versionomy
@@ -66,7 +65,7 @@ dependencies:
   type: :development
   version_requirements: *id003
 description: |-
-  rubygem-instantcache provides the InstantCache module, a mixin
+  *rubygem-instantcache* provides the InstantCache module, a mixin
   which has accessors that allow you to declare 'instance variables'
   that are actually stored in a memcached cluster rather than
   local memory.
@@ -98,8 +97,7 @@ files:
 - test/test_sharing_complex.rb
 - test/test_sharing_simple.rb
 - .gemtest
-has_rdoc: true
-homepage: http://github.com/RoUS/rubygem-instantcache
+homepage: http://instantcache.rubyforge.org/
 licenses: []
 
 post_install_message: 
@@ -120,21 +118,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
-      hash: 25
+      hash: 3
       segments: 
-      - 1
-      - 3
-      - 1
-      version: 1.3.1
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: instantcache
-rubygems_version: 1.3.7
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
-summary: rubygem-instantcache provides the InstantCache module, a mixin which has accessors that allow you to declare 'instance variables' that are actually stored in a memcached cluster rather than local memory.
+summary: "*rubygem-instantcache* provides the InstantCache module, a mixin which has accessors that allow you to declare 'instance variables' that are actually stored in a memcached cluster rather than local memory."
 test_files: 
 - test/test_instantcache.rb
 - test/test_helper.rb