/ 
AnyEvent-JSONRPC-Lite-0.15
River stage zero No dependents
/ AnyEvent::JSONRPC::Lite::Client

NAME

AnyEvent::JSONRPC::Lite::Client - Simple TCP-based JSONRPC client

SYNOPSIS

use AnyEvent::JSONRPC::Lite::Client;

my $client = AnyEvent::JSONRPC::Lite::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::JSONRPC::Lite.

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::JSONRPC::Lite::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 occurred. This has same arguments as AnyEvent::Handle, and also act as handler's on_error callback.

Default is just croak.

If you want to set other options to handle object, use handler_options option showed below.

handler_options => 'HashRef'

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

Default is empty.

call ($method, @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 = $@) {
    # ...
}

notify ($method, @params)

Same as call method, but not handle response. This method just notify to server.

$client->notify( echo => 'Hello' );

AUTHOR

Daisuke Murase <typester@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2009 by KAYAC Inc.

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.