nsswitch: Remove #if SAMBA_BUILD_ >= 4 now we only have the waf build
[Samba/gebeck_regimport.git] / lib / tevent / doc / tutorials.dox
blobe8beed7dc0d147ccb34f70aae203806059a812b3
1 /**
2  * @page tevent_queue_tutorial The tevent_queue tutorial
3  *
4  * @section Introduction
5  *
6  * A tevent_queue is used to queue up async requests that must be
7  * serialized. For example writing buffers into a socket must be
8  * serialized. Writing a large lump of data into a socket can require
9  * multiple write(2) or send(2) system calls. If more than one async
10  * request is outstanding to write large buffers into a socket, every
11  * request must individually be completed before the next one begins,
12  * even if multiple syscalls are required.
13  *
14  * To do this, every socket gets assigned a tevent_queue struct.
15  *
16  * Creating a serialized async request follows the usual convention to
17  * return a tevent_req structure with an embedded state structure. To
18  * serialize the work the requests is about to so, instead of directly
19  * starting or doing that work, tevent_queue_add must be called. When it
20  * is time for the serialized async request to do its work, the trigger
21  * callback function tevent_queue_add was given is called. In the example
22  * of writing to a socket, the trigger is called when the write request
23  * can begin accessing the socket.
24  *
25  * How does this engine work behind the scenes? When the queue is empty,
26  * tevent_queue_add schedules an immediate call to the trigger
27  * callback. The trigger callback starts its work, likely by starting
28  * other async subrequests. While these async subrequests are working,
29  * more requests can accumulate in the queue by tevent_queue_add. While
30  * there is no function to explicitly trigger the next waiter in line, it
31  * still works: When the active request in the queue is done, it will be
32  * destroyed by talloc_free. Talloc_free of an serialized async request
33  * that had been added to a queue will trigger the next request in the
34  * queue via a talloc destructor attached to a child of the serialized
35  * request. This way the queue will be kept busy when an async request
36  * finishes.
37  *
38  * @section Example
39  *
40  * @code
41  *      Metze: Please add a code example here.
42  * @endcode
43  */