diff options
author | dhubbard <dhubbard@f38db490-d61c-443f-a65b-d21fe96a405b> | 2008-05-03 03:40:32 +0000 |
---|---|---|
committer | dhubbard <dhubbard@f38db490-d61c-443f-a65b-d21fe96a405b> | 2008-05-03 03:40:32 +0000 |
commit | c5a9cc7867ea784d97e5d50a55506531ce55a0a0 (patch) | |
tree | 9e22e4d92fb615007c0c43c3c517d6593731b7b9 /include | |
parent | afcd3c8a404177ee3ecde9d81edf9b05532e7199 (diff) |
A taskprocessor is an object that has a name, a task queue, and an event processing thread. Modules reference a taskprocessor, push tasks into the taskprocessor as needed, and unreference the taskprocessor when the taskprocessor is no longer needed.
A task wraps a callback function pointer and a data pointer and is managed internal to the taskprocessor subsystem. The callback function is responsible for releasing task data.
Taskprocessor API
* ast_taskprocessor_get(..) - returns a reference to a taskprocessor
* ast_taskprocessor_unreference(..) - releases reference to a taskprocessor
* ast_taskprocessor_push(..) - push a task into a taskprocessor queue
Check doxygen for more details
git-svn-id: http://svn.digium.com/svn/asterisk/trunk@115268 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'include')
-rw-r--r-- | include/asterisk/_private.h | 1 | ||||
-rw-r--r-- | include/asterisk/taskprocessor.h | 94 |
2 files changed, 95 insertions, 0 deletions
diff --git a/include/asterisk/_private.h b/include/asterisk/_private.h index 52b7e227f..215a56178 100644 --- a/include/asterisk/_private.h +++ b/include/asterisk/_private.h @@ -36,6 +36,7 @@ int ast_features_init(void); /*!< Provided by features.c */ void ast_autoservice_init(void); /*!< Provided by autoservice.c */ int ast_http_init(void); /*!< Provided by http.c */ int ast_http_reload(void); /*!< Provided by http.c */ +int ast_tps_init(void); /*!< Provided by taskprocessor.c */ /*! * \brief Reload asterisk modules. diff --git a/include/asterisk/taskprocessor.h b/include/asterisk/taskprocessor.h new file mode 100644 index 000000000..72d810c26 --- /dev/null +++ b/include/asterisk/taskprocessor.h @@ -0,0 +1,94 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2007-2008, Dwayne M. Hubbard + * + * Dwayne M. Hubbard <dhubbard@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ +#include "asterisk.h" +#include "asterisk/lock.h" +#include "asterisk/linkedlists.h" +#include "asterisk/utils.h" +#include "asterisk/options.h" + +#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@digium.com> + * + * \note A taskprocessor is a named singleton containing a processing thread and + * a task queue that serializes tasks pushed into it by [a] module(s) that reference the taskprocessor. + * A taskprocessor is created the first time its name is requested via the ast_taskprocessor_get() + * function and destroyed when the taskprocessor reference count reaches zero. + * + * Modules that obtain a reference to a taskprocessor can queue tasks into the taskprocessor + * to be processed by the singleton processing thread when the task is popped off the front + * of the queue. A task is a wrapper around a task-handling function pointer and a data + * pointer. It is the responsibility of the task handling function to free memory allocated for + * the task data pointer. A task is pushed into a taskprocessor queue using the + * ast_taskprocessor_push(taskprocessor, taskhandler, taskdata) function and freed by the + * taskprocessor after the task handling function returns. A module releases its reference to a + * taskprocessor using the ast_taskprocessor_unreference() function which may result in the + * destruction of the taskprocessor if the taskprocessor's reference count reaches zero. Tasks waiting + * to be processed in the taskprocessor queue when the taskprocessor reference count reaches zero + * will be purged and released from the taskprocessor queue without being processed. + */ +struct ast_taskprocessor; + +/*! \brief ast_tps_options for specification of taskprocessor options + * + * Specify whether a taskprocessor should be created via ast_taskprocessor_get() if the taskprocessor + * does not already exist. The default behavior is to create a taskprocessor if it does not already exist + * and provide its reference to the calling function. To only return a reference to a taskprocessor if + * and only if it exists, use the TPS_REF_IF_EXISTS option in ast_taskprocessor_get(). */ +enum ast_tps_options { + /*! \brief return a reference to a taskprocessor, create one if it does not exist */ + TPS_REF_DEFAULT = 0, + /*! \brief return a reference to a taskprocessor ONLY if it already exists */ + TPS_REF_IF_EXISTS = (1 << 0), +}; + +/*! \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary + * + * The default behavior of instantiating a taskprocessor if one does not already exist can be + * disabled by specifying the TPS_REF_IF_EXISTS ast_tps_options as the second argument to ast_taskprocessor_get(). + * \param name The name of the taskprocessor + * \param create Use 0 by default or specify TPS_REF_IF_EXISTS to return NULL if the taskprocessor does + * not already exist + * return A pointer to a reference counted taskprocessor under normal conditions, or NULL if the + * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist */ +struct ast_taskprocessor *ast_taskprocessor_get(char *name, enum ast_tps_options create); + +/*! \brief Unreference the specified taskprocessor and its reference count will decrement. + * + * Taskprocessors use astobj2 and will unlink from the taskprocessor singleton container and destroy + * themself when the taskprocessor reference count reaches zero. + * \param tps taskprocessor to unreference + * \return NULL */ +void *ast_taskprocessor_unreference(struct ast_taskprocessor *tps); + +/*! \brief Push a task into the specified taskprocessor queue and signal the taskprocessor thread + * \param tps The taskprocessor structure + * \param task_exe The task handling function to push into the taskprocessor queue + * \param datap The data to be used by the task handling function + * \return zero on success, -1 on failure */ +int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap); + +/*! \brief Return the name of the taskprocessor singleton */ +const char *ast_taskprocessor_name(struct ast_taskprocessor *tps); +#endif + |