tevent_queue_tutorial(3) tevent tevent_queue_tutorial(3)NAME
tevent_queue_tutorial - The tevent_queue tutorial
Introduction
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.
To do this, every socket gets assigned a tevent_queue struct.
Creating a serialized async request follows the usual convention to return a tevent_req structure with an embedded state structure. To
serialize the work the requests is about to so, instead of directly starting or doing that work, tevent_queue_add must be called. When it
is time for the serialized async request to do its work, the trigger callback function tevent_queue_add was given is called. In the example
of writing to a socket, the trigger is called when the write request can begin accessing the socket.
How does this engine work behind the scenes? When the queue is empty, tevent_queue_add schedules an immediate call to the trigger callback.
The trigger callback starts its work, likely by starting other async subrequests. While these async subrequests are working, more requests
can accumulate in the queue by tevent_queue_add. While there is no function to explicitly trigger the next waiter in line, it still works:
When the active request in the queue is done, it will be destroyed by talloc_free. Talloc_free of an serialized async request that had been
added to a queue will trigger the next request in the queue via a talloc destructor attached to a child of the serialized request. This way
the queue will be kept busy when an async request finishes.
Example
* Metze: Please add a code example here.
*
Version 0.9.8 Tue Jun 17 2014 tevent_queue_tutorial(3)
Check Out this Related Man Page
The tevent queue functions(3) tevent The tevent queue functions(3)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.
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.
Author
Generated automatically by Doxygen for tevent from the source code.
Version 0.9.8 Tue Jun 17 2014 The tevent queue functions(3)