[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_async_proc.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 the asynchronous processing module.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_ASYNC_PROC_H_\r
44 #define _CL_ASYNC_PROC_H_\r
45 \r
46 \r
47 #include <complib/cl_qlist.h>\r
48 #include <complib/cl_qpool.h>\r
49 #include <complib/cl_threadpool.h>\r
50 #include <complib/cl_spinlock.h>\r
51 \r
52 \r
53 /****h* Component Library/Asynchronous Processor\r
54 * NAME\r
55 *       Asynchronous Processor\r
56 *\r
57 * DESCRIPTION\r
58 *       The asynchronous processor provides threads for executing queued callbacks.\r
59 *\r
60 *       The threads in the asynchronous processor wait for callbacks to be queued.\r
61 *\r
62 *       The asynchronous processor functions operate on a cl_async_proc_t structure\r
63 *       which should be treated as opaque and manipulated only through the provided\r
64 *       functions.\r
65 *\r
66 * SEE ALSO\r
67 *       Structures:\r
68 *               cl_async_proc_t, cl_async_proc_item_t\r
69 *\r
70 *       Initialization:\r
71 *               cl_async_proc_construct, cl_async_proc_init, cl_async_proc_destroy\r
72 *\r
73 *       Manipulation:\r
74 *               cl_async_proc_queue\r
75 *********/\r
76 \r
77 \r
78 /****s* Component Library: Asynchronous Processor/cl_async_proc_t\r
79 * NAME\r
80 *       cl_async_proc_t\r
81 *\r
82 * DESCRIPTION\r
83 *       Asynchronous processor structure.\r
84 *\r
85 *       The cl_async_proc_t structure should be treated as opaque, and should be\r
86 *       manipulated only through the provided functions.\r
87 *\r
88 * SYNOPSIS\r
89 */\r
90 typedef struct _cl_async_proc\r
91 {\r
92         cl_thread_pool_t        thread_pool;\r
93         cl_qlist_t                      item_queue;\r
94         cl_spinlock_t           lock;\r
95         cl_state_t                      state;\r
96 \r
97 } cl_async_proc_t;\r
98 /*\r
99 * FIELDS\r
100 *       item_pool\r
101 *               Pool of items storing the callback function and contexts to be invoked\r
102 *               by the asynchronous processor's threads.\r
103 *\r
104 *       thread_pool\r
105 *               Thread pool that will invoke the callbacks.\r
106 *\r
107 *       item_queue\r
108 *               Queue of items that the threads should process.\r
109 *\r
110 *       lock\r
111 *               Lock used to synchronize access to the item pool and queue.\r
112 *\r
113 * SEE ALSO\r
114 *       Asynchronous Processor\r
115 *********/\r
116 \r
117 \r
118 /*\r
119  * Declare the structure so we can reference it in the following function\r
120  * prototype.\r
121  */\r
122 typedef struct _cl_async_proc_item      *__p_cl_async_proc_item_t;\r
123 \r
124 \r
125 /****d* Component Library: Asynchronous Processor/cl_pfn_async_proc_cb_t\r
126 * NAME\r
127 *       cl_pfn_async_proc_cb_t\r
128 *\r
129 * DESCRIPTION\r
130 *       The cl_pfn_async_proc_cb_t function type defines the prototype for\r
131 *       callbacks queued to and invoked by the asynchronous processor.\r
132 *\r
133 * SYNOPSIS\r
134 */\r
135 typedef void\r
136 (CL_API *cl_pfn_async_proc_cb_t)(\r
137         IN      struct _cl_async_proc_item      *p_item );\r
138 /*\r
139 * PARAMETERS\r
140 *       p_item\r
141 *               Pointer to the cl_async_proc_item_t structure that was queued in\r
142 *               a call to cl_async_proc_queue.\r
143 *\r
144 * NOTES\r
145 *       This function type is provided as function prototype reference for the\r
146 *       function provided by users as a parameter to the cl_async_proc_queue\r
147 *       function.\r
148 *\r
149 * SEE ALSO\r
150 *       Asynchronous Processor, cl_async_proc_item_t\r
151 *********/\r
152 \r
153 \r
154 /****s* Component Library: Asynchronous Processor/cl_async_proc_item_t\r
155 * NAME\r
156 *       cl_async_proc_item_t\r
157 *\r
158 * DESCRIPTION\r
159 *       Asynchronous processor item structure passed to the cl_async_proc_queue\r
160 *       function to queue a callback for execution.\r
161 *\r
162 * SYNOPSIS\r
163 */\r
164 typedef struct _cl_async_proc_item\r
165 {\r
166         cl_pool_item_t                  pool_item;\r
167         cl_pfn_async_proc_cb_t  pfn_callback;\r
168 \r
169 } cl_async_proc_item_t;\r
170 /*\r
171 * FIELDS\r
172 *       pool_item\r
173 *               Pool item for queuing the item to be invoked by the asynchronous\r
174 *               processor's threads.  This field is defined as a pool item to\r
175 *               allow items to be managed by a pool.\r
176 *\r
177 *       pfn_callback\r
178 *               Pointer to a callback function to invoke when the item is dequeued.\r
179 *\r
180 * SEE ALSO\r
181 *       Asynchronous Processor, cl_async_proc_queue, cl_pfn_async_proc_cb_t\r
182 *********/\r
183 \r
184 \r
185 #ifdef __cplusplus\r
186 extern "C"\r
187 {\r
188 #endif\r
189 \r
190 \r
191 /****f* Component Library: Asynchronous Processor/cl_async_proc_construct\r
192 * NAME\r
193 *       cl_async_proc_construct\r
194 *\r
195 * DESCRIPTION\r
196 *       The cl_async_proc_construct function initializes the state of a\r
197 *       thread pool.\r
198 *\r
199 * SYNOPSIS\r
200 */\r
201 CL_EXPORT void CL_API\r
202 cl_async_proc_construct(\r
203         IN      cl_async_proc_t* const  p_async_proc );\r
204 /*\r
205 * PARAMETERS\r
206 *       p_async_proc\r
207 *               [in] Pointer to an asynchronous processor structure.\r
208 *\r
209 * RETURN VALUE\r
210 *       This function does not return a value.\r
211 *\r
212 * NOTES\r
213 *       Allows calling cl_async_proc_destroy without first calling\r
214 *       cl_async_proc_init.\r
215 *\r
216 *       Calling cl_async_proc_construct is a prerequisite to calling any other\r
217 *       thread pool function except cl_async_proc_init.\r
218 *\r
219 * SEE ALSO\r
220 *       Asynchronous Processor, cl_async_proc_init, cl_async_proc_destroy\r
221 *********/\r
222 \r
223 \r
224 /****f* Component Library: Asynchronous Processor/cl_async_proc_init\r
225 * NAME\r
226 *       cl_async_proc_init\r
227 *\r
228 * DESCRIPTION\r
229 *       The cl_async_proc_init function initialized an asynchronous processor\r
230 *       for use.\r
231 *\r
232 * SYNOPSIS\r
233 */\r
234 CL_EXPORT cl_status_t CL_API\r
235 cl_async_proc_init(\r
236         IN      cl_async_proc_t* const  p_async_proc,\r
237         IN      const uint32_t                  thread_count,\r
238         IN      const char* const               name );\r
239 /*\r
240 * PARAMETERS\r
241 *       p_async_proc\r
242 *               [in] Pointer to an asynchronous processor structure to initialize.\r
243 *\r
244 *       thread_count\r
245 *               [in] Number of threads to be managed by the asynchronous processor.\r
246 *\r
247 *       name\r
248 *               [in] Name to associate with the threads.  The name may be up to 16\r
249 *               characters, including a terminating null character.  All threads\r
250 *               created in the asynchronous processor have the same name.\r
251 *\r
252 * RETURN VALUES\r
253 *       CL_SUCCESS if the asynchronous processor creation succeeded.\r
254 *\r
255 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize\r
256 *       the asynchronous processor.\r
257 *\r
258 *       CL_ERROR if the threads could not be created.\r
259 *\r
260 * NOTES\r
261 *       cl_async_proc_init creates and starts the specified number of threads.\r
262 *       If thread_count is zero, the asynchronous processor creates as many\r
263 *       threads as there are processors in the system.\r
264 *\r
265 * SEE ALSO\r
266 *       Asynchronous Processor, cl_async_proc_construct, cl_async_proc_destroy,\r
267 *       cl_async_proc_queue\r
268 *********/\r
269 \r
270 \r
271 /****f* Component Library: Asynchronous Processor/cl_async_proc_destroy\r
272 * NAME\r
273 *       cl_async_proc_destroy\r
274 *\r
275 * DESCRIPTION\r
276 *       The cl_async_proc_destroy function performs any necessary cleanup\r
277 *       for a thread pool.\r
278 *\r
279 * SYNOPSIS\r
280 */\r
281 CL_EXPORT void CL_API\r
282 cl_async_proc_destroy(\r
283         IN      cl_async_proc_t* const  p_async_proc );\r
284 /*\r
285 * PARAMETERS\r
286 *       p_async_proc\r
287 *               [in] Pointer to an asynchronous processor structure to destroy.\r
288 *\r
289 * RETURN VALUE\r
290 *       This function does not return a value.\r
291 *\r
292 * NOTES\r
293 *       This function blocks until all threads exit, and must therefore not\r
294 *       be called from any of the asynchronous processor's threads. Because of\r
295 *       its blocking nature, callers of cl_async_proc_destroy must ensure that\r
296 *       entering a wait state is valid from the calling thread context.\r
297 *\r
298 *       This function should only be called after a call to\r
299 *       cl_async_proc_construct or cl_async_proc_init.\r
300 *\r
301 * SEE ALSO\r
302 *       Asynchronous Processor, cl_async_proc_construct, cl_async_proc_init\r
303 *********/\r
304 \r
305 \r
306 /****f* Component Library: Asynchronous Processor/cl_async_proc_queue\r
307 * NAME\r
308 *       cl_async_proc_queue\r
309 *\r
310 * DESCRIPTION\r
311 *       The cl_async_proc_queue function queues a callback to an asynchronous\r
312 *       processor.\r
313 *\r
314 * SYNOPSIS\r
315 */\r
316 CL_EXPORT void CL_API\r
317 cl_async_proc_queue(\r
318         IN      cl_async_proc_t* const          p_async_proc,\r
319         IN      cl_async_proc_item_t* const     p_item );\r
320 /*\r
321 * PARAMETERS\r
322 *       p_async_proc\r
323 *               [in] Pointer to an asynchronous processor structure to initialize.\r
324 *\r
325 *       p_item\r
326 *               [in] Pointer to an asynchronous processor item to queue for execution.\r
327 *               The callback and context fields of the item must be valid.\r
328 *\r
329 * RETURN VALUES\r
330 *       This function does not return a value.\r
331 *\r
332 * SEE ALSO\r
333 *       Asynchronous Processor, cl_async_proc_init, cl_pfn_async_proc_cb_t\r
334 *********/\r
335 \r
336 \r
337 #ifdef __cplusplus\r
338 }       /* extern "C" */\r
339 #endif\r
340 \r
341 \r
342 #endif  /* !defined(_CL_ASYNC_PROC_H_) */\r