From: Christian Walde Date: Sun, 16 Oct 2016 14:30:11 +0000 (+0200) Subject: further detail OR->connect arguments, and document other bits X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=refs%2Fheads%2Farg_docs;p=scpubgit%2FObject-Remote.git further detail OR->connect arguments, and document other bits --- diff --git a/lib/Object/Remote/Connection.pm b/lib/Object/Remote/Connection.pm index d4dee82..f2a90b8 100644 --- a/lib/Object/Remote/Connection.pm +++ b/lib/Object/Remote/Connection.pm @@ -526,7 +526,10 @@ Object::Remote::Connection - An underlying connection for L =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 diff --git a/lib/Object/Remote/Connector/INET.pm b/lib/Object/Remote/Connector/INET.pm index 09fb583..e6a248d 100644 --- a/lib/Object/Remote/Connector/INET.pm +++ b/lib/Object/Remote/Connector/INET.pm @@ -33,6 +33,11 @@ push @Object::Remote::Connection::Guess, sub { 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 if the connection spec is in C format. + =head1 ARGUMENTS Inherits arguments from L and provides the @@ -40,4 +45,10 @@ following: =head2 socket_path +When invoked via L, specified via the connection spec, +and not overridable. + +The remote address to connect to. Expected to be understandable by +L for its C argument. + =cut diff --git a/lib/Object/Remote/Connector/Local.pm b/lib/Object/Remote/Connector/Local.pm index 6dfd9ab..f43cfe3 100644 --- a/lib/Object/Remote/Connector/Local.pm +++ b/lib/Object/Remote/Connector/Local.pm @@ -21,6 +21,11 @@ push @Object::Remote::Connection::Guess, sub { 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 if the connection spec is C<->. + =head1 ARGUMENTS Inherits arguments from L and diff --git a/lib/Object/Remote/Connector/LocalSudo.pm b/lib/Object/Remote/Connector/LocalSudo.pm index 886f5fe..b04a571 100644 --- a/lib/Object/Remote/Connector/LocalSudo.pm +++ b/lib/Object/Remote/Connector/LocalSudo.pm @@ -103,6 +103,12 @@ push @Object::Remote::Connection::Guess, sub { 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 if +the connection spec is a username followed by a @. + =head1 ARGUMENTS Inherits arguments from L and provides the @@ -110,8 +116,19 @@ following: =head2 target_user +When invoked via L, 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 to open +the perl process. Defaults to a specific sudo incantation. + =cut diff --git a/lib/Object/Remote/Connector/SSH.pm b/lib/Object/Remote/Connector/SSH.pm index ea27a37..0e0d820 100644 --- a/lib/Object/Remote/Connector/SSH.pm +++ b/lib/Object/Remote/Connector/SSH.pm @@ -47,6 +47,12 @@ push @Object::Remote::Connection::Guess, sub { 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 if the connection spec looks like a hostname or +user@hostname combo. + =head1 ARGUMENTS Inherits arguments from L and @@ -54,10 +60,25 @@ provides the following: =head2 ssh_to -=head2 ssh_perl_command +When invoked via L, 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 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. + +=head2 ssh_perl_command + +An arrayref containing a list of strings to be passed to L to open +the perl process. Defaults to constructing an ssh client incantation with the +other arguments here. + =cut diff --git a/lib/Object/Remote/Connector/STDIO.pm b/lib/Object/Remote/Connector/STDIO.pm index 908f8b3..781ed9d 100644 --- a/lib/Object/Remote/Connector/STDIO.pm +++ b/lib/Object/Remote/Connector/STDIO.pm @@ -27,10 +27,17 @@ sub connect { =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 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 diff --git a/lib/Object/Remote/Connector/UNIX.pm b/lib/Object/Remote/Connector/UNIX.pm index ca90dda..477e6c0 100644 --- a/lib/Object/Remote/Connector/UNIX.pm +++ b/lib/Object/Remote/Connector/UNIX.pm @@ -33,6 +33,12 @@ push @Object::Remote::Connection::Guess, sub { 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 if the connection spec looks like a unix path name +that's either absolute, or relative to C<.>. + =head1 ARGUMENTS Inherits arguments from L and provides the @@ -40,4 +46,9 @@ following: =head2 socket_path +When invoked via L, specified via the connection spec, +and not overridable. + +The path name of the unix socket to connect to. Passed to L. + =cut diff --git a/lib/Object/Remote/Node.pm b/lib/Object/Remote/Node.pm index a3f88a5..f6d05ca 100644 --- a/lib/Object/Remote/Node.pm +++ b/lib/Object/Remote/Node.pm @@ -41,3 +41,30 @@ sub run { } 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. + +=head1 ARGUMENTS + +=head2 watchdog_timeout + +If provided sets up a L 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 diff --git a/lib/Object/Remote/Role/Connector.pm b/lib/Object/Remote/Role/Connector.pm index 4386a82..01b7623 100644 --- a/lib/Object/Remote/Role/Connector.pm +++ b/lib/Object/Remote/Role/Connector.pm @@ -71,4 +71,7 @@ Object::Remote::Role::Connector - Basic Future-compatible connector capability =head2 timeout +Time in seconds after which the current connection is closed if there was no +activity. Defaults to 10 seconds. + =cut diff --git a/lib/Object/Remote/WatchDog.pm b/lib/Object/Remote/WatchDog.pm index bbcd188..7582b8f 100644 --- a/lib/Object/Remote/WatchDog.pm +++ b/lib/Object/Remote/WatchDog.pm @@ -55,4 +55,48 @@ sub shutdown { 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 with the timeout specified. The C 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 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 back to 0, thus preventing the C handler from quitting the +process. + +=cut +