Add better listener support.
[asterisk/asterisk.git] / include / asterisk / threadpool.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012, 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;
25 struct ast_threadpool_listener;
26
27 struct ast_threadpool_listener_callbacks {
28         /*!
29          * \brief Allocate the listener's private data
30          *
31          * It is not necessary to assign the private data to the listener.
32          * \param listener The listener the private data will belong to
33          * \retval NULL Failure to allocate private data
34          * \retval non-NULL The newly allocated private data
35          */
36         void *(*alloc)(struct ast_threadpool_listener *listener);
37         /*!
38          * \brief Indicates that the state of threads in the pool has changed
39          *
40          * \param listener The threadpool listener
41          * \param active_threads The number of active threads in the pool
42          * \param idle_threads The number of idle threads in the pool
43          */
44         void (*state_changed)(struct ast_threadpool *pool,
45                         struct ast_threadpool_listener *listener,
46                         int active_threads,
47                         int idle_threads);
48         /*!
49          * \brief Indicates that a task was pushed to the threadpool
50          *
51          * \param listener The threadpool listener
52          * \param was_empty Indicates whether there were any tasks prior to adding the new one.
53          */
54         void (*task_pushed)(struct ast_threadpool *pool,
55                         struct ast_threadpool_listener *listener,
56                         int was_empty);
57         /*!
58          * \brief Indicates the threadpoo's taskprocessor has become empty
59          * 
60          * \param listener The threadpool's listener
61          */
62         void (*emptied)(struct ast_threadpool *pool, struct ast_threadpool_listener *listener);
63
64         /*!
65          * \brief Free the listener's private data
66          * \param private_data The private data to destroy
67          */
68         void (*destroy)(void *private_data);
69 };
70
71 /*!
72  * \brief listener for a threadpool
73  *
74  * The listener is notified of changes in a threadpool. It can
75  * react by doing things like increasing the number of threads
76  * in the pool
77  */
78 struct ast_threadpool_listener {
79         /*! Callbacks called by the threadpool */
80         const struct ast_threadpool_listener_callbacks *callbacks;
81         /*! User data for the listener */
82         void *private_data;
83 };
84
85 /*!
86  * \brief Allocate a threadpool listener
87  *
88  * This function will call back into the alloc callback for the
89  * listener.
90  *
91  * \param callbacks Listener callbacks to assign to the listener
92  * \retval NULL Failed to allocate the listener
93  * \retval non-NULL The newly-created threadpool listener
94  */
95 struct ast_threadpool_listener *ast_threadpool_listener_alloc(
96                 const struct ast_threadpool_listener_callbacks *callbacks);
97
98 /*!
99  * \brief Create a new threadpool
100  *
101  * This function creates a threadpool. Tasks may be pushed onto this thread pool
102  * in and will be automatically acted upon by threads within the pool.
103  *
104  * \param listener The listener the threadpool will notify of changes
105  * \param initial_size The number of threads for the pool to start with
106  * \retval NULL Failed to create the threadpool
107  * \retval non-NULL The newly-created threadpool
108  */
109 struct ast_threadpool *ast_threadpool_create(struct ast_threadpool_listener *listener, int initial_size);
110
111 /*!
112  * \brief Set the number of threads for the thread pool
113  *
114  * This number may be more or less than the current number of
115  * threads in the threadpool.
116  * 
117  * \param threadpool The threadpool to adjust
118  * \param size The new desired size of the threadpool
119  */
120 void ast_threadpool_set_size(struct ast_threadpool *threadpool, unsigned int size);
121
122 /*!
123  * \brief Push a task to the threadpool
124  *
125  * Tasks pushed into the threadpool will be automatically taken by
126  * one of the threads within
127  * \param pool The threadpool to add the task to
128  * \param task The task to add
129  * \param data The parameter for the task
130  * \retval 0 success
131  * \retval -1 failure
132  */
133 int ast_threadpool_push(struct ast_threadpool *pool, int (*task)(void *data), void *data);
134
135 /*!
136  * \brief Shut down a threadpool and destroy it
137  *
138  * \param pool The pool to shut down
139  */
140 void ast_threadpool_shutdown(struct ast_threadpool *pool);
141 #endif /* ASTERISK_THREADPOOL_H */