Fri Aug 17 00:17:20 2018

Asterisk developer's documentation


taskprocessor.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2007-2008, Digium, Inc.
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 
00019 /*!
00020  * \file taskprocessor.h
00021  * \brief An API for managing task processing threads that can be shared across modules
00022  *
00023  * \author Dwayne M. Hubbard <dhubbard@digium.com>
00024  *
00025  * \note A taskprocessor is a named singleton containing a processing thread and
00026  * a task queue that serializes tasks pushed into it by [a] module(s) that reference the taskprocessor.  
00027  * A taskprocessor is created the first time its name is requested via the ast_taskprocessor_get()
00028  * function and destroyed when the taskprocessor reference count reaches zero.
00029  *
00030  * Modules that obtain a reference to a taskprocessor can queue tasks into the taskprocessor
00031  * to be processed by the singleton processing thread when the task is popped off the front 
00032  * of the queue.  A task is a wrapper around a task-handling function pointer and a data
00033  * pointer.  It is the responsibility of the task handling function to free memory allocated for
00034  * the task data pointer.  A task is pushed into a taskprocessor queue using the 
00035  * ast_taskprocessor_push(taskprocessor, taskhandler, taskdata) function and freed by the
00036  * taskprocessor after the task handling function returns.  A module releases its reference to a
00037  * taskprocessor using the ast_taskprocessor_unreference() function which may result in the
00038  * destruction of the taskprocessor if the taskprocessor's reference count reaches zero.  Tasks waiting
00039  * to be processed in the taskprocessor queue when the taskprocessor reference count reaches zero
00040  * will be purged and released from the taskprocessor queue without being processed.
00041  */
00042 
00043 #ifndef __AST_TASKPROCESSOR_H__
00044 #define __AST_TASKPROCESSOR_H__
00045 
00046 struct ast_taskprocessor;
00047 
00048 /*!
00049  * \brief ast_tps_options for specification of taskprocessor options
00050  *
00051  * Specify whether a taskprocessor should be created via ast_taskprocessor_get() if the taskprocessor 
00052  * does not already exist.  The default behavior is to create a taskprocessor if it does not already exist 
00053  * and provide its reference to the calling function.  To only return a reference to a taskprocessor if 
00054  * and only if it exists, use the TPS_REF_IF_EXISTS option in ast_taskprocessor_get().
00055  */
00056 enum ast_tps_options {
00057    /*! \brief return a reference to a taskprocessor, create one if it does not exist */
00058    TPS_REF_DEFAULT = 0,
00059    /*! \brief return a reference to a taskprocessor ONLY if it already exists */
00060    TPS_REF_IF_EXISTS = (1 << 0),
00061 };
00062 
00063 /*!
00064  * \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary
00065  *
00066  * The default behavior of instantiating a taskprocessor if one does not already exist can be
00067  * disabled by specifying the TPS_REF_IF_EXISTS ast_tps_options as the second argument to ast_taskprocessor_get().
00068  * \param name The name of the taskprocessor
00069  * \param create Use 0 by default or specify TPS_REF_IF_EXISTS to return NULL if the taskprocessor does 
00070  * not already exist
00071  * return A pointer to a reference counted taskprocessor under normal conditions, or NULL if the
00072  * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist
00073  * \since 1.6.1
00074  */
00075 struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_options create);
00076 
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 /*!
00089  * \brief Push a task into the specified taskprocessor queue and signal the taskprocessor thread
00090  * \param tps The taskprocessor structure
00091  * \param task_exe The task handling function to push into the taskprocessor queue
00092  * \param datap The data to be used by the task handling function
00093  * \retval 0 success
00094  * \retval -1 failure
00095  * \since 1.6.1
00096  */
00097 int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap);
00098 
00099 /*!
00100  * \brief Return the name of the taskprocessor singleton
00101  * \since 1.6.1
00102  */
00103 const char *ast_taskprocessor_name(struct ast_taskprocessor *tps);
00104 
00105 #endif /* __AST_TASKPROCESSOR_H__ */

Generated on 17 Aug 2018 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1