Gearman Public API Documentation

Worker Declarations

Data Structures

struct  gearman_worker_st

Modules

 Constants
 Types
 Job Declarations

Enumerations

enum  gearman_worker_options_t {
  GEARMAN_WORKER_ALLOCATED = (1 << 0), GEARMAN_WORKER_NON_BLOCKING = (1 << 1), GEARMAN_WORKER_PACKET_INIT = (1 << 2), GEARMAN_WORKER_GRAB_JOB_IN_USE = (1 << 3),
  GEARMAN_WORKER_PRE_SLEEP_IN_USE = (1 << 4), GEARMAN_WORKER_WORK_JOB_IN_USE = (1 << 5), GEARMAN_WORKER_CHANGE = (1 << 6), GEARMAN_WORKER_GRAB_UNIQ = (1 << 7),
  GEARMAN_WORKER_TIMEOUT_RETURN = (1 << 8), GEARMAN_WORKER_MAX = (1 << 9)
}

Functions

gearman_worker_stgearman_worker_create (gearman_worker_st *worker)
gearman_worker_stgearman_worker_clone (gearman_worker_st *worker, const gearman_worker_st *from)
void gearman_worker_free (gearman_worker_st *worker)
const char * gearman_worker_error (gearman_worker_st *worker)
int gearman_worker_errno (gearman_worker_st *worker)
gearman_worker_options_t gearman_worker_options (const gearman_worker_st *worker)
void gearman_worker_set_options (gearman_worker_st *worker, gearman_worker_options_t options)
void gearman_worker_add_options (gearman_worker_st *worker, gearman_worker_options_t options)
void gearman_worker_remove_options (gearman_worker_st *worker, gearman_worker_options_t options)
int gearman_worker_timeout (gearman_worker_st *worker)
void gearman_worker_set_timeout (gearman_worker_st *worker, int timeout)
void * gearman_worker_context (const gearman_worker_st *worker)
void gearman_worker_set_context (gearman_worker_st *worker, void *context)
void gearman_worker_set_log_fn (gearman_worker_st *worker, gearman_log_fn *function, void *context, gearman_verbose_t verbose)
void gearman_worker_set_workload_malloc_fn (gearman_worker_st *worker, gearman_malloc_fn *function, void *context)
void gearman_worker_set_workload_free_fn (gearman_worker_st *worker, gearman_free_fn *function, void *context)
gearman_return_t gearman_worker_add_server (gearman_worker_st *worker, const char *host, in_port_t port)
gearman_return_t gearman_worker_add_servers (gearman_worker_st *worker, const char *servers)
void gearman_worker_remove_servers (gearman_worker_st *worker)
gearman_return_t gearman_worker_wait (gearman_worker_st *worker)
gearman_return_t gearman_worker_register (gearman_worker_st *worker, const char *function_name, uint32_t timeout)
gearman_return_t gearman_worker_unregister (gearman_worker_st *worker, const char *function_name)
gearman_return_t gearman_worker_unregister_all (gearman_worker_st *worker)
gearman_job_stgearman_worker_grab_job (gearman_worker_st *worker, gearman_job_st *job, gearman_return_t *ret_ptr)
void gearman_job_free_all (gearman_worker_st *worker)
bool gearman_worker_function_exist (gearman_worker_st *worker, const char *function_name, size_t function_length)
gearman_return_t gearman_worker_add_function (gearman_worker_st *worker, const char *function_name, uint32_t timeout, gearman_worker_fn *function, void *context)
gearman_return_t gearman_worker_work (gearman_worker_st *worker)
gearman_return_t gearman_worker_echo (gearman_worker_st *worker, const void *workload, size_t workload_size)

Detailed Description

This is the interface gearman workers should use.

See Main Page for full details.


Enumeration Type Documentation

Options for gearman_worker_st.

