package Object::Remote; use Object::Remote::MiniLoop; use Object::Remote::Handle; use Object::Remote::Logging qw( :log ); use Module::Runtime qw(use_module); our $VERSION = '0.002003'; # 0.2.3 sub new::on { my ($class, $on, @args) = @_; my $conn = __PACKAGE__->connect($on); log_trace { sprintf("constructing instance of $class on connection for child pid of %i", $conn->child_pid) }; return $conn->remote_object(class => $class, args => \@args); } sub can::on { my ($class, $on, $name) = @_; my $conn = __PACKAGE__->connect($on); log_trace { "Invoking remote \$class->can('$name')" }; return $conn->remote_sub(join('::', $class, $name)); } sub new { shift; Object::Remote::Handle->new(@_)->proxy; } sub connect { my ($class, $to) = @_; use_module('Object::Remote::Connection')->maybe::start::new_from_spec($to); } sub current_loop { our $Current_Loop ||= Object::Remote::MiniLoop->new } 1; =head1 NAME Object::Remote - Call methods on objects in other processes or on other hosts =head1 SYNOPSIS Creating a connection: use Object::Remote; my $conn = Object::Remote->connect('myserver'); # invokes ssh Calling a subroutine: my $capture = IPC::System::Simple->can::on($conn, 'capture'); warn $capture->('uptime'); Using an object: my $eval = Eval::WithLexicals->new::on($conn); $eval->eval(q{my $x = `uptime`}); warn $eval->eval(q{$x}); Importantly: 'myserver' only requires perl 5.8+ - no non-core modules need to be installed on the far side, Object::Remote takes care of it for you! =head1 DESCRIPTION Object::Remote allows you to create an object in another process - usually one running on another machine you can connect to via ssh, although there are other connection mechanisms available. The idea here is that in many cases one wants to be able to run a piece of code on another machine, or perhaps many other machines - but without having to install anything on the far side. =head1 COMPONENTS =head2 Object::Remote The "main" API, which provides the L method to create a connection to a remote process/host, L to create an object on a connection, and L to retrieve a subref over a connection. =head2 Object::Remote::Connection The object representing a connection, which provides the L and L methods that are used by L and L to return proxies for objects and subroutines on the far side. =head2 Object::Remote::Future Code for dealing with asynchronous operations, which provides the L syntax for calling a possibly asynchronous method without blocking, and L and L to block until an asynchronous call completes or fails. =head1 METHODS =head2 connect my $conn = Object::Remote->connect('-'); # fork()ed connection my $conn = Object::Remote->connect('myserver'); # connection over ssh my $conn = Object::Remote->connect('user@myserver'); # connection over ssh my $conn = Object::Remote->connect('root@'); # connection over sudo =head2 new::on my $eval = Eval::WithLexicals->new::on($conn); my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect my $obj = Some::Class->new::on($conn, %args); # with constructor arguments =head2 can::on my $hostname = Sys::Hostname->can::on($conn, 'hostname'); my $hostname = Sys::Hostname->can::on('myserver', 'hostname'); =head1 ENVIRONMENT =over 4 =item OBJECT_REMOTE_PERL_BIN When starting a new Perl interpreter the contents of this environment variable will be used as the path to the executable. If the variable is not set the path is 'perl' =item OBJECT_REMOTE_LOG_LEVEL Setting this environment variable will enable logging and send all log messages at the specfied level or higher to STDERR. Valid level names are: trace debug verbose info warn error fatal =item OBJECT_REMOTE_LOG_FORMAT The format of the logging output is configurable. By setting this environment variable the format can be controlled via printf style position variables. See L. =item OBJECT_REMOTE_LOG_FORWARDING Forward log events from remote connections to the local Perl interpreter. Set to 1 to enable this feature which is disabled by default. See L. =item OBJECT_REMOTE_LOG_SELECTIONS Space seperated list of class names to display logs for if logging output is enabled. Default value is "Object::Remote::Logging" which selects all logs generated by Object::Remote. See L. =back =head1 SUPPORT IRC: #web-simple on irc.perl.org =head1 AUTHOR mst - Matt S. Trout (cpan:MSTROUT) =head1 CONTRIBUTORS phaylon - Robert Sedlacek (cpan:PHAYLON) triddle - Tyler Riddle (cpan:TRIDDLE) =head1 SPONSORS Parts of this code were paid for by Socialflow L Shadowcat Systems L =head1 COPYRIGHT Copyright (c) 2012 the Object::Remote L, L and L as listed above. =head1 LICENSE This library is free software and may be distributed under the same terms as perl itself. =cut