2. EL 9
  3. libtevent-devel
  4. tevent_queue(3)

Scroll to navigation

tevent_queue(3) tevent tevent_queue(3)

NAME

tevent_queue - The tevent queue functions


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

SYNOPSIS

Modules


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

Typedefs


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

Functions


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.

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

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.

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.

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

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_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

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

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

void tevent_queue_entry_set_tag (struct tevent_queue_entry * qe, uint64_t tag)

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.

void tevent_queue_entry_untrigger (struct tevent_queue_entry * entry)

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 don't have access to the quene 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()

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

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

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.

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.

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_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

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.

Mon Dec 4 2023 Version 0.9.8