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