Merge of patch lp:~ahiguti100/maria/handlersocket-fix-78 by Akira Higuchi

A bugfix of HandlerSocket is not applied to mariadb yet

plugin/handler_socket/docs-ja/installation.ja.txt

@@ -8,7 +8,8 @@ HandlerSocketプラグインのビルド方法(RPMを使わない方法)
   $ ./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のソースコードのトップディレク
-トリを指定します。--with-mysql-bindirにはインストール済みのMySQL
+トリを指定します(そこにVERSIONファイルかconfigure.inファイルがなく
+てはなりません)。--with-mysql-bindirにはインストール済みのMySQL
 のmysql_configコマンドが有るディレクトリを指定します。
 その後以下のようにビルド・インストールします。
 

plugin/handler_socket/docs-ja/perl-client.ja.txt

@@ -86,7 +86,6 @@ 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呼び出しの
@@ -109,6 +108,15 @@ execute_multiメソッドを使えば、複数のリクエストを一つの呼
     # ...
   }
 
+-----------------------------------------------------------------
+もし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エラーが起こったことを示し、その場合はその

plugin/handler_socket/docs-ja/protocol.ja.txt

@@ -1,94 +1,180 @@
 
------------------------------------------------------------------
+----------------------------------------------------------------------------
 handlersocketの通信プロトコル
 
------------------------------------------------------------------
-構文
+----------------------------------------------------------------------------
+基本的な構文
 
-・コマンド行は改行(LF)で終わる。
-・コマンド行は複数のトークンからなり、トークン間はTABで区切られる。
+・HandlerSocketのプロトコルは行ベース。各行は改行文字(0x0a)で終わる。
+・各行は複数のトークンからなり、トークン間はTAB文字(0x09)で区切られる。
 ・トークンはNULLトークンか、文字列トークンのいずれか。
-・NULLトークンは単一のNUL文字であらわされる。
-・文字列トークンは、0バイト以上の文字列であらわされる。ただし0x10
-  未満の文字については0x01を前置し、0x40を加えたコードであらわさ
-  れる。それ以外の文字はその文字自身のコードであらわされる。
+・NULLトークンは単一のNUL文字(0x00)であらわされる。
+・文字列トークンは、0バイト以上の文字列であらわされる。ただし0x10未満の文字
+  については0x01を前置し、0x40を加えたコードであらわされる。それ以外の文字は
+  その文字自身のコードであらわされる。
 
------------------------------------------------------------------
+----------------------------------------------------------------------------
 リクエストとレスポンス
 
-・接続が確立した直後の状態では、まずクライアントがコマンド行を送
-  る。(リクエスト)
-・サーバはクライアントが送ったリクエストと丁度同じ数のコマンド行
-  を返す。(レスポンス)
-・リクエストはパイプライン化してよい。つまりクライアントは前に
-  送ったリクエストに対する返事を待たずに次のリクエストを送っても
-  よい。
+・HandlerSocketのプロトコルは単純なリクエスト・レスポンスプロトコルになって
+  いる。接続が確立した後は、まずクライアントがリクエストを送る。
+・サーバは、クライアントが送ったリクエストと丁度同じ数の行(レスポンス)を返
+  す。
+・リクエストはパイプライン化してよい。つまりクライアントは前に送ったリクエス
+  トに対する返事(レスポンス)を待たずに次のリクエストを送ってもよい。
 
------------------------------------------------------------------
-リクエスト
+----------------------------------------------------------------------------
+インデックスを開く
 
-・open_index命令は次のような構文を持つ。
-        'P' indexid dbname tablename indexname fieldlist
-  indexidは開いている索引に付けられる番号で、同一接続上で後に実行
-  する命令の、対象索引を指定するために使われる。dbname、tablename、
-  indexnameはそれぞれ開きたいDB、テーブル、索引の名前。索引の名前
-  として"PRIMARY"を指定するとプライマリキーが開かれる。fieldlist
-  はカンマ区切りの列名のリスト。
-・find命令は次のような構文を持つ。
-        indexid op nflds v1 ... vn limit offset
-  indexidは実行対象の索引を指定する。opは索引検索の演算子(後述)。
-  v1からvnは可変長で、その個数はnflds。nfldsはindexidで指定された
-  open_index命令のindexnameの索引のfieldlistのフィールド数に等し
-  いか小さくなくてはならない。m2からmkは可変長で、その個数は
-  indexidで指定されたopen_index命令が発行された際のfieldlistに一
-  致しなければならない。コマンド行のlimit以降は省略できる。limit
-  とoffsetは、検索条件に合致する列のうちレスポンスに返す列数の上
-  限と、スキップする列数。limitとoffsetを省略した場合はそれぞれ1
-  と0が指定されたときと同じ動作をする。find命令はレスポンスとして、
-  条件に合致した列のリストを返す。opとして指定できる演算子は次の
-  とおり。
-      '='       -  v1 ... vnと一致するものを取得
-      '>'       -  v1 ... vnより大きいものを昇順に取得
-      '>='      -  v1 ... vnに一致するか大きいものを昇順に取得
-      '<'       -  v1 ... vnより小さいものを降順に取得
-      '<='      -  v1 ... vnに一致するか等しいものを降順に取得
-  nfldsが1より大きい(v1 ... vnが2個以上)ときは辞書式順序で比較さ
-  れる。
-・find_modify命令は次のような構文を持つ。
-        indexid op nflds v1 ... vn limit offset modop m1 ... mk
-  modopより前の部分はfind命令と同等で、これによって操作対象の行を
-  指定する。その操作対象の行に対しmodopで指定された変更処理を実行
-  する。m1 ... mkは可変長で、省略できる。modopは次いずれか。
-      'U'       -  indexidで指定されたopen_index命令のfieldlist列
-                   の内容を、m1 ... mkの値で更新する。
-      'D'       -  対象の行を削除する。m1 ... mkの値は無視される。
-・insert命令はのような構文を持つ。
-        indexid '+' nflds v1 ... vn
-  indexidで指定されたテーブルに、列を挿入する。v1 ... vnは可変長
-  で、その個数はnflds。nfldsはindexidで指定されたopen_index命令の
-  indexnameの索引のfieldlistのフィールド数に等しいか小さくなくて
-  はならない。
+open_index命令は次のような構文を持つ。
 
------------------------------------------------------------------
-レスポンス
+    P <indexid> <dbname> <tablename> <indexname> <columns> [<fcolumns>]
 
-・open_index命令が成功したとき、レスポンスは次の構文を持つ。
-        '0' '1'
-・find命令が成功したとき、レスポンスは次の構文を持つ。
-        '0' nflds v1 ... vn
-  nfldsは結果セットの列の数をあらわす。v1 ... vnは可変長で、その
-  長さはnfldsの整数倍。v1 ... vnは空のこともあり、それは条件に合
-  致するレコードが存在しなかったことをあらわす。結果セットが複数
-  行になったときはv1 ... vnの長さがnfldsの2倍以上となり、最初の
-  行から順にv1 ... vnにセットされる。
-・modify命令が成功したとき、レスポンスは次の構文を持つ。
-        '0' '1' nummod
-  nummodは変更が施された行数。nummodが0のときは変更された行が無
-  かったことをあらわす。
-・insert命令が成功したとき、レスポンスは次の構文を持つ。
-        '0' '1'
-・命令が失敗したとき、レスポンスは命令に関わらず次の構文を持つ。
-        err '1' message
-  errは0以外の数値で、エラーコードをあらわす。messageは人間可読な
-  エラーメッセージ。ただしmessageが無いこともある。
+- <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