[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_syscallback.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  *      System Callback abstractions.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_SYS_CALLBACK_H_\r
44 #define _CL_SYS_CALLBACK_H_\r
45 \r
46 \r
47 #include <complib/cl_types.h>\r
48 \r
49 /****h* Component Library/System Callback\r
50 * NAME\r
51 *       System Callback\r
52 *\r
53 * DESCRIPTION\r
54 *       The System Callback provider uses threads from a system thread-pool to\r
55 *       invoke specified callback functions.\r
56 *\r
57 *       Callbacks can be queued in a low- or high-priority queue for processing.\r
58 *\r
59 *       cl_thread_suspend and cl_thread_stall can be used to delay or stall the\r
60 *       callback thread.\r
61 *\r
62 *       Environments that do not have a native system thread-pool emulate this\r
63 *       functionality to provide cross-environment support.\r
64 *\r
65 *       The cl_sys_callback_item_t structure should be treated as opaque and be\r
66 *       manipulated only through the provided functions.\r
67 *********/\r
68 \r
69 \r
70 /****d* Component Library: System Callback/cl_pfn_sys_callback_t\r
71 * NAME\r
72 *       cl_pfn_sys_callback_t\r
73 *\r
74 * DESCRIPTION\r
75 *       The cl_pfn_sys_callback_t function type defines the prototype for\r
76 *       functions invoked by the system callback provider.\r
77 *\r
78 * SYNOPSIS\r
79 */\r
80 typedef void\r
81 (CL_API *cl_pfn_sys_callback_t)(\r
82         IN      void*   get_context,\r
83         IN      void*   queue_context );\r
84 /*\r
85 * PARAMETERS\r
86 *       get_context\r
87 *               [in] Value of the get_context parameter specified in a call\r
88 *               to cl_sys_callback_get.\r
89 *\r
90 *       queue_context\r
91 *               [in] Value of the queue_context parameter specified in a call\r
92 *               to cl_sys_callback_queue.\r
93 *\r
94 * RETURN VALUE\r
95 *       This function does not return a value.\r
96 *\r
97 * NOTES\r
98 *       This function type is provided as function prototype reference for\r
99 *       the function provided by users as a parameter to the\r
100 *       cl_sys_callback_queue function.\r
101 *\r
102 * SEE ALSO\r
103 *       System Callback, cl_sys_callback_queue\r
104 *********/\r
105 \r
106 \r
107 /* Include platform specific system callback support. */\r
108 #include <complib/cl_syscallback_osd.h>\r
109 \r
110 \r
111 #ifdef __cplusplus\r
112 extern "C"\r
113 {\r
114 #endif\r
115 \r
116 \r
117 /****i* Component Library: System Callback/cl_sys_callback_construct\r
118 * NAME\r
119 *       cl_sys_callback_construct\r
120 *\r
121 * DESCRIPTION\r
122 *       The cl_sys_callback_construct function is called to initialize the state\r
123 *       of the system callback provider.\r
124 *\r
125 * SYNOPSIS\r
126 */\r
127 void\r
128 __cl_sys_callback_construct( void );\r
129 /*\r
130 * RETURN VALUE\r
131 *       This function does not return a value.\r
132 *\r
133 * NOTES\r
134 *       This function is called internally when initializing the component\r
135 *       library for use.  Users should never call this function directly.\r
136 *\r
137 *       Calling cl_sys_callback_construct is a prerequisite to calling any other\r
138 *       system callback function.\r
139 *\r
140 *       Allows calling cl_sys_callback_init, cl_sys_callback_destroy, and\r
141 *       cl_is_sys_callback_inited.\r
142 *\r
143 * SEE ALSO\r
144 *       System Callback, cl_sys_callback_init, cl_sys_callback_destroy,\r
145 *       cl_is_sys_callback_inited\r
146 *********/\r
147 \r
148 \r
149 /****f* Component Library: System Callback/cl_is_sys_callback_inited\r
150 * NAME\r
151 *       cl_is_sys_callback_inited\r
152 *\r
153 * DESCRIPTION\r
154 *       The cl_is_sys_callback_inited function returns whether the system\r
155 *       callback provider was initialized successfully\r
156 *\r
157 * SYNOPSIS\r
158 */\r
159 boolean_t\r
160 __cl_is_sys_callback_inited( void );\r
161 /*\r
162 * RETURN VALUES\r
163 *       TRUE if the system callback provider was initialized successfully.\r
164 *\r
165 *       FALSE otherwise.\r
166 *\r
167 * NOTES\r
168 *       Allows checking the state of the system callback provider to determine\r
169 *       if invoking member functions is appropriate.\r
170 *\r
171 * SEE ALSO\r
172 *       System Callback\r
173 *********/\r
174 \r
175 \r
176 /****i* Component Library: System Callback/cl_sys_callback_init\r
177 * NAME\r
178 *       cl_sys_callback_init\r
179 *\r
180 * DESCRIPTION\r
181 *       The cl_sys_callback_init function is called to initialize the system\r
182 *       callback provider.\r
183 *\r
184 * SYNOPSIS\r
185 */\r
186 cl_status_t\r
187 __cl_sys_callback_init( void );\r
188 /*\r
189 * RETURN VALUES\r
190 *       CL_SUCCESS if the system callback provider was initialized successfully.\r
191 *\r
192 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize\r
193 *       the system callback provider.\r
194 *\r
195 *       CL_ERROR if the system callback provider's threads could not be created.\r
196 *\r
197 * NOTES\r
198 *       This function is called internally when initializing the component\r
199 *       library for use.  Users should never call this function directly.\r
200 *\r
201 * SEE ALSO\r
202 *       System Callback, cl_sys_callback_construct, cl_sys_callback_destroy\r
203 *********/\r
204 \r
205 \r
206 /****i* Component Library: System Callback/cl_sys_callback_destroy\r
207 * NAME\r
208 *       cl_sys_callback_destroy\r
209 *\r
210 * DESCRIPTION\r
211 *       The cl_sys_callback_destroy function is called to destroy the system\r
212 *       callback provider.\r
213 *\r
214 * SYNOPSIS\r
215 */\r
216 void\r
217 __cl_sys_callback_destroy( void );\r
218 /*\r
219 * RETURN VALUE\r
220 *       This function does not return a value.\r
221 *\r
222 * NOTES\r
223 *       This function is called internally when destroying the component\r
224 *       library after use.  Users should never call this function directly.\r
225 *\r
226 *       All threads and resources allocated by the system callback provider\r
227 *       are freed.\r
228 *\r
229 *       This function should only be called after calling either\r
230 *       cl_sys_callback_construct or cl_sys_callback_construct.\r
231 *\r
232 * SEE ALSO\r
233 *       System Callback, cl_sys_callback_construct, cl_sys_callback_construct\r
234 *********/\r
235 \r
236 \r
237 /****f* Component Library: System Callback/cl_sys_callback_get\r
238 * NAME\r
239 *       cl_sys_callback_get\r
240 *\r
241 * DESCRIPTION\r
242 *       The cl_sys_callback_get function retrieves a system callback item.\r
243 *\r
244 * SYNOPSIS\r
245 */\r
246 CL_EXPORT cl_sys_callback_item_t* CL_API\r
247 cl_sys_callback_get(\r
248         IN      const void* const get_context );\r
249 /*\r
250 * PARAMETERS\r
251 *       get_context\r
252 *               [in] Context value to pass into the callback function.\r
253 *\r
254 * RETURN VALUES\r
255 *       Returns a pointer to a system callback item if successful.\r
256 *\r
257 *       Returns NULL if the call fails.\r
258 *\r
259 * NOTES\r
260 *       A system callback item must be released with a call to cl_sys_callback_put.\r
261 *\r
262 *       Care must be taken to prevent a system callback item from being returned\r
263 *       to the pool while it is queued. Callers of cl_sys_callback_queue must not\r
264 *       return the system callback item to the pool until their callback has been\r
265 *       invoked.\r
266 *\r
267 *       In Windows 2000 Kernel Mode, the get_context is a pointer to the device\r
268 *       object for which the system callback is being used.\r
269 *\r
270 * SEE ALSO\r
271 *       System Callback, SysCallbackPut, SysCallbackQueue\r
272 *********/\r
273 \r
274 \r
275 /****f* Component Library: System Callback/cl_sys_callback_put\r
276 * NAME\r
277 *       cl_sys_callback_put\r
278 *\r
279 * DESCRIPTION\r
280 *       The cl_sys_callback_put function releases the specified\r
281 *       system callback item.\r
282 *\r
283 * SYNOPSIS\r
284 */\r
285 CL_EXPORT void CL_API\r
286 cl_sys_callback_put(\r
287         IN      cl_sys_callback_item_t* const   p_item );\r
288 /*\r
289 * PARAMETERS\r
290 *       p_item\r
291 *               [in] Pointer to a system callback item to release.\r
292 *\r
293 * RETURN VALUE\r
294 *       This function does not return a value.\r
295 *\r
296 * NOTES\r
297 *       The p_item parameter points to a system callback item returned by\r
298 *       a previous call to cl_sys_callback_get.\r
299 *\r
300 *       The specified system callback item must not be queued when making\r
301 *       a call to this function.  This function can, however, be called\r
302 *       from the callback function.\r
303 *\r
304 * SEE ALSO\r
305 *       System Callback, cl_sys_callback_get, cl_sys_callback_queue\r
306 *********/\r
307 \r
308 \r
309 /****f* Component Library: System Callback/cl_sys_callback_queue\r
310 * NAME\r
311 *       cl_sys_callback_queue\r
312 *\r
313 * DESCRIPTION\r
314 *       The cl_sys_callback_queue function queues the specified system callback item\r
315 *       for execution.\r
316 *\r
317 * SYNOPSIS\r
318 */\r
319 CL_EXPORT cl_status_t CL_API\r
320 cl_sys_callback_queue(\r
321         IN      cl_sys_callback_item_t* const   p_item,\r
322         IN      cl_pfn_sys_callback_t                   pfn_callback,\r
323         IN      const void* const                               queue_context,\r
324         IN      const boolean_t                                 high_priority );\r
325 /*\r
326 * PARAMETERS\r
327 *       p_item\r
328 *               [in] Pointer to a system callback item.\r
329 *\r
330 *       pfn_callback\r
331 *               [in] Pointer to a function to be invoked by the system callback module.\r
332 *               See the cl_pfn_sys_callback_t function type definition for details\r
333 *               about the callback function.\r
334 *\r
335 *       queue_context\r
336 *               [in] Value passed to the system callback function.\r
337 *\r
338 *       high_priority\r
339 *               [in] Specifies whether the request should be queued in the high- or\r
340 *               low-priority queue.\r
341 *\r
342 * RETURN VALUES\r
343 *       CL_SUCCESS if the system callback item was successfully queued.\r
344 *\r
345 *       CL_ERROR otherwise.\r
346 *\r
347 * NOTES\r
348 *       A thread from the system thread pool will invoke the specified callback\r
349 *       function with the get_context value specified in the call to\r
350 *       cl_sys_callback_get and the specified context as parameters.\r
351 *\r
352 *       The high priority queue is processed before the low priority queue. There\r
353 *       is no fairness algorithm implemented for removing items from the queues.\r
354 *\r
355 *       Care should be taken to only queue a given system callback item once\r
356 *       at a time.\r
357 *\r
358 * SEE ALSO\r
359 *       System Callback, cl_sys_callback_get, cl_pfn_sys_callback_t\r
360 *********/\r
361 \r
362 \r
363 #ifdef __cplusplus\r
364 }       /* extern "C" */\r
365 #endif\r
366 \r
367 \r
368 #endif  /* _CL_SYS_CALLBACK_H_ */\r