Add doxygen and constify some things.
authorMark Michelson <mmichelson@digium.com>
Fri, 9 Nov 2012 22:49:25 +0000 (22:49 +0000)
committerMark Michelson <mmichelson@digium.com>
Fri, 9 Nov 2012 22:49:25 +0000 (22:49 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/team/mmichelson/threadpool@376123 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/taskprocessor.h
main/taskprocessor.c

index a92e1f3..5ea1490 100644 (file)
@@ -63,24 +63,70 @@ enum ast_tps_options {
 struct ast_taskprocessor_listener;
 
 struct ast_taskprocessor_listener_callbacks {
 struct ast_taskprocessor_listener;
 
 struct ast_taskprocessor_listener_callbacks {
-       /*! Allocate the listener's private data */
+       /*! 
+        * \brief Allocate the listener's private data
+        *
+        * It is not necessary to assign the private data to the listener.
+        *
+        * \param listener The listener to which the private data belongs
+        * \retval NULL Error while attempting to initialize private data
+        * \retval non-NULL Allocated private data
+        */
        void *(*alloc)(struct ast_taskprocessor_listener *listener);
        void *(*alloc)(struct ast_taskprocessor_listener *listener);
-       /*! Indicates a task was pushed to the processor */
+       /*! 
+        * \brief Indicates a task was pushed to the processor
+        *
+        * \param listener The listener
+        * \param was_empty If non-zero, the taskprocessor was empty prior to the task being pushed
+        */
        void (*task_pushed)(struct ast_taskprocessor_listener *listener, int was_empty);
        void (*task_pushed)(struct ast_taskprocessor_listener *listener, int was_empty);
-       /*! Indicates the task processor has become empty */
+       /*! 
+        * \brief Indicates the task processor has become empty
+        *
+        * \param listener The listener
+        */
        void (*emptied)(struct ast_taskprocessor_listener *listener);
        void (*emptied)(struct ast_taskprocessor_listener *listener);
-       /*! Destroy the listener's private data */
+       /*! 
+        * \brief Destroy the listener's private data
+        *
+        * It is required that you free the private data in this callback
+        * in addition to the private data's individual fields.
+        *
+        * \param private_data The listener's private data
+        */
        void (*destroy)(void *private_data);
 };
 
        void (*destroy)(void *private_data);
 };
 
+/*!
+ * \brief A listener for taskprocessors
+ *
+ * When a taskprocessor's state changes, the listener
+ * is notified of the change. This allows for tasks
+ * to be addressed in whatever way is appropriate for
+ * the module using the taskprocessor.
+ */
 struct ast_taskprocessor_listener {
 struct ast_taskprocessor_listener {
-       struct ast_taskprocessor_listener_callbacks *callbacks;
+       /*! The callbacks the taskprocessor calls into to notify of state changes */
+       const struct ast_taskprocessor_listener_callbacks *callbacks;
+       /*! The taskprocessor that the listener is listening to */
        struct ast_taskprocessor *tps;
        struct ast_taskprocessor *tps;
+       /*! Data private to the listener */
        void *private_data;
 };
 
        void *private_data;
 };
 
-struct ast_taskprocessor_listener *ast_taskprocessor_listener_alloc(struct ast_taskprocessor *tps,
-               struct ast_taskprocessor_listener_callbacks *callbacks);
+/*!
+ * Allocate a taskprocessor listener
+ *
+ * This will result in the listener being allocated with the specified
+ * callbacks. The listener's alloc() callback will be called to allocate
+ * private data for the listener. The private data will be assigned to the
+ * listener when the listener's alloc() function returns.
+ *
+ * \param callbacks The callbacks to assign to the listener
+ * \retval NULL Failure
+ * \retval non-NULL The newly allocated taskprocessor listener
+ */
+struct ast_taskprocessor_listener *ast_taskprocessor_listener_alloc(const struct ast_taskprocessor_listener_callbacks *callbacks);
 
 /*!
  * \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary
 
 /*!
  * \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary
index 4ca01f9..00c9485 100644 (file)
@@ -210,7 +210,7 @@ static void default_emptied(struct ast_taskprocessor_listener *listener)
        /* No-op */
 }
 
        /* No-op */
 }
 
-static struct ast_taskprocessor_listener_callbacks default_listener_callbacks = {
+static const struct ast_taskprocessor_listener_callbacks default_listener_callbacks = {
        .alloc = default_listener_alloc,
        .task_pushed = default_task_pushed,
        .emptied = default_emptied,
        .alloc = default_listener_alloc,
        .task_pushed = default_task_pushed,
        .emptied = default_emptied,
@@ -457,8 +457,7 @@ const char *ast_taskprocessor_name(struct ast_taskprocessor *tps)
        return tps->name;
 }
 
        return tps->name;
 }
 
-struct ast_taskprocessor_listener *ast_taskprocessor_listener_alloc(struct ast_taskprocessor *tps,
-               struct ast_taskprocessor_listener_callbacks *callbacks)
+struct ast_taskprocessor_listener *ast_taskprocessor_listener_alloc(const struct ast_taskprocessor_listener_callbacks *callbacks)
 {
        RAII_VAR(struct ast_taskprocessor_listener *, listener,
                        ao2_alloc(sizeof(*listener), listener_destroy), ao2_cleanup);
 {
        RAII_VAR(struct ast_taskprocessor_listener *, listener,
                        ao2_alloc(sizeof(*listener), listener_destroy), ao2_cleanup);
@@ -498,7 +497,7 @@ struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_o
                return NULL;
        }
        /* Create a new taskprocessor. Start by creating a default listener */
                return NULL;
        }
        /* Create a new taskprocessor. Start by creating a default listener */
-       listener = ast_taskprocessor_listener_alloc(p, &default_listener_callbacks);
+       listener = ast_taskprocessor_listener_alloc(&default_listener_callbacks);
        if (!listener) {
                return NULL;
        }
        if (!listener) {
                return NULL;
        }