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

NAME

6       tevent_queue_tutorial - The tevent_queue tutorial
7
8

Introduction

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

Example

42       Metze: Please add a code example here.
43
44Version 0.9.8                   Fri Jun 10 2022       tevent_queue_tutorial(3)