1tevent_queue_tutorial(3)            tevent            tevent_queue_tutorial(3)
2
3
4

NAME

6       tevent_queue_tutorial - The tevent_queue tutorial
7

Introduction

9       A tevent_queue is used to queue up async requests that must be
10       serialized. For example writing buffers into a socket must be
11       serialized. Writing a large lump of data into a socket can require
12       multiple write(2) or send(2) system calls. If more than one async
13       request is outstanding to write large buffers into a socket, every
14       request must individually be completed before the next one begins, even
15       if multiple syscalls are required.
16
17       To do this, every socket gets assigned a tevent_queue struct.
18
19       Creating a serialized async request follows the usual convention to
20       return a tevent_req structure with an embedded state structure. To
21       serialize the work the requests is about to so, instead of directly
22       starting or doing that work, tevent_queue_add must be called. When it
23       is time for the serialized async request to do its work, the trigger
24       callback function tevent_queue_add was given is called. In the example
25       of writing to a socket, the trigger is called when the write request
26       can begin accessing the socket.
27
28       How does this engine work behind the scenes? When the queue is empty,
29       tevent_queue_add schedules an immediate call to the trigger callback.
30       The trigger callback starts its work, likely by starting other async
31       subrequests. While these async subrequests are working, more requests
32       can accumulate in the queue by tevent_queue_add. While there is no
33       function to explicitly trigger the next waiter in line, it still works:
34       When the active request in the queue is done, it will be destroyed by
35       talloc_free. Talloc_free of an serialized async request that had been
36       added to a queue will trigger the next request in the queue via a
37       talloc destructor attached to a child of the serialized request. This
38       way the queue will be kept busy when an async request finishes.
39

Example

41       Metze: Please add a code example here.
42
43Version 0.9.8                   Thu Feb 16 2023       tevent_queue_tutorial(3)