tevent_queue (3) - Linux Manuals

NAME

The tevent queue functions -

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

Typedefs

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

Functions

struct tevent_queue * tevent_queue_create (TALLOC_CTX *mem_ctx, const char *name)
Create and start a tevent queue.
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.
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.
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.
void tevent_queue_start (struct tevent_queue *queue)
Start a tevent queue.
void tevent_queue_stop (struct tevent_queue *queue)
Stop a tevent queue.
size_t tevent_queue_length (struct tevent_queue *queue)
Get the length of the queue.
bool tevent_queue_running (struct tevent_queue *queue)
Is the tevent queue running.
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.
bool tevent_queue_wait_recv (struct tevent_req *req)
Check if we no longer need to wait in the queue.
struct tevent_thread_proxy * tevent_thread_proxy_create (struct tevent_context *dest_ev_ctx)
Create a tevent_thread_proxy for message passing between threads.
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.

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

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

A callback trigger function run by the queue.

Parameters:

req The tevent request the trigger function is executed on.
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

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

Add a tevent request to the queue.

Parameters:

queue The queue to add the request.
ev The event handle to use for the request.
req The tevent request to add to the queue.
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.
private_data The private data passed to the trigger function.

Returns:

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

struct tevent_queue_entry* tevent_queue_add_entry (struct tevent_queue *queue, struct tevent_context *ev, struct tevent_req *req, tevent_queue_trigger_fn_ttrigger, 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:

queue The queue to add the request.
ev The event handle to use for the request.
req The tevent request to add to the queue.
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.
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()

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_ttrigger, 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:

queue The queue to add the request.
ev The event handle to use for the request.
req The tevent request to add to the queue.
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.
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()

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

Create and start a tevent queue.

Parameters:

mem_ctx The talloc memory context to allocate the queue.
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()

size_t tevent_queue_length (struct tevent_queue *queue)

Get the length of the queue.

Parameters:

queue The queue to get the length from.

Returns:

The number of elements.

bool tevent_queue_running (struct tevent_queue *queue)

Is the tevent queue running. The queue is started by default.

Parameters:

queue The queue.

Returns:

Wether the queue is running or not..

void tevent_queue_start (struct tevent_queue *queue)

Start a tevent queue. The queue is started by default.

Parameters:

queue The queue to start.

void tevent_queue_stop (struct tevent_queue *queue)

Stop a tevent queue. The queue is started by default.

Parameters:

queue The queue to stop.

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:

req The tevent request to check.

Returns:

True on success, false otherwise.

See Also:

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:

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

Returns:

The new subrequest, NULL on error.

See Also:

tevent_queue_wait_recv()

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:

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

void tevent_thread_proxy_schedule (struct tevent_thread_proxy *tp, struct tevent_immediate **pp_im, tevent_immediate_handler_thandler, 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:

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

See Also:

tevent_thread_proxy_create()

Author

Generated automatically by Doxygen for tevent from the source code.