NAME

AnyEvent::MPRPC::Client - Simple TCP-based MessagePack RPC client

SYNOPSIS

use AnyEvent::MPRPC::Client;

my $client = AnyEvent::MPRPC::Client->new(
    host => '127.0.0.1',
    port => 4423,
);

# blocking interface
my $res = $client->call( echo => 'foo bar' )->recv; # => 'foo bar';

# non-blocking interface
$client->call( echo => 'foo bar' )->cb(sub {
    my $res = $_[0]->recv;  # => 'foo bar';
});

DESCRIPTION

This module is client part of AnyEvent::MPRPC.

AnyEvent condvars

The main thing you have to remember is that all the data retrieval methods return an AnyEvent condvar, $cv. If you want the actual data from the request, there are a few things you can do.

You may have noticed that many of the examples in the SYNOPSIS call recv on the condvar. You're allowed to do this under 2 circumstances:

Either you're in a main program,

Main programs are "allowed to call recv blockingly", according to the author of AnyEvent.

or you're in a Coro + AnyEvent environment.

When you call recv inside a coroutine, only that coroutine is blocked while other coroutines remain active. Thus, the program as a whole is still responsive.

If you're not using Coro, and you don't want your whole program to block, what you should do is call cb on the condvar, and give it a coderef to execute when the results come back. The coderef will be given a condvar as a parameter, and it can call recv on it to get the data. The final example in the SYNOPSIS gives a brief example of this.

Also note that recv will throw an exception if the request fails, so be prepared to catch exceptions where appropriate.

Please read the AnyEvent documentation for more information on the proper use of condvars.

METHODS

new (%options)

Create new client object and return it.

my $client = AnyEvent::MRPPC::Client->new(
    host => '127.0.0.1',
    port => 4423,
    %options,
);

Available options are:

host => 'Str'

Hostname to connect. (Required)

You should set this option to "unix/" if you will set unix socket to port option.

port => 'Int | Str'

Port number or unix socket path to connect. (Required)

on_error => $cb->($handle, $fatal, $message)

Error callback code reference, which is called when some error occured. This has same arguments as AnyEvent::Handle, and also act as handler's on_error callback.

Default is just croak.

before_connect => $cb->($self, $filehandle)

It will be called with the file handle in not-yet-connected state as only argument.

after_connect => $cb->($self, $filehandle, $host, $port, $retry)

After the connection is established, then this callback will be invoked.

If the connect is unsuccessful, then the on_error callback will be invoked.

on_connect => $cb->($self, $filehandle)

It will be called with the file handle in not-yet-connected state as only argument.

*******************************************************************
 The on_connect callback is deprecated! Please use before_connect
 (same as $prepare_cb of AnyEvent::Socket#tcp_connect) or
 after_connect (which call in $connect_cb of
 AnyEvent::Socket#tcp_connect).
*******************************************************************

handler_options => 'HashRef'

This is passed to constructor of AnyEvent::Handle that is used manage connection.

Default is empty.

call ($method, (@params | \@params))

Call remote method named $method with parameters @params. And return condvar object for response.

my $cv = $client->call( echo => 'Hello!' );
my $res = $cv->recv;

If server returns an error, <$cv-recv>> causes croak by using <$cv-croak>>. So you can handle this like following:

my $res;
eval { $res = $cv->recv };

if (my $error = $@) {
    # ...
}

AUTHOR

Tokuhiro Matsuno <tokuhirom@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2009 by tokuhirom.

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

The full text of the license can be found in the LICENSE file included with this module.