jsvd-blackboard 0.2.3

data/ChangeLog

@@ -0,0 +1,41 @@
+== 0.2.3 / 2009-01-16
+
+* Fixed subsubfolders
+
+== 0.2.2 / 2009-01-15
+
+* Removed overriden Folder#keys. Now Hash#keys is called.
+
+== 0.2.1 / 2009-01-15
+
+* Fixed Folder#_update
+
+== 0.2.0 / 2009-01-15
+
+* New fluent interface
+
+== 0.1.4 / 2008-12-15
+
+* Imposed upper bound on ttl to #seconds in 30 days
+
+== 0.1.3 / 2008-12-12
+
+* Blackboard will only replace Data objects if new is..newer
+
+== 0.1.2 / 2008-12-11
+
+* TTL now configured per-folder (or defaults to BB's generic ttl)
+
+== 0.1.1 / 2008-12-09
+
+* Improved get method error handling
+
+== 0.1.0 / 2008-12-09
+
+* Added expiration times
+* Added folders and data objects
+* Added one memcache instance per folder
+
+== 0.0.1 / 2008-11-28
+
+* initial release

data/README

@@ -0,0 +1,62 @@
+
+= blackboard
+
+
+== Description
+
+BlackBoard provides a folder-layer to memcache-client. A BlackBoard is created with a static structure of folders and items.
+
+bb = Pulso::BlackBoard.new :ttl => 2 do
+ folder :folder1, [:name1] do
+   folder :folder1, [:name1, :name2]
+   folder :folder2, [:name2]
+   folder :folder3, [:name2]
+ end
+
+It is aimed at quickly writing and reading, usually attached to EventMachine, for example.
+Objects written to the blackboard must answer to :timestamp, for they will expire.
+
+class TestObject
+  attr_reader :timestamp
+  def initialize; @timestamp = Time.now; end
+end
+
+obj = TestObject.new
+
+To write an item from a folder:
+
+bb.folder1.folder1.name1 = obj
+
+To retrieve an item from a folder
+
+obj = bb.folder1.folder1.name1
+
+To retrive all items in a folder:
+
+items = bb.folder1
+obj = items[:folder1][:name1]
+
+== Installation
+
+=== Archive Installation
+
+	rake install
+
+=== Gem Installation
+
+	gem install blackboard
+
+
+== Features/Problems
+
+Must include Pulso module to use.
+Fully specced.
+
+== Synopsis
+
+
+== Copyright
+
+Author::    João Duarte <jsvduarte@gmail.com>
+Copyright:: Copyright (c) 2008 jsvd
+License::   

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'rake/contrib/sshpublisher'
+require 'spec/rake/spectask'
+require 'fileutils'
+require 'metric_fu'
+include FileUtils
+
+MetricFu::CHURN_OPTIONS = {:scm => :git}
+MetricFu::DIRECTORIES_TO_FLOG = ['lib']  
+MetricFu::SAIKURO_OPTIONS = {"--input_directory" => 'lib'}
+
+CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+task :default => [:test]
+#task :package => [:clean]
+
+Rake::TestTask.new("test") do |t|
+	t.libs   << "test"
+	t.pattern = "test/**/*_test.rb"
+	t.verbose = true
+end
+
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('examples_with_rcov') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'examples']
+end
+
+task :cruise => [ "metrics:flog", "metrics:churn", "metrics:coverage", "metrics:saikuro" ]

data/blackboard.gemspec

@@ -0,0 +1,30 @@
+spec = Gem::Specification.new do |s|
+	s.name              = "blackboard"
+	s.version           = "0.2.3"
+	s.platform          = Gem::Platform::RUBY
+	s.has_rdoc          = false
+	s.summary           = ""
+	s.description       = ""
+	s.author            = "João Duarte"
+	s.email             = "jsvduarte@gmail.com"
+	s.executables       = %w(  )
+	s.bindir            = "bin"
+	s.require_path      = "lib"
+
+	s.add_dependency('memcache-client', '>=1.4.0')
+	s.required_ruby_version = '>= 1.8.5'
+
+  s.files = %w(
+    test
+    test/test_helper.rb
+    test/blackboard_test.rb
+    lib
+    lib/blackboard.rb
+    README
+    spec
+    spec/blackboard_spec.rb
+    ChangeLog
+    Rakefile
+    blackboard.gemspec)
+
+end

data/lib/blackboard.rb

