Object::Remote(3)

📦
version 0.005001 · 7 versions
, in epel 10

🦋 NAME 🦋

Object::Remote — bestie, this is the manual page for calling methods on objects in totally different processes or even on other hosts ✨ (and yes, this page lives in that "User Contributed Perl Documentation" section, iykyk 💅)

🌸 SYNOPSIS 🌸

Okay so first you make a connection:

use Object::Remote;

my $conn = Object::Remote->connect('myserver'); # invokes ssh

Then you can call a subroutine:

my $capture = IPC::System::Simple->can::on($conn, 'capture');

warn $capture->('uptime');

Or use a whole object:

my $eval = Eval::WithLexicals->new::on($conn);

$eval->eval(q{my $x = `uptime`});

warn $eval->eval(q{$x});
🔥 the important part, do not skip: 'myserver' only requires perl 5.8+ — literally no non-core modules need to be installed on the far side, because Object::Remote handles all of that for you. No cap, that's the whole magic trick 🎩✨

💖 DESCRIPTION 💖

Object::Remote lets you create an object in another process — usually one running on another machine you can connect to via ssh, though there are other connection mechanisms available too.

The vibe here is: sometimes you wanna run a piece of code on another machine (or like, many other machines 👀) but without having to install anything on the far side. That's it. That's the dream. And Object::Remote makes it happen.

🧚 COMPONENTS 🧚

Here's the friend group:

💫 Object::Remote

The "main" API — it provides the connect method to create a connection to a remote process/host, new::on to create an object on a connection, and can::on to retrieve a subref over a connection. This is the one you'll be hanging out with the most.

🔗 Object::Remote::Connection

The object that represents a connection. It provides the remote_object in Object::Remote::Connection and remote_sub in Object::Remote::Connection methods, which are what new::on and can::on use to return proxies for objects and subroutines on the far side.

⏳ Object::Remote::Future

Code for dealing with asynchronous operations. It provides the start::method in Object::Remote::Future syntax for calling a possibly asynchronous method without blocking (slay), and await_future in Object::Remote::Future plus await_all in Object::Remote::Future to block until an asynchronous call completes or fails. Very "wait for it…" energy 💅

💅 METHODS 💅

📡 connect

Four flavors, pick your fighter:

my $conn = Object::Remote->connect('-'); # fork()ed connection

my $conn = Object::Remote->connect('myserver'); # connection over ssh

my $conn = Object::Remote->connect('user@myserver'); # connection over ssh

my $conn = Object::Remote->connect('root@'); # connection over sudo

✨ new::on

my $eval = Eval::WithLexicals->new::on($conn);

my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect

my $obj = Some::Class->new::on($conn, %args); # with constructor arguments

Yes bestie, you can do an implicit connect just by passing 'myserver' directly. Convenient AF.

🫶 can::on

my $hostname = Sys::Hostname->can::on($conn, 'hostname');

my $hostname = Sys::Hostname->can::on('myserver', 'hostname');

Retrieve a subref over a connection. Iconic behavior.

🌈 ENVIRONMENT 🌈