Enumerator:
GEARMAN_WORKER_ALLOCATED 
GEARMAN_WORKER_NON_BLOCKING 
GEARMAN_WORKER_PACKET_INIT 
GEARMAN_WORKER_GRAB_JOB_IN_USE 
GEARMAN_WORKER_PRE_SLEEP_IN_USE 
GEARMAN_WORKER_WORK_JOB_IN_USE 
GEARMAN_WORKER_CHANGE 
GEARMAN_WORKER_GRAB_UNIQ 
GEARMAN_WORKER_TIMEOUT_RETURN 
GEARMAN_WORKER_MAX 

Definition at line 222 of file constants.h.


Function Documentation

gearman_worker_st* gearman_worker_create ( gearman_worker_st worker  ) 

Initialize a worker structure. Always check the return value even if passing in a pre-allocated structure. Some other initialization may have failed. It is not required to memset() a structure before providing it.

Parameters:
[in] worker Caller allocated structure, or NULL to allocate one.
Returns:
On success, a pointer to the (possibly allocated) structure. On failure this will be NULL.
gearman_worker_st* gearman_worker_clone ( gearman_worker_st worker,
const gearman_worker_st from 
)

Clone a worker structure.

Parameters:
[in] worker Caller allocated structure, or NULL to allocate one.
[in] from Structure to use as a source to clone from.
Returns:
Same return as gearman_worker_create().
void gearman_worker_free ( gearman_worker_st worker  ) 

Free resources used by a worker structure.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
const char* gearman_worker_error ( gearman_worker_st worker  ) 

See gearman_error() for details.

int gearman_worker_errno ( gearman_worker_st worker  ) 

See gearman_errno() for details.

gearman_worker_options_t gearman_worker_options ( const gearman_worker_st worker  ) 

Get options for a worker structure.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
Returns:
Options set for the worker structure.
void gearman_worker_set_options ( gearman_worker_st worker,
gearman_worker_options_t  options 
)

Set options for a worker structure.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
options Available options for worker structures.
void gearman_worker_add_options ( gearman_worker_st worker,
gearman_worker_options_t  options 
)

Add options for a worker structure.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
options Available options for worker structures.
void gearman_worker_remove_options ( gearman_worker_st worker,
gearman_worker_options_t  options 
)

Remove options for a worker structure.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
options Available options for worker structures.
int gearman_worker_timeout ( gearman_worker_st worker  ) 

See gearman_universal_timeout() for details.

void gearman_worker_set_timeout ( gearman_worker_st worker,
int  timeout 
)

See gearman_universal_set_timeout() for details.

void* gearman_worker_context ( const gearman_worker_st worker  ) 

Get the application context for a worker.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
Returns:
Application context that was previously set, or NULL.
void gearman_worker_set_context ( gearman_worker_st worker,
void *  context 
)

Set the application context for a worker.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
[in] context Application context to set.
void gearman_worker_set_log_fn ( gearman_worker_st worker,
gearman_log_fn function,
void *  context,
gearman_verbose_t  verbose 
)

See gearman_set_log_fn() for details.

void gearman_worker_set_workload_malloc_fn ( gearman_worker_st worker,
gearman_malloc_fn function,
void *  context 
)

See gearman_set_workload_malloc_fn() for details.

void gearman_worker_set_workload_free_fn ( gearman_worker_st worker,
gearman_free_fn function,
void *  context 
)

Set custom memory free function for workloads. Normally gearman uses the standard system free to free memory used with workloads. The provided function will be used instead.

Parameters:
[in] gearman Structure previously initialized with gearman_universal_create() or gearman_clone().
[in] function Memory free function to use instead of free().
[in] context Argument to pass into the callback function.
gearman_return_t gearman_worker_add_server ( gearman_worker_st worker,
const char *  host,
in_port_t  port 
)

Add a job server to a worker. This goes into a list of servers that can be used to run tasks. No socket I/O happens here, it is just added to a list.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
[in] host Hostname or IP address (IPv4 or IPv6) of the server to add.
[in] port Port of the server to add.
Returns:
Standard gearman return value.
gearman_return_t gearman_worker_add_servers ( gearman_worker_st worker,
const char *  servers 
)

