Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
threadpool.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2012-2013, Digium, Inc.
5 *
6 * Mark Michelson <mmmichelson@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#ifndef _ASTERISK_THREADPOOL_H
21#define _ASTERISK_THREADPOOL_H
22
23struct ast_threadpool;
26
28 /*!
29 * \brief Indicates that the state of threads in the pool has changed
30 *
31 * \param pool The pool whose state has changed
32 * \param listener The threadpool listener
33 * \param active_threads The number of active threads in the pool
34 * \param idle_threads The number of idle threads in the pool
35 */
36 void (*state_changed)(struct ast_threadpool *pool,
38 int active_threads,
39 int idle_threads);
40 /*!
41 * \brief Indicates that a task was pushed to the threadpool
42 *
43 * \param pool The pool that had a task pushed
44 * \param listener The threadpool listener
45 * \param was_empty Indicates whether there were any tasks prior to adding the new one.
46 */
47 void (*task_pushed)(struct ast_threadpool *pool,
49 int was_empty);
50 /*!
51 * \brief Indicates the threadpool's taskprocessor has become empty
52 *
53 * \param pool The pool that has become empty
54 * \param listener The threadpool's listener
55 */
57
58 /*!
59 * \brief The threadpool is shutting down
60 *
61 * This would be an opportune time to free the listener's user data
62 * if one wishes. However, it is acceptable to not do so if the user data
63 * should persist beyond the lifetime of the pool.
64 *
65 * \param listener The threadpool's listener
66 */
68};
69
71#define AST_THREADPOOL_OPTIONS_VERSION 1
72 /*! Version of threadpool options in use */
74 /*!
75 * \brief Time limit in seconds for idle threads
76 *
77 * A time of 0 or less will mean no timeout.
78 */
80 /*!
81 * \brief Number of threads to increment pool by
82 *
83 * If a task is added into a pool and no idle thread is
84 * available to activate, then the pool can automatically
85 * grow by the given amount.
86 *
87 * Zero is a perfectly valid value to give here if you want
88 * to control threadpool growth yourself via your listener.
89 */
91 /*!
92 * \brief Number of threads the pool will start with
93 *
94 * When the threadpool is allocated, it will immediately size
95 * itself to have this number of threads in it.
96 *
97 * Zero is a valid value if the threadpool should start
98 * without any threads allocated.
99 */
101 /*!
102 * \brief Maximum number of threads a pool may have
103 *
104 * When the threadpool's size increases, it can never increase
105 * beyond this number of threads.
106 *
107 * Zero is a valid value if the threadpool does not have a
108 * maximum size.
109 */
111 /*!
112 * \brief Function to call when a thread starts
113 *
114 * This is useful if there is something common that all threads
115 * in a threadpool need to do when they start.
116 */
117 void (*thread_start)(void);
118 /*!
119 * \brief Function to call when a thread ends
120 *
121 * This is useful if there is common cleanup to execute when
122 * a thread completes
123 */
124 void (*thread_end)(void);
125};
126
127/*!
128 * \brief Allocate a threadpool listener
129 *
130 * This function will call back into the alloc callback for the
131 * listener.
132 *
133 * \param callbacks Listener callbacks to assign to the listener
134 * \param user_data User data to be stored in the threadpool listener
135 * \retval NULL Failed to allocate the listener
136 * \retval non-NULL The newly-created threadpool listener
137 */
140
141/*!
142 * \brief Get the threadpool listener's user data
143 * \param listener The threadpool listener
144 * \return The user data
145 */
147
148/*!
149 * \brief Create a new threadpool
150 *
151 * This function creates a threadpool. Tasks may be pushed onto this thread pool
152 * and will be automatically acted upon by threads within the pool.
153 *
154 * Only a single threadpool with a given name may exist. This function will fail
155 * if a threadpool with the given name already exists.
156 *
157 * \param name The unique name for the threadpool
158 * \param listener The listener the threadpool will notify of changes. Can be NULL.
159 * \param options The behavioral options for this threadpool
160 * \retval NULL Failed to create the threadpool
161 * \retval non-NULL The newly-created threadpool
162 */
163struct ast_threadpool *ast_threadpool_create(const char *name,
165 const struct ast_threadpool_options *options);
166
167/*!
168 * \brief Set the number of threads for the thread pool
169 *
170 * This number may be more or less than the current number of
171 * threads in the threadpool.
172 *
173 * \param threadpool The threadpool to adjust
174 * \param size The new desired size of the threadpool
175 */
176void ast_threadpool_set_size(struct ast_threadpool *threadpool, unsigned int size);
177
178/*!
179 * \brief Push a task to the threadpool
180 *
181 * Tasks pushed into the threadpool will be automatically taken by
182 * one of the threads within
183 * \param pool The threadpool to add the task to
184 * \param task The task to add
185 * \param data The parameter for the task
186 * \retval 0 success
187 * \retval -1 failure
188 */
189int ast_threadpool_push(struct ast_threadpool *pool, int (*task)(void *data), void *data)
191
192/*!
193 * \brief Shut down a threadpool and destroy it
194 *
195 * \param pool The pool to shut down
196 */
197void ast_threadpool_shutdown(struct ast_threadpool *pool);
198
200
201/*!
202 * \brief Create a serializer group shutdown control object.
203 * \since 13.5.0
204 *
205 * \return ao2 object to control shutdown of a serializer group.
206 */
208
209/*!
210 * \brief Wait for the serializers in the group to shutdown with timeout.
211 * \since 13.5.0
212 *
213 * \param shutdown_group Group shutdown controller. (Returns 0 immediately if NULL)
214 * \param timeout Number of seconds to wait for the serializers in the group to shutdown.
215 * Zero if the timeout is disabled.
216 *
217 * \return Number of serializers that did not get shutdown within the timeout.
218 */
220
221/*!
222 * \brief Get the threadpool serializer currently associated with this thread.
223 * \since 14.0.0
224 *
225 * \note The returned pointer is valid while the serializer
226 * thread is running.
227 *
228 * \note Use ao2_ref() on serializer if you are going to keep it
229 * for another thread. To unref it you must then use
230 * ast_taskprocessor_unreference().
231 *
232 * \retval serializer on success.
233 * \retval NULL on error or no serializer associated with the thread.
234 */
236
237/*!
238 * \brief Serialized execution of tasks within a \ref ast_threadpool.
239 *
240 * \since 12.0.0
241 *
242 * A \ref ast_taskprocessor with the same contract as a default taskprocessor
243 * (tasks execute serially) except instead of executing out of a dedicated
244 * thread, execution occurs in a thread from a \ref ast_threadpool. Think of it
245 * as a lightweight thread.
246 *
247 * While it guarantees that each task will complete before executing the next,
248 * there is no guarantee as to which thread from the \c pool individual tasks
249 * will execute. This normally only matters if your code relies on thread
250 * specific information, such as thread locals.
251 *
252 * Use ast_taskprocessor_unreference() to dispose of the returned \ref
253 * ast_taskprocessor.
254 *
255 * Only a single taskprocessor with a given name may exist. This function will fail
256 * if a taskprocessor with the given name already exists.
257 *
258 * \param name Name of the serializer. (must be unique)
259 * \param pool \ref ast_threadpool for execution.
260 *
261 * \return \ref ast_taskprocessor for enqueuing work.
262 * \retval NULL on error.
263 */
264struct ast_taskprocessor *ast_threadpool_serializer(const char *name, struct ast_threadpool *pool);
265
266/*!
267 * \brief Serialized execution of tasks within a \ref ast_threadpool.
268 * \since 13.5.0
269 *
270 * A \ref ast_taskprocessor with the same contract as a default taskprocessor
271 * (tasks execute serially) except instead of executing out of a dedicated
272 * thread, execution occurs in a thread from a \ref ast_threadpool. Think of it
273 * as a lightweight thread.
274 *
275 * While it guarantees that each task will complete before executing the next,
276 * there is no guarantee as to which thread from the \c pool individual tasks
277 * will execute. This normally only matters if your code relies on thread
278 * specific information, such as thread locals.
279 *
280 * Use ast_taskprocessor_unreference() to dispose of the returned \ref
281 * ast_taskprocessor.
282 *
283 * Only a single taskprocessor with a given name may exist. This function will fail
284 * if a taskprocessor with the given name already exists.
285 *
286 * \param name Name of the serializer. (must be unique)
287 * \param pool \ref ast_threadpool for execution.
288 * \param shutdown_group Group shutdown controller. (NULL if no group association)
289 *
290 * \return \ref ast_taskprocessor for enqueuing work.
291 * \retval NULL on error.
292 */
295
296/*!
297 * \brief Return the size of the threadpool's task queue
298 * \since 13.7.0
299 */
301
302#endif /* ASTERISK_THREADPOOL_H */
static void * listener(void *unused)
Definition: asterisk.c:1519
#define attribute_warn_unused_result
Definition: compiler.h:71
static const char name[]
Definition: format_mp3.c:68
static struct ast_serializer_shutdown_group * shutdown_group
Shutdown group for options serializers.
struct @468 callbacks
static struct ast_threadpool * threadpool
Thread pool for observers.
Definition: sorcery.c:86
A ast_taskprocessor structure is a singleton by name.
Definition: taskprocessor.c:69
void(* shutdown)(struct ast_threadpool_listener *listener)
The threadpool is shutting down.
Definition: threadpool.h:67
void(* emptied)(struct ast_threadpool *pool, struct ast_threadpool_listener *listener)
Indicates the threadpool's taskprocessor has become empty.
Definition: threadpool.h:56
void(* task_pushed)(struct ast_threadpool *pool, struct ast_threadpool_listener *listener, int was_empty)
Indicates that a task was pushed to the threadpool.
Definition: threadpool.h:47
void(* state_changed)(struct ast_threadpool *pool, struct ast_threadpool_listener *listener, int active_threads, int idle_threads)
Indicates that the state of threads in the pool has changed.
Definition: threadpool.h:36
listener for a threadpool
Definition: threadpool.c:110
void(* thread_start)(void)
Function to call when a thread starts.
Definition: threadpool.h:117
int idle_timeout
Time limit in seconds for idle threads.
Definition: threadpool.h:79
int max_size
Maximum number of threads a pool may have.
Definition: threadpool.h:110
void(* thread_end)(void)
Function to call when a thread ends.
Definition: threadpool.h:124
int auto_increment
Number of threads to increment pool by.
Definition: threadpool.h:90
int initial_size
Number of threads the pool will start with.
Definition: threadpool.h:100
An opaque threadpool structure.
Definition: threadpool.c:36
static struct test_options options
static int task(void *data)
Queued task for baseline test.
void ast_threadpool_shutdown(struct ast_threadpool *pool)
Shut down a threadpool and destroy it.
Definition: threadpool.c:966
struct ast_taskprocessor * ast_threadpool_serializer_get_current(void)
Get the threadpool serializer currently associated with this thread.
Definition: threadpool.c:1393
int ast_threadpool_push(struct ast_threadpool *pool, int(*task)(void *data), void *data) attribute_warn_unused_result
Push a task to the threadpool.
Definition: threadpool.c:957
long ast_threadpool_queue_size(struct ast_threadpool *pool)
Return the size of the threadpool's task queue.
Definition: threadpool.c:1433
void * ast_threadpool_listener_get_user_data(const struct ast_threadpool_listener *listener)
Get the threadpool listener's user data.
Definition: threadpool.c:906
struct ast_taskprocessor * ast_threadpool_serializer_group(const char *name, struct ast_threadpool *pool, struct ast_serializer_shutdown_group *shutdown_group)
Serialized execution of tasks within a ast_threadpool.
Definition: threadpool.c:1398
int ast_serializer_shutdown_group_join(struct ast_serializer_shutdown_group *shutdown_group, int timeout)
Wait for the serializers in the group to shutdown with timeout.
Definition: threadpool.c:1241
void ast_threadpool_set_size(struct ast_threadpool *threadpool, unsigned int size)
Set the number of threads for the thread pool.
Definition: threadpool.c:875
struct ast_threadpool * ast_threadpool_create(const char *name, struct ast_threadpool_listener *listener, const struct ast_threadpool_options *options)
Create a new threadpool.
Definition: threadpool.c:916
struct ast_threadpool_listener * ast_threadpool_listener_alloc(const struct ast_threadpool_listener_callbacks *callbacks, void *user_data)
Allocate a threadpool listener.
Definition: threadpool.c:894
struct ast_taskprocessor * ast_threadpool_serializer(const char *name, struct ast_threadpool *pool)
Serialized execution of tasks within a ast_threadpool.
Definition: threadpool.c:1428
struct ast_serializer_shutdown_group * ast_serializer_shutdown_group_alloc(void)
Create a serializer group shutdown control object.
Definition: threadpool.c:1229