=head1 DESCRIPTION
-This is the class that supports connections to remote objects.
+This is the base class for connections in OR objects. Connections are present
+both in the local and remote parts of each OR pair, and handle the data
+processing for sending OR commands and responses as JSON via the appropiate
+connection mechanism.
=head1 METHODS
Object::Remote::Connector::INET - A connector for INET sockets
+=head1 DESCRIPTION
+
+Used to create a connector that talks to an INET socket. Invoked by
+L<Object::Remote/connect> if the connection spec is in C<host:port> format.
+
=head1 ARGUMENTS
Inherits arguments from L<Object::Remote::Role::Connector> and provides the
=head2 socket_path
+When invoked via L<Object::Remote/connect>, specified via the connection spec,
+and not overridable.
+
+The remote address to connect to. Expected to be understandable by
+L<IO::Socket::INET> for its C<PeerAddr> argument.
+
=cut
Object::Remote::Connector::Local - A connector for a local Perl process
+=head1 DESCRIPTION
+
+Used to create a connector that talks to a Perl process started on the local
+machine. Invoked by L<Object::Remote/connect> if the connection spec is C<->.
+
=head1 ARGUMENTS
Inherits arguments from L<Object::Remote::Role::Connector::PerlInterpreter> and
Object::Remote::Connector::LocalSudo - A connector for a local Perl process with
sudo
+=head1 DESCRIPTION
+
+Used to create a connector that talks to a Perl process started on the local
+machine, via sudo as a specific user. Invoked by L<Object::Remote/connect> if
+the connection spec is a username followed by a @.
+
=head1 ARGUMENTS
Inherits arguments from L<Object::Remote::Connector::Local> and provides the
=head2 target_user
+When invoked via L<Object::Remote/connect>, specified via the connection spec,
+and not overridable.
+
+The name of the user to run the process as.
+
=head2 password_callback
+A function that returns the password to be passed on to sudo. Defaults to asking
+the operator via command line.
+
=head2 sudo_perl_command
+An arrayref containing a list of strings to be passed to L<IPC::Open3> to open
+the perl process. Defaults to a specific sudo incantation.
+
=cut
Object::Remote::Connector::SSH - A connector for SSH servers
+=head1 DESCRIPTION
+
+Used to create a connector that talks to an SSH server. Invoked by
+L<Object::Remote/connect> if the connection spec looks like a hostname or
+user@hostname combo.
+
=head1 ARGUMENTS
Inherits arguments from L<Object::Remote::Role::Connector::PerlInterpreter> and
=head2 ssh_to
-=head2 ssh_perl_command
+When invoked via L<Object::Remote/connect>, specified via the connection spec,
+and not overridable.
+
+String that contains hostname or user@hostname to connect to.
=head2 ssh_options
+An arrayref containing a list of strings to be passed to L<IPC::Open3> with
+options to be passed specifically to the ssh client. Defaults to C<-A>.
+
=head2 ssh_command
+A string or arrayref of strings with the ssh command to be run. Defaults to
+C<ssh>.
+
+=head2 ssh_perl_command
+
+An arrayref containing a list of strings to be passed to L<IPC::Open3> to open
+the perl process. Defaults to constructing an ssh client incantation with the
+other arguments here.
+
=cut
=head1 NAME
-Object::Remote::Connector::STDIO - ???
+Object::Remote::Connector::STDIO - A connector used in remote OR nodes
+
+=head1 DESCRIPTION
+
+This connector only exists to provide L<Object:Remote::Node> with a connection
+that handles its OR JSON command and response processing. Reads from STDIN and
+prints to STDOUT.
=head1 ARGUMENTS
-Provides no arguments.
+Provides no arguments. However the adventurous can replace STDIN/STDOUT of the
+current process with other filehandles.
=cut
Object::Remote::Connector::UNIX - A connector for UNIX sockets
+=head1 DESCRIPTION
+
+Used to create a connector that talks to a unix socket. Invoked by
+L<Object::Remote/connect> if the connection spec looks like a unix path name
+that's either absolute, or relative to C<.>.
+
=head1 ARGUMENTS
Inherits arguments from L<Object::Remote::Role::Connector> and provides the
=head2 socket_path
+When invoked via L<Object::Remote/connect>, specified via the connection spec,
+and not overridable.
+
+The path name of the unix socket to connect to. Passed to L<IO::Socket::UNIX>.
+
=cut
}
1;
+
+=head1 NAME
+
+Object::Remote::Node - A minimum remote OR command processing loop
+
+=head1 SYNOPSIS
+
+ use Object::Remote::Node;
+
+ Object::Remote::Node->run(%args);
+
+=head1 DESCRIPTION
+
+The minimum amount of code necessary to read OR JSON commands from STDIN and
+send responses to STDOUT after processing. Uses
+L<Object::Remote::Connector::STDIO>.
+
+=head1 ARGUMENTS
+
+=head2 watchdog_timeout
+
+If provided sets up a L<Object::Remote::WatchDog> with the timeout set to the
+value in seconds specified by this argument.
+
+If not provided or undef/0, attempts to cancel any existing watch dogs. ???
+
+=cut
=head2 timeout
+Time in seconds after which the current connection is closed if there was no
+activity. Defaults to 10 seconds.
+
=cut
1;
+=head1 NAME
+
+Object::Remote::WatchDog - alarm-based event loop timeout singleton
+
+=head1 DESCRIPTION
+
+This is a singleton class intended to be used in remote nodes to kill the
+process if the event loop seems to have stalled for longer than the timeout
+specified.
+
+=head1 METHODS
+
+The following are all class methods.
+
+=head2 instance
+
+ my $d = Object::Remote::WatchDog->instance(timeout => 10);
+
+Creates a new watch dog if there wasn't one yet, with the timeout set to the
+specified value. The timeout argument is required. The timeout is immediately
+started by calling C<alarm> with the timeout specified. The C<ALRM> signal is
+replaced with a handler that, when triggered, quits the process with an error.
+
+If there already was a watchdog it just returns that, however in that case the
+timeout value is ignored.
+
+=head2 reset
+
+ Object::Remote::WatchDog->reset;
+
+Calls C<alarm> with the timeout value of the current watch dog singleton to
+reset it. Throws an exception if there is no current singleton. Intended to be
+called repeatedly by the event loop to signal it's still running and not
+stalled.
+
+=head2 shutdown
+
+ Object::Remote::WatchDog->shutdown;
+
+Sets C<alarm> back to 0, thus preventing the C<ALRM> handler from quitting the
+process.
+
+=cut
+
projects / scpubgit/Object-Remote.git / commitdiff