vincentchu-handlersocket 0.0.1

data/ext/HandlerSocket-Plugin-for-MySQL/docs-ja/about-handlersocket.ja.txt

@@ -0,0 +1,51 @@
+
+
+-----------------------------------------------------------------
+ソースコードの利用にあたっての免責事項
+
+本ソフトウェアの開発者および株式会社ディー・エヌ・エーは、本フト
+ウェアの不稼動、稼動不良を含む法律上の瑕疵担保責任、その他保証責
+任を負わないものとします。また、本ソフトウエアの開発者および株式
+会社ディー・エヌ・エーは、本ソフトウェアの商品性、またはお客様の
+特定の目的に対する適合性について、いかなる保証も負わないものとし
+ます。
+
+-----------------------------------------------------------------
+handlersocket pluginについて
+
+mysqlサーバに常駐し、innodb等のストレージエンジンへの直接のアクセ
+スを提供するプラグインです。handlersocketプラグインは自前のリス
+ナーを持ち、専用のクライアントライブラリ(libhsclient)を使ってそれ
+にアクセスします。
+
+mysqlの標準クライアントライブラリ(libmysql)を使ったアクセスと比べ
+て、以下のような利点があります。
+・接続あたりに消費するリソースが少ないため、同時接続数が事実上無
+  制限。したがって接続数を気にせず持続接続を使えます。
+・高速(単純な参照クエリで3倍〜10倍程度)。
+・通信プロトコルがコンパクト。libmysqlを使うとデータ転送時にレ
+  コード名などが付随するために通信内容が冗長ですが、libhsclientで
+  はデータのみが転送されるため、帯域消費が少なくなります。場合に
+  よっては10倍以上libmysqlのほうが冗長になります。
+
+現在のバージョンでは以下のような処理をサポートしています。
+・指定された索引について、指定された値と完全一致するようなレコー
+  ドを取得。(SELECT ??? FROM tbl WHERE k1 = v1 AND k2 = v2...)。
+  索引を使わない検索はサポートしていません。
+・指定された索引について、指定された値の位置の前後のレコードを取
+  得。(SELECT ??? FROM tbl WHERE k1 >= v1 LIMIT 100)
+・前述のような手段で取得したレコードに対するUPDATEとDELETE
+・レコードのINSERT
+
+以下のような言語をサポートします。
+・C++。libhsclientをリンクします。
+・Perl。Net::HandlerSocketをuseします。
+
+現在のバージョンではGNU/Linuxでのみ動作します。
+
+-----------------------------------------------------------------
+既知の問題
+
+・killでhandlersocketスレッドを殺すと、スレッド数が減ったまま回復
+  しません。
+

data/ext/HandlerSocket-Plugin-for-MySQL/docs-ja/installation.ja.txt

