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

[SVN commits to the Asterisk project]

Author: dhubbard
Date: Sat Mar 29 00:47:17 2008
New Revision: 111947

URL: http://svn.digium.com/view/asterisk?view=rev&rev=111947
Log:
yay doxygen

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=111947&r1=111946&r2=111947
==============================================================================
--- team/group/taskprocessors/include/asterisk/taskprocessor.h (original)
+++ team/group/taskprocessors/include/asterisk/taskprocessor.h Sat Mar 29 00:47:17 2008
@@ -50,7 +50,10 @@
  * count reaches zero.
  */
 
-/*! \brief Definition of a_task structure */
+/*! \brief a_task structure is queued to a taskprocessor and released
+ * by the taskprocessing thread.  The callback function that is assigned
+ * to the execute() function pointer is responsible for releasing
+ * _datap resources if necessary. */
 struct a_task {
 	/*! \brief The execute() task callback function pointer */
 	int (*execute)(struct a_task *t);
@@ -62,42 +65,71 @@
 	AST_LIST_ENTRY(a_task) list;
 };
 
+/*! \brief taskprocessor_singleton_stats are technically optional, but
+ * used by default to keep track of statistics for an individual taskprocessor */
 struct taskprocessor_singleton_stats {
+	/*! \brief This is the maximum number of tasks queued at any one time */
 	unsigned long _max_qsize;
+	/*! \brief This is the current number of tasks processed */
 	unsigned long _tasks_processed_count;
 };
 
+/*! \brief A taskprocessor_singleton_info structure is used to manage 
+ *  a unique taskprocessor thread */
 struct taskprocessor_singleton_info {
+	/*! \brief Friendly name of the taskprocessor */
 	char _name[80];
+	/*! \brief Address of the taskprocessor singleton structure */
 	unsigned long _id;
+	/*! \brief Thread poll condition */
 	ast_cond_t _poll_cond;
+	/*! \brief Taskprocessor thread */
 	pthread_t _poll_thread;
+	/*! \brief Taskprocessor lock */
 	ast_mutex_t _taskprocessor_lock;
+	/*! \brief Taskprocesor thread run flag */
 	unsigned char _poll_thread_run;
+	/*! \brief Taskprocessor statistics */
 	struct taskprocessor_singleton_stats *_stats;
+	/*! \brief private data for a taskprocessor */
 	void *_private;
+	/*! \brief Taskprocessor current queue size */
 	long _queue_size;
+	/*! \brief Taskprocessor queue */
 	AST_LIST_HEAD(_queue, a_task) _queue;
+	/*! \brief Taskprocessor singleton list entry */
 	AST_LIST_ENTRY(taskprocessor_singleton_info) list;
 };
 
+/*! \brief A taskproducer structure is for convenience and wraps a taskprocessor
+ * and a queue_task operation. */
 struct ast_taskproducer {
+	/*! \brief The taskprocessor that this taskproducer queues tasks to */ 
 	struct taskprocessor_singleton_info *_taskprocessor;
+	/*! \brief Counter of the number of tasks queued by this taskproducer */
 	unsigned long _tasks_produced;
-
+	/*! \brief The default queue_task() function */
 	int (*queue_task)(struct ast_taskproducer *producer, struct a_task *task);
 }; 
 
+/*! \brief Initialize the taskprocessor subsystem */
 int ast_tps_init(void);
 
+/*! \brief Allocate a_task object */
 struct a_task *ast_task_alloc(int (*task_exe)(struct a_task *task), void *datap, char *src);
+/*! \brief Release a_task resources */
 int ast_task_free(struct a_task *task);
 
+/*! \brief Obtain a taskprocessor reference */
 struct taskprocessor_singleton_info *ast_taskprocessor_reference(const char *name, void *(*func)(void*));
+/*! \brief Push a task on the taskprocessor */
 int ast_taskprocessor_push(struct taskprocessor_singleton_info *tp, struct a_task *t);
+/*! \brief Pop the front task off the taskprocessor queue and return it to the calling function */
 struct a_task *ast_taskprocessor_pop(struct taskprocessor_singleton_info *tp);
+/*! \brief Return the number of a_task elements currently in the taskprocessor queue */
 int ast_taskprocessor_depth(struct taskprocessor_singleton_info *tp);
 
+/*! \brief Allocate and initialize a taskproducer convenience object */
 struct ast_taskproducer *ast_taskproducer_alloc(const char *name);
 #endif