[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_reqmgr.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 asynchronous request manager.  The request manager does\r
37  *      not return resources, only notifies the user when resources are available.\r
38  *\r
39  * Environment:\r
40  *      All\r
41  */\r
42 \r
43 \r
44 #ifndef _CL_REQ_MGR_H_\r
45 #define _CL_REQ_MGR_H_\r
46 \r
47 \r
48 #include <complib/cl_qpool.h>\r
49 \r
50 \r
51 /****h* Component Library/Request Manager\r
52 * NAME\r
53 *       Request Manager\r
54 *\r
55 * DESCRIPTION\r
56 *       The Request Manager manages synchronous as well as asynchronous\r
57 *       requests for objects.\r
58 *\r
59 *       Request manager does not supply the objects, but merely returns whether\r
60 *       objects are available to satisfy requests. This allows users to use\r
61 *       various sources for objects.\r
62 *\r
63 *       While the request manager manages synchronous and asynchronous requests\r
64 *       for objects, it does not itself operate asynchronously. Instead, the\r
65 *       cl_req_mgr_resume function returns information for resuming asynchronous\r
66 *       requests. If a call to cl_req_mgr_resume returns CL_SUCCESS, additional\r
67 *       requests may be able to resume. It is recommended that users flush\r
68 *       pending requests by calling cl_req_mgr_resume while CL_SUCCESS is returned.\r
69 *\r
70 *       The request manager functions operates on a cl_req_mgr_t structure which\r
71 *       should be treated as opaque and should be manipulated only through the\r
72 *       provided functions.\r
73 *\r
74 * SEE ALSO\r
75 *       Types:\r
76 *               cl_req_type_t\r
77 *\r
78 *       Structures:\r
79 *               cl_req_mgr_t\r
80 *\r
81 *       Callbacks:\r
82 *               cl_pfn_req_cb_t, cl_pfn_reqmgr_get_count_t\r
83 *\r
84 *       Initialization/Destruction:\r
85 *               cl_req_mgr_construct, cl_req_mgr_init, cl_req_mgr_destroy\r
86 *\r
87 *       Manipulation:\r
88 *               cl_req_mgr_get, cl_req_mgr_resume\r
89 *\r
90 *       Attributes:\r
91 *               cl_is_req_mgr_inited, cl_req_mgr_count\r
92 *********/\r
93 \r
94 \r
95 /****d* Component Library: Request Manager/cl_pfn_req_cb_t\r
96 * NAME\r
97 *       cl_pfn_req_cb_t\r
98 *\r
99 * DESCRIPTION\r
100 *       The cl_pfn_req_cb_t function type defines the prototype for functions\r
101 *       used to store a function pointer to a user defined function.\r
102 *\r
103 * SYNOPSIS\r
104 */\r
105 typedef void\r
106 (CL_API *cl_pfn_req_cb_t)( void );\r
107 /*\r
108 * PARAMETERS\r
109 *       This function does not take parameters.\r
110 *\r
111 * RETURN VALUE\r
112 *       This function does not return a value.\r
113 *\r
114 * NOTES\r
115 *       Function pointers specified by this parameter do not have to match the\r
116 *       defined syntax, as these callbacks are never invoked directly by the\r
117 *       request manager.  When specifying a function with a different prototype,\r
118 *       cast the function pointer to this type.\r
119 *\r
120 * SEE ALSO\r
121 *       Request Manager, cl_req_mgr_get, cl_req_mgr_resume\r
122 *********/\r
123 \r
124 \r
125 /****d* Component Library: Request Manager/cl_req_type_t\r
126 * NAME\r
127 *       cl_req_type_t\r
128 *\r
129 * DESCRIPTION\r
130 *       The cl_req_type_t enumerated type describes the type of request.\r
131 *\r
132 * SYNOPSIS\r
133 */\r
134 typedef enum _cl_req_type\r
135 {\r
136         REQ_GET_SYNC,\r
137         REQ_GET_ASYNC,\r
138         REQ_GET_PARTIAL_OK\r
139 \r
140 } cl_req_type_t;\r
141 /*\r
142 * VALUES\r
143 *       REQ_GET_SYNC\r
144 *               Synchronous request.\r
145 *\r
146 *       REQ_GET_ASYNC\r
147 *               Asynchronous requests for which all objects are required at once.\r
148 *\r
149 *       REQ_GET_PARTIAL_OK\r
150 *               Asynchronous requests that may be broken into multiple smaller requests.\r
151 *\r
152 * SEE ALSO\r
153 *       Request Manager, cl_req_mgr_get\r
154 *********/\r
155 \r
156 \r
157 /****d* Component Library: Request Manager/cl_pfn_reqmgr_get_count_t\r
158 * NAME\r
159 *       cl_pfn_reqmgr_get_count_t\r
160 *\r
161 * DESCRIPTION\r
162 *       The cl_pfn_reqmgr_get_count_t function type defines the prototype for\r
163 *       functions used to retrieve the number of available objects in a pool.\r
164 *\r
165 * SYNOPSIS\r
166 */\r
167 typedef size_t\r
168 (CL_API *cl_pfn_reqmgr_get_count_t)(\r
169         IN      void*   context );\r
170 /*\r
171 * PARAMETERS\r
172 *       Context\r
173 *               [in] Context provided in a call to cl_req_mgr_init by\r
174 *               the get_context parameter.\r
175 *\r
176 * RETURN VALUE\r
177 *       Returns the number of objects available in an object pool for which\r
178 *       requests are managed by a request manager.\r
179 *\r
180 * NOTES\r
181 *       This function type is provided as function prototype reference for the\r
182 *       function passed into cl_req_mgr_init. This function is invoked by the\r
183 *       request manager when trying to fulfill requests for resources, either\r
184 *       through a call to cl_req_mgr_get or cl_req_mgr_resume.\r
185 *\r
186 * SEE ALSO\r
187 *       Request Manager, cl_req_mgr_init, cl_req_mgr_get, cl_req_mgr_resume\r
188 *********/\r
189 \r
190 \r
191 /****s* Component Library: Request Manager/cl_req_mgr_t\r
192 * NAME\r
193 *       cl_req_mgr_t\r
194 *\r
195 * DESCRIPTION\r
196 *       Quick composite pool structure.\r
197 *\r
198 *       The cl_req_mgr_t structure should be treated as opaque and should be\r
199 *       manipulated only through the provided functions.\r
200 *\r
201 * SYNOPSIS\r
202 */\r
203 typedef struct _cl_req_mgr\r
204 {\r
205         cl_pfn_reqmgr_get_count_t       pfn_get_count;\r
206         const void                                      *get_context;\r
207         cl_qlist_t                                      request_queue;\r
208         cl_qpool_t                                      request_pool;\r
209 \r
210 } cl_req_mgr_t;\r
211 /*\r
212 * FIELDS\r
213 *       pfn_get_count\r
214 *               Pointer to the count callback function.\r
215 *\r
216 *       get_context\r
217 *               Context to pass as single parameter to count callback.\r
218 *\r
219 *       request_queue\r
220 *               Pending requests for elements.\r
221 *\r
222 *       request_pool\r
223 *               Pool of request structures for storing requests in the request queue.\r
224 *\r
225 * SEE ALSO\r
226 *       Request Manager\r
227 *********/\r
228 \r
229 \r
230 #ifdef __cplusplus\r
231 extern "C"\r
232 {\r
233 #endif\r
234 \r
235 \r
236 /****f* Component Library: Request Manager/cl_req_mgr_construct\r
237 * NAME\r
238 *       cl_req_mgr_construct\r
239 *\r
240 * DESCRIPTION\r
241 *       The cl_req_mgr_construct function constructs a request manager.\r
242 *\r
243 * SYNOPSIS\r
244 */\r
245 CL_EXPORT void CL_API\r
246 cl_req_mgr_construct(\r
247         IN      cl_req_mgr_t* const     p_req_mgr );\r
248 /*\r
249 * PARAMETERS\r
250 *       p_req_mgr\r
251 *               [in] Pointer to a cl_req_mgr_t structure to construct.\r
252 *\r
253 * RETURN VALUE\r
254 *       This function does not return a value.\r
255 *\r
256 * NOTES\r
257 *       cl_req_mgr_construct allows calling cl_req_mgr_destroy without first\r
258 *       calling cl_req_mgr_init.\r
259 *\r
260 *       Calling cl_req_mgr_construct is a prerequisite to calling any other\r
261 *       request manager function except cl_req_mgr_init.\r
262 *\r
263 * SEE ALSO\r
264 *       Request Manager, cl_req_mgr_init, cl_req_mgr_destroy\r
265 *********/\r
266 \r
267 \r
268 /****f* Component Library: Request Manager/cl_req_mgr_init\r
269 * NAME\r
270 *       cl_req_mgr_init\r
271 *\r
272 * DESCRIPTION\r
273 *       The cl_req_mgr_init function initializes a request manager for use.\r
274 *\r
275 * SYNOPSIS\r
276 */\r
277 CL_EXPORT cl_status_t CL_API\r
278 cl_req_mgr_init(\r
279         IN      cl_req_mgr_t* const                     p_req_mgr,\r
280         IN      cl_pfn_reqmgr_get_count_t       pfn_get_count,\r
281         IN      const void* const                       get_context );\r
282 /*\r
283 * PARAMETERS\r
284 *       p_req_mgr\r
285 *               [in] Pointer to a cl_req_mgr_t structure to initialize.\r
286 *\r
287 *       pfn_get_count\r
288 *               [in] Callback function invoked by the request manager to get the\r
289 *               number of objects available in a pool of objects for which the\r
290 *               request manager is managing requests.\r
291 *               See the cl_pfn_req_mgr_get_count_t function type declaration for\r
292 *               details about the callback function.\r
293 *\r
294 *       get_context\r
295 *               [in] Context to pass into the function specified by the\r
296 *               pfn_get_count parameter.\r
297 *\r
298 * RETURN VALUES\r
299 *       CL_SUCCESS if the request manager was successfully initialized.\r
300 *\r
301 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize\r
302 *       the request manager.\r
303 *\r
304 * SEE ALSO\r
305 *       Request Manager, cl_req_mgr_construct, cl_req_mgr_destroy, cl_req_mgr_get,\r
306 *       cl_req_mgr_resume, cl_pfn_req_mgr_get_count_t\r
307 *********/\r
308 \r
309 \r
310 /****f* Component Library: Request Manager/cl_req_mgr_destroy\r
311 * NAME\r
312 *       cl_req_mgr_destroy\r
313 *\r
314 * DESCRIPTION\r
315 *       The cl_req_mgr_destroy function destroys a request manager.\r
316 *\r
317 * SYNOPSIS\r
318 */\r
319 CL_EXPORT void CL_API\r
320 cl_req_mgr_destroy(\r
321         IN      cl_req_mgr_t* const     p_req_mgr );\r
322 /*\r
323 * PARAMETERS\r
324 *       p_req_mgr\r
325 *               [in] Pointer to a cl_req_mgr_t structure to destroy.\r
326 *\r
327 * RETURN VALUE\r
328 *       This function does not return a value.\r
329 *\r
330 * NOTES\r
331 *       cl_req_mgr_destroy frees all memory allocated by the request manager.\r
332 *       Further operations on the request manager should not be attempted.\r
333 *\r
334 *       This function should only be called after a call to cl_req_mgr_construct\r
335 *       or cl_req_mgr_init.\r
336 *\r
337 * SEE ALSO\r
338 *       Request Manager, cl_req_mgr_construct, cl_req_mgr_init\r
339 *********/\r
340 \r
341 \r
342 /****f* Component Library: Request Manager/cl_req_mgr_get\r
343 * NAME\r
344 *       cl_req_mgr_get\r
345 *\r
346 * DESCRIPTION\r
347 *       The cl_req_mgr_get function handles synchronous and asynchronous\r
348 *       requests for objects.\r
349 *\r
350 * SYNOPSIS\r
351 */\r
352 CL_EXPORT cl_status_t CL_API\r
353 cl_req_mgr_get(\r
354         IN              cl_req_mgr_t* const     p_req_mgr,\r
355         IN OUT  size_t* const           p_count,\r
356         IN              const cl_req_type_t     req_type,\r
357         IN              cl_pfn_req_cb_t         pfn_callback,\r
358         IN              const void* const       context1,\r
359         IN              const void* const       context2 );\r
360 /*\r
361 * PARAMETERS\r
362 *       p_req_mgr\r
363 *               [in] Pointer to a cl_req_mgr_t structure from which to check\r
364 *               for resources.\r
365 *\r
366 *       p_count\r
367 *               [in/out] On input, contains the number of objects requested.\r
368 *               On output, contains the number of objects available.\r
369 *\r
370 *       req_type\r
371 *               [in] Enumerated type describing the type of request. Valid values are:\r
372 *                       ReqGetSync\r
373 *                               Synchronous request.\r
374 *                       ReqGetAsync\r
375 *                               Asynchronous requests for which all objects are required at\r
376 *                               once.\r
377 *                       ReqGetAsyncPartialOk\r
378 *                               Asynchronous requests that may be broken into multiple smaller\r
379 *                               requests.\r
380 *\r
381 *       pfn_callback\r
382 *               [in] Pointer to a callback function for use by the caller. This\r
383 *               callback function is never invoked by the request manager.\r
384 *\r
385 *       context1\r
386 *               [in] First of two contexts for a resource request.\r
387 *\r
388 *       context2\r
389 *               [in] Second of two contexts for a resource request.\r
390 *\r
391 * RETURN VALUES\r
392 *       CL_SUCCESS if all objects requested are available.\r
393 *\r
394 *       CL_PENDING if the request could not be completed in its entirety.\r
395 *       The p_count parameter contains the number of objects immediately available.\r
396 *\r
397 *       CL_INSUFFICIENT_RESOURCES if the request could not be completed due to\r
398 *       insufficient objects being available.\r
399 *\r
400 *       CL_INSUFFICIENT_MEMORY if the request failed due to a lack of system memory.\r
401 *\r
402 * NOTES\r
403 *       Upon successful completion of this function, the p_count parameter contains\r
404 *       the number of objects available.\r
405 *\r
406 *       Synchronous requests fail if there are any asynchronous requests pending,\r
407 *       or if there are not enough resources to immediately satisfy the request in\r
408 *       its entirety .\r
409 *\r
410 *       Asynchronous requests fail if there is insufficient system memory to\r
411 *       queue them.\r
412 *\r
413 *       Once an asynchronous request is queued, use cl_req_mgr_resume to retrieve\r
414 *       information for resuming queued requests.\r
415 *\r
416 * SEE ALSO\r
417 *       Request Manager, cl_req_mgr_resume\r
418 *********/\r
419 \r
420 \r
421 /****f* Component Library: Request Manager/cl_req_mgr_resume\r
422 * NAME\r
423 *       cl_req_mgr_resume\r
424 *\r
425 * DESCRIPTION\r
426 *       The cl_req_mgr_resume function attempts to resume queued requests.\r
427 *\r
428 * SYNOPSIS\r
429 */\r
430 CL_EXPORT cl_status_t CL_API\r
431 cl_req_mgr_resume(\r
432         IN      cl_req_mgr_t* const             p_req_mgr,\r
433         OUT     size_t* const                   p_count,\r
434         OUT     cl_pfn_req_cb_t* const  ppfn_callback,\r
435         OUT     const void** const              p_context1,\r
436         OUT     const void** const              p_context2 );\r
437 /*\r
438 * PARAMETERS\r
439 *       p_req_mgr\r
440 *               [in] Pointer to a cl_req_mgr_t structure from which to resume requests.\r
441 *\r
442 *       p_count\r
443 *               [out] Contains the number of objects available for a resuming request.\r
444 *\r
445 *       ppfn_callback\r
446 *               [out] Contains the pfn_callback value for the resuming request, as\r
447 *               provided to the call to the cl_req_mgr_get function.\r
448 *\r
449 *       p_context1\r
450 *               [out] Contains the context1 value for the resuming request, as provided\r
451 *               to the call to the cl_req_mgr_get function.\r
452 *\r
453 *       p_context2\r
454 *               [out] Contains the context2 value for the resuming request, as provided\r
455 *               to the call to the cl_req_mgr_get function.\r
456 *\r
457 * RETURN VALUES\r
458 *       CL_SUCCESS if a request was completed.\r
459 *\r
460 *       CL_PENDING if a request was continued, but not completed.\r
461 *\r
462 *       CL_INSUFFICIENT_RESOURCES if a request could not be continued due to\r
463 *       a lack of resources.\r
464 *\r
465 *       CL_NOT_DONE if there were no pending requests.\r
466 *\r
467 * NOTES\r
468 *       cl_req_mgr_resume resumes at most one request. Further requests may be\r
469 *       able to be resumed if this call returns CL_SUCCESS.\r
470 *\r
471 * SEE ALSO\r
472 *       Request Manager, cl_req_mgr_get\r
473 *********/\r
474 \r
475 \r
476 #ifdef __cplusplus\r
477 }\r
478 #endif\r
479 \r
480 \r
481 #endif  /* _CL_REQ_MGR_H_ */\r