| 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 | */
|
|---|
