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 Object::Remote::Logging->init_logging;
15 my ($class, $on, @args) = @_;
16 my $conn = __PACKAGE__->connect($on);
17 log_trace { sprintf("constructing instance of $class on connection for child pid of %i", $conn->child_pid) };
18 return $conn->remote_object(class => $class, args => \@args);
22 my ($class, $on, $name) = @_;
23 my $conn = __PACKAGE__->connect($on);
24 log_trace { "Invoking remote \$class->can('$name')" };
25 return $conn->remote_sub(join('::', $class, $name));
30 Object::Remote::Handle->new(@_)->proxy;
34 my ($class, $to) = @_;
35 use_module('Object::Remote::Connection')->maybe::start::new_from_spec($to);
39 our $Current_Loop ||= Object::Remote::MiniLoop->new
46 Object::Remote - Call methods on objects in other processes or on other hosts
50 Creating a connection:
54 my $conn = Object::Remote->connect('myserver'); # invokes ssh
58 my $capture = IPC::System::Simple->can::on($conn, 'capture');
60 warn $capture->('uptime');
64 my $eval = Eval::WithLexicals->new::on($conn);
66 $eval->eval(q{my $x = `uptime`});
68 warn $eval->eval(q{$x});
70 Importantly: 'myserver' only requires perl 5.8+ - no non-core modules need to
71 be installed on the far side, Object::Remote takes care of it for you!
75 Object::Remote allows you to create an object in another process - usually
76 one running on another machine you can connect to via ssh, although there
77 are other connection mechanisms available.
79 The idea here is that in many cases one wants to be able to run a piece of
80 code on another machine, or perhaps many other machines - but without having
81 to install anything on the far side.
87 The "main" API, which provides the L</connect> method to create a connection
88 to a remote process/host, L</new::on> to create an object on a connection,
89 and L</can::on> to retrieve a subref over a connection.
91 =head2 Object::Remote::Connection
93 The object representing a connection, which provides the
94 L<Object::Remote::Connection/remote_object> and
95 L<Object::Remote::Connection/remote_sub> methods that are used by
96 L</new::on> and L</can::on> to return proxies for objects and subroutines
99 =head2 Object::Remote::Future
101 Code for dealing with asynchronous operations, which provides the
102 L<Object::Remote::Future/start::method> syntax for calling a possibly
103 asynchronous method without blocking, and
104 L<Object::Remote::Future/await_future> and L<Object::Remote::Future/await_all>
105 to block until an asynchronous call completes or fails.
111 my $conn = Object::Remote->connect('-'); # fork()ed connection
113 my $conn = Object::Remote->connect('myserver'); # connection over ssh
115 my $conn = Object::Remote->connect('user@myserver'); # connection over ssh
117 my $conn = Object::Remote->connect('root@'); # connection over sudo
121 my $eval = Eval::WithLexicals->new::on($conn);
123 my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect
125 my $obj = Some::Class->new::on($conn, %args); # with constructor arguments
129 my $hostname = Sys::Hostname->can::on($conn, 'hostname');
131 my $hostname = Sys::Hostname->can::on('myserver', 'hostname');
137 =item OBJECT_REMOTE_PERL_BIN
139 When starting a new Perl interpreter the contents of this environment
140 variable will be used as the path to the executable. If the variable
141 is not set the path is 'perl'
143 =item OBJECT_REMOTE_LOG_LEVEL
145 Setting this environment variable will enable logging and send all log messages
146 at the specfied level or higher to STDERR. Valid level names are: trace debug
147 verbose info warn error fatal
149 =item OBJECT_REMOTE_LOG_FORMAT
151 The format of the logging output is configurable. By setting this environment variable
152 the format can be controlled via printf style position variables. See
153 L<Object::Remote::Logging::Logger>.
155 =item OBJECT_REMOTE_LOG_FORWARDING
157 Forward log events from remote connections to the local Perl interpreter. Set to 1 to enable
158 this feature which is disabled by default. See L<Object::Remote::Logging>.
160 =item OBJECT_REMOTE_LOG_SELECTIONS
162 Space seperated list of class names to display logs for if logging output is enabled. Default
163 value is "Object::Remote::Logging" which selects all logs generated by Object::Remote.
164 See L<Object::Remote::Logging::Router>.
170 IRC: #web-simple on irc.perl.org
174 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
178 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
180 triddle - Tyler Riddle (cpan:TRIDDLE) <t.riddle@shadowcat.co.uk>
184 Parts of this code were paid for by
186 Socialflow L<http://www.socialflow.com>
188 Shadowcat Systems L<http://www.shadow.cat>
192 Copyright (c) 2012 the Object::Remote L</AUTHOR>, L</CONTRIBUTORS> and
193 L</SPONSORS> as listed above.
197 This library is free software and may be distributed under the same terms