volatiledb 0.0.2 → 0.0.3

data/README.md

@@ -1,13 +1,48 @@
 #### Summary
 
-The VolatileDB gem allows you to specify a key and an action yielding a particular piece of data.
+The VolatileDB gem allows you to specify a key and an action yielding a particular piece of 
+data.
   
-This data will be stored in the /tmp folder of the file system you are currently running on. Data is accessible
-  by key. Data will be read and written to storage using File.read() and File.open() -- that's it. It's up to the
-  consuming application to serialize and deserialize data correctly. All VolatileDB does is push and pull data to
-  the FS. 
+
+This data will be stored in the /tmp folder of the file system you are currently running on. Data 
+is accessible by key. Data will be read and written to storage using File.read() and File.open() 
+-- that's it. It's up to the consuming application to serialize and deserialize data correctly. All 
+VolatileDB does is push and pull data to the FS. 
   
 If the underlying file supporting the data is found to be missing, it will be re-initialized.
   
-This gets to the main idea behind VolatileDB: use it to persist data that is transient and can be re-seeded 
-periodically as conditions change. 
+This gets to the main idea behind VolatileDB: use it to persist data that is transient and can be 
+re-seeded periodically as conditions change. 
+
+#### Usage
+
+    require 'volatiledb'
+    db = Volatile::DB.new
+    db.put(:foo) { "acts as" } 
+    #=> :foo
+    db.get(:foo) 
+    #=> "acts as"
+    db.get(:bar) 
+    #=> nil
+    db.put(:bar) { "chunky bacon" }
+    db.get(:bar)
+    #=> "chunky bacon"
+
+#### License
+
+Copyright (c) 2012 Sebastian Wittenkamp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the "Software", to deal in the Software without restriction, including 
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to 
+the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial 
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN 
+NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR 
+THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/TODO.md

@@ -0,0 +1,4 @@
+*TODOS*
+- the API assumes that put is called before all 
+other methods. ensure that get/fetch/pull return 
+nil if no action has been defined for the given key.

data/lib/volatiledb.rb

@@ -9,19 +9,93 @@ module Volatile
       @db  ||= {}
     end 
 
-    def put(key, &action)
-      @db[key] = action
-      @raw.put(key, action.call)
+    #
+    # Define an action for a given key. The action should return a String.
+    # A timeout in seconds may optionally be defined. Default is 3 seconds.
+    #
+    # This method should be called before using any of the read operations.
+    #
+    def put(key, timeout=3, &action)
+      populate_db key, timeout, action
+      raw_put key
       key
     end
 
+    #
+    # Read the data for the given key from storage. If the underlying storage
+    # has disappeared, it will be re-initialized by calling the action defined
+    # for that key again. After the storage has been re-initialized, its value
+    # will be read and returned.
+    #
     def get(key)
       data = @raw.get key
-      unless data.nil?
+      if data.nil?
+        sync key
+      else
         data
+      end
+    end
+    
+    # 
+    # Works the same as get, but will fire the action defined for the given key
+    # after the timeout defined for that key has elapsed.
+    #
+    def fetch(key)
+      checking key do |k|
+        item = @db[k]
+        delta = now - item[:last_access]
+        delta > item[:timeout] ? sync(k) : get(k)
+      end
+    end
+
+    #
+    # Works the same as fetch, but ignores timeout and calls the defined action
+    # every time.
+    #
+    def pull(key)
+      sync key
+    end
+
+    private
+    def populate_db(key, timeout, action)
+      @db[key] = {
+        :action => action, 
+        :timeout => timeout, 
+        :last_access => now
+      }
+    end
+
+    def sync(key)
+      touch key
+      save key
+    end
+
+    def touch(key)
+      checking(key) {|k| @db[k][:last_access] = now }
+    end
+
+    def now
+      Time.now.to_i
+    end
+
+    def save(key)
+      raw_put key
+      raw_get key
+    end
+
+    def raw_put(key)
+      checking(key) {|k| @raw.put(k, @db[k][:action].call) }
+    end
+
+    def raw_get(key)
+      checking(key) {|k| @raw.get k }
+    end
+
+    def checking(key)
+      if @db.key?(key)
+        yield(key)
       else
-        @raw.put(key, @db[key].call)
-        @raw.get(key)
+        nil
       end
     end
   end
@@ -41,7 +115,7 @@ module Volatile
     def get(key)
       handle = @db[key]
       f = "/tmp/#{handle}"
-      if File.exists?(f)
+      if File.file?(f)
         File.read f
       else
         nil

data/lib/volatiledb/version.rb

@@ -1,3 +1,3 @@
 module Volatile
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -2,7 +2,7 @@
 name: volatiledb
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Sebastian Wittenkamp (bitops)
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-04 00:00:00 Z
+date: 2012-01-10 00:00:00 Z
 dependencies: []
 
 description: "  The VolatileDB gem allows you to specify a key and an action yielding a particular piece of data.\n  \n  This data will be stored in the /tmp folder of the file system you are currently running on. Data is accessible\n  by key. Data will be read and written to storage using File.read() and File.open() -- that's it. It's up to the\n  consuming application to serialize and deserialize data correctly. All VolatileDB does is push and pull data to\n  the FS. \n  \n  If the underlying file supporting the data is found to be missing, it will be re-initialized.\n  \n  This gets to the main idea behind VolatileDB: use it to persist data that is transient and can be re-seeded \n  periodically as conditions change. \n"
@@ -27,6 +27,7 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- TODO.md
 - lib/volatiledb.rb
 - lib/volatiledb/version.rb
 - volatiledb.gemspec