NAME

RPC::Async::Server - server side of asynchronous RPC framework

SYNOPSIS

  use RPC::Async::Server;
  use IO::EventMux;
  
  my $mux = IO::EventMux->new;
  my $rpc = RPC::Async::Server->new($mux);
  init_clients($rpc);
  
  while ($rpc->has_clients()) {
      my $event = $rpc->io($mux->mux) or next;
  }
  
  sub rpc_add_numbers {
      my ($caller, %args) = @_;
      my $sum = $args{n1} + $args{n2};
      $rpc->return($caller, sum => $sum);
  }
  
  1;

DESCRIPTION

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

When creating a new RPC::Async::Server object with the new method, you are also telling it what package it should invoke callback functions in. If the package argument is omitted, it will use the caller's package.

Users of this module are written as a kind of hybrid between a perl executable program and a library module. They need a small wrapper program around them to initialise communication with their clients somehow. The convention of RPC::Async::Client dictates that they call a method named init_clients as described in "SYNOPSIS".

METHODS

rpc_*($caller, @args) (callbacks)

The method named rpc_PROCEDURE will be called back from io when the client calls the method PROCEDURE. The first argument is an opaque handle to be used when calling return, and the remaining arguments are the ones given by the client.

The return values from these methods are ignored. Return a value by calling return on the RPC server object. It is not necessary to call return before returning from this method, but it should be called eventually. If the client sends invalid data, throw an exception to disconnect him.

new($mux [, $package])

Instantiate a new RPC server object that will call back methods in $package. If $package is omitted, the caller's package will be used.

The $mux object must be an instance of IO::EventMux or something compatible, which will be used for I/O. It is the responsibility of the caller to poll this object and call io, as detailed below.

add_client($socket)

Add a client to the internal list of clients. This method is not usually called directly.

add_listener($socket)

Add a listening socket. Connections to this socket will be automatically added to the internal list of clients. This method is not usually called directly.

return($caller, @args)

Must be called exactly once for each callback to one of the rpc_* methods.

io($event)

This method is called in the program's main loop every time an event is received from IO::EventMux::mux. If io processed this event and determined that it is not relevant to the caller, it returns undef. Otherwise, the event is returned. This leads to the calling style of

  my $event = $rpc->io($mux->mux) or next;

in the main loop. If more than one RPC server is in use, chain the calls like

  my $event = $mux->mux;
  $event = $rpc1->io($event) or next;
  $event = $rpc2->io($event) or next;

This method will invoke the rpc_* callbacks as needed.

has_clients()

Returns true if and only if at least one client is still connected to this server.

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.