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;

Protocol

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

• undef
• Number
• String
• Array
• Hash
• Complex of Array and Hash.

Server and Client Commons

  $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

  $service->start;

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

Client side

  $service->client_start;

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

stop

  $service->stop;

Shutdown the connection.

Utilities

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