NAME

RPC::EPC::Service - An Asynchronous Remote Procedure Stack.

VERSION

This document describes RPC::EPC::Service version 0.0.11

SYNOPSIS

Server code

    use RPC::EPC::Service;
    
    my $server = RPC::EPC::Service->new(8888, {
        'add' => sub {
            my $args_ref = shift;
            my ($a,$b) = @$args_ref;
            return $a + $b;
        });
    $server->start;

Client code

    use RPC::EPC::Service;
    
    my $client = RPC::EPC::Service->new($port,{});
    $client->client_start;
    
    my $ret = $client->call_method('add', [1,2]);
    $ret->recv == 3;
    
    $client->stop;

DESCRIPTION

This module enables to connect the other process with the S-expression protocol, like the Swank protocol of the SLIME.

SLIME : http://common-lisp.net/project/slime/

The primary objective is for users to make some Emacs extensions with the Perl and CPAN.

Protocol

The encoding format is the S-expression.

The TCP socket is employed by the communication.

Because the RPC session is written in the async manner, the programs can call the procedures asynchronously.

Object Serialization

This module can translate following types:

• undef

• Number

• String

• Array

• Hash

• Complex of Array and Hash.

INTERFACE

Server and Client Commons

new

  $service = RPC::EPC::Service->new($port, $handlers);

Create a server object. If port number is 0 or undef, the number is decided by the OS.

The $handlers object is a hash of method names and sub blocks, which methods are called by the peer process. Methods can be also defined by define_method after the initialization.

define_method

  $service->define_method($method_name, sub { .... });

Define a method which is called by the peer process.

The following form defines a method with documents for the method argument and specifications.

  $service->define_method($method_name,
      sub { .... },
      "arg1 arg2",
      "document for this method");

The documents are referred by the peer process for users to inspect the methods.

call_method

  $ret = $service->call_method($method_name, $args);
  print $ret->recv;

Call the peer's method. The arguments should be packed in one object, such as Array and Hash.

This method returns immediately, not waiting for the result, and value $ret is AnyEvent::condvar object. To obtain the result, the program calls the recv method, because the peer's task is executed concurrently and the result is sent asynchronously.

The recv method may raise the error. The error has two types, the peer's program (Application Error) and the RPC stack (RPC Error).

The Application Error is a normal error which is caused by peer's program, such as 'division by zero', 'file not found' and so on. The programmers are responsible to this type errors, recovering error handling or just fixing bugs.

The RPC Error is a communication error which is caused by RPC stack, such as 'connection closed', 'method not found', 'serialization error' and so on. This type errors are caused by environment problems, bugs of peer's program, our side one or the RPC stack.

Here is a sample robust code:

  $ret = $service->call_method($method_name, $args);
  eval {
    print $ret->recv; # normal result
  };
  if ($@) {
    # Error handling
    if ($@->[0] eq "ERROR") {
      # Application Error
      print $@->[1];  # error message
    } elsif ($@->[0] eq "EPC-ERROR") {
      # RPC Error
      print $@->[1];  # error message
    }
  }

query_methods

  $service->query_methods();

Define a method which is called by the peer process.

Server side

start

  $service->start;

Initialize the connection port and wait for the client connection. This method starts the event loop and blocks the control.

Client side

client_start

  $service->client_start;

Establish the connection to the server. If connection failed, it will die.

stop

  $service->stop;

Shutdown the connection.

Utilities

to_sexp

Translate a Perl object into S-expression string. In normal use, serializing and unserializing are applied automatically.

AUTHOR

Masashi Sakurai <m.sakurai@kiwanami.net>

LICENSE AND COPYRIGHT

Copyright (c) 2011, 2012 Masashi Sakurai <m.sakurai@kiwanami.net>. All rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm RPC::EPC::Service

perl -MCPAN -e shell
install RPC::EPC::Service