NAME
RMI - Remote Method Invocation with transparent proxies
SYNOPSIS
#process 1: an example server on host "myserver"
use RMI::Server::Tcp;
my $s = RMI::Server::Tcp->new(port => 1234);
$s->run;
#process 2: an example client
use RMI::Client::Tcp;
my $c = RMI::Client::Tcp->new(
host => 'myserver',
port => 1234,
);
$c->call_use('IO::File');
$r = $c->call_class_method('IO::File','new','/etc/passwd');
$line1 = $r->getline; # works as an object
$line2 = <$r>; # works as a file handle
@rest = <$r>; # detects scalar/list context correctly
$r->isa('IO::File'); # transparent in standard ways
$r->can('getline');
ref($r) eq 'RMI::ProxyObject'; # the only sign this isn't a real IO::File...
# (see RMI::Client's use_remote() to fix this)DESCRIPTION
RMI stands for Remote Method Invocation. The RMI modules allow one process to have virtual object "stubs" which are proxies for real objects in another process. When methods are invoked on the proxy, the method actually runs in the other process. When results are returned, those values may also be proxies for the real items in the other process. Parameters from the client are also automatically proxied on the server side during method execution.
In addition to invoking methods on proxy objects trasparently, an RMI::Client can invoke class methods, regular function calls, and other Perl functionaity on the remote server. Calls like these are typically the first step to obtain a remote object in the first place. This is different than implementations in other languages, which typically require that a server have limited and specific objects it returns, with all further proxying happening through them.
The procedure typically goes as follows:
1. a server is started which has access to some objects or data which is of value
2. a client connects to that server, and asks that it execute code on its behalf
3. the results returned may contain objects or other references, which the client recieves as proxies which "seem like" the real thing
4. further interaction with the returned proxy objects/refs automatically make calls through the client to the server internally
METHODS
The RMI module has no public methods of its own.
See RMI::Client and RMI::Server for detailed API information and examples.
See RMI::ProxyObject and RMI::ProxyReference for details on behavior of proxies.
See RMI::Node for internals and details on the wire protocol.
PROXY OBJECTS AND REFERENCES
A proxy object is an object on one "side" of an RMI connection which represents an object which really exists on the other side. When an RMI::Client calls a method on its associated RMI::Server, and that method returns a reference of any kind, a proxy is made on the client side, rather than a copy. The proxy object appears to be a reference to the real object, but internally it engages in messaging across the client to the server for all method calls, dereferencing, etc. It contains no actual data, and implements no actual methods calls.
By the same token, when a client passes objects or other references to the server as parameters to a method call, the server generates a proxy for those objects, so that the remote method call may "call back" the client for detailed access to the objects it passed.
The choice to proxy by default rather than generate a copy on the remote side by default is distinct from some remoting systems. It is, of course, possible to explicitly ask the server to serialize a given object, but because a serialized object may not behave the same way when it has lost its environment, this is not the default behavior.
Proxied objects are only revealed as such by a call to ref(), which reveals the object is actually an RMI::ProxyObject. Calls to isa() and can() are proxied across the connection to the remote side, and will maintain the correct API. Remote objects which implement AUTOLOAD for their API will still work correctly.
Plain proxied references, and as well as objects, are "tied" so as to operate as the correct type of Perl primitive. SCALAR, ARRAY, HASH, CODE and GLOB/IO references, blessed or otherwise, will be proxied as the same type of reference on the other side. The RMI system uses Perl's "tie" functionality to do this.
GARBAGE COLLECTION
Until a proxy is destroyed, the side which sent the item will keep an additional reference to the real item, both to facilitate proxying, and to prevent garbage collection. Upon destruction on the reciever side, a message is sent to the sender to expire its link to the item in question, and allow garbage collection if no other references exist.
DEBUGGING RMI CODE
When the RMI_DEBUG environment variable set to 1, the RMI modules will emit detailed information to STDERR during all "conversations" between itself and the remote side. This works for RMI::Client, RMI::Server, and anything else which inherits from RMI::Node.
This value is available inside the application as $RMI::DEBUG.
The package variable $RMI::DEBUG_MSG_PREFIX will be printed at the beginning of each message. Changing this value allows the viewer to separate both halves of a conversation. (The test suite for RMI sets this value to ' ' for the server side, causing server activity to be indented relative to client activity in the debug output.)
RMI_DEBUG=1 perl -I lib t/01_*.tSECURITY
no inherent security is built-in
If you require restrctions on what the server provides, a custom sub-class should be written around the server to restrict the types of calls it will receive.
This is wise whenever the server is exposed to an untrusted network.
LIMITS TO TRANSPARENCY
calls to ref($my_proxy) reveal the true class RMI::ProxyObject
Proxied objects/references reveal that they are proxies when ref($o) is called on them, unless the entire package is proxied with ->use_remote.
Calls to ->isa() still operate as though the proxy were the object it represents. Code which goes around the isa() override to UNIVERSAL::isa() will circumvent the illusion as well.
remote objects do not stringify to matche the original object
Like ref(), this reveals the actual reference (and possibly class) of the proxy, not the object which is proxied.
calls to use_remote() does not auto-proxy all package variables
Calls to "use_remote" will proxy subroutine calls, but not package variable access automatically, besides @ISA. If necessary, it must be done explicitly with a call to bind().
the client may not be able to "tie" variables which are proxies
The RMI modules use "tie" on every proxy reference to channel access to the other side. The effect of attempting to tie a proxy reference may destroy its ability to proxy. (This is untested.)
In most cases, applications do not tie a variable created elsewhere because it destroys its prior value. As such this is unlikely to be a problem, but is still technically a hole in transparency.
change to $_[N] values will not affect the original variable
Remote calls to subroutines/methods which modify aliases in @_ directly to tamper with the caller's variables will not work as it would with a local method call.
This is supportable, but adds considerable overhead to support modules which create a side effect which is avoided because it is, mostly, a bad idea.
Perl technically passes an alias to even non-reference values, though the common "my ($v1,$v2) = @_;" makes a copy which safely allows the subroutine to behave as though the values were pass-by-copy.
sub foo {
$_[0]++; # BAD!
}
my $v = 1;
foo($v);
$v == 2; # SURPRISE!If foo() were called via RMI, in the current implementation, $v would still have its original value.
Packages which implement this surprise behavior include Compress::Zlib! If this feature were added the overhead to Compress::Zlib would still make you want to wrap the call...
code which relies on caller() will probably fail
This means that some modules which perform magic during import() may not work as intended.
This problem is prevented in one place automatically by the current RMI implementation: there is custom code to handle exporting of methods into the caller's namespace inside "use_remote".
IMPLEMENTATIONS IN OTHER LANGUAGES
The use of transparent proxy objects goes by the term "RMI" in Java, "Drb" in Ruby, "PYRO" in Python, "Remoting" in .NET.
It is similar in functionality to architectures such as CORBA, SOAP, RPC and DCOM.
None of the above use the same protocols (except Java's RMI has an optional CORBA-related implementation). This module is no exception, sadly. Patches are welcome.
SEE ALSO
RMI::Server, RMI::Client, RMI::Node, RMI::ProxyObject, RMI::ProxyReference, SOAP, RPC
AUTHORS
Scott Smith <sakoht@cpan.org>
COPYRIGHT
Copyright (c) 2008 - 2009 Scott Smith <sakoht@cpan.org> All rights reserved.
LICENSE
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.