@@ -0,0 +1,143 @@
+# vim: expandtab : tabstop=2 : shiftwidth=2 : softtabstop=2
+
+module Pulso
+
+  class Folder < Hash
+
+    attr_reader :name, :ttl
+
+    def initialize name, children, args = {}, &block
+      @name = name
+
+      @items = {}
+      @folders = []
+      @ttl = args[:ttl]
+      @cache = args[:cache]
+
+      raise ArgumentError, "Pulso::Folder.new should receive name, keys, cache and ttl" if @ttl.nil? || args[:cache].nil?
+      raise ArgumentError, "Pulso::Folder.new should not receive ttl bigger than #seconds in 30 days" if @ttl > 2592000
+
+      create_children children
+      
+      instance_eval(&block) unless block.nil?
+
+    end
+
+    def method_missing folder
+      raise BlackBoardError, "Folder #{folder} not found"
+    end
+
+    def _update
+      @items.keys.each do |k|
+        self[k] = get k
+      end
+      @folders.each {|f| self[f]._update }
+    end
+
+    private
+    def folder name, keys, args = {}, &block
+      raise BlackBoardError, "Folder #{name} already exists" if self.has_key?(name)
+      ttl = args[:ttl]
+      ttl ||= @ttl
+      @folders << name
+      self[name] = Pulso::Folder.new "#{@name}.#{name}", keys, :cache => @cache, :ttl => ttl, &block
+      instance_eval %Q{def #{name}; self[:#{name}]._update ;self[:#{name}]; end}
+      
+    end
+
+    def create_children children
+      children.each do |child| 
+        self[child] = nil
+        instance_eval %Q{
+        def #{child}=(object); add :#{child}, object; end
+        def #{child}; self[:#{child}] = get :#{child}; end}
+        @items[child] = Time.at 0 
+      end
+    end
+
+    def add name, object
+      obj_ttl = (@ttl - (Time.now - object.timestamp)).round
+      return unless obj_ttl > 0
+      return if object.timestamp < @items[name]
+
+      @items[name] = object.timestamp
+      obj = Pulso::Data.new(name, object)
+      @cache.set "#{@name}.#{name}", obj, obj_ttl
+    end
+
+    def get obj_name
+      raise BlackBoardError, "Key #{obj_name} doesn't exist in folder #{@name}." unless @items.has_key?(obj_name)
+      ret = @cache["#{@name}.#{obj_name}"]
+      return if ret.nil?
+      ret.data
+    end
+
+  end
+
+  class Data
+
+    attr_reader :name, :data, :timestamp
+
+    def initialize name, object
+      @name = name
+      raise BlackBoardError, "Object does not have timestamp" unless object.respond_to?(:timestamp)
+      @data = object
+      @timestamp = Time.now
+    end
+
+  end
+
+  class BlackBoard
+
+    require 'rubygems'
+    require 'memcache'
+
+    @cache = nil
+
+    attr_reader :folders
+
+    def initialize opts = {}, &block
+      @folders = {}
+      @ttl = opts[:ttl] || 60
+      raise ArgumentError, "Pulso::BlackBoard.new should not receive ttl bigger than #seconds in 30 days" if @ttl > 2592000
+      @servers = opts[:servers]
+      @servers ||= "127.0.0.1:11411"
+      @cache = MemCache.new(@servers, :namespace => 'blackboard')
+      instance_eval(&block) unless block.nil?
+    end
+
+    def active?
+      @cache.active?
+    end
+
+    def has_folders?
+      !@folders.empty?
+    end
+
+    def empty? 
+      @cache.stats.inject(0) {|sum, server| sum + server.last["curr_items"]} == 0
+    end
+
+    def folder name, keys, args = {}, &block
+      raise BlackBoardError, "Folder #{name} already exists" if @folders.has_key?(name)
+      ttl = args[:ttl]
+      ttl ||= @ttl
+      instance_eval %Q{def #{name}; @folders[:#{name}]._update; @folders[:#{name}]; end}
+      @folders[name] = Pulso::Folder.new name, keys, :cache => @cache, :ttl => ttl, &block
+    end
+
+    def clean
+      @cache.flush_all
+    end
+
+    def method_missing folder
+      raise BlackBoardError, "Folder #{folder} not found"
+    end
+
+  end
+
+  class BlackBoardError < RuntimeError
+
+  end
+
+end

data/spec/blackboard_spec.rb

@@ -0,0 +1,374 @@
+require 'spec'
+require 'lib/blackboard'
+
+class TestObject
+
+  def initialize
+    @timestamp = Time.now
+  end
+
+  attr_accessor :color
+  attr_reader :timestamp
+end
+
+describe Pulso::Folder do
+
+  before :each do
+    @cache = MemCache.new("127.0.0.1:11411", :namespace => 'blackboard')
+  end
+
+  it "should be created with a name, servers and ttl" do
+    f = nil
+    lambda { f = Pulso::Folder.new }.should raise_error ArgumentError
+    lambda { f = Pulso::Folder.new :folder1, [], :cache => @cache }.should raise_error ArgumentError
+    lambda { f = Pulso::Folder.new :folder1, [], :ttl => 20 }.should raise_error ArgumentError
+    lambda { f = Pulso::Folder.new :folder1, [], :cache => @cache, :ttl => 20 }.should_not raise_error ArgumentError
+    f.name.should == :folder1
+  end
+
+  it "should complain if ttl is bigger than seconds in 30 days" do
+    lambda { Pulso::Folder.new :folder1, [], :cache => @cache, :ttl => 30*24*3600+1 }.should raise_error ArgumentError
+    lambda { Pulso::Folder.new :folder1, [], :cache => @cache, :ttl => 30*24*3600 }.should_not raise_error ArgumentError
+  end
+
+  it "should not complain when creating subfolders" do
+    lambda { 
+      Pulso::Folder.new :folder1, [:name1, :name2], :cache => @cache, :ttl => 30*24*3600 do
+        folder :folder2, [:name4, :name5], :ttl => 30*24*3600
+      end
+    }.should_not raise_error ArgumentError
+  end
+
+  it "should return a kind of Hash" do
+    f = Pulso::Folder.new :folder1, [:name1], :cache => @cache, :ttl => 20
+    f.should be_a_kind_of Hash
+    f.should == { :name1 => nil }
+  end
+
+  it "should respond to folder name method" do
+    `memcached -d -p 11411 -P /tmp/memcached-test.pid`
+    k = Pulso::Folder.new :folder1, [:name1, :name2], :cache => @cache, :ttl => 30*24*3600 do
+      folder :folder2, [:name1]
+    end
+    lambda { k.folder2 }.should_not raise_error
+    k.folder2.should == { :name1 => nil } 
+    `killall memcached`
+  end
+
+end
+
+describe Pulso::Data do
+
+  it "should be initialized with a name and an object that responds to :timestamp" do
+    lambda { Pulso::Data.new }.should raise_error
+    lambda { Pulso::Data.new :name1, Object.new }.should raise_error Pulso::BlackBoardError
+    obj = TestObject.new
+    data = nil
+    lambda { data = Pulso::Data.new :name1, obj }.should_not raise_error Pulso::BlackBoardError
+    data.name.should == :name1
+    data.data.should == obj
+  end
+
+  it "should have a timestamp" do
+    Pulso::Data.new(:name1, TestObject.new).timestamp.should be_close Time.now,1
+  end
+
+end
+
+describe Pulso::BlackBoard do
+
+  before :all do
+    `memcached -d -p 11411 -P /tmp/memcached-test.pid`
+    @blackboard = Pulso::BlackBoard.new :ttl => 2 do
+      folder :folder1, [:name1, :name2]
+    end
+  end
+
+  describe "(default)" do 
+
+    it "should be active?" do
+      @blackboard.should be_active
+    end
+
+    it "should have folders" do
+      @blackboard.should have_folders
+    end
+
+    it "should complain if ttl is bigger than seconds in 30 days" do
+      lambda { Pulso::BlackBoard.new :ttl => 30*24*3600+1 }.should raise_error ArgumentError
+      lambda { Pulso::BlackBoard.new :ttl => 30*24*3600 }.should_not raise_error ArgumentError
+    end
+
+  end
+
+  describe "(empty)" do
+
+    it { @blackboard.should be_empty }
+
+    it "should have folders after adding one" do
+      bb = Pulso::BlackBoard.new do
+        folder :folder1, [:name1, :name2]
+      end
+      bb.should have_folders
+      bb.folders.keys.should include(:folder1)
+    end
+
+    # TODO improve by regexp matching
+    it "should complain when retrieving from inexistant folder" do
+      lambda { @blackboard.folder2.name1 }.should raise_error Pulso::BlackBoardError
+    end
+
+    it "should return nil when retrieving known data key from folder" do
+      @blackboard.folder1.name2.should be_nil
+    end
+
+    it "should complain when retrieving unknown data key from folder" do
+      lambda { @blackboard.folder1.name5 }.should raise_error Pulso::BlackBoardError
+    end
+
+  end
+
+  describe "(non-empty)" do
+    
+    before :all do
+      @blackboard = Pulso::BlackBoard.new :ttl => 2 do
+        folder :folder1, [:name1, :name2, :name3]
+        folder :folder2, [:name4, :name5, :name6]
+      end
+      @blackboard.folders.keys.should include(:folder1)
+    end
+
+    before :each do
+      @obj = TestObject.new
+      @obj.color = :green
+      @blackboard.folder1.name2 = @obj
+      @obj = TestObject.new
+      @obj.color = :black
+      @blackboard.folder1.name3 = @obj
+      @obj = TestObject.new
+      @obj.color = :blue
+      @blackboard.folder1.name1 = @obj
+    end
+
+    it "should not be empty" do 
+      @blackboard.should have_folders
+      obj = TestObject.new
+      obj.color = :green
+      @blackboard.folder1.name2 = obj
+      @blackboard.should_not be_empty
+    end
+
+    it "should be able to retrieve object from a folder" do
+      obj = @blackboard.folder1.name1
+      obj.color.should == :blue
+    end
+
+    it "should be empty after cleaning" do
+      @blackboard.clean
+      @blackboard.should be_empty
+    end
+
+    it "should not return nil when retrieving object whose time-to-live was not exceeded" do 
+      `sleep 1`
+      @blackboard.folder1.name1.should_not be_nil
+    end
+
+    it "should return nil when retrieving object whose time-to-live was exceeded" do 
+      @blackboard.folder1.name1.should_not be_nil
+      `sleep 2`
+      @blackboard.folder1.name1.should be_nil
+      @blackboard.folder1.name1 = @obj # already expired
+      @blackboard.folder1.name1.should be_nil
+    end
+
+    it "should be possible to retrieve all data from a folder" do
+      ret = @blackboard.folder1
+      ret.name1.color.should == :blue
+      ret.name2.color.should == :green
+      ret.name3.color.should == :black
+    end
+
+    it "should timestamp the BlackBoard::Data object with current time when adding" do
+      obj = TestObject.new
+      obj.color = :blue
+      @blackboard.folder1.name1 = obj
+      @blackboard.folder1.name1.timestamp.should be_close Time.now, 0.2
+    end
+
+    it "should keep a Data object if new one is older" do
+      obj1 = TestObject.new
+      obj1.color = :blue
+      `sleep 1`
+      obj2 = TestObject.new
+      obj2.color = :green
+      @blackboard.folder2.name5 = obj2
+      @blackboard.folder2.name5 = obj1
+      obj = @blackboard.folder2.name5
+      obj.color.should == :green
+    end
+
+    it "should replace a Data object if new one is newer" do
+      obj1 = TestObject.new
+      obj1.color = :blue
+      `sleep 1`
+      obj2 = TestObject.new
+      obj2.color = :green
+
+      @blackboard.folder1.name2 = obj1
+      obj = @blackboard.folder1.name2
+      obj.color.should == :blue
+
+      @blackboard.folder1.name2 = obj2
+      obj = @blackboard.folder1.name2
+      obj.color.should == :green
+    end
+
+    after :each do
+      @blackboard.clean
+    end
+  end
+
+  describe "(with subfolders)" do
+
+    it "should allow subfolders" do
+
+      lambda { 
+        @blackboard = Pulso::BlackBoard.new :ttl => 2 do
+          folder :folder1, [:name1, :name2, :name3] do
+            folder :folder2, [:name4, :name5]
+          end
+        end
+      }.should_not raise_error
+
+      @blackboard.folder1.should == { :name1 => nil, :name2 => nil, :name3 => nil, :folder2 => { :name4 => nil, :name5 => nil } }
+
+    end
+
+    it "should be possible to write to a subfolder" do
+
+      @blackboard = Pulso::BlackBoard.new :ttl => 2 do
+        folder :folder1, [:name1, :name2, :name3] do
+          folder :folder2, [:name4, :name5]
+        end
+      end
+
+      obj = TestObject.new 
+      obj.color = :green
+
+      lambda { @blackboard.folder1.folder2.name5 = obj }.should_not raise_error
+
+      ret = @blackboard.folder1.folder2.name5
+      ret.color.should == :green
+
+      ret = @blackboard.folder1.folder2
+      ret[:name4].should be_nil
+      ret[:name5].color.should == :green
+
+      lambda { @blackboard.folder1.folder2.name5 = obj }.should_not raise_error
+
+    end
+
+    it "should allow different ttl for subfolders" do
+      @blackboard = Pulso::BlackBoard.new :ttl => 2 do
+        folder :folder1, [:name1], :ttl => 1
+        folder :folder2, [:name2], :ttl => 2
+      end
+      obj = TestObject.new 
+      obj.color = :green
+      @blackboard.folder1.name1 = obj
+      @blackboard.folder2.name2 = obj
+      @blackboard.folder1.name1.should_not be_nil
+      @blackboard.folder2.name2.should_not be_nil
+      `sleep 1`
+      @blackboard.folder1.name1.should be_nil
+      @blackboard.folder2.name2.should_not be_nil
+      `sleep 1`
+      @blackboard.folder1.name1.should be_nil
+      @blackboard.folder2.name2.should be_nil
+    end
+
+    it "should allow different ttl between folder and subfolder" do
+      @blackboard = Pulso::BlackBoard.new :ttl => 2 do
+        folder :folder1, [:name1], :ttl => 1 do
+          folder :folder2, [:name2], :ttl => 2
+        end
+      end
+      obj = TestObject.new 
+      obj.color = :green
+      @blackboard.folder1.name1 = obj
+      @blackboard.folder1.folder2.name2 = obj
+
+      @blackboard.folder1.name1.should_not be_nil
+      @blackboard.folder1.folder2.name2.should_not be_nil
+      `sleep 1`
+      @blackboard.folder1.name1.should be_nil
+      @blackboard.folder1.folder2.name2.should_not be_nil
+      `sleep 1`
+      @blackboard.folder1.name1.should be_nil
+      @blackboard.folder1.folder2.name2.should be_nil
+    end
+
+    it "should propagate tll to subfolders " do
+      @blackboard = Pulso::BlackBoard.new :ttl => 2 do
+        folder :folder1, [:name1], :ttl => 1 do
+          folder :folder2, [:name2]
+        end
+      end
+      obj = TestObject.new 
+      obj.color = :green
+      @blackboard.folder1.name1 = obj
+      @blackboard.folder1.folder2.name2 = obj
+
+      @blackboard.folder1.name1.should_not be_nil
+      @blackboard.folder1.folder2.name2.should_not be_nil
+      `sleep 1`
+      @blackboard.folder1.name1.should be_nil
+      @blackboard.folder1.folder2.name2.should be_nil
+      `sleep 1`
+      @blackboard.folder1.name1.should be_nil
+      @blackboard.folder1.folder2.name2.should be_nil
+    end
+
+    it "should support writing to two elements with same name on different folders" do
+      @blackboard = Pulso::BlackBoard.new :ttl => 10 do
+        folder :folder1, [:name1]
+        folder :folder2, [:name1]
+      end
+      obj = TestObject.new 
+      obj.color = :green
+      @blackboard.folder1.name1 = obj
+      obj = TestObject.new 
+      obj.color = :blue
+      @blackboard.folder2.name1 = obj
+
+      @blackboard.folder1.name1.color.should == :green
+      @blackboard.folder2.name1.color.should == :blue
+    end
+
+    it "should not complain when creating sub sub folders" do
+      lambda { @blackboard = Pulso::BlackBoard.new :ttl => 10 do
+        folder :folder1, [:name1] do
+          folder :folder1, [:name1] do
+            folder :folder1, [:name1] do
+              folder :folder1, [:name1] do
+                folder :folder1, [:name1] do
+                  folder :folder1, [:name1]
+                end
+              end
+            end
+          end
+        end
+      end }.should_not raise_error
+      obj = TestObject.new 
+      obj.color = :green
+      @blackboard.folder1.folder1.folder1.folder1.folder1.folder1.name1 = obj
+      @blackboard.folder1.folder1.folder1.folder1.folder1.folder1.name1.color.should == :green
+    end
+
+  end
+
+  after :all do
+    `killall memcached`
+  end
+
+end

data/test/blackboard_test.rb

@@ -0,0 +1,8 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+require "test/unit"
+class BlackboardTest < Test::Unit::TestCase
+  def test_nothing
+    true
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/blackboard'
+

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: jsvd-blackboard
+version: !ruby/object:Gem::Version 
+  version: 0.2.3
+platform: ruby
+authors: 
+- "Jo\xC3\xA3o Duarte"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-11 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: memcache-client
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.4.0
+    version: 
+description: ""
+email: jsvduarte@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- test
+- test/test_helper.rb
+- test/blackboard_test.rb
+- lib
+- lib/blackboard.rb
+- README
+- spec
+- spec/blackboard_spec.rb
+- ChangeLog
+- Rakefile
+- blackboard.gemspec
+has_rdoc: false
+homepage: 
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.5
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: ""
+test_files: []
+