Gearman Core Interface


Enumerations
enum	gearman_options_t { GEARMAN_ALLOCATED = (1 << 0), GEARMAN_NON_BLOCKING = (1 << 1), GEARMAN_DONT_TRACK_PACKETS = (1 << 2) }
Functions
const char *	gearman_version (void)
const char *	gearman_bugreport (void)
const char *	gearman_verbose_name (gearman_verbose_t verbose)
gearman_st *	gearman_create (gearman_st *gearman)
gearman_st *	gearman_clone (gearman_st gearman, const gearman_st from)
void	gearman_free (gearman_st *gearman)
const char *	gearman_error (const gearman_st *gearman)
int	gearman_errno (const gearman_st *gearman)
gearman_options_t	gearman_options (const gearman_st *gearman)
void	gearman_set_options (gearman_st *gearman, gearman_options_t options)
void	gearman_add_options (gearman_st *gearman, gearman_options_t options)
void	gearman_remove_options (gearman_st *gearman, gearman_options_t options)
int	gearman_timeout (gearman_st *gearman)
void	gearman_set_timeout (gearman_st *gearman, int timeout)
void	gearman_set_log_fn (gearman_st gearman, gearman_log_fn function, const void *context, gearman_verbose_t verbose)
void	gearman_set_event_watch_fn (gearman_st gearman, gearman_event_watch_fn function, const void *context)
void	gearman_set_workload_malloc_fn (gearman_st gearman, gearman_malloc_fn function, const void *context)
void	gearman_set_workload_free_fn (gearman_st gearman, gearman_free_fn function, const void *context)
gearman_con_st *	gearman_con_create (gearman_st gearman, gearman_con_st con)
gearman_con_st *	gearman_con_add (gearman_st gearman, gearman_con_st con, const char *host, in_port_t port)
gearman_con_st *	gearman_con_clone (gearman_st gearman, gearman_con_st con, const gearman_con_st *from)
void	gearman_con_free (gearman_con_st *con)
void	gearman_con_free_all (gearman_st *gearman)
gearman_return_t	gearman_con_flush_all (gearman_st *gearman)
gearman_return_t	gearman_con_send_all (gearman_st gearman, const gearman_packet_st packet)
gearman_return_t	gearman_con_wait (gearman_st *gearman)
gearman_con_st *	gearman_con_ready (gearman_st *gearman)
gearman_return_t	gearman_con_echo (gearman_st gearman, const void workload, size_t workload_size)
gearman_packet_st *	gearman_packet_create (gearman_st gearman, gearman_packet_st packet)
gearman_return_t	gearman_packet_add (gearman_st gearman, gearman_packet_st packet, gearman_magic_t magic, gearman_command_t command, const void *arg,...)
void	gearman_packet_free (gearman_packet_st *packet)
void	gearman_packet_free_all (gearman_st *gearman)

Detailed Description

This is a low level interface for gearman library instances. This is used internally by both client and worker interfaces, so you probably want to look there first. This is usually used to write lower level clients, workers, proxies, or your own server.

There is no locking within a single gearman_st structure, so for threaded applications you must either ensure isolation in the application or use multiple gearman_st structures (for example, one for each thread).

Enumeration Type Documentation

enum gearman_options_t

Options for gearman_st.

Enumerator:

GEARMAN_ALLOCATED
GEARMAN_NON_BLOCKING
GEARMAN_DONT_TRACK_PACKETS

Definition at line 128 of file constants.h.

Function Documentation

const char* gearman_version ( void )

Get Gearman library version.

Returns:: Version string of library.

const char* gearman_bugreport ( void )

Get bug report URL.

Returns:: Bug report URL string.

const char* gearman_verbose_name ( gearman_verbose_t verbose )

Get string with the name of the given verbose level.

Parameters:

[in] verbose Verbose logging level.

Returns:: String form of verbose level.

gearman_st* gearman_create ( gearman_st * gearman )

Initialize a gearman structure. Always check the return value even if passing in a pre-allocated structure. Some other initialization may have failed.

Parameters:

[in] gearman 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_st* gearman_clone	(	gearman_st *	gearman,
		const gearman_st *	from
	)

Clone a gearman structure.

Parameters:

`[in]`	gearman	Caller allocated structure, or NULL to allocate one.
`[in]`	from	Structure to use as a source to clone from.

Returns:: Same return as gearman_create().

void gearman_free ( gearman_st * gearman )

Free a gearman structure.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

const char* gearman_error ( const gearman_st * gearman )

Return an error string for last error encountered.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

Returns:: Pointer to a buffer in the structure that holds an error string.

int gearman_errno ( const gearman_st * gearman )

Value of errno in the case of a GEARMAN_ERRNO return value.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

Returns:: An errno value as defined in your system errno.h file.

gearman_options_t gearman_options ( const gearman_st * gearman )

Get options for a gearman structure.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

Returns:: Options set for the gearman structure.

void gearman_set_options	(	gearman_st *	gearman,
		gearman_options_t	options
	)

Set options for a gearman structure.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	options	Available options for gearman structures.

void gearman_add_options	(	gearman_st *	gearman,
		gearman_options_t	options
	)

Add options for a gearman structure.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	options	Available options for gearman structures.

void gearman_remove_options	(	gearman_st *	gearman,
		gearman_options_t	options
	)

Remove options for a gearman structure.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	options	Available options for gearman structures.

int gearman_timeout ( gearman_st * gearman )

Get current socket I/O activity timeout value.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

