2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 2012, Digium, Inc.
6 * Mark Michelson <mmmichelson@digium.com>
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.
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.
20 #ifndef _ASTERISK_THREADPOOL_H
21 #define _ASTERISK_THREADPOOL_H
23 struct ast_threadpool;
24 struct ast_taskprocessor;
25 struct ast_threadpool_listener;
27 struct ast_threadpool_listener_callbacks {
29 * \brief Indicates that the state of threads in the pool has changed
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
36 void (*state_changed)(struct ast_threadpool *pool,
37 struct ast_threadpool_listener *listener,
41 * \brief Indicates that a task was pushed to the threadpool
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.
47 void (*task_pushed)(struct ast_threadpool *pool,
48 struct ast_threadpool_listener *listener,
51 * \brief Indicates the threadpool's taskprocessor has become empty
53 * \param pool The pool that has become empty
54 * \param listener The threadpool's listener
56 void (*emptied)(struct ast_threadpool *pool, struct ast_threadpool_listener *listener);
59 * \brief The threadpool is shutting down
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.
65 * \param listener The threadpool's listener
67 void (*shutdown)(struct ast_threadpool_listener *listener);
71 * \brief listener for a threadpool
73 * The listener is notified of changes in a threadpool. It can
74 * react by doing things like increasing the number of threads
77 struct ast_threadpool_listener {
78 /*! Callbacks called by the threadpool */
79 const struct ast_threadpool_listener_callbacks *callbacks;
80 /*! User data for the listener */
84 struct ast_threadpool_options {
85 #define AST_THREADPOOL_OPTIONS_VERSION 1
86 /*! Version of thradpool options in use */
89 * \brief Time limit in seconds for idle threads
91 * A time of 0 or less will mean no timeout.
95 * \brief Number of threads to increment pool by
97 * If a task is added into a pool and no idle thread is
98 * available to activate, then the pool can automatically
99 * grow by the given amount.
101 * Zero is a perfectly valid value to give here if you want
102 * to control threadpool growth yourself via your listener.
106 * \brief Number of threads the pool will start with
108 * When the threadpool is allocated, it will immediately size
109 * itself to have this number of threads in it.
111 * Zero is a valid value if the threadpool should start
112 * without any threads allocated.
118 * \brief Allocate a threadpool listener
120 * This function will call back into the alloc callback for the
123 * \param callbacks Listener callbacks to assign to the listener
124 * \param user_data User data to be stored in the threadpool listener
125 * \retval NULL Failed to allocate the listener
126 * \retval non-NULL The newly-created threadpool listener
128 struct ast_threadpool_listener *ast_threadpool_listener_alloc(
129 const struct ast_threadpool_listener_callbacks *callbacks, void *user_data);
132 * \brief Create a new threadpool
134 * This function creates a threadpool. Tasks may be pushed onto this thread pool
135 * in and will be automatically acted upon by threads within the pool.
137 * \param name The name for the threadpool
138 * \param listener The listener the threadpool will notify of changes. Can be NULL.
139 * \param options The behavioral options for this threadpool
140 * \retval NULL Failed to create the threadpool
141 * \retval non-NULL The newly-created threadpool
143 struct ast_threadpool *ast_threadpool_create(const char *name,
144 struct ast_threadpool_listener *listener,
145 const struct ast_threadpool_options *options);
148 * \brief Set the number of threads for the thread pool
150 * This number may be more or less than the current number of
151 * threads in the threadpool.
153 * \param threadpool The threadpool to adjust
154 * \param size The new desired size of the threadpool
156 void ast_threadpool_set_size(struct ast_threadpool *threadpool, unsigned int size);
159 * \brief Push a task to the threadpool
161 * Tasks pushed into the threadpool will be automatically taken by
162 * one of the threads within
163 * \param pool The threadpool to add the task to
164 * \param task The task to add
165 * \param data The parameter for the task
169 int ast_threadpool_push(struct ast_threadpool *pool, int (*task)(void *data), void *data);
172 * \brief Shut down a threadpool and destroy it
174 * \param pool The pool to shut down
176 void ast_threadpool_shutdown(struct ast_threadpool *pool);
177 #endif /* ASTERISK_THREADPOOL_H */