Class: Rufus::Tokyo::Cabinet

Included Modules

Rufus::Tokyo::HashMethods, Rufus::Tokyo::Transactions, Rufus::Tokyo::Outlen

A ‘cabinet’, ie a Tokyo Cabinet [abstract] 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

Constructor Summary

public initialize(name, params = {})

Creates/opens the cabinet, raises an exception in case of creation/opening failure.

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.

Note that there is an #open method similar to File#open for openening a db and closing it when it’s no longer needed :

  Rufus::Tokyo::Cabinet.new('data.tch') do |db|
    db['key'] = value
  end

database name

From http://tokyocabinet.sourceforge.net/spex-en.html#tcadbapi :

‘If it is "*", the database will be an on-memory hash database. If it is

 "<tt>", the database will be an on-memory tree database. If its suffix is
 ".tch", the database will be a hash database. If its suffix is ".tcb",
 the database will be a B</tt> tree database. If its suffix is ".tcf", the
 database will be a fixed-length database. If its suffix is ".tct", the
 database will be a table database.'

You’re supposed to give a path to the database file you want to use and Cabinet expects you to give the proper prefix.

  db = Rufus::Tokyo::Cabinet.new('data.tch') # hash database
  db = Rufus::Tokyo::Cabinet.new('data.tcb') # B+ tree db
  db = Rufus::Tokyo::Cabinet.new('data.tcf') # fixed-length db

will result with the same file names :

  db = Rufus::Tokyo::Cabinet.new('data', :type => :hash) # hash database
  db = Rufus::Tokyo::Cabinet.new('data', :type => :btree) # B+ tree db
  db = Rufus::Tokyo::Cabinet.new('data', :type => :fixed) # fixed-length db

You can open an in-memory hash and an in-memory B+ tree with :

  h = Rufus::Tokyo::Cabinet.new(:mem_hash) # or
  h = Rufus::Tokyo::Cabinet.new('*')

  t = Rufus::Tokyo::Cabinet.new(:mem_tree) # or
  t = Rufus::Tokyo::Cabinet.new('+')

parameters

There are two ways to pass parameters at the opening of a db :

  db = Rufus::Tokyo::Cabinet.new('data.tch#opts=ld#mode=w') # or
  db = Rufus::Tokyo::Cabinet.new('data.tch', :opts => 'ld', :mode => 'w')

most verbose :

  db = Rufus::Tokyo::Cabinet.new(
    'data', :type => :hash, :opts => 'ld', :mode => 'w')

mode

  * :mode    a set of chars ('r'ead, 'w'rite, 'c'reate, 't'runcate,
             'e' non locking, 'f' non blocking lock), default is 'wc'

other parameters

‘On-memory hash database supports "bnum", "capnum", and "capsiz".

 On-memory tree database supports "capnum" and "capsiz".
 Hash database supports "mode", "bnum", "apow", "fpow", "opts",
 "rcnum", and "xmsiz".
 B+ tree database supports "mode", "lmemb", "nmemb", "bnum", "apow",
 "fpow", "opts", "lcnum", "ncnum", and "xmsiz".
 Fixed-length database supports "mode", "width", and "limsiz"'

  * :opts    a set of chars ('l'arge, 'd'eflate, 'b'zip2, 't'cbs)
             (usually empty or something like 'ld' or 'lb')

  * :bnum    number of elements of the bucket array
  * :apow    size of record alignment by power of 2 (defaults to 4)
  * :fpow    maximum number of elements of the free block pool by
             power of 2 (defaults to 10)
  * :mutex   when set to true, makes sure only 1 thread at a time
             accesses the table (well, Ruby, global thread lock, ...)

  * :rcnum   specifies the maximum number of records to be cached.
             If it is not more than 0, the record cache is disabled.
             It is disabled by default.
  * :lcnum   specifies the maximum number of leaf nodes to be cached.
             If it is not more than 0, the default value is specified.
             The default value is 2048.
  * :ncnum   specifies the maximum number of non-leaf nodes to be
             cached. If it is not more than 0, the default value is
             specified. The default value is 512.

  * :xmsiz   specifies the size of the extra mapped memory. If it is
             not more than 0, the extra mapped memory is disabled.
             The default size is 67108864.

  * :capnum  specifies the capacity number of records.
  * :capsiz  specifies the capacity size of using memory.

  * :dfunit  unit step number. If it is not more than 0,
             the auto defragmentation is disabled. (Since TC 1.4.21)

NOTE :

On reopening a file, Cabinet will tend to stick to the parameters as set when the file was opened. To change that, have a look at the man pages of the various command line tools coming with Tokyo Cabinet.

new_hash(params = {})	Returns a new in-memory hash.
new_tree(params = {})	Returns a new in-memory B+ tree.
open(name, params = {})	Same args as initialize, but can take a block form that will close the db when done.

#[]=(k, v)	No comment.
#clear	Removes all the records in the cabinet (use with care).
#close	Closes the cabinet (and frees the datastructure allocated for it), returns true in case of success.
#compact_copy(target_path)	Copies the current cabinet to a new file.
#copy(target_path)	Copies the current cabinet to a new file.
#defrag	Triggers a defrag run (TC >= 1.
#delete(k)	Removes a record from the cabinet, returns the value if successful else nil.
#delete_keys_with_prefix(prefix)	Deletes all the entries whose keys begin with the given prefix.
#get4(k) #getdup	This is a B+ Tree method only, returns all the values for a given key.
#incr(key, inc = 1) #add_double #addint #adddouble #add_int	Increments the value stored under the given key with the given increment (defaults to 1 (integer)).
#keys(options = {})	Returns an array with all the keys in the databse.
#ldelete(keys)	Given a list of keys, deletes all the matching entries (in one sweep).
#lget(keys) #mget	Given a list of keys, returns a Hash { key => value } of the matching entries (in one sweep).
#lib	Using the cabinet lib.
#merge!(hash) #lput	Merges the given hash into this Cabinet (or Tyrant) and returns self.
#path	Returns the path to this database.
#putcat(k, v)	Appends the given string at the end of the current string value for key k.
#putdup(k, v)	--.
#putkeep(k, v)	Like #put but doesn’t overwrite the value if already set.
#size	Returns the number of records in the ‘cabinet’.
#sync	"synchronize updated contents of an abstract database object with the file and the device".
#tranabort	Warning : this method is low-level, you probably only need to use #transaction and a block.
#tranbegin	Warning : this method is low-level, you probably only need to use #transaction and a block.
#trancommit	Warning : this method is low-level, you probably only need to use #transaction and a block.
#weight	Returns the ‘weight’ of the db (in bytes).

Class: Rufus::Tokyo::Cabinet

Included Modules

Constructor Summary

database name

parameters

mode

other parameters

NOTE :

Public Visibility

Public Class Method Summary

Public Instance Method Summary

Public Instance Methods Included from Rufus::Tokyo::HashMethods

Public Instance Methods Included from Rufus::Tokyo::Transactions

Public Instance Methods Included from Rufus::Tokyo::Outlen

Public Class Method Details

new_hash

new_tree

open

Public Instance Method Details

[]=

clear

close

compact_copy

copy

defrag

Meta Tags

Raises:

delete

delete_keys_with_prefix

get4

incr

Meta Tags

Raises:

keys

ldelete

lget

lib

merge!

path

putcat

putdup

putkeep

size

sync

tranabort

tranbegin

trancommit

weight