[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_threadpool.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Declaration of thread pool.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_THREAD_POOL_H_\r
44 #define _CL_THREAD_POOL_H_\r
45 \r
46 \r
47 #include <complib/cl_list.h>\r
48 #include <complib/cl_thread.h>\r
49 #include <complib/cl_event.h>\r
50 \r
51 \r
52 /****h* Component Library/Thread Pool\r
53 * NAME\r
54 *       Thread Pool\r
55 *\r
56 * DESCRIPTION\r
57 *       The Thread Pool manages a user specified number of threads.\r
58 *\r
59 *       Each thread in the thread pool waits for a user initiated signal before\r
60 *       invoking a user specified callback function. All threads in the thread\r
61 *       pool invoke the same callback function.\r
62 *\r
63 *       The thread pool functions operate on a cl_thread_pool_t structure which\r
64 *       should be treated as opaque, and should be manipulated only through the\r
65 *       provided functions.\r
66 *\r
67 * SEE ALSO\r
68 *       Structures:\r
69 *               cl_thread_pool_t\r
70 *\r
71 *       Initialization:\r
72 *               cl_thread_pool_construct, cl_thread_pool_init, cl_thread_pool_destroy\r
73 *\r
74 *       Manipulation\r
75 *               cl_thread_pool_signal\r
76 *********/\r
77 \r
78 \r
79 /****s* Component Library: Thread Pool/cl_thread_pool_t\r
80 * NAME\r
81 *       cl_thread_pool_t\r
82 *\r
83 * DESCRIPTION\r
84 *       Thread pool structure.\r
85 *\r
86 *       The cl_thread_pool_t structure should be treated as opaque, and should be\r
87 *       manipulated only through the provided functions.\r
88 *\r
89 * SYNOPSIS\r
90 */\r
91 typedef struct _cl_thread_pool\r
92 {\r
93         cl_pfn_thread_callback_t        pfn_callback;\r
94         const void                                      *context;\r
95         cl_list_t                                       thread_list;\r
96         cl_event_t                                      wakeup_event;\r
97         cl_event_t                                      destroy_event;\r
98         boolean_t                                       exit;\r
99         cl_state_t                                      state;\r
100         atomic32_t                                      running_count;\r
101 \r
102 } cl_thread_pool_t;\r
103 /*\r
104 * FIELDS\r
105 *       pfn_callback\r
106 *               Callback function for the thread to invoke.\r
107 *\r
108 *       context\r
109 *               Context to pass to the thread callback function.\r
110 *\r
111 *       thread_list\r
112 *               List of threads managed by the thread pool.\r
113 *\r
114 *       event\r
115 *               Event used to signal threads to wake up and do work.\r
116 *\r
117 *       destroy_event\r
118 *               Event used to signal threads to exit.\r
119 *\r
120 *       exit\r
121 *               Flag used to indicates threads to exit.\r
122 *\r
123 *       state\r
124 *               State of the thread pool.\r
125 *\r
126 *       running_count\r
127 *               Number of threads running.\r
128 *\r
129 * SEE ALSO\r
130 *       Thread Pool\r
131 *********/\r
132 \r
133 \r
134 #ifdef __cplusplus\r
135 extern "C"\r
136 {\r
137 #endif\r
138 \r
139 \r
140 /****f* Component Library: Thread Pool/cl_thread_pool_construct\r
141 * NAME\r
142 *       cl_thread_pool_construct\r
143 *\r
144 * DESCRIPTION\r
145 *       The cl_thread_pool_construct function initializes the state of a\r
146 *       thread pool.\r
147 *\r
148 * SYNOPSIS\r
149 */\r
150 CL_EXPORT void CL_API\r
151 cl_thread_pool_construct(\r
152         IN      cl_thread_pool_t* const p_thread_pool );\r
153 /*\r
154 * PARAMETERS\r
155 *       p_thread_pool\r
156 *               [in] Pointer to a thread pool structure.\r
157 *\r
158 * RETURN VALUE\r
159 *       This function does not return a value.\r
160 *\r
161 * NOTES\r
162 *       Allows calling cl_thread_pool_destroy without first calling\r
163 *       cl_thread_pool_init.\r
164 *\r
165 *       Calling cl_thread_pool_construct is a prerequisite to calling any other\r
166 *       thread pool function except cl_thread_pool_init.\r
167 *\r
168 * SEE ALSO\r
169 *       Thread Pool, cl_thread_pool_init, cl_thread_pool_destroy\r
170 *********/\r
171 \r
172 \r
173 /****f* Component Library: Thread Pool/cl_thread_pool_init\r
174 * NAME\r
175 *       cl_thread_pool_init\r
176 *\r
177 * DESCRIPTION\r
178 *       The cl_thread_pool_init function creates the threads to be\r
179 *       managed by a thread pool.\r
180 *\r
181 * SYNOPSIS\r
182 */\r
183 CL_EXPORT cl_status_t CL_API\r
184 cl_thread_pool_init(\r
185         IN      cl_thread_pool_t* const         p_thread_pool,\r
186         IN      uint32_t                                        thread_count,\r
187         IN      cl_pfn_thread_callback_t        pfn_callback,\r
188         IN      const void* const                       context,\r
189         IN      const char* const                       name );\r
190 /*\r
191 * PARAMETERS\r
192 *       p_thread_pool\r
193 *               [in] Pointer to a thread pool structure to initialize.\r
194 *\r
195 *       thread_count\r
196 *               [in] Number of threads to be managed by the thread pool.\r
197 *\r
198 *       pfn_callback\r
199 *               [in] Address of a function to be invoked by a thread.\r
200 *               See the cl_pfn_thread_callback_t function type definition for\r
201 *               details about the callback function.\r
202 *\r
203 *       context\r
204 *               [in] Value to pass to the callback function.\r
205 *\r
206 *       name\r
207 *               [in] Name to associate with the threads.  The name may be up to 16\r
208 *               characters, including a terminating null character.  All threads\r
209 *               created in the pool have the same name.\r
210 *\r
211 * RETURN VALUES\r
212 *       CL_SUCCESS if the thread pool creation succeeded.\r
213 *\r
214 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize\r
215 *       the thread pool.\r
216 *\r
217 *       CL_ERROR if the threads could not be created.\r
218 *\r
219 * NOTES\r
220 *       cl_thread_pool_init creates and starts the specified number of threads.\r
221 *       If thread_count is zero, the thread pool creates as many threads as there\r
222 *       are processors in the system.\r
223 *\r
224 * SEE ALSO\r
225 *       Thread Pool, cl_thread_pool_construct, cl_thread_pool_destroy,\r
226 *       cl_thread_pool_signal, cl_pfn_thread_callback_t\r
227 *********/\r
228 \r
229 \r
230 /****f* Component Library: Thread Pool/cl_thread_pool_destroy\r
231 * NAME\r
232 *       cl_thread_pool_destroy\r
233 *\r
234 * DESCRIPTION\r
235 *       The cl_thread_pool_destroy function performs any necessary cleanup\r
236 *       for a thread pool.\r
237 *\r
238 * SYNOPSIS\r
239 */\r
240 CL_EXPORT void CL_API\r
241 cl_thread_pool_destroy(\r
242         IN      cl_thread_pool_t* const p_thread_pool );\r
243 /*\r
244 * PARAMETERS\r
245 *       p_thread_pool\r
246 *               [in] Pointer to a thread pool structure to destroy.\r
247 *\r
248 * RETURN VALUE\r
249 *       This function does not return a value.\r
250 *\r
251 * NOTES\r
252 *       This function blocks until all threads exit, and must therefore not\r
253 *       be called from any of the thread pool's threads. Because of its blocking\r
254 *       nature, callers of cl_thread_pool_destroy must ensure that entering a wait\r
255 *       state is valid from the calling thread context.\r
256 *\r
257 *       This function should only be called after a call to\r
258 *       cl_thread_pool_construct or cl_thread_pool_init.\r
259 *\r
260 * SEE ALSO\r
261 *       Thread Pool, cl_thread_pool_construct, cl_thread_pool_init\r
262 *********/\r
263 \r
264 \r
265 /****f* Component Library: Thread Pool/cl_thread_pool_signal\r
266 * NAME\r
267 *       cl_thread_pool_signal\r
268 *\r
269 * DESCRIPTION\r
270 *       The cl_thread_pool_signal function signals a single thread of\r
271 *       the thread pool to invoke the thread pool\92s callback function.\r
272 *\r
273 * SYNOPSIS\r
274 */\r
275 CL_EXPORT cl_status_t CL_API\r
276 cl_thread_pool_signal(\r
277         IN      cl_thread_pool_t* const p_thread_pool );\r
278 /*\r
279 * PARAMETERS\r
280 *       p_thread_pool\r
281 *               [in] Pointer to a thread pool structure to signal.\r
282 *\r
283 * RETURN VALUES\r
284 *       CL_SUCCESS if the thread pool was successfully signalled.\r
285 *\r
286 *       CL_ERROR otherwise.\r
287 *\r
288 * NOTES\r
289 *       Each call to this function wakes up at most one waiting thread in\r
290 *       the thread pool.\r
291 *\r
292 *       If all threads are running, cl_thread_pool_signal has no effect.\r
293 *\r
294 * SEE ALSO\r
295 *       Thread Pool\r
296 *********/\r
297 \r
298 \r
299 #ifdef __cplusplus\r
300 }       /* extern "C" */\r
301 #endif\r
302 \r
303 \r
304 #endif /* _CL_THREAD_POOL_H_ */\r