00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2007-2008, Dwayne M. Hubbard 00005 * 00006 * Dwayne M. Hubbard <dhubbard@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 #include "asterisk.h" 00019 #include "asterisk/lock.h" 00020 #include "asterisk/linkedlists.h" 00021 #include "asterisk/utils.h" 00022 #include "asterisk/options.h" 00023 00024 #ifndef __taskprocessor_h__ 00025 #define __taskprocessor_h__ 00026 00027 /*! 00028 * \file taskprocessor.h 00029 * \brief An API for managing task processing threads that can be shared across modules 00030 * 00031 * \author Dwayne M. Hubbard <dhubbard@digium.com> 00032 * 00033 * \note A taskprocessor is a named singleton containing a processing thread and 00034 * a task queue that serializes tasks pushed into it by [a] module(s) that reference the taskprocessor. 00035 * A taskprocessor is created the first time its name is requested via the ast_taskprocessor_get() 00036 * function and destroyed when the taskprocessor reference count reaches zero. 00037 * 00038 * Modules that obtain a reference to a taskprocessor can queue tasks into the taskprocessor 00039 * to be processed by the singleton processing thread when the task is popped off the front 00040 * of the queue. A task is a wrapper around a task-handling function pointer and a data 00041 * pointer. It is the responsibility of the task handling function to free memory allocated for 00042 * the task data pointer. A task is pushed into a taskprocessor queue using the 00043 * ast_taskprocessor_push(taskprocessor, taskhandler, taskdata) function and freed by the 00044 * taskprocessor after the task handling function returns. A module releases its reference to a 00045 * taskprocessor using the ast_taskprocessor_unreference() function which may result in the 00046 * destruction of the taskprocessor if the taskprocessor's reference count reaches zero. Tasks waiting 00047 * to be processed in the taskprocessor queue when the taskprocessor reference count reaches zero 00048 * will be purged and released from the taskprocessor queue without being processed. 00049 */ 00050 struct ast_taskprocessor; 00051 00052 /*! \brief ast_tps_options for specification of taskprocessor options 00053 * 00054 * Specify whether a taskprocessor should be created via ast_taskprocessor_get() if the taskprocessor 00055 * does not already exist. The default behavior is to create a taskprocessor if it does not already exist 00056 * and provide its reference to the calling function. To only return a reference to a taskprocessor if 00057 * and only if it exists, use the TPS_REF_IF_EXISTS option in ast_taskprocessor_get(). */ 00058 enum ast_tps_options { 00059 /*! \brief return a reference to a taskprocessor, create one if it does not exist */ 00060 TPS_REF_DEFAULT = 0, 00061 /*! \brief return a reference to a taskprocessor ONLY if it already exists */ 00062 TPS_REF_IF_EXISTS = (1 << 0), 00063 }; 00064 00065 /*! \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary 00066 * 00067 * The default behavior of instantiating a taskprocessor if one does not already exist can be 00068 * disabled by specifying the TPS_REF_IF_EXISTS ast_tps_options as the second argument to ast_taskprocessor_get(). 00069 * \param name The name of the taskprocessor 00070 * \param create Use 0 by default or specify TPS_REF_IF_EXISTS to return NULL if the taskprocessor does 00071 * not already exist 00072 * return A pointer to a reference counted taskprocessor under normal conditions, or NULL if the 00073 * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist 00074 * \since 1.6.1 00075 */ 00076 struct ast_taskprocessor *ast_taskprocessor_get(char *name, enum ast_tps_options create); 00077 00078 /*! \brief Unreference the specified taskprocessor and its reference count will decrement. 00079 * 00080 * Taskprocessors use astobj2 and will unlink from the taskprocessor singleton container and destroy 00081 * themself when the taskprocessor reference count reaches zero. 00082 * \param tps taskprocessor to unreference 00083 * \return NULL 00084 * \since 1.6.1 00085 */ 00086 void *ast_taskprocessor_unreference(struct ast_taskprocessor *tps); 00087 00088 /*! \brief Push a task into the specified taskprocessor queue and signal the taskprocessor thread 00089 * \param tps The taskprocessor structure 00090 * \param task_exe The task handling function to push into the taskprocessor queue 00091 * \param datap The data to be used by the task handling function 00092 * \return zero on success, -1 on failure 00093 * \since 1.6.1 00094 */ 00095 int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap); 00096 00097 /*! \brief Return the name of the taskprocessor singleton 00098 * \since 1.6.1 00099 */ 00100 const char *ast_taskprocessor_name(struct ast_taskprocessor *tps); 00101 #endif 00102