1Object::Remote(3)     User Contributed Perl Documentation    Object::Remote(3)
2
3
4

NAME

6       Object::Remote - Call methods on objects in other processes or on other
7       hosts
8

SYNOPSIS

10       Creating a connection:
11
12         use Object::Remote;
13
14         my $conn = Object::Remote->connect('myserver'); # invokes ssh
15
16       Calling a subroutine:
17
18         my $capture = IPC::System::Simple->can::on($conn, 'capture');
19
20         warn $capture->('uptime');
21
22       Using an object:
23
24         my $eval = Eval::WithLexicals->new::on($conn);
25
26         $eval->eval(q{my $x = `uptime`});
27
28         warn $eval->eval(q{$x});
29
30       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

DESCRIPTION

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
39       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

COMPONENTS

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
49   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
56   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

METHODS

64   connect
65         my $conn = Object::Remote->connect('-'); # fork()ed connection
66
67         my $conn = Object::Remote->connect('myserver'); # connection over ssh
68
69         my $conn = Object::Remote->connect('user@myserver'); # connection over ssh
70
71         my $conn = Object::Remote->connect('root@'); # connection over sudo
72
73   new::on
74         my $eval = Eval::WithLexicals->new::on($conn);
75
76         my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect
77
78         my $obj = Some::Class->new::on($conn, %args); # with constructor arguments
79
80   can::on
81         my $hostname = Sys::Hostname->can::on($conn, 'hostname');
82
83         my $hostname = Sys::Hostname->can::on('myserver', 'hostname');
84

ENVIRONMENT

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
91       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
96       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
101       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
106       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

KNOWN ISSUES

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
123           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
128       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
136           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
140       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
149           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
155       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
165       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
174           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

SUPPORT

179       IRC: #web-simple on irc.perl.org
180

AUTHOR

182       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
183

CONTRIBUTORS

185       bfwg - Colin Newell (cpan:NEWELLC) <colin.newell@gmail.com>
186
187       phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
188
189       triddle - Tyler Riddle (cpan:TRIDDLE) <t.riddle@shadowcat.co.uk>
190

SPONSORS

192       Parts of this code were paid for by
193
194         Socialflow L<http://www.socialflow.com>
195
196         Shadowcat Systems L<http://www.shadow.cat>
197
199       Copyright (c) 2012 the Object::Remote "AUTHOR", "CONTRIBUTORS" and
200       "SPONSORS" as listed above.
201

LICENSE

203       This library is free software and may be distributed under the same
204       terms as perl itself.
205
206
207
208perl v5.36.0                      2023-01-20                 Object::Remote(3)
Impressum