# NAME

Patro - proxy access to remote objects

# SYNOPSIS

```perl
# on machine 1 (server)
use Patro;
my $obj = ...
$config = patronize($obj);
$config->to_file( 'config_file' );
```

```perl
# on machines 2 through n (clients)
use Patro;
my ($proxy) = getProxies('config_file');
...
$proxy->{key} = $val;         # updates $obj->{key} for obj on server
$val = $proxy->method(@args); # calls $obj->method for obj on server
```

# DESCRIPTION

`Patro` is a mechanism for making any Perl reference in one Perl program
accessible is other processes, even processes running on different hosts.
The "proxy" references have the same look and feel as the native references
in the original process, and any manipulation of the proxy reference
will have an effect on the original reference.

## Some important features:

* Hash members and array elements

Accessing or updating hash values or array values on a remote reference
is done with the same syntax as with the local reference:

```perl
# host 1
use Patro;
my $hash1 = { abc => 123, def => [ 456, { ghi => "jkl" }, "mno" ] };
patronize($hash1)->to_file('/network/accessible/file');
...

# host 2
use Patro;
my $hash2 = getProxies('/network/accessible/file');
print $hash2->{abc};                # "123"
$hash2->{def}[2] = "pqr";           # updates $hash1 on host 1
print delete $hash2->{def}[1]{ghi}; # "jkl", updates $hash1 on host1
```

* Remote method calls

Method calls on the proxy object are propagated to the original object,
affecting the remote object and returning the result of the call.

```perl
# host 1
use Patro;
sub Foofie::new { bless \$_[1],'Foofie' }
sub Foofie::blerp { my $self=shift; wantarray ? (5,6,7,$$self) : ++$$self }
patronize(Foofie->new(17))->to_file('/file/accessible/to-host2');
...

# host 2
use Patro;
my $foo = getProxies('/file/accessible/to-host2');
my @x = $foo->blerp;           # (5,6,7,17)
my $x = $foo->blerp;           # 18
```

* Overloaded operators

Any overloaded operations on the original object are supported on the
remote object.

```perl
# host 1
use Patro;
my $obj = Barfie->new(2,5);
patronize($obj)->to_file('/network/file');
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 @{$_[0]->{vals}}; $z }

# host 2
use Patro;
my $proxy = getProxies('/network/file');
print $proxy->prod;      # calls Barfie::prod($obj) on host1, 2 * 5 => 10
$proxy += 4;             # calls Barfie '+=' sub on host1
print $proxy->prod;      # 6 * 9 => 54
```

# FUNCTIONS

## `patronize(@REFS)`

Creates a server on the local machine that provides proxy access to
the given list of references. It returns an object with information
about how to connect to the server. The object has `to_string` and
`to_file` methods to make the connection information available to
other hosts. The output of this method, or its string or file output,
can be used as input to the `getProxies()` function to retrieve
proxies to the shared references.

## `getProxies(CONFIG)`

Connects to a server on another machine, specified in the `CONFIG`
string, and returns proxies to the list of references that are served.