Asterisk - The Open Source Telephony Project  GIT-master-b7027de
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 
23 struct ast_threadpool;
24 struct ast_taskprocessor;
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  */
56  void (*emptied)(struct ast_threadpool *pool, struct ast_threadpool_listener *listener);
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 */
73  int version;
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  */
110  int max_size;
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  */
163 struct 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  */
176 void 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  */
189 int 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  */
197 void 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 seriaizers 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 relys 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  * \return \c NULL on error.
263  */
264 struct 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 relys 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  * \return \c NULL on error.
292  */
295 
296 /*!
297  * \brief Return the size of the threadpool's task queue
298  * \since 13.7.0
299  */
300 long ast_threadpool_queue_size(struct ast_threadpool *pool);
301 
302 #endif /* ASTERISK_THREADPOOL_H */
int auto_increment
Number of threads to increment pool by.
Definition: threadpool.h:90
void ast_threadpool_set_size(struct ast_threadpool *threadpool, unsigned int size)
Set the number of threads for the thread pool.
Definition: threadpool.c:874
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
int idle_timeout
Time limit in seconds for idle threads.
Definition: threadpool.h:79
int initial_size
Number of threads the pool will start with.
Definition: threadpool.h:100
int max_size
Maximum number of threads a pool may have.
Definition: threadpool.h:110
struct ast_taskprocessor * ast_threadpool_serializer(const char *name, struct ast_threadpool *pool)
Serialized execution of tasks within a ast_threadpool.
Definition: threadpool.c:1432
struct ast_serializer_shutdown_group * ast_serializer_shutdown_group_alloc(void)
Create a serializer group shutdown control object.
Definition: threadpool.c:1229
static int timeout
Definition: cdr_mysql.c:86
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:1402
void(* shutdown)(struct ast_threadpool_listener *listener)
The threadpool is shutting down.
Definition: threadpool.h:67
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
struct ast_taskprocessor * ast_threadpool_serializer_get_current(void)
Get the threadpool serializer currently associated with this thread.
Definition: threadpool.c:1397
const struct ast_threadpool_listener_callbacks * callbacks
Definition: threadpool.c:112
static int task(void *data)
Queued task for baseline test.
void(* emptied)(struct ast_threadpool *pool, struct ast_threadpool_listener *listener)
Indicates the threadpool&#39;s taskprocessor has become empty.
Definition: threadpool.h:56
static void * listener(void *unused)
Definition: asterisk.c:1476
void * ast_threadpool_listener_get_user_data(const struct ast_threadpool_listener *listener)
Get the threadpool listener&#39;s user data.
Definition: threadpool.c:905
static struct ast_threadpool * threadpool
Thread pool for observers.
Definition: sorcery.c:86
long ast_threadpool_queue_size(struct ast_threadpool *pool)
Return the size of the threadpool&#39;s task queue.
Definition: threadpool.c:1437
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:893
static const char name[]
Definition: cdr_mysql.c:74
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:915
#define attribute_warn_unused_result
Definition: compiler.h:71
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:956
void ast_threadpool_shutdown(struct ast_threadpool *pool)
Shut down a threadpool and destroy it.
Definition: threadpool.c:965
listener for a threadpool
Definition: threadpool.c:110
A ast_taskprocessor structure is a singleton by name.
Definition: taskprocessor.c:69
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
An opaque threadpool structure.
Definition: threadpool.c:36
static struct test_options options
static struct ast_serializer_shutdown_group * shutdown_group
Shutdown group for options serializers.