NAME

RapidApp::BgTask::MsgPipe

SYNOPSIS

  # basic send/recv
  my $pipe= RapidApp::BgTask::MsgPipe->new( socket => $sock );
  $pipe->sendMessage({ blah => 1, foo => 2 });
  my $hash= $pipe->recvMessage();
  my $ret= $pipe->callRemoteMethod(foo => [1, 2, 3]);
  
  # a simple method server
  my $obj= MyClassWithPublicMethods->new();
  my $pipe2= RapidApp::BgTask::MsgPipe->new( socket => $sock, autoRMI => 1, rmiTargetObj => $obj );
  do { $pipe->recvMessage() } while (!$obj->terminated);

DESCRIPTION

This class implements a message pipe that can send and receive perl data structures, and also do some simple remote-method-invocation.

Note that for a real server, you probably want to use the non-blocking version of this class (RapidApp::BgTask::MsgPipeNB)

ATTRIBUTES

socket

The bi-directional socket to use for communication.

autoPingReply

Whether to automatically send "pong" responses to "ping" messages. When enabled, ->recvMessage does not return the ping message, and just keeps blocking until it gets a real message.

autoRMI

Whether to automatically run remote method requests. When enabled, RMI requests get handled automatically during recvMessage, and the caller of recvMessage never sees them.

rmiTargetObj

The object on which remote method calls will be made. This is necessary in order for "autoRMI" to be able to handle the requests behind the scenes.

onEof( callback( $pipe ) )

A callback for when EOF is encountered on the read-end of the socket.

onErr( callback( $pipe, $message ) )

A callback for when a fatal error occurs on either reading or writing the socket.

sendMessage( \%message )

Send a message (which must be a hash) to the other end.

recvMessage

Returns the next message received which is not auto-handled. Returns undef on EOF.

Any messages that are meant to be handled automatically (like ping replies or RMI requests) will be processed during this method, and only a real message or EOF will cause it to return.

recvRmiResponse( $rmi_instance )

This method is used internally by ->callRemoteMethod. You probably don't need to use it.

Returns the next message received which is a response to the RMI request with the given instance ID. Essentially, this method skips over messages until it finds one that the caller wanted, and puts any other messages into a hidden queue.

When you call recvMessage next, it will draw messages from the queue first, then start waiting for new messages.

callRemoteMethod( methodName => \@params )

This builds a RMI message for the given method and parameters, sends the message, waits for a RMI response message, and then converts that response either into an exception or a return value.

In a vast majority of cases, it is just like calling the method locally.

handleRemoteMethodInvocation( \%methodMessage )

Performs the act of invoking the method on $self->rmiTarget, and then sending a RMI response message.

You only need to use this method if you are not auto-handling the RMI messages.

_execMethodOnTarget( \%methodMessage, $targetObjectRef )

Call a method on the target object, and return a RMI response message.

MethodMsg has parameters of

  rmi_request   (used to identify which method call a response belongs to)
  method        name of the method to run
  params        array of the parameters to be passed to the method

The response has parameters of

  rmi_response  identical to input parameter
  method        name of the method that was called
  ok            boolean success flag
  result        an array of the values returned form the function in array context
  err           an error message if the method died

cpanm RapidApp

perl -MCPAN -e shell
install RapidApp