1Object::Remote(3) User Contributed Perl Documentation Object::Remote(3)
2
6 Object::Remote - Call methods on objects in other processes or on other
7 hosts
8
10 Creating a connection:
11 use Object::Remote;
13 my $conn = Object::Remote->connect('myserver'); # invokes ssh
15 Calling a subroutine:
17 my $capture = IPC::System::Simple->can::on($conn, 'capture');
19 warn $capture->('uptime');
21 Using an object:
23 my $eval = Eval::WithLexicals->new::on($conn);
25 $eval->eval(q{my $x = `uptime`});
27 warn $eval->eval(q{$x});
29 Importantly: 'myserver' only requires perl 5.8+ - no non-core modules
31 need to be installed on the far side, Object::Remote takes care of it
32 for you!
33
35 Object::Remote allows you to create an object in another process -
36 usually one running on another machine you can connect to via ssh,
37 although there are other connection mechanisms available.
38 The idea here is that in many cases one wants to be able to run a piece
40 of code on another machine, or perhaps many other machines - but
41 without having to install anything on the far side.
42
44 Object::Remote
45 The "main" API, which provides the "connect" method to create a
46 connection to a remote process/host, "new::on" to create an object on a
47 connection, and "can::on" to retrieve a subref over a connection.
48 Object::Remote::Connection
50 The object representing a connection, which provides the
51 "remote_object" in Object::Remote::Connection and "remote_sub" in
52 Object::Remote::Connection methods that are used by "new::on" and
53 "can::on" to return proxies for objects and subroutines on the far
54 side.
55 Object::Remote::Future
57 Code for dealing with asynchronous operations, which provides the
58 "start::method" in Object::Remote::Future syntax for calling a possibly
59 asynchronous method without blocking, and "await_future" in
60 Object::Remote::Future and "await_all" in Object::Remote::Future to
61 block until an asynchronous call completes or fails.
62
64 connect
65 my $conn = Object::Remote->connect('-'); # fork()ed connection
66 my $conn = Object::Remote->connect('myserver'); # connection over ssh
68 my $conn = Object::Remote->connect('user@myserver'); # connection over ssh
70 my $conn = Object::Remote->connect('root@'); # connection over sudo
72 new::on
74 my $eval = Eval::WithLexicals->new::on($conn);
75 my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect
77 my $obj = Some::Class->new::on($conn, %args); # with constructor arguments
79 can::on
81 my $hostname = Sys::Hostname->can::on($conn, 'hostname');
82 my $hostname = Sys::Hostname->can::on('myserver', 'hostname');
84
86 OBJECT_REMOTE_PERL_BIN
87 When starting a new Perl interpreter the contents of this
88 environment variable will be used as the path to the executable. If
89 the variable is not set the path is 'perl'
90 OBJECT_REMOTE_LOG_LEVEL
92 Setting this environment variable will enable logging and send all
93 log messages at the specfied level or higher to STDERR. Valid level
94 names are: trace debug verbose info warn error fatal
95 OBJECT_REMOTE_LOG_FORMAT
97 The format of the logging output is configurable. By setting this
98 environment variable the format can be controlled via printf style
99 position variables. See Object::Remote::Logging::Logger.
100 OBJECT_REMOTE_LOG_FORWARDING
102 Forward log events from remote connections to the local Perl
103 interpreter. Set to 1 to enable this feature which is disabled by
104 default. See Object::Remote::Logging.
105 OBJECT_REMOTE_LOG_SELECTIONS
107 Space seperated list of class names to display logs for if logging
108 output is enabled. Default value is "Object::Remote::Logging" which
109 selects all logs generated by Object::Remote. See
110 Object::Remote::Logging.
111
113 Large data structures
114 Object::Remote communication is encapsalated with JSON and values
115 passed to remote objects will be serialized with it. When sending
116 large data structures or data structures with a lot of deep
117 complexity (hashes in arrays in hashes in arrays) the processor
118 time and memory requirements for serialization and deserialization
119 can be either painful or unworkable. During times of serialization
120 the local or remote nodes will be blocked potentially causing all
121 remote interpreters to block as well under worse case conditions.
122 To help deal with this issue it is possible to configure resource
124 ulimits for a Perl interpreter that is executed by Object::Remote.
125 See "Object::Remote::Role::Connector::PerlInterpreter" for details
126 on the perl_command attribute.
127 User can starve run loop of execution opportunities
129 The Object::Remote run loop is responsible for performing I/O and
130 managing timers in a cooperative multitasing way but it can only do
131 these tasks when the user has given control to Object::Remote.
132 There are times when Object::Remote must wait for the user to
133 return control to the run loop and during these times no I/O can be
134 performed and no timers can be executed.
135 As an end user of Object::Remote if you depend on connection
137 timeouts, the watch dog or timely results from remote objects then
138 be sure to hand control back to Object::Remote as soon as you can.
139 Run loop favors certain filehandles/connections
141 High levels of load can starve timers of execution opportunities
142 These are issues that only become a problem at large scales. The
143 end result of these two issues is quite similiar: some remote
144 objects may block while the local run loop is either busy servicing
145 a different connection or is not executing because control has not
146 yet been returned to it. For the same reasons timers may not get an
147 opportunity to execute in a timely way.
148 Internally Object::Remote uses timers managed by the run loop for
150 control tasks. Under high load the timers can be preempted by
151 servicing I/O on the filehandles and execution can be severely
152 delayed. This can lead to connection watchdogs not being updated or
153 connection timeouts taking longer than configured.
154 Deadlocks
156 Deadlocks can happen quite easily because of flaws in programs that
157 use Object::Remote or Object::Remote itself so the
158 "Object::Remote::WatchDog" is available. When used the run loop
159 will periodically update the watch dog object on the remote Perl
160 interpreter. If the watch dog goes longer than the configured
161 interval with out being updated then it will terminate the Perl
162 process. The watch dog will terminate the process even if a
163 deadlock condition has occured.
164 Log forwarding at scale can starve timers of execution opportunities
166 Currently log forwarding can be problematic at large scales. When
167 there is a large amount of log events the load produced by log
168 forwarding can be high enough that it starves the timers and the
169 remote object watch dogs (if in use) don't get updated in timely
170 way causing them to erroneously terminate the Perl process. If the
171 watch dog is not in use then connection timeouts can be delayed but
172 will execute when load settles down enough.
173 Because of the load related issues Object::Remote disables log
175 forwarding by default. See "Object::Remote::Logging" for
176 information on log forwarding.
177
179 IRC: #web-simple on irc.perl.org
180
182 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
183
185 bfwg - Colin Newell (cpan:NEWELLC) <colin.newell@gmail.com>
186 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
188 triddle - Tyler Riddle (cpan:TRIDDLE) <t.riddle@shadowcat.co.uk>
190
192 Parts of this code were paid for by
193 Socialflow L<http://www.socialflow.com>
195 Shadowcat Systems L<http://www.shadow.cat>
197
199 Copyright (c) 2012 the Object::Remote "AUTHOR", "CONTRIBUTORS" and
200 "SPONSORS" as listed above.
201
203 This library is free software and may be distributed under the same
204 terms as perl itself.
205perl v5.36.0 2023-01-20 Object::Remote(3)