Add a list of job servers to a worker. The format for the server list is: SERVER[:PORT][,SERVER[:PORT]]... Some examples are: 10.0.0.1,10.0.0.2,10.0.0.3 localhost LIBGEARMAN_BITFIELD234,jobserver2.domain.com:7003,10.0.0.3

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
[in] servers Server list described above.
Returns:
Standard gearman return value.
void gearman_worker_remove_servers ( gearman_worker_st worker  ) 

Remove all servers currently associated with the worker.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
gearman_return_t gearman_worker_wait ( gearman_worker_st worker  ) 

When in non-blocking I/O mode, wait for activity from one of the servers.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
Returns:
Standard gearman return value.
gearman_return_t gearman_worker_register ( gearman_worker_st worker,
const char *  function_name,
uint32_t  timeout 
)

Register function with job servers with an optional timeout. The timeout specifies how many seconds the server will wait before marking a job as failed. If timeout is zero, there is no timeout.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
[in] function_name Function name to register.
[in] timeout Optional timeout (in seconds) that specifies the maximum time a job should. This is enforced on the job server. A value of 0 means an infinite time.
Returns:
Standard gearman return value.
gearman_return_t gearman_worker_unregister ( gearman_worker_st worker,
const char *  function_name 
)

Unregister function with job servers.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
[in] function_name Function name to unregister.
Returns:
Standard gearman return value.
gearman_return_t gearman_worker_unregister_all ( gearman_worker_st worker  ) 

Unregister all functions with job servers.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
Returns:
Standard gearman return value.
gearman_job_st* gearman_worker_grab_job ( gearman_worker_st worker,
gearman_job_st job,
gearman_return_t ret_ptr 
)

Get a job from one of the job servers. This does not used the callback interface below, which means results must be sent back to the job server manually. It is also the responsibility of the caller to free the job once it has been completed.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
[in] job Caller allocated structure, or NULL to allocate one.
[out] ret_ptr Standard gearman return value.
Returns:
On success, a pointer to the (possibly allocated) structure. On failure this will be NULL.
void gearman_job_free_all ( gearman_worker_st worker  ) 

Free all jobs for a gearman structure.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
bool gearman_worker_function_exist ( gearman_worker_st worker,
const char *  function_name,
size_t  function_length 
)

See if a function exists in the server. It will not return true if the function is currently being de-allocated.

Parameters:
[in] worker gearman_worker_st that will be used.
[in] function_name Function name for search.
[in] function_length Length of function name.
Returns:
bool
gearman_return_t gearman_worker_add_function ( gearman_worker_st worker,
const char *  function_name,
uint32_t  timeout,
gearman_worker_fn function,
void *  context 
)

Register and add callback function for worker. To remove functions that have been added, call gearman_worker_unregister() or gearman_worker_unregister_all().

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
[in] function_name Function name to register.
[in] timeout Optional timeout (in seconds) that specifies the maximum time a job should. This is enforced on the job server. A value of 0 means an infinite time.
[in] function Function to run when there is a job ready.
[in] context Argument to pass into the callback function.
Returns:
Standard gearman return value.
gearman_return_t gearman_worker_work ( gearman_worker_st worker  ) 

Wait for a job and call the appropriate callback function when it gets one.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
Returns:
Standard gearman return value.
gearman_return_t gearman_worker_echo ( gearman_worker_st worker,
const void *  workload,
size_t  workload_size 
)

Send data to all job servers to see if they echo it back. This is a test function to see if job servers are responding properly.

Parameters:
[in] worker Structure previously initialized with gearman_worker_create() or gearman_worker_clone().
[in] workload The workload to ask the server to echo back.
[in] workload_size Size of the workload.
Returns:
Standard gearman return value.
Generated on Mon Jun 14 15:58:44 2010 by  doxygen 1.6.3