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: $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->parse_packet( $bytes ) Attempts to parse a complete message packet from the given byte string. If it succeeds, it returns the type and data body, as an opaque byte string. 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. ( $type, $body ) = $gearman->recv_packet( $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( $type, $body ) Returns a byte string containing a complete packet with the given fields. $gearman->send_packet( $fh, $type, $body ) Sends a complete packet to the given filehandle. If an IO error happens, an exception is thrown. ( $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 ) $gearman->pack_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_read( $buffer ) The implementation should call this method on receipt of more bytes of data. 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. AUTHOR Paul Evans