MR::IProto(3pm)

🦋 NAME 🦋

hiii bestie, meet MR::IProto — it's an iproto network protocol client 💅

(also hi, this page is MR::IProto(3pm) from the User Contributed Perl Documentation, just so you know what you're reading ✨)

---

✨ SYNOPSIS ✨

okay so you can create an IProto client 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, like, without all that:

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, so it's giving a lil extra work for your processor but it's cute):

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 (main character energy fr):

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

🫶 real talk: it is recommended to disconnect all connections in child after fork() to prevent possible conflicts. no cap.

my $pid = fork();
if ($pid == 0) {
    MR::IProto->disconnect_all();
}

---

🌸 DESCRIPTION 🌸

This client is used to communicate with a cluster of balanced servers using the iproto network protocol.

To use it nicely (and honestly, why would you not), you should implement two subclasses of MR::IProto::Message for each message type — one for the request message and another for the reply. This classes must be named as "prefix::*::suffix", where prefix must be passed to the constructor of MR::IProto as the value of the "prefix" attribute, and suffix is either "Request" or "Response". This classes must be loaded before the first message through the client object will be sent. 👑

To send messages asynchronously you should implement the 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 the servers parameter of the 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 the server and receive the reply.

If $callback is passed then the request is done asynchronously and the reply is passed to the callback as the 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 the callback as the second argument. Additional information can be extracted from the $! variable.

In sync mode (when the $callback argument is skipped) all errors are raised and $! is also set. The response is returned from the method, so the method must be called in scalar context.

The request $message can be an instance of an MR::IProto::Message subclass. In this case the reply will also be a subclass of MR::IProto::Message. Or it can be passed as a \%args hash reference with the keys described in "_send". 💅

send_bulk( \@messages, $callback? )

Send all of the messages in \@messages and return the result (sync mode) or call the callback (async mode) after all replies were received. The result is returned as an array reference, whose values can be instances of MR::IProto::Response or MR::IProto::Error if the request was passed as an object, or a hash with the keys data and error if the message was passed as \%args. Replies in the result can be returned in an order different than the order of the requests. 🔥

heads up bestie — see "_send" for more information about message data. Either $message or \%args is allowed as the 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 the previous version of the client and for simplicity, some additional arguments to the constructor are 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 the constructor of MR::IProto::Cluster::Server.
• balance — Is passed directly to the 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 a \%args hash reference is passed instead of $message, then it can contain the 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 an array reference and the additional parameter pack must be passed.
• pack — First argument of the pack function.
• unpack — Code reference which is used to unpack the reply.
• no_reply — Message have no reply.
• retry — Is retry is allowed. Values of the attributes "max_request_retries" and "retry_delay" is used if retry is allowed.
• is_retry — Callback used to determine if the 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. 💜

---

and that's the whole page bestie, you ate 🫶

this one was served up by perl v5.30.3, dated 2020-07-21. mwah, go forth and balance some servers 💅✨