Tokyo Cabinet第1版仕様書

Copyright (C) 2006-2007 Mikio Hirabayashi
Last Update: Mon, 16 Jul 2007 19:45:16 +0900

目次

  1. はじめに
  2. インストール
  3. ハッシュデータベースAPI
  4. ユーティリティAPI
  5. データベースフォーマット
  6. ライセンス

はじめに

Tokyo Cabinetはデータベースを扱うルーチン群のライブラリです。データベースといっても単純なもので、キーと値のペアからなるレコード群を格納したデータファイルです。キーと値は任意の長さを持つ一連のバイト列であり、文字列でもバイナリでも扱うことができます。テーブルやデータ型の概念はありません。レコードはハッシュ表で編成されます。

ハッシュ表のデータベースでは、キーはデータベース内で一意であり、キーが重複する複数のレコードを格納することはできません。このデータベースに対しては、キーと値を指定してレコードを格納したり、キーを指定して対応するレコードを削除したり、キーを指定して対応するレコードを検索したりすることができます。また、データベースに格納してある全てのキーを順不同に一つずつ取り出すこともできます。このような操作は、UNIX標準で定義されている DBMライブラリおよびその追従であるNDBMやGDBMに類するものです。Tokyo CabinetはDBMのより良い代替として利用することができます。


インストール

Tokyo Cabinetのソースパッケージからのインストール方法を説明します。バイナリパッケージのインストール方法についてはそれぞれのパッケージの説明書をご覧ください。

前提

Tokyo Cabinetの現在バージョンは、UNIX系のOSで利用することができます。少なくとも、以下の環境では動作するはずです。

ソースパッケージを用いてTokyo Cabinetをインストールするには、gccのバージョン3.1以降とmakeが必要です。それらはLinuxやFreeBSDには標準的にインストールされています。

Tokyo Cabinetは、以下のライブラリを利用しています。予めそれらをインストールしておいてください。

ビルドとインストール

Tokyo Cabinetの配布用アーカイブファイルを展開したら、生成されたディレクトリに入ってインストール作業を行います。

configureスクリプトを実行して、ビルド環境を設定します。

./configure

プログラムをビルドします。

make

プログラムの自己診断テストを行います。

make check

プログラムをインストールします。作業はrootユーザで行います。

make install

結果

一連の作業が終ると、以下のファイルがインストールされます。

/usr/local/include/tcutil.h
/usr/local/include/tchdb.h
/usr/local/lib/libtokyocabinet.a
/usr/local/lib/libtokyocabinet.so.1.6.0
/usr/local/lib/libtokyocabinet.so.1
/usr/local/lib/libtokyocabinet.so
/usr/local/share/tokyocabinet/...
/usr/local/man/man1/...
/usr/local/man/man3/...

configureのオプション

「./configure」を実行する際には、以下のオプションを指定することができます。


ハッシュデータベースAPI

とりあえずヘッダ(tchdb.h)読んでね。


ユーティリティAPI

とりあえずヘッダ(tcutil.h)読んでね。


データベースフォーマット

この節ではデータベースファイルのフォーマットに関する仕様を示す。

ハッシュデータベースのファイルフォーマット

ハッシュデータベースが管理するデータベースファイルの内容は、ヘッダ部、バケット部、フリーブロックプール部、レコード部の4つに大別される。ファイルに記録される数値は固定長数値もしくは可変長数値として記録される。前者は数値を特定の領域にリトルエンディアンで直列化したものである。後者は数値を可変長の領域に128進法のデルタ符号で直列化したものである。

ヘッダ部はファイルの先頭から128バイトの固定長でとられ、以下の情報が記録される。

名前 オフセット データ長 機能
マジックナンバ 0 32 データベースファイルであることの判別。「ToKyO CaBiNeT」で始まる
データベースタイプ 32 1 ハッシュ表(1)かB+木(2)
追加フラグ 33 1 開きっぱなし(1<<0)、致命的エラー(1<<1)の論理和
アラインメント力 34 1 アラインメントに対する2の冪乗
フリーブロックプール力 34 1 フリーブロックプールの要素数に対する2の冪乗
オプション 36 1 ラージモード(1<<0)、圧縮モード(1<<1)の論理和
バケット数 40 8 バケット配列の要素数
レコード数 48 8 格納しているレコードの数
ファイルサイズ 56 8 データベースファイルのサイズ
先頭レコード 64 8 最初のレコードのオフセット
不透明領域 80 48 ユーザが自由に使える領域

バケット部はヘッダ部の直後にバケット配列の要素数に応じた大きさでとられ、ハッシュチェーンの先頭要素のオフセットが各要素に記録される。各要素は固定長数値であり、そのサイズはノーマルモードでは4バイト、ラージモードでは8バイトである。また、オフセットはアラインメントで割った商として記録される。

フリーブロックプール部はバケット部の直後にフリーブロックプールの要素数に応じた大きさでとられ、未使用領域のオフセットと長さが各要素に記録される。オフセットはアラインメントで割った商に変換した上で、直前の要素の値との差分として記録される。オフセットとサイズは可変長数値として扱われる。

レコード部はバケット部の直後からファイルの末尾までを占め、各レコードの以下の情報を持つ要素が記録される。各レコードの領域は常にアラインメントされた位置から始まる。

名前 オフセット データ長 機能
マジックナンバ 0 1 データの識別と整合性確認に用いる。0xA1固定
ハッシュ値 1 1 チェーンの進路決定に用いるハッシュ値
左チェーン 2 4 左チェーン接続先のオフセットのアラインメント商
右チェーン 6 4 右チェーン接続先のオフセットのアラインメント商
パディングサイズ 10 2 パディングのサイズ
キーサイズ 12 可変 キーのサイズ
値サイズ 可変 可変 値のサイズ
キー 可変 可変 キーのデータ
可変 可変 値のデータ
パディング 可変 可変 パディング

ただし、フリーブロックとなった領域には、各レコードの以下の情報を持つ要素が記録される。

名前 オフセット データ長 機能
マジックナンバ 0 1 データの識別と整合性確認に用いる。0xA2固定
ブロックサイズ 1 4 ブロックのサイズ

あと細かいことがいろいろあるけど、割愛。


ライセンス

Tokyo Cabinetはフリーソフトウェアです。あなたは、Free Software Foundationが公表したGNU Lesser General Public Licenseのバージョン2.1あるいはそれ以降の各バージョンの中からいずれかを選択し、そのバージョンが定める条項に従ってTokyo Cabinetを再頒布または変更することができます。

Tokyo Cabinetは有用であると思われますが、頒布にあたっては、市場性及び特定目的適合性についての暗黙の保証を含めて、いかなる保証も行ないません。詳細についてはGNU Lesser General Public Licenseを読んでください。

あなたは、Tokyo Cabinetと一緒にGNU Lesser General Public Licenseの写しを受け取っているはずです(`COPYING' ファイルを参照してください)。そうでない場合は、Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA へ連絡してください。