Returns:: Timeout in milliseconds to wait for I/O activity. A negative value means an infinite timeout.

void gearman_set_timeout	(	gearman_st *	gearman,
		int	timeout
	)

Set socket I/O activity timeout for connections in a Gearman structure.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	timeout	Milliseconds to wait for I/O activity. A negative value means an infinite timeout.

void gearman_set_log_fn	(	gearman_st *	gearman,
		gearman_log_fn *	function,
		const void *	context,
		gearman_verbose_t	verbose
	)

Set logging function for a gearman structure.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	function	Function to call when there is a logging message.
`[in]`	context	Argument to pass into the callback function.
`[in]`	verbose	Verbosity level threshold. Only call function when the logging message is equal to or less verbose that this.

void gearman_set_event_watch_fn	(	gearman_st *	gearman,
		gearman_event_watch_fn *	function,
		const void *	context
	)

Set custom I/O event callback function for a gearman structure.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	function	Function to call when there is an I/O event.
`[in]`	context	Argument to pass into the callback function.

void gearman_set_workload_malloc_fn	(	gearman_st *	gearman,
		gearman_malloc_fn *	function,
		const void *	context
	)

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

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	function	Memory allocation function to use instead of malloc().
`[in]`	context	Argument to pass into the callback function.

void gearman_set_workload_free_fn	(	gearman_st *	gearman,
		gearman_free_fn *	function,
		const 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_create() or gearman_clone().
`[in]`	function	Memory free function to use instead of free().
`[in]`	context	Argument to pass into the callback function.

gearman_con_st* gearman_con_create	(	gearman_st *	gearman,
		gearman_con_st *	con
	)

Initialize a connection structure. Always check the return value even if passing in a pre-allocated structure. Some other initialization may have failed.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	con	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_con_st* gearman_con_add	(	gearman_st *	gearman,
		gearman_con_st *	con,
		const char *	host,
		in_port_t	port
	)

Create a connection structure with the given host and port.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	con	Caller allocated structure, or NULL to allocate one.
`[in]`	host	Host or IP address to connect to.
`[in]`	port	Port to connect to.

Returns:: On success, a pointer to the (possibly allocated) structure. On failure this will be NULL.

gearman_con_st* gearman_con_clone	(	gearman_st *	gearman,
		gearman_con_st *	con,
		const gearman_con_st *	from
	)

Clone a connection structure.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	con	Caller allocated structure, or NULL to allocate one.
`[in]`	from	Structure to use as a source to clone from.

Returns:: On success, a pointer to the (possibly allocated) structure. On failure this will be NULL.

void gearman_con_free ( gearman_con_st * con )

Free a connection structure.

Parameters:

[in] con Structure previously initialized with gearman_con_create(), gearman_con_add(), or gearman_con_clone().

void gearman_con_free_all ( gearman_st * gearman )

Free all connections for a gearman structure.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

gearman_return_t gearman_con_flush_all ( gearman_st * gearman )

Flush the send buffer for all connections.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

Returns:: Standard gearman return value.

gearman_return_t gearman_con_send_all	(	gearman_st *	gearman,
		const gearman_packet_st *	packet
	)

Send packet to all connections.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	packet	Initialized packet to send to all connections.

Returns:: Standard gearman return value.

gearman_return_t gearman_con_wait ( gearman_st * gearman )

Wait for I/O on connections.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

Returns:: Standard gearman return value.

gearman_con_st* gearman_con_ready ( gearman_st * gearman )

Get next connection that is ready for I/O.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

Returns:: Connection that is ready for I/O, or NULL if there are none.

gearman_return_t gearman_con_echo	(	gearman_st *	gearman,
		const void *	workload,
		size_t	workload_size
	)

Test echo with all connections.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	workload	Data to send in echo packet.
`[in]`	workload_size	Size of workload.

Returns:: Standard gearman return value.

gearman_packet_st* gearman_packet_create	(	gearman_st *	gearman,
		gearman_packet_st *	packet
	)

Initialize a packet structure.

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	packet	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_return_t gearman_packet_add	(	gearman_st *	gearman,
		gearman_packet_st *	packet,
		gearman_magic_t	magic,
		gearman_command_t	command,
		const void *	arg,
			...
	)

Initialize a packet with all arguments. Variable list is NULL terminated alternating argument and argument size (size_t) pairs. For example:

 ret= gearman_packet_add_args(gearman, packet,
                              GEARMAN_MAGIC_REQUEST,
                              GEARMAN_COMMAND_SUBMIT_JOB,
                              function_name, strlen(function_name) + 1,
                              unique_string, strlen(unique_string) + 1,
                              workload, workload_size, NULL);

Parameters:

`[in]`	gearman	Structure previously initialized with gearman_create() or gearman_clone().
`[in]`	packet	Pre-allocated packet to initialize with arguments.
`[in]`	magic	Magic type for packet header.
`[in]`	command	Command type for packet.
`[in]`	arg	NULL terminated argument list in pairs of "arg, arg_size".

Returns:: Standard gearman return value.

void gearman_packet_free ( gearman_packet_st * packet )

Free a packet structure.

Parameters:

[in] packet Structure previously initialized with gearman_packet_create() or gearman_packet_add().

void gearman_packet_free_all ( gearman_st * gearman )

Free all packets for a gearman structure.

Parameters:

[in] gearman Structure previously initialized with gearman_create() or gearman_clone().

Gearman Public API Documentation

Gearman Core Interface

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation