Adding upstream version 1:10.11.6.upstream/1%10.11.6upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 134 insertions, 0 deletions

diff --git a/plugin/handler_socket/docs-en/perl-client.en.txt b/plugin/handler_socket/docs-en/perl-client.en.txt
new file mode 100644
index 00000000..cc913851
--- /dev/null
+++ b/plugin/handler_socket/docs-en/perl-client.en.txt
@@ -0,0 +1,134 @@
+
+-----------------------------------------------------------------
+To open a connection to the handlersocket plugin, you need to
+create a Net::HandlerSocket object.
+
+  use Net::HandlerSocket;
+  my $args = { host => 'localhost', port => 9998 };
+  my $hs = new Net::HandlerSocket($args);
+
+-----------------------------------------------------------------
+Before executing table operations, you need to open an index to
+work with.
+
+  my $err = $hs->open_index(3, 'database1', 'table1', 'PRIMARY',
+    'f1,f2');
+  die $hs->get_error() if $res->[0] != 0;
+
+The first argument for open_index is an integer value which is
+used to identify an open table, which is only valid within the
+same Net::HandlerSocket object. The 4th argument is the name of
+index to open. If 'PRIMARY' is specified, the primary index is
+open. The 5th argument is a comma-separated list of column names.
+
+-----------------------------------------------------------------
+To read a record from a table using an index, call the
+execute_single method.
+
+  my $res = $hs->execute_single(3, '=', [ 'foo' ], 1, 0);
+  die $hs->get_error() if $res->[0] != 0;
+  shift(@$res);
+
+The first argument must be an integer which has specified as the
+first argument for open_index on the same Net::HandlerSocket
+object. The second argument specifies the search operation. The
+current version of handlersocket supports '=', '>=', '<=', '>',
+and '<'. The 3rd argument specifies the key to find, which must
+an arrayref whose length is equal to or smaller than the number
+of key columns of the index. The 4th and the 5th arguments
+specify the maximum number of records to be retrieved, and the
+number of records skipped before retrieving records. The columns
+to be retrieved are specified by the 5th argument for the
+corresponding open_index call.
+
+The execute_single method always returns an arrayref. The first
+element is the error code, which is 0 when no error is occurred.
+The remaining are the field values. If more than one record is
+returned, it is flatten to an 1-dimensional array. For example,
+when 5 records that have 3 columns are returned, you can retrieve
+values using the following code.
+
+  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];
+      # ...
+    }
+  }
+
+-----------------------------------------------------------------
+To update or delete records, you need to specify more arguments
+for the execute_single method. Note that the Net::HandlerSocket
+object must be connected to a handlersocket worker for write
+operations, which is port 9999 by default.
+(For safety, the port 9998 only allows read operations, and the
+port 9999 allows write operations also. The port 9999 allows
+read operations too, but slower than 9998 because of record
+locking etc.. Port numbers can be changed using the
+'handlersocket_port' and the 'handlersocket_port_wr'
+configuration options of mysqld.)
+
+  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];
+
+The 6th argument for execute_single specifies the modification
+operation. The current version supports 'U' and 'D'. For the 'U'
+operation, the 7th argument specifies the new value for the row.
+The columns to be modified are specified by the 5th argument for
+the corresponding open_index call. For the 'D' operation, the
+7th argument can be omitted.
+
+-----------------------------------------------------------------
+The execute_single method can be used for inserting records also.
+
+  my $res = $hs->execute_single(3, '+', [ 'foo', 'bar', 'baz' ]);
+  die $hs->get_error() if $res->[0] != 0;
+
+The 3rd argument must be an arrayref whose elements correspond to
+the 5th argument for the corresponding open_index call. If there
+is a column which is not appeared in the 5th argument for the
+open_index, the default value for the column is set.
+
+-----------------------------------------------------------------
+Multiple operations can be executed in a single call. Executing
+multiple operations in a single call is much faster than
+executing them separatedly. 
+
+  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);
+    # ...
+  }
+
+-----------------------------------------------------------------
+If handlersocket is configured to authenticate client connections
+(ie., handlersocket_plain_secret or handlersocket_plain_secret_wr
+is set), a client must call 'auth' method before any other
+methods.
+
+  my $res = $hs->auth('password');
+  die $hs->get_error() if $res->[0] != 0;
+
+-----------------------------------------------------------------
+When an error is occurred, the first element of the returned
+arrayref becomes a non-zero value. A negative value indicates
+that an I/O error is occurred and the Net::HandlerSocket object
+should be disposed. A positive value means that the connection is
+still active and the Net::HandlerSocket object can be reused
+later.
+