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

      * Protocol::Gearman::Client

      * Protocol::Gearman::Worker

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

      * Net::Gearman::Client

      * Net::Gearman::Worker

REQUIRED METHODS

    The implementation should provide the following methods:

 new_future

       $f = $gearman->new_future;

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

 send

       $gearman->send( $bytes );

    Send the given bytes to the server.

 gearman_state

       $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.

 pack_packet

       ( $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 );

 unpack_packet

       ( $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 );

 parse_packet_from_string

       ( $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.

 recv_packet_from_fh

       ( $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.

 build_packet_to_string

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

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

 send_packet_to_fh

       $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.

 send_packet

       $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.

 on_recv

       $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.

 on_ERROR

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

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

 echo_request

       $payload = await $gearman->echo_request( $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 },
       );

 new_prototype

       $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>

