A tevent_queue is used to queue up async requests that must be serialized. More...

Typedefs
typedef void(*	tevent_queue_trigger_fn_t) (struct tevent_req req, void private_data)
	A callback trigger function run by the queue. More...

Functions
struct tevent_queue *	tevent_queue_create (TALLOC_CTX mem_ctx, const char name)
	Create and start a tevent queue. More...

bool	tevent_queue_add (struct tevent_queue queue, struct tevent_context ev, struct tevent_req req, tevent_queue_trigger_fn_t trigger, void private_data)
	Add a tevent request to the queue. More...

struct tevent_queue_entry *	tevent_queue_add_entry (struct tevent_queue queue, struct tevent_context ev, struct tevent_req req, tevent_queue_trigger_fn_t trigger, void private_data)
	Add a tevent request to the queue. More...

struct tevent_queue_entry *	tevent_queue_add_optimize_empty (struct tevent_queue queue, struct tevent_context ev, struct tevent_req req, tevent_queue_trigger_fn_t trigger, void private_data)
	Add a tevent request to the queue using a possible optimization. More...

void	tevent_queue_start (struct tevent_queue *queue)
	Start a tevent queue. More...

void	tevent_queue_stop (struct tevent_queue *queue)
	Stop a tevent queue. More...

size_t	tevent_queue_length (struct tevent_queue *queue)
	Get the length of the queue. More...

bool	tevent_queue_running (struct tevent_queue *queue)
	Is the tevent queue running. More...

struct tevent_req *	tevent_queue_wait_send (TALLOC_CTX mem_ctx, struct tevent_context ev, struct tevent_queue *queue)
	Create a tevent subrequest that waits in a tevent_queue. More...

bool	tevent_queue_wait_recv (struct tevent_req *req)
	Check if we no longer need to wait in the queue. More...

struct tevent_thread_proxy *	tevent_thread_proxy_create (struct tevent_context *dest_ev_ctx)
	Create a tevent_thread_proxy for message passing between threads. More...

void	tevent_thread_proxy_schedule (struct tevent_thread_proxy tp, struct tevent_immediate pp_im, tevent_immediate_handler_t handler, void pp_private_data)
	Schedule an immediate event on an event context from another thread. More...

Detailed Description

A tevent_queue is used to queue up async requests that must be serialized.

For example writing buffers into a socket must be serialized. Writing a large lump of data into a socket can require multiple write(2) or send(2) system calls. If more than one async request is outstanding to write large buffers into a socket, every request must individually be completed before the next one begins, even if multiple syscalls are required.

Take a look at The tevent_queue tutorial for more details.

Typedef Documentation

§ tevent_queue_trigger_fn_t

typedef void(* tevent_queue_trigger_fn_t) (struct tevent_req *req, void *private_data)

A callback trigger function run by the queue.

Parameters

[in]	req	The tevent request the trigger function is executed on.
[in]	private_data	The private data pointer specified by tevent_queue_add().

See also: tevent_queue_add(); tevent_queue_add_entry(); tevent_queue_add_optimize_empty()

Function Documentation

§ tevent_queue_add()

bool tevent_queue_add	(	struct tevent_queue *	queue,
		struct tevent_context *	ev,
		struct tevent_req *	req,
		tevent_queue_trigger_fn_t	trigger,
		void *	private_data
	)

Add a tevent request to the queue.

Parameters

[in]	queue	The queue to add the request.
[in]	ev	The event handle to use for the request.
[in]	req	The tevent request to add to the queue.
[in]	trigger	The function triggered by the queue when the request is called. Since tevent 0.9.14 it's possible to pass NULL, in order to just add a "blocker" to the queue.
[in]	private_data	The private data passed to the trigger function.

Returns: True if the request has been successfully added, false otherwise.

§ tevent_queue_add_entry()

struct tevent_queue_entry* tevent_queue_add_entry	(	struct tevent_queue *	queue,
		struct tevent_context *	ev,
		struct tevent_req *	req,
		tevent_queue_trigger_fn_t	trigger,
		void *	private_data
	)

Add a tevent request to the queue.

The request can be removed from the queue by calling talloc_free() (or a similar function) on the returned queue entry. This is the only difference to tevent_queue_add().

Parameters

[in]	queue	The queue to add the request.
[in]	ev	The event handle to use for the request.
[in]	req	The tevent request to add to the queue.
[in]	trigger	The function triggered by the queue when the request is called. Since tevent 0.9.14 it's possible to pass NULL, in order to just add a "blocker" to the queue.
[in]	private_data	The private data passed to the trigger function.

Returns: a pointer to the tevent_queue_entry if the request has been successfully added, NULL otherwise.

See also: tevent_queue_add(); tevent_queue_add_optimize_empty()

§ tevent_queue_add_optimize_empty()

struct tevent_queue_entry* tevent_queue_add_optimize_empty	(	struct tevent_queue *	queue,
		struct tevent_context *	ev,
		struct tevent_req *	req,
		tevent_queue_trigger_fn_t	trigger,
		void *	private_data
	)

Add a tevent request to the queue using a possible optimization.

This tries to optimize for the empty queue case and may calls the trigger function directly. This is the only difference compared to tevent_queue_add_entry().