@@ -0,0 +1,88 @@
+
+-----------------------------------------------------------------
+HandlerSocketプラグインのビルド方法(RPMを使わない方法)
+
+以下のようにしてconfigureを実行します。
+
+  $ ./autogen.sh
+  $ ./configure --with-mysql-source=/work/mysql-5.1.50 --with-mysql-bindir=/work/mysql-5.1.50-linux-x86_64-glibc23/bin  --with-mysql-plugindir=/work/mysql-5.1.50-linux-x86_64-glibc23/lib/plugin
+
+ここで--with-mysql-sourceにはMySQLのソースコードのトップディレク
+トリを指定します(そこにVERSIONファイルかconfigure.inファイルがなく
+てはなりません)。--with-mysql-bindirにはインストール済みのMySQL
+のmysql_configコマンドが有るディレクトリを指定します。
+その後以下のようにビルド・インストールします。
+
+  $ make
+  $ sudo make install
+
+-----------------------------------------------------------------
+クライアントライブラリのビルド方法(RPMを使わない方法)
+
+クライアントライブラリをビルドする際には、MySQLのソースコードは
+必要ありません。またMySQLがインストールされている必要もありません。
+
+  $ ./autogen.sh
+  $ ./configure --disable-handlersocket-server
+  $ make
+  $ sudo make install
+  $ cd perl-Net-HandlerSocket
+  $ perl Makefile.PL
+  $ make
+  $ sudo make install
+
+-----------------------------------------------------------------
+ビルド方法(RPM)
+
+以下のように実行すれば、rpmパッケージがビルド＆インストールされま
+す。
+
+(MySQLサーバ側、HandlerSocketプラグインをインストールする)
+  $ ./autogen.sh
+  $ ./configure --with-mysql-source=/work/mysql-5.1.50 --with-mysql-bindir=/work/mysql-5.1.50-linux-x86_64-glibc23/bin  --with-mysql-plugindir=/work/mysql-5.1.50-linux-x86_64-glibc23/lib/plugin
+  $ make rpm_cli
+  $ sudo rpm -U dist/RPMS/*/libhsclient*.rpm
+  $ make rpm_c
+  $ sudo rpm -U dist/RPMS/*/handlersocket*.rpm
+
+(クライアント側、クライアントライブラリをインストールする)
+  $ ./autogen.sh
+  $ ./configure --disable-handlersocket-server
+  $ make rpm_cli
+  $ sudo rpm -U dist/RPMS/*/libhsclient*.rpm
+  $ make rpm_perl
+  $ sudo rpm -U dist/RPMS/*/perl-Net-HandlerSocket*.rpm
+
+-----------------------------------------------------------------
+起動
+
+mysqlを起動した状態で、mysqlの設定ファイル(my.cnf等)に以下の内容を
+追加します。
+
+  [mysqld]
+  handlersocket_port = 9998
+      # handlersocketが接続を受け付けるポート(参照系リクエスト用)
+  handlersocket_port_wr = 9999
+      # handlersocketが接続を受け付けるポート(更新系リクエスト用)
+  handlersocket_address =
+      # handlersocketがバインドするアドレス(空のままでOK)
+  handlersocket_verbose = 0
+      # デバッグ用
+  handlersocket_timeout = 300
+      # 通信タイムアウト(秒)
+  handlersocket_threads = 16
+      # handlersocketのワーカースレッド数
+  thread_concurrency = 128
+      # handlersocketが幾つかのスレッドを占有するため、大きめの
+      # 値を指定してください
+  open_files_limit = 65535
+      # ソケットを大量に開けるようにするため、大きめの値を指定し
+      # てください
+
+以下のクエリを実行します。
+
+  mysql> install plugin handlersocket soname 'handlersocket.so';
+  Query OK, 0 rows affected (0.06 sec)
+
+以上でhandlersocketへクライアントからアクセスできるようになります。
+

data/ext/HandlerSocket-Plugin-for-MySQL/docs-ja/perl-client.ja.txt

