[SCM] Samba Shared Repository - branch master updated
Andreas Schneider
asn at samba.org
Mon May 10 02:29:14 MDT 2010
The branch, master has been updated
via 3addebe... tevent: Added a description for tevent queue.
via d596bb1... tevent: Added an introduction to the tevent_queue tutorial.
via b2e520a... tevent: Fixed a doxygen problem with PRINTF_ATTRIBUTE.
via 876ed03... talloc: Fixed a doxygen problem with PRINTF_ATTRIBUTE.
from 7c68512... build: Update the waf build to fix python header checks
http://gitweb.samba.org/?p=samba.git;a=shortlog;h=master
- Log -----------------------------------------------------------------
commit 3addebee349d0122781410eea8166f964f885568
Author: Andreas Schneider <asn at samba.org>
Date: Mon May 10 10:27:42 2010 +0200
tevent: Added a description for tevent queue.
commit d596bb1a1db8cc2851a51525e232bdba984342d6
Author: Andreas Schneider <asn at samba.org>
Date: Mon May 10 10:24:53 2010 +0200
tevent: Added an introduction to the tevent_queue tutorial.
Thanks Volker.
commit b2e520a28b0d4b4285b177925a480ef2df89a345
Author: Andreas Schneider <asn at samba.org>
Date: Mon May 10 09:56:18 2010 +0200
tevent: Fixed a doxygen problem with PRINTF_ATTRIBUTE.
commit 876ed034c8c6c6e8ac4b2115a372bfcb244f1859
Author: Andreas Schneider <asn at samba.org>
Date: Mon May 10 09:55:44 2010 +0200
talloc: Fixed a doxygen problem with PRINTF_ATTRIBUTE.
-----------------------------------------------------------------------
Summary of changes:
lib/talloc/doxy.config | 6 +++---
lib/tevent/doc/tutorials.dox | 42 ++++++++++++++++++++++++++++++++++++++----
lib/tevent/doxy.config | 6 +++---
lib/tevent/tevent.h | 9 +++++++++
4 files changed, 53 insertions(+), 10 deletions(-)
Changeset truncated at 500 lines:
diff --git a/lib/talloc/doxy.config b/lib/talloc/doxy.config
index c3e80d2..5e3a319 100644
--- a/lib/talloc/doxy.config
+++ b/lib/talloc/doxy.config
@@ -1247,13 +1247,13 @@ ENABLE_PREPROCESSING = YES
# compilation will be performed. Macro expansion can be done in a controlled
# way by setting EXPAND_ONLY_PREDEF to YES.
-MACRO_EXPANSION = NO
+MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
# then the macro expansion is limited to the macros specified with the
# PREDEFINED and EXPAND_AS_DEFINED tags.
-EXPAND_ONLY_PREDEF = NO
+EXPAND_ONLY_PREDEF = YES
# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
# in the INCLUDE_PATH (see below) will be search if a #include is found.
@@ -1281,7 +1281,7 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
-PREDEFINED = DOXYGEN
+PREDEFINED = DOXYGEN PRINTF_ATTRIBUTE(x,y)=
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
diff --git a/lib/tevent/doc/tutorials.dox b/lib/tevent/doc/tutorials.dox
index ba1fd90..e8beed7 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
*/
diff --git a/lib/tevent/doxy.config b/lib/tevent/doxy.config
index a3cd092..578ecaf 100644
--- a/lib/tevent/doxy.config
+++ b/lib/tevent/doxy.config
@@ -1247,13 +1247,13 @@ ENABLE_PREPROCESSING = YES
# compilation will be performed. Macro expansion can be done in a controlled
# way by setting EXPAND_ONLY_PREDEF to YES.
-MACRO_EXPANSION = NO
+MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
# then the macro expansion is limited to the macros specified with the
# PREDEFINED and EXPAND_AS_DEFINED tags.
-EXPAND_ONLY_PREDEF = NO
+EXPAND_ONLY_PREDEF = YES
# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
# in the INCLUDE_PATH (see below) will be search if a #include is found.
@@ -1281,7 +1281,7 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
-PREDEFINED = DOXYGEN
+PREDEFINED = DOXYGEN PRINTF_ATTRIBUTE(x,y)=
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
diff --git a/lib/tevent/tevent.h b/lib/tevent/tevent.h
index 1bca332..40fbbe6 100644
--- a/lib/tevent/tevent.h
+++ b/lib/tevent/tevent.h
@@ -1152,6 +1152,15 @@ struct timeval tevent_timeval_current_ofs(uint32_t secs, uint32_t usecs);
* @defgroup tevent_queue The tevent queue functions
* @ingroup tevent
*
+ * 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.
+ *
+ * Take a look at @ref tevent_queue_tutorial for more details.
* @{
*/
--
Samba Shared Repository
More information about the samba-cvs
mailing list