← Back to branch summary

~ubuntu-branches/ubuntu/trusty/mariadb-5.5/trusty-proposed

« back to all changes in this revision

Viewing changes to plugin/handler_socket/docs-en/perl-client.en.txt

  • Committer: Package Import Robot
  • Author(s): Otto Kekäläinen
  • Date: 2013-12-22 10:27:05 UTC
  • Revision ID: package-import@ubuntu.com-20131222102705-mndw7s12mz0szrcn
Tags: upstream-5.5.32
Import upstream version 5.5.32

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugin/handler_socket/docs-en/perl-client.en.txt
 
1
 
 
2
-----------------------------------------------------------------
 
3
To open a connection to the handlersocket plugin, you need to
 
4
create a Net::HandlerSocket object.
 
5
 
 
6
  use Net::HandlerSocket;
 
7
  my $args = { host => 'localhost', port => 9998 };
 
8
  my $hs = new Net::HandlerSocket($args);
 
9
 
 
10
-----------------------------------------------------------------
 
11
Before executing table operations, you need to open an index to
 
12
work with.
 
13
 
 
14
  my $err = $hs->open_index(3, 'database1', 'table1', 'PRIMARY',
 
15
    'f1,f2');
 
16
  die $hs->get_error() if $res->[0] != 0;
 
17
 
 
18
The first argument for open_index is an integer value which is
 
19
used to identify an open table, which is only valid within the
 
20
same Net::HandlerSocket object. The 4th argument is the name of
 
21
index to open. If 'PRIMARY' is specified, the primary index is
 
22
open. The 5th argument is a comma-separated list of column names.
 
23
 
 
24
-----------------------------------------------------------------
 
25
To read a record from a table using an index, call the
 
26
execute_single method.
 
27
 
 
28
  my $res = $hs->execute_single(3, '=', [ 'foo' ], 1, 0);
 
29
  die $hs->get_error() if $res->[0] != 0;
 
30
  shift(@$res);
 
31
 
 
32
The first argument must be an integer which has specified as the
 
33
first argument for open_index on the same Net::HandlerSocket
 
34
object. The second argument specifies the search operation. The
 
35
current version of handlersocket supports '=', '>=', '<=', '>',
 
36
and '<'. The 3rd argument specifies the key to find, which must
 
37
an arrayref whose length is equal to or smaller than the number
 
38
of key columns of the index. The 4th and the 5th arguments
 
39
specify the maximum number of records to be retrieved, and the
 
40
number of records skipped before retrieving records. The columns
 
41
to be retrieved are specified by the 5th argument for the
 
42
corresponding open_index call.
 
43
 
 
44
The execute_single method always returns an arrayref. The first
 
45
element is the error code, which is 0 when no error is occured.
 
46
The remaining are the field values. If more than one record is
 
47
returned, it is flatten to an 1-dimensional array. For example,
 
48
when 5 records that have 3 columns are returned, you can retrieve
 
49
values using the following code.
 
50
 
 
51
  die $hs->get_error() if $res->[0] != 0;
 
52
  shift(@$res);
 
53
  for (my $row = 0; $row < 5; ++$row) {
 
54
    for (my $col = 0; $col < 3; ++$col) {
 
55
      my $value = $res->[$row * 5 + $col];
 
56
      # ...
 
57
    }
 
58
  }
 
59
 
 
60
-----------------------------------------------------------------
 
61
To update or delete records, you need to specify more arguments
 
62
for the execute_single method. Note that the Net::HandlerSocket
 
63
object must be connected to a handlersocket worker for write
 
64
operations, which is port 9999 by default.
 
65
(For safety, the port 9998 only allows read operations, and the
 
66
port 9999 allows write operations also. The port 9999 allows
 
67
read operations too, but slower than 9998 because of record
 
68
locking etc.. Port numbers can be changed using the
 
69
'handlersocket_port' and the 'handlersocket_port_wr'
 
70
configuration options of mysqld.)
 
71
 
 
72
  my $args = { host => 'localhost', port => 9999 };
 
73
  my $hs = new Net::HandlerSocket($args);
 
74
 
 
75
  my $res = $hs->execute_single(3, '=', [ 'bar' ], 1, 0, 'U',
 
76
    [ 'fubar', 'hoge' ]);
 
77
  die $hs->get_error() if $res->[0] != 0;
 
78
  my $num_updated_rows = $res->[1];
 
79
 
 
80
  my $res = $hs->execute_single(3, '=', [ 'baz' ], 1, 0, 'D');
 
81
  die $hs->get_error() if $res->[0] != 0;
 
82
  my $num_deleted_rows = $res->[1];
 
83
 
 
84
The 6th argument for execute_single specifies the modification
 
85
operation. The current version supports 'U' and 'D'. For the 'U'
 
86
operation, the 7th argument specifies the new value for the row.
 
87
The columns to be modified are specified by the 5th argument for
 
88
the corresponding open_index call. For the 'D' operation, the
 
89
7th argument can be omitted.
 
90
 
 
91
-----------------------------------------------------------------
 
92
The execute_single method can be used for inserting records also.
 
93
 
 
94
  my $res = $hs->execute_single(3, '+', [ 'foo', 'bar', 'baz' ]);
 
95
  die $hs->get_error() if $res->[0] != 0;
 
96
  my $num_inserted_rows = $res->[1];
 
97
 
 
98
The 3rd argument must be an arrayref whose elements correspond to
 
99
the 5th argument for the corresponding open_index call. If there
 
100
is a column which is not appeared in the 5th argument for the
 
101
open_index, the default value for the column is set.
 
102
 
 
103
-----------------------------------------------------------------
 
104
Multiple operations can be executed in a single call. Executing
 
105
multiple operations in a single call is much faster than
 
106
executing them separatedly. 
 
107
 
 
108
  my $rarr = $hs->execute_multi([
 
109
    [ 0, '>=', [ 'foo' ], 5, 0 ],
 
110
    [ 2, '=', [ 'bar' ], 1, 0 ],
 
111
    [ 4, '<', [ 'baz' ], 10, 5 ],
 
112
  ]);
 
113
  for my $res (@$rarr) {
 
114
    die $hs->get_error() if $res->[0] != 0;
 
115
    shift(@$res);
 
116
    # ...
 
117
  }
 
118
 
 
119
-----------------------------------------------------------------
 
120
When an error is occured, the first element of the returned
 
121
arrayref becomes a non-zero value. A negative value indicates
 
122
that an I/O error is occured and the Net::HandlerSocket object
 
123
should be disposed. A positive value means that the connection is
 
124
still active and the Net::HandlerSocket object can be reused
 
125
later.
 
126