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_debug { 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 return $conn->remote_sub(join('::', $class, $name));
29 Object::Remote::Handle->new(@_)->proxy;
33 my ($class, $to) = @_;
34 use_module('Object::Remote::Connection')->maybe::start::new_from_spec($to);
38 our $Current_Loop ||= Object::Remote::MiniLoop->new
45 Object::Remote - Call methods on objects in other processes or on other hosts
49 Creating a connection:
53 my $conn = Object::Remote->connect('myserver'); # invokes ssh
57 my $capture = IPC::System::Simple->can::on($conn, 'capture');
59 warn $capture->('uptime');
63 my $eval = Eval::WithLexicals->new::on($conn);
65 $eval->eval(q{my $x = `uptime`});
67 warn $eval->eval(q{$x});
69 Importantly: 'myserver' only requires perl 5.8+ - no non-core modules need to
70 be installed on the far side, Object::Remote takes care of it for you!
74 Object::Remote allows you to create an object in another process - usually
75 one running on another machine you can connect to via ssh, although there
76 are other connection mechanisms available.
78 The idea here is that in many cases one wants to be able to run a piece of
79 code on another machine, or perhaps many other machines - but without having
80 to install anything on the far side.
86 The "main" API, which provides the L</connect> method to create a connection
87 to a remote process/host, L</new::on> to create an object on a connection,
88 and L</can::on> to retrieve a subref over a connection.
90 =head2 Object::Remote::Connection
92 The object representing a connection, which provides the
93 L<Object::Remote::Connection/remote_object> and
94 L<Object::Remote::Connection/remote_sub> methods that are used by
95 L</new::on> and L</can::on> to return proxies for objects and subroutines
98 =head2 Object::Remote::Future
100 Code for dealing with asynchronous operations, which provides the
101 L<Object::Remote::Future/start::method> syntax for calling a possibly
102 asynchronous method without blocking, and
103 L<Object::Remote::Future/await_future> and L<Object::Remote::Future/await_all>
104 to block until an asynchronous call completes or fails.
110 my $conn = Object::Remote->connect('-'); # fork()ed connection
112 my $conn = Object::Remote->connect('myserver'); # connection over ssh
114 my $conn = Object::Remote->connect('user@myserver'); # connection over ssh
116 my $conn = Object::Remote->connect('root@'); # connection over sudo
120 my $eval = Eval::WithLexicals->new::on($conn);
122 my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect
124 my $obj = Some::Class->new::on($conn, %args); # with constructor arguments
128 my $hostname = Sys::Hostname->can::on($conn, 'hostname');
130 my $hostname = Sys::Hostname->can::on('myserver', 'hostname');
134 IRC: #web-simple on irc.perl.org
138 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
142 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
146 Parts of this code were paid for by
148 Socialflow L<http://www.socialflow.com>
150 Shadowcat Systems L<http://www.shadow.cat>
154 Copyright (c) 2012 the Object::Remote L</AUTHOR>, L</CONTRIBUTORS> and
155 L</SPONSORS> as listed above.
159 This library is free software and may be distributed under the same terms