[asterisk-commits] mmichelson: branch mmichelson/threadpool r376382 - /team/mmichelson/threadpoo...

[SVN commits to the Asterisk project]

Author: mmichelson
Date: Thu Nov 15 22:44:12 2012
New Revision: 376382

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=376382
Log:
Change the write-up on taskprocessors to reflect the new design.


Modified:
    team/mmichelson/threadpool/include/asterisk/taskprocessor.h

Modified: team/mmichelson/threadpool/include/asterisk/taskprocessor.h
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/threadpool/include/asterisk/taskprocessor.h?view=diff&rev=376382&r1=376381&r2=376382
==============================================================================
--- team/mmichelson/threadpool/include/asterisk/taskprocessor.h (original)
+++ team/mmichelson/threadpool/include/asterisk/taskprocessor.h Thu Nov 15 22:44:12 2012
@@ -22,22 +22,28 @@
  *
  * \author Dwayne M. Hubbard <dhubbard at digium.com>
  *
- * \note A taskprocessor is a named singleton containing a processing thread and
- * a task queue that serializes tasks pushed into it by [a] module(s) that reference the taskprocessor.  
- * A taskprocessor is created the first time its name is requested via the ast_taskprocessor_get()
- * function and destroyed when the taskprocessor reference count reaches zero.
- *
- * Modules that obtain a reference to a taskprocessor can queue tasks into the taskprocessor
- * to be processed by the singleton processing thread when the task is popped off the front 
- * of the queue.  A task is a wrapper around a task-handling function pointer and a data
- * pointer.  It is the responsibility of the task handling function to free memory allocated for
- * the task data pointer.  A task is pushed into a taskprocessor queue using the 
+ * \note A taskprocessor is a named singleton containing a task queue that serializes tasks pushed
+ * into it by [a] module(s) that reference the taskprocessor. A taskprocessor is created the first
+ * time its name is requested via the ast_taskprocessor_get() function and destroyed when the
+ * taskprocessor reference count reaches zero. A taskprocessor also contains an accompanying
+ * listener that is told when changes in the task queue occur.
+ *
+ * A task is a wrapper around a task-handling function pointer and a data
+ * pointer.  A task is pushed into a taskprocessor queue using the 
  * ast_taskprocessor_push(taskprocessor, taskhandler, taskdata) function and freed by the
  * taskprocessor after the task handling function returns.  A module releases its reference to a
  * taskprocessor using the ast_taskprocessor_unreference() function which may result in the
  * destruction of the taskprocessor if the taskprocessor's reference count reaches zero.  Tasks waiting
  * to be processed in the taskprocessor queue when the taskprocessor reference count reaches zero
  * will be purged and released from the taskprocessor queue without being processed.
+ *
+ * The taskprocessor listener has the flexibility of doling out tasks to best fit the module's
+ * needs. For instance, a taskprocessor listener may have a single dispatch thread that handles
+ * all tasks, or it may dispatch tasks to a thread pool.
+ *
+ * There is a default taskprocessor listener that will be used if a taskprocessor is created without
+ * a listener. This default listener runs tasks sequentially in a single thread. The listener will
+ * execute tasks as long as there are tasks to be processed.
  */
 
 #ifndef __AST_TASKPROCESSOR_H__