Asterisk - The Open Source Telephony Project  GIT-master-a24979a
taskprocessor.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007-2013, 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
21  *
22  * \brief An API for managing task processing threads that can be shared across modules
23  *
24  * \author Dwayne M. Hubbard <dhubbard@digium.com>
25  *
26  * \note A taskprocessor is a named object containing a task queue that
27  * serializes tasks pushed into it by [a] module(s) that reference the taskprocessor.
28  * A taskprocessor is created the first time its name is requested via the
29  * ast_taskprocessor_get() function or the ast_taskprocessor_create_with_listener()
30  * function and destroyed when the taskprocessor reference count reaches zero. A
31  * taskprocessor also contains an accompanying listener that is notified when changes
32  * in the task queue occur.
33  *
34  * A task is a wrapper around a task-handling function pointer and a data
35  * pointer. A task is pushed into a taskprocessor queue using the
36  * ast_taskprocessor_push(taskprocessor, taskhandler, taskdata) function and freed by the
37  * taskprocessor after the task handling function returns. A module releases its
38  * reference to a taskprocessor using the ast_taskprocessor_unreference() function which
39  * may result in the destruction of the taskprocessor if the taskprocessor's reference
40  * count reaches zero. When the taskprocessor's reference count reaches zero, its
41  * listener's shutdown() callback will be called. Any further attempts to execute tasks
42  * will be denied.
43  *
44  * The taskprocessor listener has the flexibility of doling out tasks to best fit the
45  * module's needs. For instance, a taskprocessor listener may have a single dispatch
46  * thread that handles all tasks, or it may dispatch tasks to a thread pool.
47  *
48  * There is a default taskprocessor listener that will be used if a taskprocessor is
49  * created without any explicit listener. This default listener runs tasks sequentially
50  * in a single thread. The listener will execute tasks as long as there are tasks to be
51  * processed. When the taskprocessor is shut down, the default listener will stop
52  * processing tasks and join its execution thread.
53  */
54 
55 #ifndef __AST_TASKPROCESSOR_H__
56 #define __AST_TASKPROCESSOR_H__
57 
58 struct ast_taskprocessor;
59 
60 /*! \brief Suggested maximum taskprocessor name length (less null terminator). */
61 #define AST_TASKPROCESSOR_MAX_NAME 70
62 
63 /*! Default taskprocessor high water level alert trigger */
64 #define AST_TASKPROCESSOR_HIGH_WATER_LEVEL 500
65 
66 /*!
67  * \brief ast_tps_options for specification of taskprocessor options
68  *
69  * Specify whether a taskprocessor should be created via ast_taskprocessor_get() if the taskprocessor
70  * does not already exist. The default behavior is to create a taskprocessor if it does not already exist
71  * and provide its reference to the calling function. To only return a reference to a taskprocessor if
72  * and only if it exists, use the TPS_REF_IF_EXISTS option in ast_taskprocessor_get().
73  */
75  /*! \brief return a reference to a taskprocessor, create one if it does not exist */
77  /*! \brief return a reference to a taskprocessor ONLY if it already exists */
78  TPS_REF_IF_EXISTS = (1 << 0),
79 };
80 
82 
84  /*!
85  * \brief The taskprocessor has started completely
86  *
87  * This indicates that the taskprocessor is fully set up and the listener
88  * can now start interacting with it.
89  *
90  * \param listener The listener to start
91  */
93  /*!
94  * \brief Indicates a task was pushed to the processor
95  *
96  * \param listener The listener
97  * \param was_empty If non-zero, the taskprocessor was empty prior to the task being pushed
98  */
99  void (*task_pushed)(struct ast_taskprocessor_listener *listener, int was_empty);
100  /*!
101  * \brief Indicates the task processor has become empty
102  *
103  * \param listener The listener
104  */
106  /*!
107  * \brief Indicates the taskprocessor wishes to die.
108  *
109  * All operations on the task processor must to be stopped in
110  * this callback. This is an opportune time to free the listener's
111  * user data if it is not going to be used anywhere else.
112  *
113  * After this callback returns, it is NOT safe to operate on the
114  * listener's reference to the taskprocessor.
115  *
116  * \param listener The listener
117  */
120 };
121 
122 /*!
123  * \brief Get a reference to the listener's taskprocessor
124  *
125  * This will return the taskprocessor with its reference count increased. Release
126  * the reference to this object by using ast_taskprocessor_unreference()
127  *
128  * \param listener The listener that has the taskprocessor
129  * \return The taskprocessor
130  */
132 
133 /*!
134  * \brief Get the user data from the listener
135  * \param listener The taskprocessor listener
136  * \return The listener's user data
137  */
139 
140 /*!
141  * \brief Allocate a taskprocessor listener
142  *
143  * \since 12.0.0
144  *
145  * This will result in the listener being allocated with the specified
146  * callbacks.
147  *
148  * \param callbacks The callbacks to assign to the listener
149  * \param user_data The user data for the listener
150  * \retval NULL Failure
151  * \retval non-NULL The newly allocated taskprocessor listener
152  */
154 
155 /*!
156  * \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary
157  *
158  * The default behavior of instantiating a taskprocessor if one does not already exist can be
159  * disabled by specifying the TPS_REF_IF_EXISTS ast_tps_options as the second argument to ast_taskprocessor_get().
160  * \param name The name of the taskprocessor
161  * \param create Use 0 by default or specify TPS_REF_IF_EXISTS to return NULL if the taskprocessor does
162  * not already exist
163  * return A pointer to a reference counted taskprocessor under normal conditions, or NULL if the
164  * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist
165  * \since 1.6.1
166  */
167 struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_options create);
168 
169 /*!
170  * \brief Create a taskprocessor with a custom listener
171  *
172  * \since 12.0.0
173  *
174  * Note that when a taskprocessor is created in this way, it does not create
175  * any threads to execute the tasks. This job is left up to the listener.
176  * The listener's start() callback will be called during this function.
177  *
178  * \param name The name of the taskprocessor to create
179  * \param listener The listener for operations on this taskprocessor
180  * \retval NULL Failure
181  * \retval non-NULL success
182  */
184 
185 /*!
186  * \brief Sets the local data associated with a taskprocessor.
187  *
188  * \since 12.0.0
189  *
190  * See ast_taskprocessor_push_local().
191  *
192  * \param tps Task processor.
193  * \param local_data Local data to associate with \a tps.
194  */
196 
197 /*!
198  * \brief Unreference the specified taskprocessor and its reference count will decrement.
199  *
200  * Taskprocessors use astobj2 and will unlink from the taskprocessor singleton container and destroy
201  * themself when the taskprocessor reference count reaches zero.
202  * \param tps taskprocessor to unreference
203  * \return NULL
204  * \since 1.6.1
205  */
207 
208 /*!
209  * \brief Push a task into the specified taskprocessor queue and signal the taskprocessor thread
210  * \param tps The taskprocessor structure
211  * \param task_exe The task handling function to push into the taskprocessor queue
212  * \param datap The data to be used by the task handling function
213  * \retval 0 success
214  * \retval -1 failure
215  * \since 1.6.1
216  */
217 int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap)
219 
220 /*! \brief Local data parameter */
222  /*! Local data, associated with the taskprocessor. */
223  void *local_data;
224  /*! Data pointer passed with this task. */
225  void *data;
226 };
227 
228 /*!
229  * \brief Push a task into the specified taskprocessor queue and signal the
230  * taskprocessor thread.
231  *
232  * The callback receives a \ref ast_taskprocessor_local struct, which contains
233  * both the provided \a datap pointer, and any local data set on the
234  * taskprocessor with ast_taskprocessor_set_local().
235  *
236  * \param tps The taskprocessor structure
237  * \param task_exe The task handling function to push into the taskprocessor queue
238  * \param datap The data to be used by the task handling function
239  * \retval 0 success
240  * \retval -1 failure
241  * \since 12.0.0
242  */
244  int (*task_exe)(struct ast_taskprocessor_local *local), void *datap)
246 
247 /*!
248  * \brief Indicate the taskprocessor is suspended.
249  *
250  * \since 13.12.0
251  *
252  * \param tps Task processor.
253  * \retval 0 success
254  * \retval -1 failure
255  */
257 
258 /*!
259  * \brief Indicate the taskprocessor is unsuspended.
260  *
261  * \since 13.12.0
262  *
263  * \param tps Task processor.
264  * \retval 0 success
265  * \retval -1 failure
266  */
268 
269 /*!
270  * \brief Get the task processor suspend status
271  *
272  * \since 13.12.0
273  *
274  * \param tps Task processor.
275  * \retval non-zero if the task processor is suspended
276  */
278 
279 /*!
280  * \brief Pop a task off the taskprocessor and execute it.
281  *
282  * \since 12.0.0
283  *
284  * \param tps The taskprocessor from which to execute.
285  * \retval 0 There is no further work to be done.
286  * \retval 1 Tasks still remain in the taskprocessor queue.
287  */
289 
290 /*!
291  * \brief Am I the given taskprocessor's current task.
292  * \since 12.7.0
293  *
294  * \param tps Taskprocessor to check.
295  *
296  * \retval non-zero if current thread is the taskprocessor thread.
297  */
299 
300 /*!
301  * \brief Get the next sequence number to create a human friendly taskprocessor name.
302  * \since 13.8.0
303  *
304  * \return Sequence number for use in creating human friendly taskprocessor names.
305  */
306 unsigned int ast_taskprocessor_seq_num(void);
307 
308 /*!
309  * \brief Append the next sequence number to the given string, and copy into the buffer.
310  *
311  * \param buf Where to copy the appended taskprocessor name.
312  * \param size How large is buf including null terminator.
313  * \param name A name to append the sequence number to.
314  */
315 void ast_taskprocessor_name_append(char *buf, unsigned int size, const char *name);
316 
317 /*!
318  * \brief Build a taskprocessor name with a sequence number on the end.
319  * \since 13.8.0
320  *
321  * \param buf Where to put the built taskprocessor name.
322  * \param size How large is buf including null terminator.
323  * \param format printf format to create the non-sequenced part of the name.
324  *
325  * \note The user supplied part of the taskprocessor name is truncated
326  * to allow the full sequence number to be appended within the supplied
327  * buffer size.
328  */
329 void __attribute__((format(printf, 3, 4))) ast_taskprocessor_build_name(char *buf, unsigned int size, const char *format, ...);
330 
331 /*!
332  * \brief Return the name of the taskprocessor singleton
333  * \since 1.6.1
334  */
335 const char *ast_taskprocessor_name(struct ast_taskprocessor *tps);
336 
337 /*!
338  * \brief Return the current size of the taskprocessor queue
339  * \since 13.7.0
340  */
341 long ast_taskprocessor_size(struct ast_taskprocessor *tps);
342 
343 /*!
344  * \brief Get the current taskprocessor high water alert count.
345  * \since 13.10.0
346  *
347  * \retval 0 if no taskprocessors are in high water alert.
348  * \retval non-zero if some task processors are in high water alert.
349  */
350 unsigned int ast_taskprocessor_alert_get(void);
351 
352 
353 /*!
354  * \brief Get the current taskprocessor high water alert count by subsystem.
355  * \since 13.26.0
356  * \since 16.3.0
357  *
358  * \param subsystem The subsystem name
359  *
360  * \retval 0 if no taskprocessors are in high water alert.
361  * \retval non-zero if some task processors are in high water alert.
362  */
363 unsigned int ast_taskprocessor_get_subsystem_alert(const char *subsystem);
364 
365 /*!
366  * \brief Set the high and low alert water marks of the given taskprocessor queue.
367  * \since 13.10.0
368  *
369  * \param tps Taskprocessor to update queue water marks.
370  * \param low_water New queue low water mark. (-1 to set as 90% of high_water)
371  * \param high_water New queue high water mark.
372  *
373  * \retval 0 on success.
374  * \retval -1 on error (water marks not changed).
375  */
376 int ast_taskprocessor_alert_set_levels(struct ast_taskprocessor *tps, long low_water, long high_water);
377 
378 #endif /* __AST_TASKPROCESSOR_H__ */
static void * listener(void *unused)
Definition: asterisk.c:1512
static snd_pcm_format_t format
Definition: chan_alsa.c:106
#define attribute_warn_unused_result
Definition: compiler.h:71
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static const char name[]
Definition: format_mp3.c:68
struct @498 callbacks
void(* task_pushed)(struct ast_taskprocessor_listener *listener, int was_empty)
Indicates a task was pushed to the processor.
Definition: taskprocessor.h:99
int(* start)(struct ast_taskprocessor_listener *listener)
The taskprocessor has started completely.
Definition: taskprocessor.h:92
void(* emptied)(struct ast_taskprocessor_listener *listener)
Indicates the task processor has become empty.
void(* shutdown)(struct ast_taskprocessor_listener *listener)
Indicates the taskprocessor wishes to die.
void(* dtor)(struct ast_taskprocessor_listener *listener)
A listener for taskprocessors.
Local data parameter.
A ast_taskprocessor structure is a singleton by name.
Definition: taskprocessor.c:69
void ast_taskprocessor_set_local(struct ast_taskprocessor *tps, void *local_data)
Sets the local data associated with a taskprocessor.
void * ast_taskprocessor_unreference(struct ast_taskprocessor *tps)
Unreference the specified taskprocessor and its reference count will decrement.
int ast_taskprocessor_is_suspended(struct ast_taskprocessor *tps)
Get the task processor suspend status.
ast_tps_options
ast_tps_options for specification of taskprocessor options
Definition: taskprocessor.h:74
@ TPS_REF_IF_EXISTS
return a reference to a taskprocessor ONLY if it already exists
Definition: taskprocessor.h:78
@ TPS_REF_DEFAULT
return a reference to a taskprocessor, create one if it does not exist
Definition: taskprocessor.h:76
unsigned int ast_taskprocessor_alert_get(void)
Get the current taskprocessor high water alert count.
int ast_taskprocessor_is_task(struct ast_taskprocessor *tps)
Am I the given taskprocessor's current task.
void * ast_taskprocessor_listener_get_user_data(const struct ast_taskprocessor_listener *listener)
Get the user data from the listener.
struct ast_taskprocessor * ast_taskprocessor_listener_get_tps(const struct ast_taskprocessor_listener *listener)
Get a reference to the listener's taskprocessor.
int ast_taskprocessor_push(struct ast_taskprocessor *tps, int(*task_exe)(void *datap), void *datap) attribute_warn_unused_result
Push a task into the specified taskprocessor queue and signal the taskprocessor thread.
unsigned int ast_taskprocessor_seq_num(void)
Get the next sequence number to create a human friendly taskprocessor name.
int ast_taskprocessor_push_local(struct ast_taskprocessor *tps, int(*task_exe)(struct ast_taskprocessor_local *local), void *datap) attribute_warn_unused_result
Push a task into the specified taskprocessor queue and signal the taskprocessor thread.
void ast_taskprocessor_name_append(char *buf, unsigned int size, const char *name)
Append the next sequence number to the given string, and copy into the buffer.
long ast_taskprocessor_size(struct ast_taskprocessor *tps)
Return the current size of the taskprocessor queue.
int ast_taskprocessor_unsuspend(struct ast_taskprocessor *tps)
Indicate the taskprocessor is unsuspended.
int ast_taskprocessor_execute(struct ast_taskprocessor *tps)
Pop a task off the taskprocessor and execute it.
const char * ast_taskprocessor_name(struct ast_taskprocessor *tps)
Return the name of the taskprocessor singleton.
unsigned int ast_taskprocessor_get_subsystem_alert(const char *subsystem)
Get the current taskprocessor high water alert count by subsystem.
void ast_taskprocessor_build_name(char *buf, unsigned int size, const char *format,...)
Build a taskprocessor name with a sequence number on the end.
struct ast_taskprocessor * ast_taskprocessor_create_with_listener(const char *name, struct ast_taskprocessor_listener *listener)
Create a taskprocessor with a custom listener.
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.
int ast_taskprocessor_alert_set_levels(struct ast_taskprocessor *tps, long low_water, long high_water)
Set the high and low alert water marks of the given taskprocessor queue.
struct ast_taskprocessor_listener * ast_taskprocessor_listener_alloc(const struct ast_taskprocessor_listener_callbacks *callbacks, void *user_data)
Allocate a taskprocessor listener.
int ast_taskprocessor_suspend(struct ast_taskprocessor *tps)
Indicate the taskprocessor is suspended.