tevent_queue - Man Page

The tevent operation functions
The following structure and registration functions are exclusively needed for people writing and plugging a different event engine​.

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

void tevent_queue_entry_set_tag (struct tevent_queue_entry *qe, uint64_t tag)
Associate a custom tag with the queue entry​.
uint64_t tevent_queue_entry_get_tag (const struct tevent_queue_entry *qe)
Get custom queue entry tag​.
void tevent_set_trace_queue_callback (struct tevent_context *ev, tevent_trace_queue_callback_t cb, void *private_data)
Register a callback to be called at certain trace points of queue​.
void tevent_get_trace_queue_callback (struct tevent_context *ev, tevent_trace_queue_callback_t *cb, void *p_private_data)
Retrieve the current trace callback of queue​.
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_entry_untrigger (struct tevent_queue_entry *entry)
Untrigger an already triggered queue entry​.
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​.

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

Retrieve the current trace callback of queue​.

Parameters

ev Event context
cb Registered trace callback
p_private_data Registered data to be passed to callback

Note

This can be used to allow one component that wants to register a callback to respect the callback that another component has already registered​.

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​.

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

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 trigger function has no chance to see the returned queue_entry in the optimized case​.

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

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

Associate a custom tag with the queue entry​. This tag can be then retrieved with tevent_queue_entry_get_tag()

Parameters

qe The queue entry​.
tag Custom tag​.

Untrigger an already triggered queue entry​. If a trigger function detects that it needs to remain in the queue, it needs to call tevent_queue_stop() followed by tevent_queue_entry_untrigger()​.

Note

In order to call tevent_queue_entry_untrigger() the queue must be already stopped and the given queue_entry must be the first one in the queue! Otherwise it calls abort()​.

You can't use this together with tevent_queue_add_optimize_empty() because the trigger function doesn't have access to the queue entry in the case of an empty queue​.

Parameters

queue_entry The queue entry to rearm​.

See also

tevent_queue_add_entry()

tevent_queue_stop()

Get the length of the queue​.

Parameters

queue The queue to get the length from​.

Returns

The number of elements​.

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

Parameters

queue The queue​.

Returns

Whether the queue is running or not​.​.

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

Parameters

queue The queue to start​.

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

Parameters

queue The queue to stop​.

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

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

Register a callback to be called at certain trace points of queue​.

Parameters

ev Event context
cb Trace callback
private_data Data to be passed to callback

Note

The callback will be called at trace points defined by tevent_event_trace_point​. Call with NULL to reset​.

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

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