Asterisk - The Open Source Telephony Project GIT-master-55f4e6d
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
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 */
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 */
167struct 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 */
217int 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. */
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 */
306unsigned 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 */
315void 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 */
329void __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 */
335const 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 */
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 */
350unsigned 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 */
363unsigned 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 */
376int 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:1515
#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 @468 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
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.
struct ast_taskprocessor_listener * ast_taskprocessor_listener_alloc(const struct ast_taskprocessor_listener_callbacks *callbacks, void *user_data)
Allocate a taskprocessor listener.
void * ast_taskprocessor_unreference(struct ast_taskprocessor *tps)
Unreference the specified taskprocessor and its reference count will decrement.
void ast_taskprocessor_set_local(struct ast_taskprocessor *tps, void *local_data)
Sets the local data associated with a taskprocessor.
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.
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.
void * ast_taskprocessor_listener_get_user_data(const struct ast_taskprocessor_listener *listener)
Get the user data from the listener.
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.
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_listener_get_tps(const struct ast_taskprocessor_listener *listener)
Get a reference to the listener's taskprocessor.
const char * ast_taskprocessor_name(struct ast_taskprocessor *tps)
Return the name of the taskprocessor singleton.
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.
int ast_taskprocessor_suspend(struct ast_taskprocessor *tps)
Indicate the taskprocessor is suspended.