[asterisk-commits] dhubbard: branch group/taskprocessors r111602 - /team/group/taskprocessors/in...

[SVN commits to the Asterisk project]

Author: dhubbard
Date: Fri Mar 28 00:40:14 2008
New Revision: 111602

URL: http://svn.digium.com/view/asterisk?view=rev&rev=111602
Log:
I started to doxygenize, but then I started to fall asleep...

Modified:
    team/group/taskprocessors/include/asterisk/taskprocessor.h

Modified: team/group/taskprocessors/include/asterisk/taskprocessor.h
URL: http://svn.digium.com/view/asterisk/team/group/taskprocessors/include/asterisk/taskprocessor.h?view=diff&rev=111602&r1=111601&r2=111602
==============================================================================
--- team/group/taskprocessors/include/asterisk/taskprocessor.h (original)
+++ team/group/taskprocessors/include/asterisk/taskprocessor.h Fri Mar 28 00:40:14 2008
@@ -24,10 +24,41 @@
 #ifndef __taskprocessor_h__
 #define __taskprocessor_h__
 
+/*!
+ * \file taskprocessor.h
+ * \brief An API for managing task processing threads that can be shared across modules
+ *
+ * \author Dwayne M. Hubbard <dhubbard at digium.com>
+ *
+ * \note A taskprocessor is a singleton processing thread that can be referenced
+ * with a friendly name and shared across modules.  Modules that reference a taskprocessor
+ * can push a_task objects into the default taskprocessor FIFO container.  The default
+ * taskprocessing function can be overridden at the time of taskprocessor creation using
+ * the ast_taskprocessor_reference() function.  Taskprocessors utilize astobj2 and will
+ * be created upon the first reference to a taskprocessor name, as well as destroy
+ * themselves when the taskprocessor reference count reaches zero.
+ *
+ * The a_task structure has a callback function, called execute(), that is called by the
+ * taskprocessor when the task is popped off the queue.  The execute() callback handler
+ * is responsible for processing the task data and freeing task data resources, if necessary
+ * and then setting the task datap pointer to NULL before returning.  The taskprocessor will 
+ * free the task structure after the task callback returns control to the taskprocessor function.
+ *
+ * A taskproducer structure is a convenience object that can be embedded inside another object
+ * and will provide the basic services for queuing tasks into a referenced taskprocessor.
+ * The taskproducer objects utilize astobj2 and will destroy themselves when their reference
+ * count reaches zero.
+ */
+
+/*! \brief Definition of a_task structure */
 struct a_task {
+	/*! \brief The execute() task callback function pointer */
 	int (*execute)(struct a_task *t);
+	/*! \brief The data pointer for the task execute() function */
 	void *_datap;
+	/*! \brief The function that allocated a task object (To become debug only) */
 	char _source[256];
+	/*! \brief AST_LIST_ENTRY overhead */
 	AST_LIST_ENTRY(a_task) list;
 };