The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Protocol-Gearman-0.04
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ Protocol::Gearman

NAME

Protocol::Gearman - abstract base class for both client and worker

DESCRIPTION

This base class is used by both Protocol::Gearman::Client and Protocol::Gearman::Worker. It shouldn't be used directly by end-user implementations. It is documented here largely to explain what methods an end implementation needs to provide in order to create a Gearman client or worker.

For implementing a Gearman client or worker, see the modules

For a simple synchronous Gearman client or worker module for use during testing or similar, see

REQUIRED METHODS

The implementation should provide the following methods:

$f = $gearman->new_future

Return a new Future subclass instance, for request methods to use. This instance should support awaiting appropriately.

$gearman->send( $bytes )

Send the given bytes to the server.

$h = $gearman->gearman_state

Return a HASH reference for the Gearman-related code to store its state on. If not implemented, a default method will be provided which uses $gearman itself, for the common case of HASH-based objects. All the Gearman-related state will be stored in keys whose names are prefixed by gearman_, to avoid clashes with other object state.

INTERNAL METHODS

These methods are provided for the client and worker subclasses to use; it is unlikely these will be of interest to other users but they are documented here for completeness.

( $type, $body ) = $gearman->pack_packet( $name, @args )

Given a name of a packet type (specified as a string as the name of one of the TYPE_* constants, without the leading TYPE_ prefix; case insignificant) returns the type value and the arguments for the packet packed into a body string. This is intended for passing directly into build_packet or send_packet:

 send_packet $fh, pack_packet( SUBMIT_JOB => $func, $id, $arg );

( $name, @args ) = $gearman->unpack_packet( $type, $body )

Given a type code and body string, returns the type name and unpacked arguments from the body. This function is the reverse of pack_packet and is intended to be used on the result of parse_packet or recv_packet:

The returned $name will always be a fully-captialised type name, as one of the TYPE_* constants without the leading TYPE_ prefix.

This is intended for a given/when control block, or dynamic method dispatch:

 my ( $name, @args ) = unpack_packet( recv_packet $fh );

 $self->${\"handle_$name"}( @args )

( $name, @args ) = $gearman->parse_packet_from_string( $bytes )

Attempts to parse a complete message packet from the given byte string. If it succeeds, it returns the type name and arguments. If it fails it returns an empty list.

If successful, it will remove the bytes of the packet form the $bytes scalar, which must therefore be mutable.

If the byte string begins with some bytes that are not recognised as the Gearman packet magic for a response, the function will immediately throw an exception before modifying the string.

( $name, @args ) = $gearman->recv_packet_from_fh( $fh )

Attempts to read a complete packet from the given filehandle, blocking until it is available. The results are undefined if this function is called on a non-blocking filehandle.

If an IO error happens, an exception is thrown. If the first four bytes read are not recognised as the Gearman packet magic for a response, the function will immediately throw an exception. If either of these conditions happen, the filehandle should be considered no longer valid and should be closed.

$bytes = $gearman->build_packet_to_string( $name, @args )

Returns a byte string containing a complete packet with the given fields.

$gearman->send_packet_to_fh( $fh, $name, @args )

Sends a complete packet to the given filehandle. If an IO error happens, an exception is thrown.

$gearman->send_packet( $typename, @args )

Packs a packet from a list of arguments then sends it; a combination of pack_packet and build_packet. Uses the implementation's send method.

$gearman->on_recv( $buffer )

The implementation should call this method when more bytes of data have been received. It parses and unpacks packets from the buffer, then dispatches to the appropriately named on_* method. A combination of parse_packet and unpack_packet.

The $buffer scalar may be modified; if it still contains bytes left over after the call these should be preserved by the implementation for the next time it is called.

$gearman->on_ERROR( $name, $message )

Default handler for the TYPE_ERROR packet. This method should be overriden by subclasses to change the behaviour.

$gearman->echo_request( $payload ) ==> ( $payload )

Sends an ECHO_REQ packet to the Gearman server, and returns a future that will eventually yield the payload when the server responds.

PROTOTYPICAL OBJECTS

An alternative option to subclassing to provide the missing methods, is to use Protocol::Gearman (or rather, one of the client or worker subclasses) as a prototypical object, passing in CODE references for the missing methods to a special constructor that creates a concrete object.

This may be more convenient to use in smaller one-shot cases (like unit tests or small scripts) instead of creating a subclass.

 my $socket = ...;

 my $client = Protocol::Gearman::Client->new_prototype(
    send       => sub { $socket->print( $_[1] ); },
    new_future => sub { My::Future::Subclass->new },
 );

$gearman = Protocol::Gearman->new_prototype( %methods )

Returns a new prototypical object constructed using the given methods. The named arguments must give values for the send and new_future methods.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>