NAME
Net::Objwrap - allow arbitrary access to Perl object over network
VERSION
0.08
SYNOPSIS
# on machine 1
use Net::Objwrap 'wrap';
use Some::Package;
my $obj = Some::Package->new(...);
wrap("obj17.cfg", $obj);
...
# on machine 2
use Net::Objwrap 'unwrap';
my $obj = unwrap("obj17.cfg");
$obj->{bar} = 19; # updates $obj->{bar} on the server
my $x = $obj->foo(42); # calls $obj->foo(42) on object on machine 1DESCRIPTION
The classes of the Net::Objwrap provide network access to a Perl object. The name of a configuration file and an arbitrary Perl object are passed to the "wrap" function. wrap launches a simple server and publishes connection info in the configuration file.
Another script, possibly on a another host, loads the configuration file with a call to a "unwrap", and receives a proxy to the object on the server. The client establishes communication with the server specified in the config file. As this second script manipulates or makes method calls on the proxy object, the client communicates with the server to manipulate the object and return the results of the operation.
Some important features:
Hash members and array indices
Accessing or updating hash values or array values on a remote object is done with the same syntax as access of a local object.
# host 1
use Net::Objwrap 'wrap';
my $hash1 = { abc => 123, def => [ 456, { ghi => "jkl" }, "mno" ] };
wrap('server.cfg', $hash1);
...
# host 2
use Net::Objwrap 'unwrap';
my $hash2 = unwrap('server.cfg');
print $hash2->{abc}; # "123"
$hash2->{def}[2] = "pqr"; # updates $hash1 on host1
print delete $hash2->{def}[1]{ghi}; # "jkl", updates $hash1 on host1Remote method calls
Method calls on the proxy object are propagated to the remote object, affecting the remote object and returning the result of the call.
# host 1
use Net::Objwrap 'wrap';
sub Foofie::new { bless \$_[1], 'Foofie' }
sub Foofie::blerp {my $self=shift;wantarray ? (5,6,7,$$self) : ++$$self}
wrap('server.cfg', Foofie->new(17));
# host 2
use Net::Objwrap 'unwrap';
my $foo = unwrap('server.cfg');
my @x = $foo->blerp; # (5,6,7,17)
my $x = $foo->blerp; # 18overload'ed operators
Any overloading that is enabled for a remote object will occur for the proxy as well.
# host 1
use Net::Objwrap 'wrap';
my $obj = Barfie->new(2,5);
wrap('server.cfg',$obj);
package Barfie;
use overload '+=',sub{$_+=$_[1] for @{$_[0]->{vals}};$_[0]}, fallback => 1;
sub new {
my $pkg = shift;
bless { vals => [ @_ ] }, $pkg;
}
sub prod { my $self=shift; my $z=1; $z*=$_ for @{$self->{vals}}; $z }
# host 2
use Net::Objwrap 'unwrap';
my $obj = unwrap('server.cfg');
print $obj->prod; # 2 * 5 => 10
$obj += -4;
print $obj->prod; # 6 * 9 => 54FUNCTIONS
wrap
wrap($config_filename,@object)
wrap(\%opts,$config_filename,@object)
Creates a TCP server on the local machine that provides proxy access to one or more given object, and writes information to the given filename about how to connect to the server.
This function will die if there are any issues establishing the server.
unwrap
$proxy = unwrap($config_filename)
@proxies = unwrap($config_filename)
Connects to the server specified by information in the given configuration file name, and returns a proxy to one or more remote objects that were identified in the server's wrap call.
ref
reftype
$ref = Net::Objwrap::ref($proxy)
$reftype = Net::Objwrap::reftype($proxy)
Returns the "real" object types. That is, the object types of the object on the remote server.
BUGS AND LIMITATIONS
Overhead
Every interrogation and manipulation of an object incurs network overhead.
Server runs in a separate process from the process that created the object
Once a client connects to the object wrapper server, the interaction with the client is handled in a child process, and the client is interacting with a copy of the original object. Unless the object takes care to be synchronized across different processes (like Forks::Queue does) or stashes its contents in an external data store like shared memory or a database, programs running on different hosts or in different processes on the same host will not be working with the same object.
It is possible that a future version of this distribution could use threads and shared objects to mitigate this limitation.
LICENSE AND COPYRIGHT
Copyright (c) 2017, Marty O'Brien.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.
See http://dev.perl.org/licenses/ for more information.