tevent: Added an introduction to the tevent_queue tutorial.

Thanks Volker.

1 files changed, 38 insertions, 4 deletions

diff --git a/lib/tevent/doc/tutorials.dox b/lib/tevent/doc/tutorials.dox
index ba1fd904e3..e8beed7dc0 100644
--- a/lib/tevent/doc/tutorials.dox
+++ b/lib/tevent/doc/tutorials.dox
@@ -1,9 +1,43 @@
 /**
- * @page tevent_queue_tutorial teven_queue tutorial
+ * @page tevent_queue_tutorial The tevent_queue tutorial
  *
- * @section something Something
+ * @section Introduction
  *
- * @todo Write down the logic how to use teven_queue
+ * 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.
  *
- * guru meditation
+ * 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.
+ *
+ * @section Example
+ *
+ * @code
+ *      Metze: Please add a code example here.
+ * @endcode
  */