NAME

MsgPack::RPC - MessagePack RPC client

VERSION

version 2.0.3

SYNOPSIS

    use MsgPack::RPC;

    my $rpc = MsgPack::RPC->new( io => '127.0.0.1:6666' );

    $rpc->notify( 'something' => [ 'with', 'args' ] );

    $rpc->request(
        request_method => [ 'some', 'args' ]
    )->on_done(sub{
        print "replied with: ", @_;
    });

    $rpc->loop;

DESCRIPTION

MsgPack::RPC implements a MessagePack RPC client following the protocol described at https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md.

METHODS

new( %args )

io( $socket )

io( [ $in_fh, $out_fh ] )

Required. Defines which IO on which the MessagePack messages will be received and sent.

The IO can be a local socket (e.g., /tmp/rpc.socket ), a network socket (e.g., 127.0.0.1:6543), or a pair of filehandles.

io()

Returns the IO descriptor(s) used by the object.

request( $method, $args, $id )

Sends the request. The $id is optional, and will be automatically assigned from an internal self-incrementing list if not given.

Returns a promise that will be fulfilled once a response is received. The response can be either a success or a failure, and in both case the fulfilled promise will be given whatever values are passed in the response.

    $rpc->request( 'ls', [ '/home', '/tmp' ] )
        ->on_done(sub{ say for @_ })
        ->on_fail(sub{ die "couldn't read directories: ", @_ });

notify( $method, $args )

Sends a notification.

subscribe( $event_name, \&callback )

    # 'ping' is a request
    $rpc->subscribe( ping => sub($msg) {
        $msg->response->done('pong');
    });

    # 'log' is a notification
    $rpc->subscribe( log => sub($msg) {
        print {$fh} @{$msg->args};
    });

Register a callback for the given event. If a notification or a request matching the event is received, the callback will be called. The callback will be passed either a MsgPack::RPC::Message (if triggered by a notification) or MsgPack::RPC::Message::Request object.

Events can have any number of callbacks assigned to them.

The subscription system is implemented using the Beam::Emitter role.

loop( $end_condition )

Reads and process messages from the incoming stream, endlessly if not be given an optional $end_condition. The end condition can be given a number of messages to read, or a promise that will end the loop once fulfilled.

    # loop until we get a response from our request

    my $response = $rpc->request('add', [1,2] );

    $response->on_done(sub{ print "sum is ", @_ });

    $rpc->loop($response);


    # loop 100 times
    $rpc->loop(100);

SEE ALSO

MsgPack::RPC::Message

MsgPack::RPC::Message::Request

MsgPack::Encoder

MsgPack::Decoder

Data::MessagePack (alternative to MsgPack::Encoder and MsgPack::Decoder.

AUTHOR

Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2017, 2016, 2015 by Yanick Champoux.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm MsgPack::RPC

perl -MCPAN -e shell
install MsgPack::RPC