@@ -0,0 +1,127 @@
+
+-----------------------------------------------------------------
+handlersocketプラグインへの接続を開くには、Net::HandlerSocketオブ
+ジェクトを作成します。
+
+  use Net::HandlerSocket;
+  my $args = { host => 'localhost', port => 9998 };
+  my $hs = new Net::HandlerSocket($args);
+
+-----------------------------------------------------------------
+検索などの命令を実行する前に、処理対象となる索引を開く必要があり
+ます。
+
+  my $err = $hs->open_index(3, 'database1', 'table1', 'PRIMARY',
+    'f1,f2');
+  die $hs->get_error() if $res->[0] != 0;
+
+最初の引数は開く索引に付ける番号です。付けた番号は同一の
+Net::HandlerSocketオブジェクトについてのみ有効です。第4引数は開く
+索引の名前で、「PRIMARY」が指定され場合はプライマリキーが開かれま
+す。第5引数は「,」で区切られた列名のリストです。
+
+-----------------------------------------------------------------
+テーブルから索引を使って行を取得するには、execute_singleメソッド
+を呼びます。
+
+  my $res = $hs->execute_single(3, '=', [ 'foo' ], 1, 0);
+  die $hs->get_error() if $res->[0] != 0;
+  shift(@$res);
+
+最初の引数は索引の番号で、同じNet::HandlerSocketオブジェクトへ
+open_indexで付けたものでなければなりません。第2引数には操作を指定
+します。現在のバージョンでは、「=」、「>=」、「<=」、「>」、「<」
+の操作が利用可能です。第3引数は配列への参照で、これは探すべき行の
+キー値を指定します。配列の長さは索引のキーの個数と同じか少ない数
+でなければなりません。第4引数と第5引数はそれぞれ、取得する最大行
+数、取得前に読み飛ばす行数を指定します。取得される列は対応する
+open_index呼び出しの第5引数で指定されたものになります。
+
+execute_singleメソッドは常に配列への参照を返します。最初の要素は
+エラーコードで、これが0ならば成功を表します。残りの要素は列の値で
+す。もし取得されたデータが複数行の場合は、それが一つの配列へ連結
+された形で格納されています。例えば、5行3列のデータの場合、次のよ
+うなコードによってその内容を取得できます。
+
+  die $hs->get_error() if $res->[0] != 0;
+  shift(@$res);
+  for (my $row = 0; $row < 5; ++$row) {
+    for (my $col = 0; $col < 3; ++$col) {
+      my $value = $res->[$row * 5 + $col];
+      # ...
+    }
+  }
+
+-----------------------------------------------------------------
+行を更新または削除するには、更に多くの引数を指定して
+execute_singleメソッドを呼び出します。書き込み処理をするには、
+対象のNet::HandlerSocketオブジェクトは更新用handlersocketワーカ(既
+定ではポート9999)へ接続されたものでなくてはなりません。
+(安全のため、ポート9998は参照処理だけを受け付け、ポート9999は更新
+処理も受け付けるようになっています。ポート9999は参照処理も受け付
+けますが、レコードロック等の影響で遅くなります。ポート番号は
+mysqldの「handlersocket_port」と「handlersocket_port_wr」の設定項
+目で変更できます。)
+
+  my $args = { host => 'localhost', port => 9999 };
+  my $hs = new Net::HandlerSocket($args);
+
+  my $res = $hs->execute_single(3, '=', [ 'bar' ], 1, 0, 'U',
+    [ 'fubar', 'hoge' ]);
+  die $hs->get_error() if $res->[0] != 0;
+  my $num_updated_rows = $res->[1];
+
+  my $res = $hs->execute_single(3, '=', [ 'baz' ], 1, 0, 'D');
+  die $hs->get_error() if $res->[0] != 0;
+  my $num_deleted_rows = $res->[1];
+
+execute_singleの第6引数は変更処理の種類を指定します。現在のバー
+ジョンでは「U」と「D」が利用可能です。「U」については、第7引数で
+新しい値を指定します。更新される列は、対応するopen_index呼び出し
+の第5引数で指定されたものになります。「D」については第7引数は省
+略できます。
+
+-----------------------------------------------------------------
+execute_singleメソッドは列の挿入にも使用できます。
+
+  my $res = $hs->execute_single(3, '+', [ 'foo', 'bar', 'baz' ]);
+  die $hs->get_error() if $res->[0] != 0;
+  my $num_inserted_rows = $res->[1];
+
+第3引数は、対応するopen_index呼び出しの第5引数の列リストと同じだ
+けの長さの配列への参照でなければなりません。open_index呼び出しの
+第5引数に指定されていない列については、その列の既定値がセットされ
+ます。
+
+-----------------------------------------------------------------
+execute_multiメソッドを使えば、複数のリクエストを一つの呼び出しで
+実行することができます。これはリクエストを個別に実行するより高速
+です。
+
+  my $rarr = $hs->execute_multi([
+    [ 0, '>=', [ 'foo' ], 5, 0 ],
+    [ 2, '=', [ 'bar' ], 1, 0 ],
+    [ 4, '<', [ 'baz' ], 10, 5 ],
+  ]);
+  for my $res (@$rarr) {
+    die $hs->get_error() if $res->[0] != 0;
+    shift(@$res);
+    # ...
+  }
+
+-----------------------------------------------------------------
+もしhandlersocketが接続を認証するように設定されている
+(handlersocket_plain_secret又はhandlersocket_plain_secret_wrがセッ
+トされている)ならば、クライアントは他のメソッド呼び出しの前にauth
+メソッドを呼び出す必要があります。
+
+  my $res = $hs->auth('password');
+  die $hs->get_error() if $res->[0] != 0;
+
+-----------------------------------------------------------------
+エラーが起こると返値の配列参照の最初の要素が0以外になります。負の
+数の場合はI/Oエラーが起こったことを示し、その場合はその
+Net::HandlerSocketオブジェクトは破棄するべきです。正の値の場合は
+接続は維持されているため、そのオブジェクトはそれ以後も再利用でき
+ます。
+

data/ext/HandlerSocket-Plugin-for-MySQL/docs-ja/protocol.ja.txt

