Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


taskprocessor.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007-2008, Digium, Inc.
5  *
6  * Dwayne M. Hubbard <dhubbard@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*!
20  * \file taskprocessor.h
21  * \brief An API for managing task processing threads that can be shared across modules
22  *
23  * \author Dwayne M. Hubbard <dhubbard@digium.com>
24  *
25  * \note A taskprocessor is a named singleton containing a processing thread and
26  * a task queue that serializes tasks pushed into it by [a] module(s) that reference the taskprocessor.
27  * A taskprocessor is created the first time its name is requested via the ast_taskprocessor_get()
28  * function and destroyed when the taskprocessor reference count reaches zero.
29  *
30  * Modules that obtain a reference to a taskprocessor can queue tasks into the taskprocessor
31  * to be processed by the singleton processing thread when the task is popped off the front
32  * of the queue. A task is a wrapper around a task-handling function pointer and a data
33  * pointer. It is the responsibility of the task handling function to free memory allocated for
34  * the task data pointer. A task is pushed into a taskprocessor queue using the
35  * ast_taskprocessor_push(taskprocessor, taskhandler, taskdata) function and freed by the
36  * taskprocessor after the task handling function returns. A module releases its reference to a
37  * taskprocessor using the ast_taskprocessor_unreference() function which may result in the
38  * destruction of the taskprocessor if the taskprocessor's reference count reaches zero. Tasks waiting
39  * to be processed in the taskprocessor queue when the taskprocessor reference count reaches zero
40  * will be purged and released from the taskprocessor queue without being processed.
41  */
42 
43 #ifndef __AST_TASKPROCESSOR_H__
44 #define __AST_TASKPROCESSOR_H__
45 
46 struct ast_taskprocessor;
47 
48 /*!
49  * \brief ast_tps_options for specification of taskprocessor options
50  *
51  * Specify whether a taskprocessor should be created via ast_taskprocessor_get() if the taskprocessor
52  * does not already exist. The default behavior is to create a taskprocessor if it does not already exist
53  * and provide its reference to the calling function. To only return a reference to a taskprocessor if
54  * and only if it exists, use the TPS_REF_IF_EXISTS option in ast_taskprocessor_get().
55  */
57  /*! \brief return a reference to a taskprocessor, create one if it does not exist */
59  /*! \brief return a reference to a taskprocessor ONLY if it already exists */
60  TPS_REF_IF_EXISTS = (1 << 0),
61 };
62 
63 /*!
64  * \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary
65  *
66  * The default behavior of instantiating a taskprocessor if one does not already exist can be
67  * disabled by specifying the TPS_REF_IF_EXISTS ast_tps_options as the second argument to ast_taskprocessor_get().
68  * \param name The name of the taskprocessor
69  * \param create Use 0 by default or specify TPS_REF_IF_EXISTS to return NULL if the taskprocessor does
70  * not already exist
71  * return A pointer to a reference counted taskprocessor under normal conditions, or NULL if the
72  * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist
73  * \since 1.6.1
74  */
75 struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_options create);
76 
77 /*!
78  * \brief Unreference the specified taskprocessor and its reference count will decrement.
79  *
80  * Taskprocessors use astobj2 and will unlink from the taskprocessor singleton container and destroy
81  * themself when the taskprocessor reference count reaches zero.
82  * \param tps taskprocessor to unreference
83  * \return NULL
84  * \since 1.6.1
85  */
87 
88 /*!
89  * \brief Push a task into the specified taskprocessor queue and signal the taskprocessor thread
90  * \param tps The taskprocessor structure
91  * \param task_exe The task handling function to push into the taskprocessor queue
92  * \param datap The data to be used by the task handling function
93  * \retval 0 success
94  * \retval -1 failure
95  * \since 1.6.1
96  */
97 int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap);
98 
99 /*!
100  * \brief Return the name of the taskprocessor singleton
101  * \since 1.6.1
102  */
103 const char *ast_taskprocessor_name(struct ast_taskprocessor *tps);
104 
105 #endif /* __AST_TASKPROCESSOR_H__ */
int ast_taskprocessor_push(struct ast_taskprocessor *tps, int(*task_exe)(void *datap), void *datap)
Push a task into the specified taskprocessor queue and signal the taskprocessor thread.
struct ast_taskprocessor * ast_taskprocessor_get(const char *name, enum ast_tps_options create)
Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary...
return a reference to a taskprocessor, create one if it does not exist
Definition: taskprocessor.h:58
const char * ast_taskprocessor_name(struct ast_taskprocessor *tps)
Return the name of the taskprocessor singleton.
ast_tps_options
ast_tps_options for specification of taskprocessor options
Definition: taskprocessor.h:56
static const char name[]
return a reference to a taskprocessor ONLY if it already exists
Definition: taskprocessor.h:60
A ast_taskprocessor structure is a singleton by name.
Definition: taskprocessor.c:67
void * ast_taskprocessor_unreference(struct ast_taskprocessor *tps)
Unreference the specified taskprocessor and its reference count will decrement.