Gearman Developer Documentation

Worker Interface

Data Structures

struct  gearman_worker_st
struct  gearman_worker_function_st

Modules

 Job Management
 Private Worker Functions

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)
}
enum  gearman_worker_state_t {
  GEARMAN_WORKER_STATE_START, GEARMAN_WORKER_STATE_FUNCTION_SEND, GEARMAN_WORKER_STATE_CONNECT, GEARMAN_WORKER_STATE_GRAB_JOB_SEND,
  GEARMAN_WORKER_STATE_GRAB_JOB_RECV, GEARMAN_WORKER_STATE_PRE_SLEEP
}
enum  gearman_worker_function_options_t { GEARMAN_WORKER_FUNCTION_PACKET_IN_USE = (1 << 0), GEARMAN_WORKER_FUNCTION_CHANGE = (1 << 1), GEARMAN_WORKER_FUNCTION_REMOVE = (1 << 2) }
enum  gearman_worker_work_state_t { GEARMAN_WORKER_WORK_STATE_GRAB_JOB, GEARMAN_WORKER_WORK_STATE_FUNCTION, GEARMAN_WORKER_WORK_STATE_COMPLETE, GEARMAN_WORKER_WORK_STATE_FAIL }

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, const void *context)
void gearman_worker_set_log_fn (gearman_worker_st *worker, gearman_log_fn *function, const void *context, gearman_verbose_t verbose)
void gearman_worker_set_event_watch_fn (gearman_worker_st *worker, gearman_event_watch_fn *function, const void *context)
void gearman_worker_set_workload_malloc_fn (gearman_worker_st *worker, gearman_malloc_fn *function, const void *context)
void gearman_worker_set_workload_free_fn (gearman_worker_st *worker, gearman_free_fn *function, const 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 (gearman_job_st *job)
void gearman_job_free_all (gearman_worker_st *worker)
gearman_return_t gearman_worker_add_function (gearman_worker_st *worker, const char *function_name, uint32_t timeout, gearman_worker_fn *function, const 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 

Definition at line 338 of file constants.h.

States for gearman_worker_st.

Enumerator:
GEARMAN_WORKER_STATE_START 
GEARMAN_WORKER_STATE_FUNCTION_SEND 
GEARMAN_WORKER_STATE_CONNECT 
GEARMAN_WORKER_STATE_GRAB_JOB_SEND 
GEARMAN_WORKER_STATE_GRAB_JOB_RECV 
GEARMAN_WORKER_STATE_PRE_SLEEP 

Definition at line 355 of file constants.h.

Options for gearman_worker_function_st.

Enumerator:
GEARMAN_WORKER_FUNCTION_PACKET_IN_USE 
GEARMAN_WORKER_FUNCTION_CHANGE 
GEARMAN_WORKER_FUNCTION_REMOVE 

Definition at line 369 of file constants.h.

Work states for gearman_worker_st.

Enumerator:
GEARMAN_WORKER_WORK_STATE_GRAB_JOB 
GEARMAN_WORKER_WORK_STATE_FUNCTION 
GEARMAN_WORKER_WORK_STATE_COMPLETE 
GEARMAN_WORKER_WORK_STATE_FAIL 

Definition at line 380 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.

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.

Definition at line 69 of file worker.c.

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

Definition at line 93 of file worker.c.

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

Definition at line 122 of file worker.c.

const char* gearman_worker_error ( gearman_worker_st worker  ) 

See gearman_error() for details.

Definition at line 159 of file worker.c.

int gearman_worker_errno ( gearman_worker_st worker  ) 

See gearman_errno() for details.

Definition at line 164 of file worker.c.

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.

Definition at line 169 of file worker.c.

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.

Definition at line 174 of file worker.c.

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.

Definition at line 183 of file worker.c.

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.

Definition at line 198 of file worker.c.

int gearman_worker_timeout ( gearman_worker_st worker  ) 

See gearman_timeout() for details.

Definition at line 213 of file worker.c.

void gearman_worker_set_timeout ( gearman_worker_st worker,
int  timeout 
)

See gearman_set_timeout() for details.

Definition at line 218 of file worker.c.

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.

Definition at line 224 of file worker.c.

void gearman_worker_set_context ( gearman_worker_st worker,
const 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.

Definition at line 229 of file worker.c.

void gearman_worker_set_log_fn ( gearman_worker_st worker,
gearman_log_fn function,
const void *  context,
gearman_verbose_t  verbose 
)

See gearman_set_log_fn() for details.

Definition at line 234 of file worker.c.

void gearman_worker_set_event_watch_fn ( gearman_worker_st worker,
gearman_event_watch_fn function,
const void *  context 
)

See gearman_set_event_watch_fn() for details.

Definition at line 241 of file worker.c.

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

See gearman_set_workload_malloc_fn() for details.

Definition at line 248 of file worker.c.

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

See gearman_set_workload_free_fn() for details.

Definition at line 255 of file worker.c.

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.

Definition at line 262 of file worker.c.

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:1234,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.

Definition at line 271 of file worker.c.

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.

Definition at line 277 of file worker.c.

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.

Definition at line 282 of file worker.c.

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.

Definition at line 289 of file worker.c.

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.

Definition at line 326 of file worker.c.

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.

Definition at line 356 of file worker.c.

void gearman_job_free ( gearman_job_st job  ) 

Free a job structure.

Parameters:
[in] job Structure previously initialized with gearman_worker_grab_job().

Definition at line 619 of file worker.c.

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

Definition at line 639 of file worker.c.

gearman_return_t gearman_worker_add_function ( gearman_worker_st worker,
const char *  function_name,
uint32_t  timeout,
gearman_worker_fn function,
const 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.

Definition at line 645 of file worker.c.

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.

Definition at line 669 of file worker.c.

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.

Definition at line 794 of file worker.c.


Generated on Tue Oct 13 20:19:22 2009 by  doxygen 1.6.1