more doc

README.txt

@@ -1,7 +1,9 @@
 
 = rufus-tokyo
 
-ruby-ffi based interface to Tokyo Cabinet
+ruby-ffi based interface to Tokyo Cabinet.
+
+It focuses on the abstract API for now (http://tokyocabinet.sourceforge.net/spex-en.html#tcadbapi)
 
 
 == installation

lib/rufus/tokyo.rb

@@ -36,7 +36,7 @@ module Tokyo
 
   VERSION = '0.1.0'
 
-  module Func
+  module Func #:nodoc#
     extend FFI::Library
 
     #
@@ -61,6 +61,8 @@ module Func
     attach_function :tcadbopen, [ :pointer, :string ], :int
     attach_function :tcadbclose, [ :pointer ], :int
 
+    attach_function :tcadbdel, [ :pointer ], :void
+
     attach_function :tcadbrnum, [ :pointer ], :uint64
     attach_function :tcadbsize, [ :pointer ], :uint64
 
@@ -76,7 +78,7 @@ module Func
     #  self.respond_to?(mm) ? self.send(mm, *args) : super
     #end
       #
-      # makes JRuby unhappy
+      # makes JRuby unhappy, forget it.
   end
 
   #
@@ -87,7 +89,24 @@ def self.lib
   end
 
   #
-  # http://tokyocabinet.sourceforge.net/spex-en.html#tcadbapi
+  # A 'cabinet', ie a Tokyo Cabinet database.
+  #
+  # Follows the abstract API described at :
+  #
+  #   http://tokyocabinet.sourceforge.net/spex-en.html#tcadbapi
+  #
+  # An usage example :
+  #
+  #   db = Rufus::Tokyo::Cabinet.new('test_data.tch')
+  #   db['pillow'] = 'Shonagon'
+  #
+  #   db.size # => 1
+  #   db['pillow'] # => 'Shonagon'
+  #
+  #   db.delete('pillow') # => 'Shonagon'
+  #   db.size # => 0
+  #
+  #   db.close
   #
   class Cabinet
     include Enumerable
@@ -96,17 +115,76 @@ class Cabinet
     # Creates/opens the cabinet, raises an exception in case of
     # creation/opening failure.
     #
-    def initialize (name)
+    # This method accepts a 'name' parameter and an optional 'params' hash
+    # parameter.
+    #
+    # 'name' follows the syntax described at
+    #
+    #   http://tokyocabinet.sourceforge.net/spex-en.html#tcadbapi
+    #
+    # under tcadbopen(). For example :
+    #
+    #   db = Rufus::Tokyo::Cabinet.new('casket.tch#bnum=100000#opts=ld')
+    #
+    # will open (eventually create) a hash database backed in the file
+    # 'casket.tch' with a bucket number of 100000 and the 'large' and
+    # 'deflate' options (opts) turned on.
+    #
+    # == :hash or :tree
+    #
+    # Setting the name to :hash or :tree simply will create a in-memory hash
+    # or tree respectively (see #new_tree and #new_hash).
+    #
+    # == tuning parameters
+    #
+    # It's ok to use the optional params hash to pass tuning parameters and
+    # options, thus
+    #
+    #   db = Rufus::Tokyo::Cabinet.new('casket.tch#bnum=100000#opts=ld')
+    #
+    # and
+    #
+    #   db = Rufus::Tokyo::Cabinet.new(
+    #     'casket.tch', :bnum => 100000, :opts => 'ld')
+    #
+    # are equivalent.
+    #
+    # == mode
+    #
+    # To open a db in read-only mode :
+    #
+    #   db = Rufus::Tokyo::Cabinet.new('casket.tch#mode=r')
+    #   db = Rufus::Tokyo::Cabinet.new('casket.tch', :mode => 'r')
+    #
+    def initialize (name, params={})
 
       @db = Rufus::Tokyo::Func.tcadbnew
 
       name = '*' if name == :hash # in memory hash database
       name = '+' if name == :tree # in memory B+ tree database
 
+      name = name + params.collect { |k, v| "##{k}=#{v}" }.join('')
+
       (Rufus::Tokyo::Func.tcadbopen(@db, name) == 1) ||
         raise("failed to open/create db '#{name}'")
     end
 
+    #
+    # Returns a new in-memory hash. Accepts the same optional params hash
+    # as new().
+    #
+    def self.new_hash (params={})
+      self.new(:hash, params)
+    end
+
+    #
+    # Returns a new in-memory B+ tree. Accepts the same optional params hash
+    # as new().
+    #
+    def self.new_tree (params={})
+      self.new(:tree, params)
+    end
+
     def []= (k, v)
       Rufus::Tokyo::Func.tcadbput2(@db, k, v)
     end
@@ -139,10 +217,13 @@ def weight
     end
 
     #
-    # Closes the cabinet, returns true in case of success.
+    # Closes the cabinet (and frees the datastructure allocated for it),
+    # returns true in case of success.
     #
     def close
-      (Rufus::Tokyo::Func.tcadbclose(@db) == 1)
+      result = Rufus::Tokyo::Func.tcadbclose(@db)
+      Rufus::Tokyo::Func.tcadbdel(@db)
+      (result == 1)
     end
 
     #

test/test_0.rb → test/cabinet_0_test.rb

@@ -12,7 +12,7 @@
 require 'rufus/tokyo'
 
 
-class TestZero < Test::Unit::TestCase
+class CabinetZero < Test::Unit::TestCase
 
   #def setup
   #end

test/mem.rb

@@ -1,4 +1,12 @@
 
+%w{ lib test }.each do |path|
+  path = File.expand_path(File.dirname(__FILE__) + '/../' + path)
+  $: << path unless $:.include?(path)
+end
+
+require 'fileutils'
+
+
 def self_ps
   ps = `ps -v #{$$}`.split("\n").last.split(' ')
   %w{
@@ -8,5 +16,34 @@ def self_ps
   }
 end
 
-p self_ps
+def pmem (msg)
+  p [ msg, "#{self_ps[:vsz].to_i / 1024}k" ]
+end
+
+pmem 'starting'
+
+require 'rubygems'
+require 'rufus/tokyo'
+
+FileUtils.rm('test_mem.tch')
+
+db = Rufus::Tokyo::Cabinet.new('test_mem.tch')
+
+pmem 'wired to db'
+
+500_000.times { |i| db[i.to_s] = "value#{i}" }
+
+pmem 'loaded 500_000 records'
+
+db.each { |k, v| k }
+
+pmem 'iterated 500_000 records'
+
+a = db.collect { |k, v| k + v }
+
+pmem 'collected 500_000 records'
+
+db.close
+
+pmem 'closed db'
 

test/test.rb

@@ -1,5 +1,5 @@
 
 require File.dirname(__FILE__) + '/test_base'
 
-require 'test_0'
+require 'cabinet_0_test'