Add doxygen and constify some things.
[asterisk/asterisk.git] / include / asterisk / taskprocessor.h
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  */
56 enum ast_tps_options {
57         /*! \brief return a reference to a taskprocessor, create one if it does not exist */
58         TPS_REF_DEFAULT = 0,
59         /*! \brief return a reference to a taskprocessor ONLY if it already exists */
60         TPS_REF_IF_EXISTS = (1 << 0),
61 };
62
63 struct ast_taskprocessor_listener;
64
65 struct ast_taskprocessor_listener_callbacks {
66         /*! 
67          * \brief Allocate the listener's private data
68          *
69          * It is not necessary to assign the private data to the listener.
70          *
71          * \param listener The listener to which the private data belongs
72          * \retval NULL Error while attempting to initialize private data
73          * \retval non-NULL Allocated private data
74          */
75         void *(*alloc)(struct ast_taskprocessor_listener *listener);
76         /*! 
77          * \brief Indicates a task was pushed to the processor
78          *
79          * \param listener The listener
80          * \param was_empty If non-zero, the taskprocessor was empty prior to the task being pushed
81          */
82         void (*task_pushed)(struct ast_taskprocessor_listener *listener, int was_empty);
83         /*! 
84          * \brief Indicates the task processor has become empty
85          *
86          * \param listener The listener
87          */
88         void (*emptied)(struct ast_taskprocessor_listener *listener);
89         /*! 
90          * \brief Destroy the listener's private data
91          *
92          * It is required that you free the private data in this callback
93          * in addition to the private data's individual fields.
94          *
95          * \param private_data The listener's private data
96          */
97         void (*destroy)(void *private_data);
98 };
99
100 /*!
101  * \brief A listener for taskprocessors
102  *
103  * When a taskprocessor's state changes, the listener
104  * is notified of the change. This allows for tasks
105  * to be addressed in whatever way is appropriate for
106  * the module using the taskprocessor.
107  */
108 struct ast_taskprocessor_listener {
109         /*! The callbacks the taskprocessor calls into to notify of state changes */
110         const struct ast_taskprocessor_listener_callbacks *callbacks;
111         /*! The taskprocessor that the listener is listening to */
112         struct ast_taskprocessor *tps;
113         /*! Data private to the listener */
114         void *private_data;
115 };
116
117 /*!
118  * Allocate a taskprocessor listener
119  *
120  * This will result in the listener being allocated with the specified
121  * callbacks. The listener's alloc() callback will be called to allocate
122  * private data for the listener. The private data will be assigned to the
123  * listener when the listener's alloc() function returns.
124  *
125  * \param callbacks The callbacks to assign to the listener
126  * \retval NULL Failure
127  * \retval non-NULL The newly allocated taskprocessor listener
128  */
129 struct ast_taskprocessor_listener *ast_taskprocessor_listener_alloc(const struct ast_taskprocessor_listener_callbacks *callbacks);
130
131 /*!
132  * \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary
133  *
134  * The default behavior of instantiating a taskprocessor if one does not already exist can be
135  * disabled by specifying the TPS_REF_IF_EXISTS ast_tps_options as the second argument to ast_taskprocessor_get().
136  * \param name The name of the taskprocessor
137  * \param create Use 0 by default or specify TPS_REF_IF_EXISTS to return NULL if the taskprocessor does 
138  * not already exist
139  * return A pointer to a reference counted taskprocessor under normal conditions, or NULL if the
140  * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist
141  * \since 1.6.1
142  */
143 struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_options create);
144
145 /*!
146  * \brief Create a taskprocessor with a custom listener
147  *
148  * \param name The name of the taskprocessor to create
149  * \param listener The listener for operations on this taskprocessor
150  * \retval NULL Failure
151  * \reval non-NULL success
152  */
153 struct ast_taskprocessor *ast_taskprocessor_create_with_listener(const char *name, struct ast_taskprocessor_listener *listener);
154
155 /*!
156  * \brief Unreference the specified taskprocessor and its reference count will decrement.
157  *
158  * Taskprocessors use astobj2 and will unlink from the taskprocessor singleton container and destroy
159  * themself when the taskprocessor reference count reaches zero.
160  * \param tps taskprocessor to unreference
161  * \return NULL
162  * \since 1.6.1
163  */
164 void *ast_taskprocessor_unreference(struct ast_taskprocessor *tps);
165
166 /*!
167  * \brief Push a task into the specified taskprocessor queue and signal the taskprocessor thread
168  * \param tps The taskprocessor structure
169  * \param task_exe The task handling function to push into the taskprocessor queue
170  * \param datap The data to be used by the task handling function
171  * \retval 0 success
172  * \retval -1 failure
173  * \since 1.6.1
174  */
175 int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap);
176
177 /*!
178  * \brief Pop a task off the taskprocessor and execute it.
179  * \param tps The taskprocessor from which to execute.
180  * \retval 0 There is no further work to be done.
181  * \retval 1 Tasks still remain in the taskprocessor queue.
182  */
183 int ast_taskprocessor_execute(struct ast_taskprocessor *tps);
184
185 /*!
186  * \brief Return the name of the taskprocessor singleton
187  * \since 1.6.1
188  */
189 const char *ast_taskprocessor_name(struct ast_taskprocessor *tps);
190
191 #endif /* __AST_TASKPROCESSOR_H__ */