1 package Object::Remote;
3 use Object::Remote::MiniLoop;
4 use Object::Remote::Handle;
5 use Object::Remote::Logging qw( :log );
6 use Module::Runtime qw(use_module);
8 our $VERSION = '0.002003'; # 0.2.3
11 my ($class, $on, @args) = @_;
12 my $conn = __PACKAGE__->connect($on);
13 log_trace { sprintf("constructing instance of $class on connection for child pid of %i", $conn->child_pid) };
14 return $conn->remote_object(class => $class, args => \@args);
18 my ($class, $on, $name) = @_;
19 my $conn = __PACKAGE__->connect($on);
20 log_trace { "Invoking remote \$class->can('$name')" };
21 return $conn->remote_sub(join('::', $class, $name));
26 Object::Remote::Handle->new(@_)->proxy;
30 my ($class, $to) = @_;
31 use_module('Object::Remote::Connection')->maybe::start::new_from_spec($to);
35 our $Current_Loop ||= Object::Remote::MiniLoop->new
42 Object::Remote - Call methods on objects in other processes or on other hosts
46 Creating a connection:
50 my $conn = Object::Remote->connect('myserver'); # invokes ssh
54 my $capture = IPC::System::Simple->can::on($conn, 'capture');
56 warn $capture->('uptime');
60 my $eval = Eval::WithLexicals->new::on($conn);
62 $eval->eval(q{my $x = `uptime`});
64 warn $eval->eval(q{$x});
66 Importantly: 'myserver' only requires perl 5.8+ - no non-core modules need to
67 be installed on the far side, Object::Remote takes care of it for you!
71 Object::Remote allows you to create an object in another process - usually
72 one running on another machine you can connect to via ssh, although there
73 are other connection mechanisms available.
75 The idea here is that in many cases one wants to be able to run a piece of
76 code on another machine, or perhaps many other machines - but without having
77 to install anything on the far side.
83 The "main" API, which provides the L</connect> method to create a connection
84 to a remote process/host, L</new::on> to create an object on a connection,
85 and L</can::on> to retrieve a subref over a connection.
87 =head2 Object::Remote::Connection
89 The object representing a connection, which provides the
90 L<Object::Remote::Connection/remote_object> and
91 L<Object::Remote::Connection/remote_sub> methods that are used by
92 L</new::on> and L</can::on> to return proxies for objects and subroutines
95 =head2 Object::Remote::Future
97 Code for dealing with asynchronous operations, which provides the
98 L<Object::Remote::Future/start::method> syntax for calling a possibly
99 asynchronous method without blocking, and
100 L<Object::Remote::Future/await_future> and L<Object::Remote::Future/await_all>
101 to block until an asynchronous call completes or fails.
107 my $conn = Object::Remote->connect('-'); # fork()ed connection
109 my $conn = Object::Remote->connect('myserver'); # connection over ssh
111 my $conn = Object::Remote->connect('user@myserver'); # connection over ssh
113 my $conn = Object::Remote->connect('root@'); # connection over sudo
117 my $eval = Eval::WithLexicals->new::on($conn);
119 my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect
121 my $obj = Some::Class->new::on($conn, %args); # with constructor arguments
125 my $hostname = Sys::Hostname->can::on($conn, 'hostname');
127 my $hostname = Sys::Hostname->can::on('myserver', 'hostname');
133 =item OBJECT_REMOTE_PERL_BIN
135 When starting a new Perl interpreter the contents of this environment
136 variable will be used as the path to the executable. If the variable
137 is not set the path is 'perl'
139 =item OBJECT_REMOTE_LOG_LEVEL
141 Setting this environment variable will enable logging and send all log messages
142 at the specfied level or higher to STDERR. Valid level names are: trace debug
143 verbose info warn error fatal
145 =item OBJECT_REMOTE_LOG_FORMAT
147 The format of the logging output is configurable. By setting this environment variable
148 the format can be controlled via printf style position variables. See
149 L<Object::Remote::Logging::Logger>.
151 =item OBJECT_REMOTE_LOG_FORWARDING
153 Forward log events from remote connections to the local Perl interpreter. Set to 1 to enable
154 this feature which is disabled by default. See L<Object::Remote::Logging>.
156 =item OBJECT_REMOTE_LOG_SELECTIONS
158 Space seperated list of class names to display logs for if logging output is enabled. Default
159 value is "Object::Remote::Logging" which selects all logs generated by Object::Remote.
160 See L<Object::Remote::Logging::Router>.
166 IRC: #web-simple on irc.perl.org
170 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
174 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
176 triddle - Tyler Riddle (cpan:TRIDDLE) <t.riddle@shadowcat.co.uk>
180 Parts of this code were paid for by
182 Socialflow L<http://www.socialflow.com>
184 Shadowcat Systems L<http://www.shadow.cat>
188 Copyright (c) 2012 the Object::Remote L</AUTHOR>, L</CONTRIBUTORS> and
189 L</SPONSORS> as listed above.
193 This library is free software and may be distributed under the same terms