File: tokyotyrant.rb

# tokyotyrant.rb

Path: | tokyotyrant.rb
Last Update: | Wed Nov 04 15:33:48 +0900 2009

# Pure Ruby Interface of Tokyo Tyrant

Tokyo Tyrant: network interface of Tokyo Cabinet

## INTRODUCTION

This module implements the pure Ruby client which connects to the server of Tokyo Tyrant and speaks its original binary protocol.

Tokyo Tyrant is a package of network interface to the DBM called Tokyo Cabinet. Though the DBM has high performance, you might bother in case that multiple processes share the same database, or remote processes access the database. Thus, Tokyo Tyrant is provided for concurrent and remote connections to Tokyo Cabinet. It is composed of the server process managing a database and its access library for client applications.

The server features high concurrency due to thread-pool modeled implementation and the epoll/kqueue mechanism of the modern Linux/*BSD kernel. The server and its clients communicate with each other by simple binary protocol on TCP/IP. Protocols compatible with memcached and HTTP/1.1 are also supported so that almost all principal platforms and programming languages can use Tokyo Tyrant. High availability and high integrity are also featured due to such mechanisms as hot backup, update logging, and replication. The server can embed Lua, a lightweight script language so that you can define arbitrary operations of the database.

Because the server uses the abstract API of Tokyo Cabinet, all of the six APIs: the on-memory hash database API, the on-memory tree database API, the hash API, the B+ tree database API, the fixed-length database API, and the table database API, are available from the client with the common interface. Moreover, the table extension is provided to use specifidc features of the table database.

### Setting

Get this package and extract it.

Enter the directory of the extracted package then perform installation.

     su
     ruby install.rb

The package `tokyotyrant' should be loaded in each source file of application programs.

     require 'tokyotyrant'

All symbols of Tokyo Tyrant are defined in the module `TokyoTyrant'. You can access them without any prefix by including the module.

     include TokyoTyrant

# EXAMPLE

The following code is an example to use a remote database.

     require 'tokyotyrant'
     include TokyoTyrant

     # create the object
     rdb = RDB::new

     # connect to the server
     if !rdb.open("localhost", 1978)
       ecode = rdb.ecode
       STDERR.printf("open error: %s\n", rdb.errmsg(ecode))
     end

     # store records
     if !rdb.put("foo", "hop") ||
         !rdb.put("bar", "step") ||
         !rdb.put("baz", "jump")
       ecode = rdb.ecode
       STDERR.printf("put error: %s\n", rdb.errmsg(ecode))
     end

     # retrieve records
     value = rdb.get("foo")
     if value
         printf("%s\n", value)
     else
       ecode = rdb.ecode
       STDERR.printf("get error: %s\n", rdb.errmsg(ecode))
     end

     # traverse records
     rdb.iterinit
     while key = rdb.iternext
       value = rdb.get(key)
       if value
         printf("%s:%s\n", key, value)
       end
     end

     # hash-like usage
     rdb["quux"] = "touchdown"
     printf("%s\n", rdb["quux"])
     rdb.each do |key, value|
       printf("%s:%s\n", key, value)
     end

     # close the connection
     if !rdb.close
       ecode = rdb.ecode
       STDERR.printf("close error: %s\n", rdb.errmsg(ecode))
     end

The following code is an example to use a remote database with the table extension.

     require 'tokyotyrant'
     include TokyoTyrant

     # create the object
     rdb = RDBTBL::new

     # connect to the server
     if !rdb.open("localhost", 1978)
       ecode = rdb.ecode
       STDERR.printf("open error: %s\n", rdb.errmsg(ecode))
     end

     # store a record
     pkey = rdb.genuid
     cols = { "name" => "mikio", "age" => "30", "lang" => "ja,en,c" }
     if !rdb.put(pkey, cols)
       ecode = rdb.ecode
       STDERR.printf("put error: %s\n", rdb.errmsg(ecode))
     end

     # store another record
     cols = { "name" => "falcon", "age" => "31", "lang" => "ja", "skill" => "cook,blog" }
     if !rdb.put("x12345", cols)
       ecode = rdb.ecode
       STDERR.printf("put error: %s\n", rdb.errmsg(ecode))
     end

     # search for records
     qry = RDBQRY::new(rdb)
     qry.addcond("age", RDBQRY::QCNUMGE, "20")
     qry.addcond("lang", RDBQRY::QCSTROR, "ja,en")
     qry.setorder("name", RDBQRY::QOSTRASC)
     qry.setlimit(10)
     res = qry.search
     res.each do |rkey|
       rcols = rdb.get(rkey)
       printf("name:%s\n", rcols["name"])
     end

     # close the connection
     if !rdb.close
       ecode = rdb.ecode
       STDERR.printf("close error: %s\n", rdb.errmsg(ecode))
     end

## LICENSE

     Copyright (C) 2006-2008 Mikio Hirabayashi
     All rights reserved.

Tokyo Tyrant is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License or any later version. Tokyo Tyrant is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with Tokyo Tyrant; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

### Required files

socket