NAME

Net::Objwrap - allow arbitrary access to Perl object over network

VERSION

0.09

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 1

DESCRIPTION

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 host1

Remote 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;   # 18

overload'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 => 54

FUNCTIONS

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.

cpanm Forks::Queue

perl -MCPAN -e shell
install Forks::Queue