The caller needs to be prepared that the trigger function has already called tevent_req_notify_callback(), tevent_req_error(), tevent_req_done() or a similar function.

The request can be removed from the queue by calling talloc_free() (or a similar function) on the returned queue entry.

Parameters

[in]	queue	The queue to add the request.
[in]	ev	The event handle to use for the request.
[in]	req	The tevent request to add to the queue.
[in]	trigger	The function triggered by the queue when the request is called. Since tevent 0.9.14 it's possible to pass NULL, in order to just add a "blocker" to the queue.
[in]	private_data	The private data passed to the trigger function.

Returns: a pointer to the tevent_queue_entry if the request has been successfully added, NULL otherwise.

See also: tevent_queue_add(); tevent_queue_add_entry()

§ tevent_queue_create()

struct tevent_queue* tevent_queue_create	(	TALLOC_CTX *	mem_ctx,
		const char *	name
	)

Create and start a tevent queue.

Parameters

[in]	mem_ctx	The talloc memory context to allocate the queue.
[in]	name	The name to use to identify the queue.

Returns: An allocated tevent queue on success, NULL on error.

See also: tevent_queue_start(); tevent_queue_stop()

§ tevent_queue_length()

size_t tevent_queue_length ( struct tevent_queue * queue )

Get the length of the queue.

Parameters

[in] queue The queue to get the length from.

Returns: The number of elements.

§ tevent_queue_running()

bool tevent_queue_running ( struct tevent_queue * queue )

Is the tevent queue running.

The queue is started by default.

Parameters

[in] queue The queue.

Returns: Wether the queue is running or not..

§ tevent_queue_start()

void tevent_queue_start ( struct tevent_queue * queue )

Start a tevent queue.

The queue is started by default.

Parameters

[in] queue The queue to start.

§ tevent_queue_stop()

void tevent_queue_stop ( struct tevent_queue * queue )

Stop a tevent queue.

The queue is started by default.

Parameters

[in] queue The queue to stop.

§ tevent_queue_wait_recv()

bool tevent_queue_wait_recv ( struct tevent_req * req )

Check if we no longer need to wait in the queue.

This function needs to be called in the callback function set after calling tevent_queue_wait_send().

Parameters

[in] req The tevent request to check.

Returns: True on success, false otherwise.

See also: tevent_queue_wait_send()

§ tevent_queue_wait_send()

struct tevent_req* tevent_queue_wait_send	(	TALLOC_CTX *	mem_ctx,
		struct tevent_context *	ev,
		struct tevent_queue *	queue
	)

Create a tevent subrequest that waits in a tevent_queue.

The idea is that always the same syntax for tevent requests.

Parameters

[in]	mem_ctx	The talloc memory context to use.
[in]	ev	The event handle to setup the request.
[in]	queue	The queue to wait in.

Returns: The new subrequest, NULL on error.

See also: tevent_queue_wait_recv()

§ tevent_thread_proxy_create()

struct tevent_thread_proxy* tevent_thread_proxy_create ( struct tevent_context * dest_ev_ctx )

Create a tevent_thread_proxy for message passing between threads.

The tevent_context must have been allocated on the NULL talloc context, and talloc_disable_null_tracking() must have been called.

Parameters

[in] dest_ev_ctx The tevent_context to receive events.

Returns: An allocated tevent_thread_proxy, NULL on error. If tevent was compiled without PTHREAD support NULL is always returned and errno set to ENOSYS.

See also: tevent_thread_proxy_schedule()

§ tevent_thread_proxy_schedule()

void tevent_thread_proxy_schedule	(	struct tevent_thread_proxy *	tp,
		struct tevent_immediate **	pp_im,
		tevent_immediate_handler_t	handler,
		void *	pp_private_data
	)

Schedule an immediate event on an event context from another thread.

Causes dest_ev_ctx, being run by another thread, to receive an immediate event calling the handler with the *pp_private parameter.

*pp_im must be a pointer to an immediate event talloced on a context owned by the calling thread, or the NULL context. Ownership will be transferred to the tevent_thread_proxy and *pp_im will be returned as NULL.

*pp_private_data must be a talloced area of memory with no destructors. Ownership of this memory will be transferred to the tevent library and *pp_private_data will be set to NULL on successful completion of the call. Set pp_private to NULL if no parameter transfer needed (a pure callback). This is an asynchronous request, caller does not wait for callback to be completed before returning.

Parameters

[in]	tp	The tevent_thread_proxy to use.
[in]	pp_im	Pointer to immediate event pointer.
[in]	handler	The function that will be called.
[in]	pp_private_data	The talloced memory to transfer.

See also: tevent_thread_proxy_create()

Typedefs

Functions

Detailed Description

Typedef Documentation

§ tevent_queue_trigger_fn_t

Function Documentation

§ tevent_queue_add()

§ tevent_queue_add_entry()

§ tevent_queue_add_optimize_empty()

§ tevent_queue_create()

§ tevent_queue_length()

§ tevent_queue_running()

§ tevent_queue_start()

§ tevent_queue_stop()

§ tevent_queue_wait_recv()

§ tevent_queue_wait_send()

§ tevent_thread_proxy_create()

§ tevent_thread_proxy_schedule()