gear/doc/source/index.rst

Gear: Asynchronous Event-Driven Gearman Interface

gear

This module implements an asynchronous event-driven interface to Gearman. It provides interfaces to build a client or worker, and access to the administrative protocol. The design approach is to keep it simple, with a relatively thin abstration of the Gearman protocol itself. It should be easy to use to build a client or worker that operates either synchronously or asynchronously.

The module also provides a simple Gearman server for use as a convenience in unit tests. The server is not designed for production use under load.

Client Example

To use the client interface, instantiate a :pyClient, and submit a :pyJob. For example:

import gear
client = gear.Client()
client.addServer('gearman.example.com')
client.waitForServer()  # Wait for at least one server to be connected

job = gear.Job("reverse", "test string")
client.submitJob(job)

The waitForServer() call is only necessary when running in a synchronous context. When running asynchronously, it is probably more desirable to omit that call and instead handle the :pyNoConnectedServersError exception that submitJob may raise if no servers are connected at the time.

When Gearman returns data to the client, the :pyJob object is updated immediately. Event handlers are called on the :pyClient object so that subclasses have ample facilities for reacting to events synchronously.

Worker Example

To use the worker interface, create a :pyWorker, register at least one function that the worker supports, and then wait for a Job to be dispatched to the worker.

An example of a Gearman worker:

import gear
worker = gear.Worker('reverser')
worker.addServer('gearman.example.com')
worker.registerFunction("reverse")

while True:
    job = worker.getJob()
    job.sendWorkComplete(job.arguments[::-1])

SSL Connections

For versions of Gearman supporting SSL connections, specify the files containing the SSL private key, public certificate, and CA certificate in the addServer() call. For example:

ssl_key = '/path/to/key.pem'
ssl_cert = '/path/to/cert.pem'
ssl_ca = '/path/to/ca.pem'
client.addServer('gearman.example.com', 4730, ssl_key, ssl_cert, ssl_ca)

All three files must be specified for SSL to be used.

API Reference

The following sections document the module's public API. It is divided into sections focusing on implementing a client, a worker, using the administrative protocol, and then the classes that are common to all usages of the module.

Client Usage

The classes in this section should be all that are needed in order to implement a Gearman client.

Client Objects

gear.Client

Job Objects

gear.Job

Worker Usage

The classes in this section should be all that are needed in order to implement a Gearman worker.

Worker Objects

gear.Worker

FunctionRecord Objects

gear.FunctionRecord

WorkerJob Objects

gear.WorkerJob

Administrative Protocol

Gearman provides an administrative protocol that is multiplexed on the same connection as the normal binary protocol for jobs. The classes in this section are useful for working with that protocol. They need to be used with an existing :pyConnection object; either one obtained via a :pyClient or :pyWorker, or via direct instantiation of :pyConnection to a Gearman server.

AdminRequest Objects

gear.AdminRequest

gear.StatusAdminRequest

gear.ShowJobsAdminRequest

gear.ShowUniqueJobsAdminRequest

gear.CancelJobAdminRequest

gear.VersionAdminRequest

Server Usage

geard --help

Server Objects

gear.Server

Common

These classes do not normally need to be directly instatiated to use the gear API, but they may be returned or otherwise be accessible from other classes in this module. They generally operate at a lower level, but still form part of the public API.

Connection Objects

gear.Connection

Packet Objects

gear.Packet

Exceptions

gear.ConnectionError

gear.InvalidDataError

gear.ConfigurationError

gear.NoConnectedServersError

gear.UnknownJobError

gear.InterruptedError

Constants

These constants are used by public API classes.

Normal job precedence.

Low job precedence.

High job precedence.

gear.constants

Indices and tables

• genindex
• modindex
• search