These are the environment variables that change how Object::Remote behaves:

  • OBJECT_REMOTE_PERL_BIN — When starting a new Perl interpreter, the contents of this environment variable will be used as the path to the executable. If the variable is not set, the path is 'perl'.
  • OBJECT_REMOTE_LOOP — Forces the loop implementation to the named module. Defaults to " Object::Remote::MiniLoop "; setting this value to " IO::Async::Loop " integrates Object::Remote with IO::Async. (Yes, the spaces inside those quotes are in the original, we keep them, periodt.)
  • OBJECT_REMOTE_LOG_LEVEL — Setting this environment variable will enable logging and send all log messages at the specfied level or higher to STDERR. Valid level names are: trace debug verbose info warn error fatal. (That typo is canon now, we don't fix it, we stan it ✨)
  • OBJECT_REMOTE_LOG_FORMAT — The format of the logging output is configurable. By setting this environment variable, the format can be controlled via printf style position variables. See Object::Remote::Logging::Logger.
  • OBJECT_REMOTE_LOG_FORWARDING — Forward log events from remote connections to the local Perl interpreter. Set to 1 to enable this feature which is disabled by default. See Object::Remote::Logging.
  • OBJECT_REMOTE_LOG_SELECTIONS — Space seperated list of class names to display logs for if logging output is enabled. Default value is "Object::Remote::Logging" which selects all logs generated by Object::Remote. See Object::Remote::Logging. (Another typo, another slay 💀)

💀 KNOWN ISSUES 💀

Okay bestie, this is the "read before you wreck yourself" section. Not everything is sunshine and rainbows 🌈😭

🗃️ Large data structures

Object::Remote communication is encapsalated with JSON, and values passed to remote objects will be serialized with it. When sending large data structures or data structures with a lot of deep complexity (hashes in arrays in hashes in arrays), the processor time and memory requirements for serialization and deserialization can be either painful or unworkable. During times of serialization, the local or remote nodes will be blocked, potentially causing all remote interpreters to block as well under worse case conditions.

To help deal with this issue, it is possible to configure resource ulimits for a Perl interpreter that is executed by Object::Remote. See "Object::Remote::Role::Connector::PerlInterpreter" for details on the perl_command attribute.

⚠️ tl;dr — don't yeet your gigantic deeply-nested data structure at this and expect it to be fine. It might not be fine. It might be very not fine.

🌀 User can starve run loop of execution opportunities

The Object::Remote run loop is responsible for performing I/O and managing timers in a cooperative multitasing way — but it can only do these tasks when the user has given control to Object::Remote. There are times when Object::Remote must wait for the user to return control to the run loop, and during these times no I/O can be performed and no timers can be executed.

As an end user of Object::Remote, if you depend on connection timeouts, the watch dog, or timely results from remote objects, then be sure to hand control back to Object::Remote as soon as you can. Fr fr, don't ghost it.

🔌 Run loop favors certain filehandles/connections

(This one's just a heading in the original, bestie — we're keeping it exactly as it appears, no invented details added.)

📉 High levels of load can starve timers of execution opportunities

These are issues that only become a problem at large scales. The end result of these two issues is quite similiar: some remote objects may block while the local run loop is either busy servicing a different connection or is not executing because control has not yet been returned to it. For the same reasons, timers may not get an opportunity to execute in a timely way.

Internally, Object::Remote uses timers managed by the run loop for control tasks. Under high load, the timers can be preempted by servicing I/O on the filehandles and execution can be severely delayed. This can lead to connection watchdogs not being updated or connection timeouts taking longer than configured.

🔒 Deadlocks

Deadlocks can happen quite easily because of flaws in programs that use Object::Remote or in Object::Remote itself — so the "Object::Remote::WatchDog" is available. When used, the run loop will periodically update the watch dog object on the remote Perl interpreter. If the watch dog goes longer than the configured interval without being updated, then it will terminate the Perl process. The watch dog will terminate the process even if a deadlock condition has occured. 😬

📢 Log forwarding at scale can starve timers of execution opportunities

Currently log forwarding can be problematic at large scales. When there is a large amount of log events, the load produced by log forwarding can be high enough that it starves the timers, and the remote object watch dogs (if in use) don't get updated in a timely way, causing them to erroneously terminate the Perl process. If the watch dog is not in use, then connection timeouts can be delayed but will execute when load settles down enough.

Because of the load related issues, Object::Remote disables log forwarding by default. See "Object::Remote::Logging" for information on log forwarding.

🧩 IO::Async::Loop fails on nested connections

The tests " t/bridged.t " and " t/chained.t " fail when using the IO::Async loop, meaning that using remote objects from the remote fails under IO::Async. (Fixes welcome!) 🙏

🫶 SUPPORT 🫶

Come vibe with us on IRC: #web-simple on irc.perl.org 💬

👑 AUTHOR 👑

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

🌟 CONTRIBUTORS 🌟

  • bfwg — Colin Newell (cpan:NEWELLC) <colin.newell@gmail.com>
  • phaylon — Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
  • triddle — Tyler Riddle (cpan:TRIDDLE) <t.riddle@shadowcat.co.uk>

⭐ SPONSORS ⭐

Parts of this code were paid for by:

Copyright (c) 2012 the Object::Remote "AUTHOR", "CONTRIBUTORS" and "SPONSORS" as listed above.

🍓 LICENSE 🍓

This library is free software and may be distributed under the same terms as perl itself. 💖

🌸 okay that's the whole page bestie — written by perl v5.40.2 on 2026-07-16, and yes, Object::Remote(3) is the manual name, we just folded it in all cute near the top instead of copying the header line. mwah 💋✨
📦 where this page comes from