.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MR::IProto 3pm"
.TH MR::IProto 3pm "2020-07-21" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MR::IProto \- iproto network protocol client
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
IProto client can be created with full control of
its behaviour:
.PP
.Vb 11
\&    my $client = MR::IProto\->new(
\&        cluster => MR::IProto::Cluster\->new(
\&            servers => [
\&                MR::IProto::Cluster::Server\->new(
\&                    host => \*(Aqxxx.xxx.xxx.xxx\*(Aq,
\&                    port => xxxx,
\&                ),
\&                ...
\&            ],
\&        ),
\&    );
.Ve
.PP
Or without it:
.PP
.Vb 3
\&    my $client = MR::IProto\->new(
\&        servers => \*(Aqxxx.xxx.xxx.xxx:xxxx,xxx.xxx.xxx.xxx:xxxx\*(Aq,
\&    );
.Ve
.PP
Messages can be prepared and processed using objects (requires some more \s-1CPU\s0):
.PP
.Vb 8
\&    my $request = MyProject::Message::MyOperation::Request\->new(
\&        arg1 => 1,
\&        arg2 => 2,
\&    );
\&    my $response = $client\->send($request);
\&    # $response isa My::Project::Message::MyOperation::Response.
\&    # Of course, both message classes (request and reply) must
\&    # be implemented by user.
.Ve
.PP
Or without them:
.PP
.Vb 9
\&    my $response = $client\->send({
\&        msg    => x,
\&        data   => [...],
\&        pack   => \*(Aqxxx\*(Aq,
\&        unpack => sub {
\&            my ($data) = @_;
\&            return (...);
\&        },
\&    });
.Ve
.PP
Messages can be sent synchronously:
.PP
.Vb 3
\&    my $response = $client\->send($response);
\&    # exception is raised if error is occurred
\&    # besides $@ you can check $! to identify reason of error
.Ve
.PP
Or asynchronously:
.PP
.Vb 8
\&    use AnyEvent;
\&    my $callback = sub {
\&        my ($reply, $error) = @_;
\&        # on error $error is defined and $! can be set
\&        return;
\&    };
\&    $client\->send($request, $callback);
\&    # callback is called when reply is received or error is occurred
.Ve
.PP
It is recommended to disconnect all connections in child after \fBfork()\fR to
prevent possible conflicts:
.PP
.Vb 4
\&    my $pid = fork();
\&    if ($pid == 0) {
\&        MR::IProto\->disconnect_all();
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This client is used to communicate with cluster of balanced servers using
iproto network protocol.
.PP
To use it nicely you should to implement two subclasses of
MR::IProto::Message for each message type, one for request message
and another for reply.
This classes must be named as \f(CW\*(C`prefix::*::suffix\*(C'\fR, where \fIprefix\fR
must be passed to constructor of MR::IProto as value of \*(L"prefix\*(R"
attribute and \fIsuffix\fR is either \f(CW\*(C`Request\*(C'\fR or \f(CW\*(C`Response\*(C'\fR.
This classes must be loaded before first message through client object
will be sent.
.PP
To send messages asynchronously you should to implement event loop by self.
AnyEvent is recommended.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "prefix" 4
.IX Item "prefix"
Prefix of the class name in which hierarchy subclasses of MR::IProto::Message
are located. Used to find reply message classes.
.IP "cluster" 4
.IX Item "cluster"
Instance of MR::IProto::Cluster. Contains all servers between which
requests can be balanced.
Also can be specified in \fIservers\fR parameter of constructor as a list of
\&\f(CW\*(C`host:port\*(C'\fR pairs separated by comma.
.IP "max_parallel" 4
.IX Item "max_parallel"
Max amount of simultaneous request to all servers.
.IP "max_request_retries" 4
.IX Item "max_request_retries"
Max amount of request retries which must be sent to different servers
before error is returned.
.IP "retry_delay" 4
.IX Item "retry_delay"
Delay between request retries.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.ie n .IP "new( [ %args | \e%args ] )" 4
.el .IP "new( [ \f(CW%args\fR | \e%args ] )" 4
.IX Item "new( [ %args | %args ] )"
Constructor.
See \*(L"\s-1ATTRIBUTES\*(R"\s0 and \*(L"\s-1BUILDARGS\*(R"\s0 for more information about allowed arguments.
.ie n .IP "send( [ $message | \e%args ], $callback? )" 4
.el .IP "send( [ \f(CW$message\fR | \e%args ], \f(CW$callback\fR? )" 4
.IX Item "send( [ $message | %args ], $callback? )"
Send \f(CW$message\fR to server and receive reply.
.Sp
If \f(CW$callback\fR is passed then request is done asynchronously and reply is passed
to callback as first argument.
Method \fBmust\fR be called in void context to prevent possible errors.
Only client errors can be raised in async mode. All communication errors are
passed to callback as second argument. Additional information can be extracted
from \f(CW$!\fR variable.
.Sp
In sync mode (when \f(CW$callback\fR argument is skipped) all errors are raised
and \f(CW$!\fR is also set. Response is returned from method, so method \fBmust\fR
be called in scalar context.
.Sp
Request \f(CW$message\fR can be instance of MR::IProto::Message subclass.
In this case reply will be also subclass of MR::IProto::Message.
Or it can be passed as \f(CW\*(C`\e%args\*(C'\fR hash reference with keys described
in \*(L"_send\*(R".
.ie n .IP "send_bulk( \e@messages, $callback? )" 4
.el .IP "send_bulk( \e@messages, \f(CW$callback\fR? )" 4
.IX Item "send_bulk( @messages, $callback? )"
Send all of messages in \f(CW\*(C`\e@messages\*(C'\fR and return result (sync-mode) or
call callback (async-mode) after all replies was received.
Result is returned as array reference, which values can be instances of
MR::IProto::Response or MR::IProto::Error if request was passed
as object, or hash with keys \f(CW\*(C`data\*(C'\fR and \f(CW\*(C`error\*(C'\fR if message was passed
as \f(CW\*(C`\e%args\*(C'\fR.
Replies in result can be returned in order different then order of requests.
.Sp
See \*(L"_send\*(R" for more information about message data. Either
\&\f(CW$message\fR or \f(CW\*(C`\e%args\*(C'\fR allowed as content of \f(CW\*(C`\e@messages\*(C'\fR.
.IP "disconnect_all" 4
.IX Item "disconnect_all"
Class method used to disconnect all iproto-connections. Very useful in case of \fBfork()\fR.
.SH "PROTECTED METHODS"
.IX Header "PROTECTED METHODS"
.ie n .IP "\s-1BUILDARGS\s0( [ %args | \e%args ] )" 4
.el .IP "\s-1BUILDARGS\s0( [ \f(CW%args\fR | \e%args ] )" 4
.IX Item "BUILDARGS( [ %args | %args ] )"
For compatibility with previous version of client and simplicity
some additional arguments to constructor is allowed:
.RS 4
.IP "servers" 4
.IX Item "servers"
\&\f(CW\*(C`host:port\*(C'\fR pairs separated by comma used to create
MR::IProto::Cluster::Server objects.
.IP "timeout, tcp_nodelay, tcp_keepalive, dump_no_ints" 4
.IX Item "timeout, tcp_nodelay, tcp_keepalive, dump_no_ints"
Are passed directly to constructor of MR::IProto::Cluster::Server.
.IP "balance" 4
.IX Item "balance"
Is passed directly to constructor of MR::IProto::Cluster.
.RE
.RS 4
.Sp
See \*(L"\s-1BUILDARGS\*(R"\s0 in Mouse::Manual::Construction for more information.
.RE
.ie n .IP "_send( [ $message | \e%args ], $callback? )" 4
.el .IP "_send( [ \f(CW$message\fR | \e%args ], \f(CW$callback\fR? )" 4
.IX Item "_send( [ $message | %args ], $callback? )"
Pure asyncronious internal implementation of send.
.Sp
\&\f(CW$message\fR is an instance of MR::IProto::Message.
If \f(CW\*(C`\e%args\*(C'\fR hash reference is passed instead of \f(CW$message\fR then it can
contain following keys:
.RS 4
.IP "msg" 4
.IX Item "msg"
Message code.
.IP "key" 4
.IX Item "key"
Depending on this value balancing between servers is implemented.
.IP "data" 4
.IX Item "data"
Message data. Already packed or unpacked. Unpacked data must be passed as
array reference and additional parameter \fIpack\fR must be passed.
.IP "pack" 4
.IX Item "pack"
First argument of pack function.
.IP "unpack" 4
.IX Item "unpack"
Code reference which is used to unpack reply.
.IP "no_reply" 4
.IX Item "no_reply"
Message have no reply.
.IP "retry" 4
.IX Item "retry"
Is retry is allowed. Values of attributes \*(L"max_request_retries\*(R" and
\&\*(L"retry_delay\*(R" is used if retry is allowed.
.IP "is_retry" 4
.IX Item "is_retry"
Callback used to determine if server asks for retry. Unpacked data is passed
to it as a first argument.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
MR::IProto::Cluster, MR::IProto::Cluster::Server, MR::IProto::Message.