NAME

RPC::ToWorker - invoke remote perl functions asynchronously on remote systems

SYNOPSIS

 use RPC::ToWorker;

 do_remote_job(
	prefix		=> '#output prefix',
	chdir		=> '/some/directory',
	host		=> 'some.host.name',
	data		=> $data_to_send,
	preload		=> [qw(List::Of Required::Modules )],
	desc		=> 'remote job description',
	eval		=> 'my ($data) = @_; code_to_run(); return(@values)',
	when_done	=> sub { my (@slave_return_values) = @_; },
	all_done	=> \&callback_for_slave_process_is_finished,
	error_handler	=> \&callback_for_STDERR_output_from_slave,
	output_handler	=> \&callback_for_STDOUT_output_from_slave,
 );

 IO::Event::loop;

DESCRIPTION

RPC::ToWorker provides a way to invoke a perl function on a remote system. It starts the remote perl process, passes data to it, and runs arbitrary code. It does this all with asynchronous IO (using IO::Event) so that multiple processes can run at the same time.

The slave job on the remote system can also invoke functions in the master process using master_call in RPC::ToWorker::Callback.

PARAMETERS

host

Required. The remote hostname.

eval

Required. Code to eval on the remote host. Return values will be passed to when_done code reference. One argument will arrive in @_: the data element from below.

when_done

Code reference to invoke with the return values from the eval.

data

Data reference to pass to the remote process. It will be marshalled with Storable. This reference will be passed to the eval code as is (arrays will not be expanded).

chdir

Directory to chdir() to before doing anything else.

desc

Text (short) description of the remote job for error messages.

prefix

String to prefix each line of output from the slave with. Defaults to host:.

preload

Modules to load on the remote system, a list.

prequel

Code to eval prior to the main eval. Must not return. This is a pre-amble. Local variables can be delcared. Modules can be loaded. The main eval is inside a block. This is not.

error_handler($ioe)

This is currently disabled Code reference to call when there is STDERR output from the slave process. The default handler prints the output to STDOUT prefixed with prefix. $ioe is an IO::Event object so you can loop over it like a normal file descriptor.

output_handler($ioe)

Code reference to call when there is STDOUT output from the slave process. The default handler prints the output to STDOUT prefixed with prefix. $ioe is an IO::Event object so you can loop over it like a normal file descriptor.

on_failure

Code reference to invoke if the slave process failes to run. It may be invoked multiple times for the same slave.

all_done

Code reference to invoke when the slave process is fully shut down.

local_data

A hash of data that can be made available to master_call() invocations. See RPC::ToWorker::Callback.

can_retry

Can this job be re-attempted? Defaults to 1.

SEE ALSO

To make callbacks to the master from the worker slave, use RPC::ToWorker::Callback.

This module expects to exist with an IO::Event select loop. This isn't much of a limitation since IO::Event::Any layers over AnyEvent.

LICENSE

Copyright (C) 2007-2008 SearchMe, Inc. Copyright (C) 2011 Google, Inc. This package may be used and redistributed under the terms of either the Artistic 2.0 or LGPL 2.1 license.