package Object::Remote::Role::Connector::PerlInterpreter;
-use IPC::Open3;
+use IPC::Open3;
use IO::Handle;
-use Symbol;
+use Symbol;
use Object::Remote::Logging qw(:log :dlog router);
use Object::Remote::ModuleSender;
use Object::Remote::Handle;
#By policy object-remote does not invoke a shell
sub _build_perl_command {
my $perl_bin = 'perl';
-
+
if (exists $ENV{OBJECT_REMOTE_PERL_BIN}) {
$perl_bin = $ENV{OBJECT_REMOTE_PERL_BIN};
}
- return [qw(perl -)];
+ return [$perl_bin, '-'];
}
sub _build_forward_env {
my $self = shift;
my $given_stderr = $self->stderr;
my $foreign_stderr;
-
+
Dlog_verbose {
s/\n/ /g; "invoking connection to perl interpreter using command line: $_"
} @{$self->final_perl_command};
-
+
if (defined($given_stderr)) {
#if the stderr data goes to an existing file handle
#an anonymous file handle is required
#the child stderr to the parent stderr
$foreign_stderr = ">&STDERR";
}
-
+
my $pid = open3(
my $foreign_stdin,
my $foreign_stdout,
$foreign_stderr,
@{$self->final_perl_command},
) or die "Failed to run perl at '$_[0]': $!";
-
+
$self->_set_pid($pid);
-
- if (defined($given_stderr)) {
+
+ if (defined($given_stderr)) {
Dlog_debug { "Child process STDERR is being handled via run loop" };
-
+
Object::Remote->current_loop
->watch_io(
handle => $foreign_stderr,
on_read_ready => sub {
- my $buf = '';
+ my $buf = '';
my $len = sysread($foreign_stderr, $buf, 32768);
if (!defined($len) or $len == 0) {
log_trace { "Got EOF or error on child stderr, removing from watcher" };
Dlog_trace { "got $len characters of stderr data for connection" };
print $given_stderr $buf or die "could not send stderr data: $!";
}
- }
- );
+ }
+ );
}
-
+
return ($foreign_stdin, $foreign_stdout, $pid);
}
sub _setup_watchdog_reset {
my ($self, $conn) = @_;
- my $timer_id;
-
+ my $timer_id;
+
return unless $self->watchdog_timeout;
-
+
Dlog_trace { "Creating Watchdog management timer for connection id $_" } $conn->_id;
-
+
weaken($conn);
-
+
$timer_id = Object::Remote->current_loop->watch_time(
every => $self->watchdog_timeout / 3,
code => sub {
Object::Remote->current_loop->unwatch_time($timer_id);
return;
}
-
+
unless($conn->is_valid) {
log_warn { "Watchdog timer found an invalid connection, removing the timer" };
Object::Remote->current_loop->unwatch_time($timer_id);
return;
}
-
+
Dlog_trace { "Reseting Watchdog for connection id $_" } $conn->_id;
#we do not want to block in the run loop so send the
#update off and ignore any result, we don't need it
$conn->send_class_call(0, 'Object::Remote::WatchDog', 'reset');
}
);
-
+
$conn->on_close->on_ready(sub {
log_debug { "Removing watchdog for connection that is now closed" };
Object::Remote->current_loop->unwatch_time($timer_id);
my $text = '';
require Object::Remote::FatNode;
-
+
if (defined($connection_timeout)) {
$text .= "alarm($connection_timeout);\n";
}
-
+
if (defined($watchdog_timeout)) {
$text .= "my \$WATCHDOG_TIMEOUT = $watchdog_timeout;\n";
} else {
$text .= "my \$WATCHDOG_TIMEOUT = undef;\n";
}
-
+
$text .= $self->_create_env_forward(@{$self->forward_env});
#Action at a distance but at least it's not spooky - the logging
#setup on the remote side yet so this flag allows a graceful
#degredation to happen
$text .= '$Object::Remote::FatNode::REMOTE_NODE = "1";' . "\n";
-
+
$text .= <<'END';
$INC{'Object/Remote/FatNode.pm'} = __FILE__;
$Object::Remote::FatNode::DATA = <<'ENDFAT';
eval $Object::Remote::FatNode::DATA;
die $@ if $@;
END
-
+
$text .= "__END__\n";
return $text;
}
}
1;
+
+=head1 NAME
+
+Object::Remote::Role::Connector::PerlInterpreter - Role for connections to a Perl interpreter
+
+=head1 SYNOPSIS
+
+ use Object::Remote;
+
+ my %opts = (
+ perl_command => [qw(nice -n 10 perl -)],
+ watchdog_timeout => 120, stderr => \*STDERR,
+ );
+
+ my $local_connection = Object::Remote->connect('-', %opts);
+ my $hostname = Sys::Hostname->can::on($remote, 'hostname');
+
+=head1 DESCRIPTION
+
+This is the role that supports connections to a Perl interpreter that is executed in a
+different process. The new Perl interpreter can be either on the local or a remote machine
+and is configurable via arguments passed to the constructor.
+
+=head1 ARGUMENTS
+
+=over 4
+
+=item perl_command
+
+By default the Perl interpeter will be executed as "perl -" but this can be changed by
+providing an array reference as the value to the perl_command attribute during construction.
+
+=item stderr
+
+If this value is defined then it will be used as the file handle that receives the output
+of STDERR from the Perl interpreter process and I/O will be performed by the run loop in a
+non-blocking way. If the value is undefined then STDERR of the remote process will be connected
+directly to STDERR of the local process with out the run loop managing I/O. The default value
+is undefined.
+
+There are a few ways to use this feature. By default the behavior is to form one unified STDERR
+across all of the Perl interpreters including the local one. For small scale and quick operation
+this offers a predictable and easy to use way to get at error messages generated anywhere. If
+the local Perl interpreter crashes then the remote Perl interpreters still have an active STDERR
+and it is possible to still receive output from them. This is generally a good thing but can
+cause issues.
+
+When using a file handle as the output for STDERR once the local Perl interpreter is no longer
+running there is no longer a valid STDERR for the remote interpreters to send data to. This means
+that it is no longer possible to receive error output from the remote interpreters and that the
+shell will start to kill off the child processes. Passing a reference to STDERR for the local
+interpreter (as the SYNOPSIS shows) causes the run loop to manage I/O, one unified STDERR for
+all Perl interpreters that ends as soon as the local interpreter process does, and the shell will
+start killing children when the local interpreter exits.
+
+It is also possible to pass in a file handle that has been opened for writing. This would be
+useful for logging the output of the remote interpreter directly into a dedicated file.
+
+=item watchdog_timeout
+
+If this value is defined then it will be used as the number of seconds the watchdog will wait
+for an update before it terminates the Perl interpreter process. The default value is undefined
+and will not use the watchdog. See C<Object::Remote::Watchdog> for more information.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item C<Object::Remote>
+
+=back
+
+=cut