@@ -0,0 +1,180 @@
+
+----------------------------------------------------------------------------
+handlersocketの通信プロトコル
+
+----------------------------------------------------------------------------
+基本的な構文
+
+・HandlerSocketのプロトコルは行ベース。各行は改行文字(0x0a)で終わる。
+・各行は複数のトークンからなり、トークン間はTAB文字(0x09)で区切られる。
+・トークンはNULLトークンか、文字列トークンのいずれか。
+・NULLトークンは単一のNUL文字(0x00)であらわされる。
+・文字列トークンは、0バイト以上の文字列であらわされる。ただし0x10未満の文字
+  については0x01を前置し、0x40を加えたコードであらわされる。それ以外の文字は
+  その文字自身のコードであらわされる。
+
+----------------------------------------------------------------------------
+リクエストとレスポンス
+
+・HandlerSocketのプロトコルは単純なリクエスト・レスポンスプロトコルになって
+  いる。接続が確立した後は、まずクライアントがリクエストを送る。
+・サーバは、クライアントが送ったリクエストと丁度同じ数の行(レスポンス)を返
+  す。
+・リクエストはパイプライン化してよい。つまりクライアントは前に送ったリクエス
+  トに対する返事(レスポンス)を待たずに次のリクエストを送ってもよい。
+
+----------------------------------------------------------------------------
+インデックスを開く
+
+open_index命令は次のような構文を持つ。
+
+    P <indexid> <dbname> <tablename> <indexname> <columns> [<fcolumns>]
+
+- <indexid>は数字で、同一接続上で後に実行する命令の、対象索引を指定するため
+  に使われる。
+- <dbname>, <tablename>, <indexname>は文字列で、それぞれDB名、テーブル名、
+  索引の名前を指定する。<indexname>として「PRIMARY」を指定するとプライマリ
+  キーが開かれる。
+- <columns>はカンマ区切りの列名のリスト。
+- <fcolumns>はカンマ区切りの列名のリスト。これは省略することができる。
+
+このopen_index命令が実行されると、HandlerSocketプラグインは指定されたDB、
+テーブル、索引を開く。開かれた索引は接続が閉じられるまで開かれたままになる。
+開かれた索引は<indexid>の数字で識別される。もし既に<indexid>に指定された番号
+の索引が既に開かれている場合は古いほうが閉じられる。この<indexid>はなるべく
+小さな数字を使ったほうが効率が良い。
+
+----------------------------------------------------------------------------
+データ取得
+
+find命令は次のような構文を持つ。
+
+    <indexid> <op> <vlen> <v1> ... <vn> [LIM] [IN] [FILTER ...]
+
+LIMは次のようなパラメータの並び
+
+    <limit> <offset>
+
+INは次のようなパラメータの並び
+
+    @ <icol> <ivlen> <iv1> ... <ivn>
+
+FILTERは次のようなパラメータの並び
+
+    <ftyp> <fop> <fcol> <fval>
+
+- <indexid>は数字で、これは同じ接続上で過去に実行したopen_index命令に指定さ
+  れた数字でなければならない。
+- <op>は比較演算子で、現在のバージョンでは '=', '>', '>=', '<', '<=' をサ
+  ポートしている。
+- <vlen>は後に続くパラメータ<v1> ... <vn>の長さ。この値は対応するopen_index
+  命令の<indexname>パラメータで指定された索引のキー列の数と同じか小さいもの
+  でなければならない。
+- <v1> ... <vn>は取得するべきキーの値を指定するパラメータ。
+- LIMは省略できる。<limit>と<offset>は数字で、これはSQLのLIMITと同じように
+  はたらく。省略した場合は1と0を指定した場合と同じ動作をする。FILTERによっ
+  て読み飛ばされたレコードは<limit>と<offset>にカウントされない。
+- INは省略できる。指定されると、これはSQLの WHERE ... IN のように動作する。
+  <icol>は対応するopen_index命令の<indexname>パラメータで指定された索引の
+  キー列の数より小さいものでなければならない。INが指定されたときは、find命
+  令の<v1> ... <vn>のうち<icol>番目の値は無視される。
+- FILTERは省略できる。これは行取得の際のフィルタを指定する。<ftyp>は
+  'F'(filter)か'W'(while)のいずれかでなければならない。<fop>は比較演算子。
+  <fcol>は数字で、これは対応するopen_index命令の<fcolumns>で指定された列の
+  数より小さいものでなければならない。複数のフィルタを指定することもでき、
+  その場合は各フィルタのANDと解釈される。'F'と'W'の違いは、条件にあてはま
+  らない行があったときに'F'は単にそれをスキップするが、'W'はその時点でルー
+  プを抜けるという点。
+
+----------------------------------------------------------------------------
+更新と削除
+
+find_modify命令は次のような構文を持つ。
+
+    <indexid> <op> <vlen> <v1> ... <vn> [LIM] [IN] [FILTER ...] MOD
+
+MODは次のようなパラメータの並び
+
+    <mop> <m1> ... <mk>
+
+- <mop>は'U', '+', '-', 'D', 'U?', '+?', '-?', 'D?'のいずれか。'?'が付いた
+  ものは付いていないものとほぼ同じ動作をするが、付いていないものがレスポン
+  スとして更新された行の数を返すのに対し、付いているものは更新される前の行
+  の内容を返す点のみが異なる。'U'は更新、'D'は削除、'+'はインクリメント、
+  '-'はデクリメントを実行する。
+- <m1> ... <mk>はセットされる各列の値。<m1> ... <mk>の長さは対応する
+  open_index命令の<columns>の長さと等しいか小さくなければならない。<mop>が
+  'D'のときはこれらのパラメータは無視される。<mop>が'+'か'-'のときは、これら
+  の値は数値でなければならない。<mop>が'-'で、それが負数から正数、または正数
+  から負数へ列の値を変更するようなものであった場合は、値は変更されない。
+
+----------------------------------------------------------------------------
+行の挿入
+
+insert命令は次のような構文を持つ。
+
+    <indexid> + <vlen> <v1> ... <vn>
+
+- <vlen>は後に続くパラメータ<v1> ... <vn>の長さ。これは対応するopen_indexの
+  <columns>の長さに等しいか小さくなければならない。
+- <v1> ... <vn>はセットされる各列の値。指定されないかった列についてはその列
+  のデフォルト値がセットされる。
+
+----------------------------------------------------------------------------
+認証
+
+auth命令は次のような構文を持つ。
+
+    A <atyp> <akey>
+
+- <atyp>は現在のバージョンでは'1'のみが有効。
+- 指定された<akey>が、サーバの設定の'handlersocket_plain_secret'や
+  'handlersocket_plain_secret_wr'に指定された文字列と一致した場合にのみ認証
+  は成功する。
+- HandlerSocketの認証が有効になっているときは、この'auth'が成功しない限りそ
+  れ以外の命令は全て失敗する。
+
+----------------------------------------------------------------------------
+open_indexに対するレスポンス
+
+open_index命令が成功したとき、レスポンスは次の構文を持つ。
+
+    0 1
+
+----------------------------------------------------------------------------
+findに対するレスポンス
+
+find命令が成功したとき、レスポンスは次の構文を持つ。
+
+    0 <numcolumns> <r1> ... <rn>
+
+- <numcolumns>はfind命令の対応するopen_index命令に指定した<columns>の長さに
+  一致する。
+- <r1> ... <rn>は結果セット。もしN行がfind命令で見つかったなら、<r1> ...
+  <rn>の長さは ( <numcolumns> * N )になる。
+
+----------------------------------------------------------------------------
+find_modifyに対するレスポンス
+
+find_modify命令が成功したとき、レスポンスは次の構文を持つ。
+
+    0 1 <nummod>
+
+- <nummod>は変更された行の数。
+- 例外として、<mop>が'?'の付いたものであった場合には、find命令に対するレスポ
+  ンスと同じ構文のレスポンスを返す。
+
+----------------------------------------------------------------------------
+insertに対するレスポンス
+
+insert命令が成功したとき、レスポンスは次の構文を持つ。
+
+    0 1
+
+----------------------------------------------------------------------------
+authに対するレスポンス
+
+auth命令が成功したとき、レスポンスは次の構文を持つ。
+
+    0 1
+

data/ext/HandlerSocket-Plugin-for-MySQL/handlersocket/COPYRIGHT.txt

@@ -0,0 +1,27 @@
+
+ Copyright (c) 2010 DeNA Co.,Ltd.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+
+     * Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+     * Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+     * Neither the name of DeNA Co.,Ltd. nor the names of its contributors
+       may be used to endorse or promote products derived from this software
+       without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY DeNA Co.,Ltd. "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+ EVENT SHALL DeNA Co.,Ltd. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+ OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+ OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+