--- name: "MR::IProto" section: "3pm" platform: "linux" package: "libmr-tarantool-perl" version: "0.0.24-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/MR::IProto" --- # MR::IProto(3pm) iproto network protocol client ## NAME MR::IProto - iproto network protocol client ## SYNOPSIS IProto client can be created with full control of its behaviour: ``` my $client = MR::IProto->new( cluster => MR::IProto::Cluster->new( servers => [ MR::IProto::Cluster::Server->new( host => 'xxx.xxx.xxx.xxx', port => xxxx, ), ... ], ), ); ``` Or without it: ``` my $client = MR::IProto->new( servers => 'xxx.xxx.xxx.xxx:xxxx,xxx.xxx.xxx.xxx:xxxx', ); ``` Messages can be prepared and processed using objects (requires some more CPU): ``` 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. ``` Or without them: ``` my $response = $client->send({ msg => x, data => [...], pack => 'xxx', unpack => sub { my ($data) = @_; return (...); }, }); ``` Messages can be sent synchronously: ``` my $response = $client->send($response); # exception is raised if error is occurred # besides $@ you can check $! to identify reason of error ``` Or asynchronously: ``` 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 ``` It is recommended to disconnect all connections in child after **fork()** to prevent possible conflicts: ``` my $pid = fork(); if ($pid == 0) { MR::IProto->disconnect_all(); } ``` ## DESCRIPTION This client is used to communicate with cluster of balanced servers using iproto network protocol. 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 `"prefix::*::suffix"`, where *prefix* must be passed to constructor of MR::IProto as value of "prefix" attribute and *suffix* is either `"Request"` or `"Response"`. This classes must be loaded before first message through client object will be sent. To send messages asynchronously you should to implement event loop by self. AnyEvent is recommended. ## ATTRIBUTES - prefix Prefix of the class name in which hierarchy subclasses of MR::IProto::Message are located. Used to find reply message classes. - cluster Instance of MR::IProto::Cluster. Contains all servers between which requests can be balanced. Also can be specified in *servers* parameter of constructor as a list of `"host:port"` pairs separated by comma. - max\_parallel Max amount of simultaneous request to all servers. - max\_request\_retries Max amount of request retries which must be sent to different servers before error is returned. - retry\_delay Delay between request retries. ## PUBLIC METHODS - new( \[ %args \| \\%args \] ) Constructor. See "ATTRIBUTES" and "BUILDARGS" for more information about allowed arguments. - send( \[ $message \| \\%args \], $callback? ) Send `$message` to server and receive reply. If `$callback` is passed then request is done asynchronously and reply is passed to callback as first argument. Method **must** 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 `$!` variable. In sync mode (when `$callback` argument is skipped) all errors are raised and `$!` is also set. Response is returned from method, so method **must** be called in scalar context. Request `$message` 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 `"\%args"` hash reference with keys described in "\_send". - send\_bulk( \\@messages, $callback? ) Send all of messages in `"\@messages"` 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 `"data"` and `"error"` if message was passed as `"\%args"`. Replies in result can be returned in order different then order of requests. See "\_send" for more information about message data. Either `$message` or `"\%args"` allowed as content of `"\@messages"`. - disconnect\_all Class method used to disconnect all iproto-connections. Very useful in case of **fork()**. ## PROTECTED METHODS - BUILDARGS( \[ %args \| \\%args \] ) For compatibility with previous version of client and simplicity some additional arguments to constructor is allowed: - servers `"host:port"` pairs separated by comma used to create MR::IProto::Cluster::Server objects. - timeout, tcp\_nodelay, tcp\_keepalive, dump\_no\_ints Are passed directly to constructor of MR::IProto::Cluster::Server. - balance Is passed directly to constructor of MR::IProto::Cluster. See "BUILDARGS" in Mouse::Manual::Construction for more information. - \_send( \[ $message \| \\%args \], $callback? ) Pure asyncronious internal implementation of send. `$message` is an instance of MR::IProto::Message. If `"\%args"` hash reference is passed instead of `$message` then it can contain following keys: - msg Message code. - key Depending on this value balancing between servers is implemented. - data Message data. Already packed or unpacked. Unpacked data must be passed as array reference and additional parameter *pack* must be passed. - pack First argument of pack function. - unpack Code reference which is used to unpack reply. - no\_reply Message have no reply. - retry Is retry is allowed. Values of attributes "max\_request\_retries" and "retry\_delay" is used if retry is allowed. - is\_retry Callback used to determine if server asks for retry. Unpacked data is passed to it as a first argument. ## SEE ALSO MR::IProto::Cluster, MR::IProto::Cluster::Server, MR::IProto::Message.