From ff06346ea24c8a127c19d412a48d09f092b727c3 Mon Sep 17 00:00:00 2001
From: Mark Michelson <mmichelson@digium.com>
Date: Mon, 19 Nov 2012 20:35:39 +0000
Subject: [PATCH] Add doxygen to taskprocessor tests.
git-svn-id: https://origsvn.digium.com/svn/asterisk/team/mmichelson/threadpool@376498 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---
tests/test_taskprocessor.c | 93 +++++++++++++++++++++++++++++++++++++-
1 file changed, 91 insertions(+), 2 deletions(-)
diff --git a/tests/test_taskprocessor.c b/tests/test_taskprocessor.c
index 1d6cbb869d..cbab754a94 100644
--- a/tests/test_taskprocessor.c
+++ b/tests/test_taskprocessor.c
@@ -36,12 +36,25 @@
#include "asterisk/module.h"
#include "asterisk/astobj2.h"
+/*!
+ * \brief userdata associated with baseline taskprocessor test
+ */
struct task_data {
+ /* Condition used to signal to queuing thread that task was executed */
ast_cond_t cond;
+ /* Lock protecting the condition */
ast_mutex_t lock;
+ /*! Boolean indicating that the task was run */
int task_complete;
};
+/*!
+ * \brief Queued task for baseline test.
+ *
+ * The task simply sets a boolean to indicate the
+ * task has been run and then signals a condition
+ * saying it's complete
+ */
static int task(void *data)
{
struct task_data *task_data = data;
@@ -51,6 +64,13 @@ static int task(void *data)
return 0;
}
+/*!
+ * \brief Baseline test for default taskprocessor
+ *
+ * This test ensures that when a task is added to a taskprocessor that
+ * has been allocated with a default listener that the task gets executed
+ * as expected
+ */
AST_TEST_DEFINE(default_taskprocessor)
{
struct ast_taskprocessor *tps;
@@ -66,7 +86,7 @@ AST_TEST_DEFINE(default_taskprocessor)
info->category = "/main/taskprocessor/";
info->summary = "Test of default taskproccesor";
info->description =
- "Ensures that queued tasks are executed.";
+ "Ensures that a queued task gets executed.";
return AST_TEST_NOT_RUN;
case TEST_EXECUTE:
break;
@@ -112,13 +132,26 @@ test_end:
#define NUM_TASKS 20000
+/*!
+ * \brief Relevant data associated with taskprocessor load test
+ */
static struct load_task_data {
+ /*! Condition used to indicate a task has completed executing */
ast_cond_t cond;
+ /*! Lock used to protect the condition */
ast_mutex_t lock;
+ /*! Counter of the number of completed tasks */
int tasks_completed;
+ /*! Storage for task-specific data */
int task_rand[NUM_TASKS];
} load_task_results;
+/*!
+ * \brief a queued task to be used in the taskprocessor load test
+ *
+ * The task increments the number of tasks executed and puts the passed-in
+ * data into the next slot in the array of random data.
+ */
static int load_task(void *data)
{
int *randdata = data;
@@ -128,6 +161,13 @@ static int load_task(void *data)
return 0;
}
+/*!
+ * \brief Load test for taskprocessor with default listener
+ *
+ * This test queues a large number of tasks, each with random data associated.
+ * The test ensures that all of the tasks are run and that the tasks are executed
+ * in the same order that they were queued
+ */
AST_TEST_DEFINE(default_taskprocessor_load)
{
struct ast_taskprocessor *tps;
@@ -144,7 +184,7 @@ AST_TEST_DEFINE(default_taskprocessor_load)
info->category = "/main/taskprocessor/";
info->summary = "Load test of default taskproccesor";
info->description =
- "Ensure that many queued tasks are executed.";
+ "Ensure that a large number of queued tasks are executed in the proper order.";
return AST_TEST_NOT_RUN;
case TEST_EXECUTE:
break;
@@ -201,13 +241,23 @@ test_end:
return res;
}
+/*!
+ * \brief Private data for the test taskprocessor listener
+ */
struct test_listener_pvt {
+ /* Counter of number of tasks pushed to the queue */
int num_pushed;
+ /* Counter of number of times the queue was emptied */
int num_emptied;
+ /* Counter of number of times that a pushed task occurred on an empty queue */
int num_was_empty;
+ /* Boolean indicating whether the shutdown callback was called */
int shutdown;
};
+/*!
+ * \brief test taskprocessor listener's alloc callback
+ */
static void *test_alloc(struct ast_taskprocessor_listener *listener)
{
struct test_listener_pvt *pvt;
@@ -216,6 +266,11 @@ static void *test_alloc(struct ast_taskprocessor_listener *listener)
return pvt;
}
+/*!
+ * \brief test taskprocessor listener's task_pushed callback
+ *
+ * Adjusts private data's stats as indicated by the parameters.
+ */
static void test_task_pushed(struct ast_taskprocessor_listener *listener, int was_empty)
{
struct test_listener_pvt *pvt = listener->private_data;
@@ -225,18 +280,27 @@ static void test_task_pushed(struct ast_taskprocessor_listener *listener, int wa
}
}
+/*!
+ * \brief test taskprocessor listener's emptied callback.
+ */
static void test_emptied(struct ast_taskprocessor_listener *listener)
{
struct test_listener_pvt *pvt = listener->private_data;
++pvt->num_emptied;
}
+/*!
+ * \brief test taskprocessor listener's shutdown callback.
+ */
static void test_shutdown(struct ast_taskprocessor_listener *listener)
{
struct test_listener_pvt *pvt = listener->private_data;
pvt->shutdown = 1;
}
+/*!
+ * \brief test taskprocessor listener's destroy callback.
+ */
static void test_destroy(void *private_data)
{
struct test_listener_pvt *pvt = private_data;
@@ -251,11 +315,27 @@ static const struct ast_taskprocessor_listener_callbacks test_callbacks = {
.destroy = test_destroy,
};
+/*!
+ * \brief Queued task for taskprocessor listener test.
+ *
+ * Does nothing.
+ */
static int listener_test_task(void *ignore)
{
return 0;
}
+/*!
+ * \brief helper to ensure that statistics the listener is keeping are what we expect
+ *
+ * \param test The currently-running test
+ * \param pvt The private data for the taskprocessor listener
+ * \param num_pushed The expected current number of tasks pushed to the processor
+ * \param num_emptied The expected current number of times the taskprocessor has become empty
+ * \param num_was_empty The expected current number of times that tasks were pushed to an empty taskprocessor
+ * \retval -1 Stats were not as expected
+ * \retval 0 Stats were as expected
+ */
static int check_stats(struct ast_test *test, const struct test_listener_pvt *pvt, int num_pushed, int num_emptied, int num_was_empty)
{
if (pvt->num_pushed != num_pushed) {
@@ -279,6 +359,15 @@ static int check_stats(struct ast_test *test, const struct test_listener_pvt *pv
return 0;
}
+/*!
+ * \brief Test for a taskprocessor with custom listener.
+ *
+ * This test pushes tasks to a taskprocessor with a custom listener, executes the taskss,
+ * and destroys the taskprocessor.
+ *
+ * The test ensures that the listener's callbacks are called when expected and that the data
+ * being passed in is accurate.
+ */
AST_TEST_DEFINE(taskprocessor_listener)
{
struct ast_taskprocessor *tps;
--
GitLab