tevent_queue(3)

📦

version 0.17.1 · 3 versions

0.17.1 · centos-stream 10, fedora 43, opensuse-leap 16.0 (latest)
0.17.1 · centos-stream 9
0.17.1 · fedora 44

, in centos-stream 10, fedora 43, opensuse-leap 16.0

tevent_queue 💖

okay bestie, welcome to tevent_queue(3) from the Library Functions Manual — yes it's a big one, but we're gonna get through it together, no cap. ✨

🌸 NAME 🌸

tevent_queue — the tevent queue functions, and honestly? iconic.

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

✨ SYNOPSIS ✨

🎀 Topics

The tevent operation functions

The following structure and registration functions are exclusively needed for people writing and plugging a different event engine. (iykyk — if that's you, hi, you're the main character here 👑)

🦋 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 that custom queue entry tag back out.
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 (this one hands you back the entry, slay).
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. Like, one at a time, in order, no cutting the line. 🚶♀️🚶♀️🚶♀️

For example, writing buffers into a socket must be serialized. Fr fr. Writing a large lump of data into a socket can require multiple write(2) or send(2) system calls. And 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. No skipping ahead, no vibes-based interleaving. 😤

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

✨ Function Documentation ✨

🦋 `tevent_get_trace_queue_callback()`

void tevent_get_trace_queue_callback (struct tevent_context * ev,
    tevent_trace_queue_callback_t * cb, void * p_private_data)

okay so bestie, this one retrieves the current trace callback of queue. Like, it hands you back the callback that's already vibing in there. 💖

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. So like… don't be the friend who steamrolls the group chat, okay? Respect the existing callback. 🫶

🌸 `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. Straight up. The request joins the line and waits its turn like everyone else. 👑

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.

🎀 `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 — but this time it hands you back the receipt. 🧾 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()

💅 `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. 😭 Like, no take-backs, it already happened, bestie.

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

🌈 `tevent_queue_create()`

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

Create and start a tevent queue. Boom, a whole new queue, born ready. 👑

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

🍓 `tevent_queue_entry_set_tag()`

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(). It's giving "personalized name tag at the party" energy.

Parameters

qe — The queue entry.
tag — Custom tag.

💀 `tevent_queue_entry_untrigger()`

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(). Order matters, bestie, do not freestyle this. 🚨

⚠️ 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(). That's not a vibe, that's a crash. 💀

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

🧚 `tevent_queue_length()`

size_t tevent_queue_length (struct tevent_queue * queue)

Get the length of the queue. How many besties are waiting in line. 💖

Parameters

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

queue — The queue.

Returns

Whether 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 — so lowkey it was already running, but hey, you do you. ✨

Parameters

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. Time to hit pause. ⏸️

Parameters

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(). That's the rules, iykyk.

Parameters

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. Consistent queen behavior. 💅

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

🔥 `tevent_set_trace_queue_callback()`

void tevent_set_trace_queue_callback (struct tevent_context * ev,
    tevent_trace_queue_callback_t cb, void * private_data)

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.

🧵 `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. No cap, that's a hard requirement.

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

🌈 `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.

and that's a wrap on tevent_queue(3), bestie 💖 this whole page was auto-generated by Doxygen for tevent, and it's riding with Version 0.9.8 — go forth and queue responsibly, mwah 🎀✨

📦 where this page comes from

centos-stream 10: libtevent-devel 0.17.1-100.el10 · LGPL-3.0-or-later
fedora 43: libtevent-devel 0.17.1-3.fc43 · LGPL-3.0-or-later
fedora 43: libtevent-devel 0.17.1-3.fc43 · LGPL-3.0-or-later
opensuse-leap 16.0: tevent-man 0.16.2-160000.2.2 · LGPL-3.0-or-later
opensuse-leap 16.0: tevent-man 0.16.2-160000.2.2 · LGPL-3.0-or-later
opensuse-leap 16.0: tevent-man 0.16.2-160000.2.2 · LGPL-3.0-or-later
opensuse-leap 16.0: tevent-man 0.16.2-160000.2.2 · LGPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

tevent_queue(3)

tevent_queue 💖

🌸 NAME 🌸

✨ SYNOPSIS ✨

🎀 Topics

The tevent operation functions

🦋 Typedefs

🌈 Functions

💜 Detailed Description 💜

⭐ Typedef Documentation ⭐

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

Parameters

See also

✨ Function Documentation ✨

🦋 tevent_get_trace_queue_callback()

🌸 tevent_queue_add()

🎀 tevent_queue_add_entry()

💅 tevent_queue_add_optimize_empty()

🌈 tevent_queue_create()

🍓 tevent_queue_entry_set_tag()

💀 tevent_queue_entry_untrigger()

🧚 tevent_queue_length()

⭐ tevent_queue_running()

👑 tevent_queue_start()

🛑 tevent_queue_stop()

🦋 tevent_queue_wait_recv()

🌸 tevent_queue_wait_send()

🔥 tevent_set_trace_queue_callback()

🧵 tevent_thread_proxy_create()

🌈 tevent_thread_proxy_schedule()

🫶 Author

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

🦋 `tevent_get_trace_queue_callback()`

🌸 `tevent_queue_add()`

🎀 `tevent_queue_add_entry()`

💅 `tevent_queue_add_optimize_empty()`

🌈 `tevent_queue_create()`

🍓 `tevent_queue_entry_set_tag()`

💀 `tevent_queue_entry_untrigger()`

🧚 `tevent_queue_length()`

⭐ `tevent_queue_running()`

👑 `tevent_queue_start()`

🛑 `tevent_queue_stop()`

🦋 `tevent_queue_wait_recv()`

🌸 `tevent_queue_wait_send()`

🔥 `tevent_set_trace_queue_callback()`

🧵 `tevent_thread_proxy_create()`

🌈 `tevent_thread_proxy_schedule()`