From a4a48d927468dc52ed7f58d51bbf69cfa15580c8 Mon Sep 17 00:00:00 2001
From: Mark Michelson <mmichelson@digium.com>
Date: Fri, 9 Nov 2012 22:49:25 +0000
Subject: [PATCH] Add doxygen and constify some things.
git-svn-id: https://origsvn.digium.com/svn/asterisk/team/mmichelson/threadpool@376123 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---
include/asterisk/taskprocessor.h | 60 ++++++++++++++++++++++++++++----
main/taskprocessor.c | 7 ++--
2 files changed, 56 insertions(+), 11 deletions(-)
diff --git a/include/asterisk/taskprocessor.h b/include/asterisk/taskprocessor.h
index a92e1f31c2..5ea14907a1 100644
--- a/include/asterisk/taskprocessor.h
+++ b/include/asterisk/taskprocessor.h
@@ -63,24 +63,70 @@ enum ast_tps_options {
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);
- /*! 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);
- /*! 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);
- /*! 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);
};
+/*!
+ * \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_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;
+ /*! Data private to the listener */
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
diff --git a/main/taskprocessor.c b/main/taskprocessor.c
index 4ca01f9ca2..00c9485843 100644
--- a/main/taskprocessor.c
+++ b/main/taskprocessor.c
@@ -210,7 +210,7 @@ static void default_emptied(struct ast_taskprocessor_listener *listener)
/* 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,
@@ -457,8 +457,7 @@ const char *ast_taskprocessor_name(struct ast_taskprocessor *tps)
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);
@@ -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 */
- listener = ast_taskprocessor_listener_alloc(p, &default_listener_callbacks);
+ listener = ast_taskprocessor_listener_alloc(&default_listener_callbacks);
if (!listener) {
return NULL;
}
--
GitLab