[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_thread.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 abstraction and thread related operations.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_THREAD_H_\r
44 #define _CL_THREAD_H_\r
45 \r
46 \r
47 #include <complib/cl_thread_osd.h>\r
48 \r
49 \r
50 /****i* Component Library/Thread\r
51 * NAME\r
52 *       Thread\r
53 *\r
54 * DESCRIPTION\r
55 *       The Thread provides a separate thread of execution.\r
56 *\r
57 *       The cl_thread_t structure should be treated as opaque and should be\r
58 *       manipulated only through the provided functions.\r
59 *********/\r
60 \r
61 \r
62 /****d* Component Library: Thread/cl_pfn_thread_callback_t\r
63 * NAME\r
64 *       cl_pfn_thread_callback_t\r
65 *\r
66 * DESCRIPTION\r
67 *       The cl_pfn_thread_callback_t function type defines the prototype\r
68 *       for functions invoked by thread objects\r
69 *\r
70 * SYNOPSIS\r
71 */\r
72 typedef void\r
73 (CL_API *cl_pfn_thread_callback_t)(\r
74         IN      void*   context );\r
75 /*\r
76 * PARAMETERS\r
77 *       context\r
78 *               [in] Value specified in a call to cl_thread_init or\r
79 *               cl_thread_pool_create.\r
80 *\r
81 * RETURN VALUE\r
82 *       This function does not return a value.\r
83 *\r
84 * NOTES\r
85 *       This function type is provided as function prototype reference for\r
86 *       the function provided by users as a parameter to the cl_thread_init\r
87 *       and cl_thread_pool_create functions.\r
88 *\r
89 * SEE ALSO\r
90 *       Thread Pool\r
91 *********/\r
92 \r
93 \r
94 /****i* Component Library: Thread/cl_thread_t\r
95 * NAME\r
96 *       cl_thread_t\r
97 *\r
98 * DESCRIPTION\r
99 *       Thread structure.\r
100 *\r
101 *       The cl_thread_t structure should be treated as opaque and should be\r
102 *       manipulated only through the provided functions.\r
103 *\r
104 * SYNOPSIS\r
105 */\r
106 typedef struct _cl_thread\r
107 {\r
108         cl_thread_osd_t                         osd;\r
109         cl_pfn_thread_callback_t        pfn_callback;\r
110         const void                                      *context;\r
111         char                                            name[16];\r
112 \r
113 } cl_thread_t;\r
114 /*\r
115 * FIELDS\r
116 *       osd\r
117 *               Implementation specific structure for managing thread information.\r
118 *\r
119 *       pfn_callback\r
120 *               Callback function for the thread to invoke.\r
121 *\r
122 *       context\r
123 *               Context to pass to the thread callback function.\r
124 *\r
125 *       name\r
126 *               Name to assign to the thread.\r
127 *\r
128 * SEE ALSO\r
129 *       Thread\r
130 *********/\r
131 \r
132 \r
133 #ifdef __cplusplus\r
134 extern "C"\r
135 {\r
136 #endif\r
137 \r
138 \r
139 /****i* Component Library: Thread/cl_thread_construct\r
140 * NAME\r
141 *       cl_thread_construct\r
142 *\r
143 * DESCRIPTION\r
144 *       The cl_thread_construct function initializes the state of a thread.\r
145 *\r
146 * SYNOPSIS\r
147 */\r
148 CL_EXPORT void CL_API\r
149 cl_thread_construct(\r
150         IN      cl_thread_t* const      p_thread );\r
151 /*\r
152 * PARAMETERS\r
153 *       p_thread\r
154 *               [in] Pointer to a cl_thread_t structure whose state to initialize.\r
155 *\r
156 * RETURN VALUE\r
157 *       This function does not return a value.\r
158 *\r
159 * NOTES\r
160 *       Allows calling cl_thread_destroy without first calling cl_thread_init.\r
161 *\r
162 *       Calling cl_thread_construct is a prerequisite to calling any other\r
163 *       thread function except cl_thread_init.\r
164 *\r
165 * SEE ALSO\r
166 *       Thread, cl_thread_init, cl_thread_destroy\r
167 *********/\r
168 \r
169 \r
170 /****i* Component Library: Thread/cl_thread_init\r
171 * NAME\r
172 *       cl_thread_init\r
173 *\r
174 * DESCRIPTION\r
175 *       The cl_thread_init function creates a new thread of execution.\r
176 *\r
177 * SYNOPSIS\r
178 */\r
179 CL_EXPORT cl_status_t CL_API\r
180 cl_thread_init(\r
181         IN      cl_thread_t* const                      p_thread,\r
182         IN      cl_pfn_thread_callback_t        pfn_callback,\r
183         IN      const void* const                       context,\r
184         IN      const char* const                       name );\r
185 /*\r
186 * PARAMETERS\r
187 *       p_thread\r
188 *               [in] Pointer to a cl_thread_t structure to initialize.\r
189 *\r
190 *       pfn_callback\r
191 *               [in] Address of a function to be invoked by a thread.\r
192 *               See the cl_pfn_thread_callback_t function type definition for\r
193 *               details about the callback function.\r
194 *\r
195 *       context\r
196 *               [in] Value to pass to the callback function.\r
197 *\r
198 *       name\r
199 *               [in] Name to associate with the thread.  The name may be up to 16\r
200 *               characters, including a terminating null character.\r
201 *\r
202 * RETURN VALUES\r
203 *       CL_SUCCESS if thread creation succeeded.\r
204 *\r
205 *       CL_ERROR if thread creation failed.\r
206 *\r
207 * NOTES\r
208 *       The thread created with cl_thread_init will invoke the callback\r
209 *       specified by the callback parameter with context as single parameter.\r
210 *\r
211 *       The callback function is invoked once, and the thread exits when the\r
212 *       callback returns.\r
213 *\r
214 *       It is invalid to call cl_thread_destroy from the callback function,\r
215 *       as doing so will result in a deadlock.\r
216 *\r
217 * SEE ALSO\r
218 *       Thread, cl_thread_construct, cl_thread_destroy, cl_thread_suspend,\r
219 *       cl_thread_stall, cl_pfn_thread_callback_t\r
220 *********/\r
221 \r
222 \r
223 /****i* Component Library: Thread/cl_thread_destroy\r
224 * NAME\r
225 *       cl_thread_destroy\r
226 *\r
227 * DESCRIPTION\r
228 *       The cl_thread_destroy function performs any necessary cleanup to free\r
229 *       resources associated with the specified thread.\r
230 *\r
231 * SYNOPSIS\r
232 */\r
233 CL_EXPORT void CL_API\r
234 cl_thread_destroy(\r
235         IN      cl_thread_t* const      p_thread );\r
236 /*\r
237 * PARAMETERS\r
238 *       p_thread\r
239 *               [in] Pointer to a cl_thread_t structure to destroy.\r
240 *\r
241 * RETURN VALUE\r
242 *       This function does not return a value.\r
243 *\r
244 * NOTES\r
245 *       This function blocks until the thread exits and must not be called by the\r
246 *       thread itself.  Callers must therefore ensure that such a blocking call is\r
247 *       possible from the context of the call.\r
248 *\r
249 *       This function must only be called after a call to cl_thread_construct or\r
250 *       cl_thread_init.\r
251 *\r
252 * SEE ALSO\r
253 *       Thread, cl_thread_construct, cl_thread_init\r
254 *********/\r
255 \r
256 \r
257 /****f* Component Library: Thread/cl_thread_suspend\r
258 * NAME\r
259 *       cl_thread_suspend\r
260 *\r
261 * DESCRIPTION\r
262 *       The cl_thread_suspend function suspends the calling thread for a minimum\r
263 *       of the specified number of milliseconds.\r
264 *\r
265 * SYNOPSIS\r
266 */\r
267 CL_EXPORT void CL_API\r
268 cl_thread_suspend(\r
269         IN      const uint32_t  pause_ms );\r
270 /*\r
271 * PARAMETERS\r
272 *       pause_ms\r
273 *               [in] Number of milliseconds to suspend the calling thread.\r
274 *\r
275 * RETURN VALUE\r
276 *       This function does not return a value.\r
277 *\r
278 * NOTES\r
279 *       This function should only be called if it is valid for the caller's thread\r
280 *       to enter a wait state. For stalling a thread that cannot enter a wait\r
281 *       state, callers should use cl_thread_stall.\r
282 *\r
283 * SEE ALSO\r
284 *       Thread, cl_thread_stall\r
285 *********/\r
286 \r
287 \r
288 /****f* Component Library: Thread/cl_thread_stall\r
289 * NAME\r
290 *       cl_thread_stall\r
291 *\r
292 * DESCRIPTION\r
293 *       The cl_thread_stall function stalls the calling thread for a minimum of\r
294 *       the specified number of microseconds.\r
295 *\r
296 * SYNOPSIS\r
297 */\r
298 CL_EXPORT void CL_API\r
299 cl_thread_stall(\r
300         IN      const uint32_t  pause_us );\r
301 /*\r
302 * PARAMETERS\r
303 *       pause_us\r
304 *               [in] Number of microseconds to stall the calling thread.\r
305 *\r
306 * RETURN VALUE\r
307 *       This function does not return a value.\r
308 *\r
309 * NOTES\r
310 *       The cl_thread_stall function performs a busy wait for the specified\r
311 *       number of microseconds. Care should be taken when using this function as\r
312 *       it does not relinquish its quantum of operation. For longer wait\r
313 *       operations, users should call cl_thread_suspend if possible.\r
314 *\r
315 * SEE ALSO\r
316 *       Thread, cl_thread_suspend\r
317 *********/\r
318 \r
319 \r
320 /****f* Component Library: Thread/cl_proc_count\r
321 * NAME\r
322 *       cl_proc_count\r
323 *\r
324 * DESCRIPTION\r
325 *       The cl_proc_count function returns the number of processors in the system.\r
326 *\r
327 * SYNOPSIS\r
328 */\r
329 CL_EXPORT uint32_t CL_API\r
330 cl_proc_count( void );\r
331 /*\r
332 * RETURN VALUE\r
333 *       Returns the number of processors in the system.\r
334 *********/\r
335 \r
336 \r
337 /****i* Component Library: Thread/cl_is_current_thread\r
338 * NAME\r
339 *       cl_is_current_thread\r
340 *\r
341 * DESCRIPTION\r
342 *       The cl_is_current_thread function compares the calling thread to the\r
343 *       specified thread and returns whether they are the same.\r
344 *\r
345 * SYNOPSIS\r
346 */\r
347 CL_EXPORT boolean_t CL_API\r
348 cl_is_current_thread(\r
349         IN      const cl_thread_t* const        p_thread );\r
350 /*\r
351 * PARAMETERS\r
352 *       p_thread\r
353 *               [in] Pointer to a cl_thread_t structure to compare to the\r
354 *               caller's thead.\r
355 *\r
356 * RETURN VALUES\r
357 *       TRUE if the thread specified by the p_thread parameter is the\r
358 *       calling thread.\r
359 *\r
360 *       FALSE otherwise.\r
361 *\r
362 * SEE ALSO\r
363 *       Thread, cl_threadinit_t\r
364 *********/\r
365 \r
366 \r
367 /****f* Component Library: Thread/cl_is_blockable\r
368 * NAME\r
369 *       cl_is_blockable\r
370 *\r
371 * DESCRIPTION\r
372 *       The cl_is_blockable indicates if the current caller context is\r
373 *       blockable.\r
374 *\r
375 * SYNOPSIS\r
376 */\r
377 CL_EXPORT boolean_t CL_API\r
378 cl_is_blockable( void );\r
379 /*\r
380 * RETURN VALUE\r
381 *       TRUE if the caller's thread context can be blocked, i.e it is safe\r
382 *       to perform a sleep, or call a down operation on a semaphore.\r
383 *\r
384 *       FALSE otherwise\r
385 *\r
386 * SEE ALSO\r
387 *       Thread\r
388 *********/\r
389 \r
390 \r
391 #ifdef __cplusplus\r
392 }       /* extern "C" */\r
393 #endif\r
394 \r
395 \r
396 #endif /* _CL_THREAD_H_ */\r