NAME

Protocol::Gearman::Worker - implement a Gearman worker

DESCRIPTION

A base class that implements a complete Gearman worker. This abstract class still requires the implementation methods as documented in Protocol::Gearman, but otherwise provides a full set of behaviour useful to Gearman workers.

As it is based on Future it is suitable for both synchronous and asynchronous use. When backed by an implementation capable of performing asynchronously, this object fully supports asynchronous Gearman communication. When backed by a synchronous implementation, it will still yield Future instances but the limitations of the synchronous implementation may limit how much concurrency and asynchronous behaviour can be acheived.

A simple concrete implementation suitable for synchronous use can be found in Net::Gearman::Worker.

METHODS

$worker->can_do( $name, %opts )

Informs the server that the worker can perform a function of the given name.

The following named options are recognised:

timeout => INT

If specified, the function is registered using the CAN_DO_TIMEOUT variant, which sets a timeout on the Gearman server after which the function ought to have completed. The timeout is specified in seconds.

$worker->grab_job ==> $job

Returns a future that will eventually yield another job assignment from the server as an instance of a job object; see below.

$worker->job_finished( $job )

Invoked by the complete and fail methods on a job object, after the server has been informed of the final status of the job. By default this method does nothing, but it is provided for subclasses to override, to be informed when a job is finished.

JOB OBJECTS

Objects of this type are returned by the grab_job method. They represent individual job assignments from the server, and can be used to obtain details of the work to perform, and report on its result.

$worker = $job->worker

Returns the Protocol::Gearman::Worker object the job was received by.

$handle = $job->handle

Returns the job handle assigned by the server. Most implementations should not need to use this directly.

$func = $job->func

$arg = $job->arg

The function name and opaque argument data bytes sent by the requesting client.

$job->data( $data )

Sends more data back to the client. Intended for long-running jobs with incremental output.

$job->warning( $warning )

Sends a warning to the client.

$job->status( $numerator, $denominator )

Sets the current progress of the job.

$job->complete( $result )

Informs the server that the job is now complete, and sets its result.

$job->fail( $exception )

Informs the server that the job has failed.

Optionally an exception value can be supplied; if given this will be sent to the server using a WORK_EXCEPTION message. Note that not all clients will receive this; it is an optional feature.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Protocol::Gearman

perl -MCPAN -e shell
install Protocol::Gearman