NAME

RPC::Async::Client - client side of asynchronous RPC framework

SYNOPSIS

use RPC::Async::Client;
use IO::EventMux;

my $mux = IO::EventMux->new;
my $rpc = RPC::Async::Client->new($mux, "perl://add-server.pl");
# or # my $rpc = RPC::Async::Client->new($mux, "tcp://127.0.0.1:1234");

$rpc->add_numbers(n1 => 2, n2 => 3,
    sub {
        my %reply = @_;
        print "2 + 3 = $reply{sum}\n";
    });

while ($rpc->has_requests || $rpc->has_coderefs) {
    my $event = $rpc->io($mux->mux) or next;
}

$rpc->disconnect;

DESCRIPTION

This module provides the magic that hides the details of doing asynchronous RPC on the client side. It does not dictate how to implement initialisation or main loop, although it requires the application to use IO::EventMux.

The procedures made available by the remote server can be called directly on the RPC::Async::Client instance or via the call() method where they are further documented.

METHODS

new($mux, $url, @urlargs)

Connects to an RPC server via the URL given in $url. Such URLs can be of the forms specified in RPC::Async::URL, although it must connect to a bi-directional stream socket. Alternatively, pass an open file descriptor.

call($procedure, @args, $subref)

Performs a remote procedure call. Rather than using this directly, this package enables some AUTOLOAD magic that allows calls to remote procedures directly on the RPC::Async::Client instance.

Arguments are passed in key/value style by convention, although any arguments may be given. The last argument a remote procedure call is a subroutine reference to be executed upon completion of the call. This framework makes no guarantees as to when, if ever, this sub will be called. Specifically, remote procedures may return in a different order than they were called in.

Fairly complex data structures may be given as arguments, except for circular ones. In particular, subroutine references are allowed.

The call itself is given a uniq id that is returned and can later be used with other subs.

disconnect

Call this to gracefully disconnect from the server without leaving zombie processes or such.

has_requests

Returns true iff there is at least one request pending. Usually, this means that we should not terminate yet.

has_coderefs

Returns true if the remote side holds a reference to a subroutine given to it in an earlier call. Depending on the application, this may be taken as a hint that we should not terminate yet. This information is obtained via interaction with Perl's garbage collector on the server side.

io($event)

Inspect an event from EventMux. All such events must be passed through here in order to handle asynchronous replies. If the event was handled, undef is returned. Otherwise, the event is returned for processing by other RPC::Async::Client handlers or the main program itself.

dump_requests

Returns a string documenting what requests are pending. For debugging only.

wait($timeout, [@ids])

Block until we have enough events from the RPC server to matches all the id's listed or we get a timeout. If no id's are given then any id will be used. This function can be useful when we want to make sure the server is started in the other end, fx. if we need to connect to it on another socket.

If all events was received in time, 1 is returned, undef is returned on timeout.

Any unrelated events will be buffered and pushed back on the stack when the wait call has finished.

AUTHOR

Troels Liebe Bentsen <tlb@rapanden.dk>, Jonas Jensen <jbj@knef.dk>

COPYRIGHT

Copyright(C) 2005-2007 Troels Liebe Bentsen Copyright(C) 2005-2007 Jonas Jensen

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