/ 
Prim-0.01
/ PrimObjectServer

NAME

PrimObjectServer - turns your script into a socket based object server

SYNOPSIS

use PrimObject Server;
use AnyClassYouNeed;

sub wrapper_for_AnyClassYouNeed_new {
  return AnyClassYouNeed->new(@_);
}

sub helpful_non_object_function {
  # do something interesting to set $something_helpful
  return $something_helpful;
}

PrimObject->new('my.registered.name.company.com',
  'file.acl',
  make_object_you_need => { CODE => \&wrapper_for_AnyClassYouNeed_new,
                            DOC  => 'returns an AnyClassYouNeed object'
                          },
  helpful => { CODE => \&helpful_non_object_funtion,
               DOC  => 'Gives you something helpful',
             }
);

DESCRIPTION

For a more useful example look in objectserver in the distribution.

To use this class, first declare any functions you want to expose to your caller (and any helper functions you don't want your caller to access directly). In particular, to expose an object to your caller, simply write a wrapper function which returns whatever that class's constructor returns. (This class and its opposite number on the client side will create the illusion that the caller is calling functions in the calling interpreter. Further, the methods in the server interpreter will think the user is local.)

When you are ready to become a server, call new on this class with the name you want your service to have, an access control file name (pass undef if you don't want access controls), and an API hash in the form shown. Keys in the hash are the external names, values are hashes. Those hashes have two keys (at present). CODE must be a valid code reference which the PrimObject will use as a callback. DOC should tell a caller what the function does and how to use it. Try to be as helpful as possible.

For additional examples see the following scripts: trivialobjectserver and objectserver which rely on trivialobjectclient and objectclient

INTERNALS

The constructor of this class binds a socket to an ephemeral port, records that port number in /tmp/your.name.prim, and begins an infinite loop accepting connections. For each connection a child is formed. Typical clients use PrimObject.pm which maintains this connection until the initial PrimObject goes out of scope or is otherwise destroyed.

All requests must be newline terminated prim requests (which is an xml protocol). </prim> is used as the end of request sentinel value. Responses are formed in the same way, so the client can do the same thing. See the protocols file in the distribution directory for more details.

BUGS

There are no timeouts.

EXPORT

None.

SEE ALSO

PrimServer.pm is the non-object version of this script.

AUTHOR

Phil Crow, philcrow2000@yahoo.com

new

Turns your script into a server. Pass it two things:

  1. The name you want others to call your object.

  2. A hash with your exposed function names as keys and code references to implement those functions as values (the name of the key and the function may differ).

This function NEVER returns. It goes into a standard forking accept loop on the socket it creates.