[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_qcomppool.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 quick composite pool.  The quick composite pool\r
37  *      manages a pool of composite objects.  A composite object is an object\r
38  *      that is made of multiple sub objects.\r
39  *      It can grow to meet demand, limited only by system memory.\r
40  *\r
41  * Environment:\r
42  *      All\r
43  */\r
44 \r
45 \r
46 #ifndef _CL_QUICK_COMPOSITE_POOL_H_\r
47 #define _CL_QUICK_COMPOSITE_POOL_H_\r
48 \r
49 \r
50 #include <complib/cl_types.h>\r
51 #include <complib/cl_qlist.h>\r
52 \r
53 \r
54 /****h* Component Library/Quick Composite Pool\r
55 * NAME\r
56 *       Quick Composite Pool\r
57 *\r
58 * DESCRIPTION\r
59 *       The Quick Composite Pool provides a self-contained and self-sustaining\r
60 *       pool of user defined composite objects.\r
61 *\r
62 *       A composite object is an object that is composed of one or more\r
63 *       sub-objects, each of which needs to be treated separately for\r
64 *       initialization. Objects can be retrieved from the pool as long as there\r
65 *       is memory in the system.\r
66 *\r
67 *       To aid in object oriented design, the Quick Composite Pool provides users\r
68 *       the ability to specify callbacks that are invoked for each object for\r
69 *       construction, initialization, and destruction. Constructor and destructor\r
70 *       callback functions may not fail.\r
71 *\r
72 *       A Quick Composite Pool does not return memory to the system as the user\r
73 *       returns objects to the pool. The only method of returning memory to the\r
74 *       system is to destroy the pool.\r
75 *\r
76 *       The Quick Composite Pool operates on cl_pool_item_t structures that\r
77 *       describe composite objects. This provides for more efficient memory use.\r
78 *       If using a cl_pool_item_t is not desired, the Composite Pool provides\r
79 *       similar functionality but operates on opaque objects.\r
80 *\r
81 *       The Quick Composit Pool functions operate on a cl_qcpool_t structure\r
82 *       which should be treated as opaque and should be manipulated only through\r
83 *       the provided functions.\r
84 *\r
85 * SEE ALSO\r
86 *       Structures:\r
87 *               cl_qcpool_t, cl_pool_item_t\r
88 *\r
89 *       Callbacks:\r
90 *               cl_pfn_qcpool_init_t, cl_pfn_qcpool_dtor_t\r
91 *\r
92 *       Initialization/Destruction:\r
93 *               cl_qcpool_construct, cl_qcpool_init, cl_qcpool_destroy\r
94 *\r
95 *       Manipulation:\r
96 *               cl_qcpool_get, cl_qcpool_put, cl_qcpool_put_list, cl_qcpool_grow\r
97 *\r
98 *       Attributes:\r
99 *               cl_is_qcpool_inited, cl_qcpool_count\r
100 *********/\r
101 \r
102 \r
103 /****s* Component Library: Quick Composite Pool/cl_pool_item_t\r
104 * NAME\r
105 *       cl_pool_item_t\r
106 *\r
107 * DESCRIPTION\r
108 *       The cl_pool_item_t structure is used by pools to store objects.\r
109 *\r
110 * SYNOPSIS\r
111 */\r
112 typedef struct _cl_pool_item\r
113 {\r
114         cl_list_item_t          list_item;\r
115 #ifdef _DEBUG_\r
116         /* Pad to make the cl_pool_obj structure line up properly */\r
117         void                            *pad;\r
118         /* Pointer to the owner pool used for sanity checks. */\r
119         struct _cl_qcpool       *p_pool;\r
120 #endif\r
121 \r
122 } cl_pool_item_t;\r
123 /*\r
124 * FIELDS\r
125 *       list_item\r
126 *               Used internally by the pool. Users should not use this field.\r
127 *\r
128 *       p_pool\r
129 *               Used internally by the pool in debug builds to check for consistency.\r
130 *\r
131 * NOTES\r
132 *       The pool item structure is defined in such a way as to safely allow\r
133 *       users to cast from a pool item to a list item for storing items\r
134 *       retrieved from a quick pool in a quick list.\r
135 *\r
136 * SEE ALSO\r
137 *       Quick Composite Pool, cl_list_item_t\r
138 *********/\r
139 \r
140 \r
141 /****i* Component Library: Quick List/cl_pool_obj_t\r
142 * NAME\r
143 *       cl_pool_obj_t\r
144 *\r
145 * DESCRIPTION\r
146 *       The cl_pool_obj_t structure is used by pools to store objects.\r
147 *\r
148 * SYNOPSIS\r
149 */\r
150 typedef struct _cl_pool_obj\r
151 {\r
152         /* The pool item must be the first item to allow casting. */\r
153         cl_list_obj_t           list_obj;\r
154 #ifdef _DEBUG_\r
155         /* Pointer to the owner pool used for sanity checks. */\r
156         struct _cl_qcpool       *p_pool;\r
157 #endif\r
158 \r
159 } cl_pool_obj_t;\r
160 /*\r
161 * FIELDS\r
162 *       pool_item\r
163 *               Used internally by the pool. Users should not use this field.\r
164 *\r
165 *       p_object\r
166 *               Pointer to the user's object being stored in the pool.\r
167 *\r
168 * NOTES\r
169 *       The pool object structure is used by non-quick pools to store object.\r
170 *\r
171 * SEE ALSO\r
172 *       cl_pool_item_t\r
173 *********/\r
174 \r
175 \r
176 /****d* Component Library: Quick Composite Pool/cl_pfn_qcpool_init_t\r
177 * NAME\r
178 *       cl_pfn_qcpool_init_t\r
179 *\r
180 * DESCRIPTION\r
181 *       The cl_pfn_qcpool_init_t function type defines the prototype for\r
182 *       functions used as initializer for objects being allocated by a\r
183 *       quick composite pool.\r
184 *\r
185 * SYNOPSIS\r
186 */\r
187 typedef cl_status_t\r
188 (CL_API *cl_pfn_qcpool_init_t)(\r
189         IN      void** const                    p_comp_array,\r
190         IN      const uint32_t                  num_components,\r
191         IN      void*                                   context,\r
192         OUT     cl_pool_item_t** const  pp_pool_item );\r
193 /*\r
194 * PARAMETERS\r
195 *       p_comp_array\r
196 *               [in] Pointer to the first entry in an array of pointers, each of\r
197 *               which points to a component that makes up a composite object.\r
198 *\r
199 *       num_components\r
200 *               [in] Number of components that in the component array.\r
201 *\r
202 *       context\r
203 *               [in] Context provided in a call to cl_qcpool_init.\r
204 *\r
205 *       pp_pool_item\r
206 *               [out] Users should set this pointer to reference the cl_pool_item_t\r
207 *               structure that represents the composite object.  This pointer must\r
208 *               not be NULL if the function returns CL_SUCCESS.\r
209 *\r
210 * RETURN VALUE\r
211 *       Return CL_SUCCESS to indicate that initialization of the object\r
212 *       was successful and that initialization of further objects may continue.\r
213 *\r
214 *       Other cl_status_t values will be returned by cl_qcpool_init\r
215 *       and cl_qcpool_grow.\r
216 *\r
217 * NOTES\r
218 *       This function type is provided as function prototype reference for\r
219 *       the function provided by the user as a parameter to the\r
220 *       cl_qcpool_init function.\r
221 *\r
222 *       The initializer is invoked once per allocated object, allowing the user\r
223 *       to chain components to form a composite object and perform any necessary\r
224 *       initialization.  Returning a status other than CL_SUCCESS aborts a grow\r
225 *       operation, initiated either through cl_qcpool_init or cl_qcpool_grow,\r
226 *       and causes the initiating function to fail.  Any non-CL_SUCCESS status\r
227 *       will be returned by the function that initiated the grow operation.\r
228 *\r
229 *       All memory for the requested number of components is pre-allocated.  Users\r
230 *       should include space in one of their components for the cl_pool_item_t\r
231 *       structure that will represent the composite object to avoid having to\r
232 *       allocate that structure in the initialization callback.  Alternatively,\r
233 *       users may specify an additional component for the cl_pool_item_t structure.\r
234 *\r
235 *       When later performing a cl_qcpool_get call, the return value is a pointer\r
236 *       to the cl_pool_item_t returned by this function in the pp_pool_item\r
237 *       parameter. Users must set pp_pool_item to a valid pointer to the\r
238 *       cl_pool_item_t representing the object if they return CL_SUCCESS.\r
239 *\r
240 * SEE ALSO\r
241 *       Quick Composite Pool, cl_qcpool_init\r
242 *********/\r
243 \r
244 \r
245 /****d* Component Library: Quick Composite Pool/cl_pfn_qcpool_dtor_t\r
246 * NAME\r
247 *       cl_pfn_qcpool_dtor_t\r
248 *\r
249 * DESCRIPTION\r
250 *       The cl_pfn_qcpool_dtor_t function type defines the prototype for\r
251 *       functions used as destructor for objects being deallocated by a\r
252 *       quick composite pool.\r
253 *\r
254 * SYNOPSIS\r
255 */\r
256 typedef void\r
257 (CL_API *cl_pfn_qcpool_dtor_t)(\r
258         IN      const cl_pool_item_t* const     p_pool_item,\r
259         IN      void*                                           context );\r
260 /*\r
261 * PARAMETERS\r
262 *       p_pool_item\r
263 *               [in] Pointer to a cl_pool_item_t structure representing an object.\r
264 *\r
265 *       context\r
266 *               [in] Context provided in a call to cl_qcpool_init.\r
267 *\r
268 * RETURN VALUE\r
269 *       This function does not return a value.\r
270 *\r
271 * NOTES\r
272 *       This function type is provided as function prototype reference for\r
273 *       the function provided by the user as an optional parameter to the\r
274 *       cl_qcpool_init function.\r
275 *\r
276 *       The destructor is invoked once per allocated object, allowing the user\r
277 *       to perform any necessary cleanup. Users should not attempt to deallocate\r
278 *       the memory for the composite object, as the quick composite pool manages\r
279 *       object allocation and deallocation.\r
280 *\r
281 * SEE ALSO\r
282 *       Quick Composite Pool, cl_qcpool_init\r
283 *********/\r
284 \r
285 \r
286 /****s* Component Library: Quick Composite Pool/cl_qcpool_t\r
287 * NAME\r
288 *       cl_qcpool_t\r
289 *\r
290 * DESCRIPTION\r
291 *       Quick composite pool structure.\r
292 *\r
293 *       The cl_qcpool_t structure should be treated as opaque and should be\r
294 *       manipulated only through the provided functions.\r
295 *\r
296 * SYNOPSIS\r
297 */\r
298 typedef struct _cl_qcpool\r
299 {\r
300         uint32_t                                num_components;\r
301         size_t                                  *component_sizes;\r
302         void                                    **p_components;\r
303         size_t                                  num_objects;\r
304         size_t                                  max_objects;\r
305         size_t                                  grow_size;\r
306         cl_pfn_qcpool_init_t    pfn_init;\r
307         cl_pfn_qcpool_dtor_t    pfn_dtor;\r
308         const void                              *context;\r
309         cl_qlist_t                              free_list;\r
310         cl_qlist_t                              alloc_list;\r
311         cl_state_t                              state;\r
312 \r
313 } cl_qcpool_t;\r
314 /*\r
315 * FIELDS\r
316 *       num_components\r
317 *               Number of components per object.\r
318 *\r
319 *       component_sizes\r
320 *               Array of sizes, one for each component.\r
321 *\r
322 *       p_components\r
323 *               Array of pointers to components, used for the constructor callback.\r
324 *\r
325 *       num_objects\r
326 *               Number of objects managed by the pool\r
327 *\r
328 *       grow_size\r
329 *               Number of objects to add when automatically growing the pool.\r
330 *\r
331 *       pfn_init\r
332 *               Pointer to the user's initializer callback to invoke when initializing\r
333 *               new objects.\r
334 *\r
335 *       pfn_dtor\r
336 *               Pointer to the user's destructor callback to invoke before deallocating\r
337 *               memory allocated for objects.\r
338 *\r
339 *       context\r
340 *               User's provided context for callback functions, used by the pool\r
341 *               when invoking callbacks.\r
342 *\r
343 *       free_list\r
344 *               Quick list of objects available.\r
345 *\r
346 *       alloc_list\r
347 *               Quick list used to store information about allocations.\r
348 *\r
349 *       state\r
350 *               State of the pool.\r
351 *\r
352 * SEE ALSO\r
353 *       Quick Composite Pool\r
354 *********/\r
355 \r
356 \r
357 \r
358 #ifdef __cplusplus\r
359 extern "C"\r
360 {\r
361 #endif  /* __cplusplus */\r
362 \r
363 \r
364 /****f* Component Library: Quick Composite Pool/cl_qcpool_construct\r
365 * NAME\r
366 *       cl_qcpool_construct\r
367 *\r
368 * DESCRIPTION\r
369 *       The cl_qcpool_construct function constructs a quick composite pool.\r
370 *\r
371 * SYNOPSIS\r
372 */\r
373 CL_EXPORT void CL_API\r
374 cl_qcpool_construct(\r
375         IN      cl_qcpool_t* const      p_pool );\r
376 /*\r
377 * PARAMETERS\r
378 *       p_pool\r
379 *               [in] Pointer to a cl_qcpool_t structure whose state to initialize.\r
380 *\r
381 * RETURN VALUE\r
382 *       This function does not return a value.\r
383 *\r
384 * NOTES\r
385 *       Allows calling cl_qcpool_init, cl_qcpool_destroy, cl_is_qcpool_inited.\r
386 *\r
387 *       Calling cl_qcpool_construct is a prerequisite to calling any other\r
388 *       quick composite pool function except cl_qcpool_init.\r
389 *\r
390 * SEE ALSO\r
391 *       Quick Composite Pool, cl_qcpool_init, cl_qcpool_destroy,\r
392 *       cl_is_qcpool_inited\r
393 *********/\r
394 \r
395 \r
396 /****f* Component Library: Quick Composite Pool/cl_is_qcpool_inited\r
397 * NAME\r
398 *       cl_is_qcpool_inited\r
399 *\r
400 * DESCRIPTION\r
401 *       The cl_is_qcpool_inited function returns whether a quick composite pool was\r
402 *       successfully initialized.\r
403 *\r
404 * SYNOPSIS\r
405 */\r
406 CL_INLINE uint32_t CL_API\r
407 cl_is_qcpool_inited(\r
408         IN      const cl_qcpool_t* const        p_pool )\r
409 {\r
410         /* CL_ASSERT that a non-null pointer is provided. */\r
411         CL_ASSERT( p_pool );\r
412         /* CL_ASSERT that the pool is not in some invalid state. */\r
413         CL_ASSERT( cl_is_state_valid( p_pool->state ) );\r
414 \r
415         return( p_pool->state == CL_INITIALIZED );\r
416 }\r
417 /*\r
418 * PARAMETERS\r
419 *       p_pool\r
420 *               [in] Pointer to a cl_qcpool_t structure to check.\r
421 *\r
422 * RETURN VALUES\r
423 *       TRUE if the quick composite pool was initialized successfully.\r
424 *\r
425 *       FALSE otherwise.\r
426 *\r
427 * NOTES\r
428 *       Allows checking the state of a quick composite pool to determine if\r
429 *       invoking member functions is appropriate.\r
430 *\r
431 * SEE ALSO\r
432 *       Quick Composite Pool\r
433 *********/\r
434 \r
435 \r
436 /****f* Component Library: Quick Composite Pool/cl_qcpool_init\r
437 * NAME\r
438 *       cl_qcpool_init\r
439 *\r
440 * DESCRIPTION\r
441 *       The cl_qcpool_init function initializes a quick composite pool for use.\r
442 *\r
443 * SYNOPSIS\r
444 */\r
445 CL_EXPORT cl_status_t CL_API\r
446 cl_qcpool_init(\r
447         IN      cl_qcpool_t* const              p_pool,\r
448         IN      const size_t                    min_size,\r
449         IN      const size_t                    max_size,\r
450         IN      const size_t                    grow_size,\r
451         IN      const size_t* const             component_sizes,\r
452         IN      const uint32_t                  num_components,\r
453         IN      cl_pfn_qcpool_init_t    pfn_initializer OPTIONAL,\r
454         IN      cl_pfn_qcpool_dtor_t    pfn_destructor OPTIONAL,\r
455         IN      const void* const               context );\r
456 /*\r
457 * PARAMETERS\r
458 *       p_pool\r
459 *               [in] Pointer to a cl_qcpool_t structure to initialize.\r
460 *\r
461 *       min_size\r
462 *               [in] Minimum number of objects that the pool should support. All\r
463 *               necessary allocations to allow storing the minimum number of items\r
464 *               are performed at initialization time, and all necessary callbacks\r
465 *               successfully invoked.\r
466 *\r
467 *       max_size\r
468 *               [in] Maximum number of objects to which the pool is allowed to grow.\r
469 *               A value of zero specifies no maximum.\r
470 *\r
471 *       grow_size\r
472 *               [in] Number of objects to allocate when incrementally growing the pool.\r
473 *               A value of zero disables automatic growth.\r
474 *\r
475 *       component_sizes\r
476 *               [in] Pointer to the first entry in an array of sizes describing,\r
477 *               in order, the sizes of the components that make up a composite object.\r
478 *\r
479 *       num_components\r
480 *               [in] Number of components that make up a composite object.\r
481 *\r
482 *       pfn_initializer\r
483 *               [in] Initializer callback to invoke for every new object when growing\r
484 *               the pool. This parameter may be NULL only if the objects stored in\r
485 *               the quick composite pool consist of only one component. If NULL, the\r
486 *               pool assumes the cl_pool_item_t structure describing objects is\r
487 *               located at the head of each object. See the cl_pfn_qcpool_init_t\r
488 *               function type declaration for details about the callback function.\r
489 *\r
490 *       pfn_destructor\r
491 *               [in] Destructor callback to invoke for every object before memory for\r
492 *               that object is freed. This parameter is optional and may be NULL.\r
493 *               See the cl_pfn_qcpool_dtor_t function type declaration for details\r
494 *               about the callback function.\r
495 *\r
496 *       context\r
497 *               [in] Value to pass to the callback functions to provide context.\r
498 *\r
499 * RETURN VALUES\r
500 *       CL_SUCCESS if the quick composite pool was initialized successfully.\r
501 *\r
502 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize the\r
503 *       quick composite pool.\r
504 *\r
505 *       CL_INVALID_SETTING if a NULL constructor was provided for composite objects\r
506 *       consisting of more than one component.  Also returns CL_INVALID_SETTING if\r
507 *       the maximum size is non-zero and less than the minimum size.\r
508 *\r
509 *       Other cl_status_t value returned by optional initialization callback function\r
510 *       specified by the pfn_initializer parameter.\r
511 *\r
512 *       If initialization fails, the pool is left in a destroyed state.  Callers\r
513 *       may still safely call cl_qcpool_destroy.\r
514 *\r
515 * NOTES\r
516 *       cl_qcpool_init initializes, and if necessary, grows the pool to\r
517 *       the capacity desired.\r
518 *\r
519 * SEE ALSO\r
520 *       Quick Composite Pool, cl_qcpool_construct, cl_qcpool_destroy,\r
521 *       cl_qcpool_get, cl_qcpool_put, cl_qcpool_grow,\r
522 *       cl_qcpool_count, cl_pfn_qcpool_init_t, cl_pfn_qcpool_dtor_t\r
523 *********/\r
524 \r
525 \r
526 /****f* Component Library: Quick Composite Pool/cl_qcpool_destroy\r
527 * NAME\r
528 *       cl_qcpool_destroy\r
529 *\r
530 * DESCRIPTION\r
531 *       The cl_qcpool_destroy function destroys a quick composite pool.\r
532 *\r
533 * SYNOPSIS\r
534 */\r
535 CL_EXPORT void CL_API\r
536 cl_qcpool_destroy(\r
537         IN      cl_qcpool_t* const      p_pool );\r
538 /*\r
539 * PARAMETERS\r
540 *       p_pool\r
541 *               [in] Pointer to a cl_qcpool_t structure to destroy.\r
542 *\r
543 * RETURN VALUE\r
544 *       This function does not return a value.\r
545 *\r
546 * NOTES\r
547 *       All memory allocated for composite objects is freed. The destructor\r
548 *       callback, if any, will be invoked for every allocated object. Further\r
549 *       operations on the composite pool should not be attempted after\r
550 *       cl_qcpool_destroy is invoked.\r
551 *\r
552 *       This function should only be called after a call to\r
553 *       cl_qcpool_construct or cl_qcpool_init.\r
554 *\r
555 *       In a debug build, cl_qcpool_destroy asserts that all objects are in\r
556 *       the pool.\r
557 *\r
558 * SEE ALSO\r
559 *       Quick Composite Pool, cl_qcpool_construct, cl_qcpool_init\r
560 *********/\r
561 \r
562 \r
563 /****f* Component Library: Quick Composite Pool/cl_qcpool_count\r
564 * NAME\r
565 *       cl_qcpool_count\r
566 *\r
567 * DESCRIPTION\r
568 *       The cl_qcpool_count function returns the number of available objects\r
569 *       in a quick composite pool.\r
570 *\r
571 * SYNOPSIS\r
572 */\r
573 CL_INLINE size_t CL_API\r
574 cl_qcpool_count(\r
575         IN      cl_qcpool_t* const      p_pool )\r
576 {\r
577         CL_ASSERT( p_pool );\r
578         CL_ASSERT( p_pool->state == CL_INITIALIZED );\r
579 \r
580         return( cl_qlist_count( &p_pool->free_list ) );\r
581 }\r
582 /*\r
583 * PARAMETERS\r
584 *       p_pool\r
585 *               [in] Pointer to a cl_qcpool_t structure for which the number of\r
586 *               available objects is requested.\r
587 *\r
588 * RETURN VALUE\r
589 *       Returns the number of objects available in the specified\r
590 *       quick composite pool.\r
591 *\r
592 * SEE ALSO\r
593 *       Quick Composite Pool\r
594 *********/\r
595 \r
596 \r
597 /****f* Component Library: Quick Composite Pool/cl_qcpool_get\r
598 * NAME\r
599 *       cl_qcpool_get\r
600 *\r
601 * DESCRIPTION\r
602 *       The cl_qcpool_get function retrieves an object from a\r
603 *       quick composite pool.\r
604 *\r
605 * SYNOPSIS\r
606 */\r
607 CL_EXPORT cl_pool_item_t* CL_API\r
608 cl_qcpool_get(\r
609         IN      cl_qcpool_t* const      p_pool );\r
610 /*\r
611 * PARAMETERS\r
612 *       p_pool\r
613 *               [in] Pointer to a cl_qcpool_t structure from which to retrieve\r
614 *               an object.\r
615 *\r
616 * RETURN VALUES\r
617 *       Returns a pointer to a cl_pool_item_t for a composite object.\r
618 *\r
619 *       Returns NULL if the pool is empty and can not be grown automatically.\r
620 *\r
621 * NOTES\r
622 *       cl_qcpool_get returns the object at the head of the pool. If the pool is\r
623 *       empty, it is automatically grown to accommodate this request unless the\r
624 *       grow_size parameter passed to the cl_qcpool_init function was zero.\r
625 *\r
626 * SEE ALSO\r
627 *       Quick Composite Pool, cl_qcpool_get_tail, cl_qcpool_put,\r
628 *       cl_qcpool_grow, cl_qcpool_count\r
629 *********/\r
630 \r
631 \r
632 /****f* Component Library: Quick Composite Pool/cl_qcpool_put\r
633 * NAME\r
634 *       cl_qcpool_put\r
635 *\r
636 * DESCRIPTION\r
637 *       The cl_qcpool_put function returns an object to a quick composite pool.\r
638 *\r
639 * SYNOPSIS\r
640 */\r
641 CL_INLINE void CL_API\r
642 cl_qcpool_put(\r
643         IN      cl_qcpool_t* const              p_pool,\r
644         IN      cl_pool_item_t* const   p_pool_item )\r
645 {\r
646         CL_ASSERT( p_pool );\r
647         CL_ASSERT( p_pool->state == CL_INITIALIZED );\r
648         CL_ASSERT( p_pool_item );\r
649         /* Make sure items being returned came from the specified pool. */\r
650         CL_ASSERT( p_pool_item->p_pool == p_pool );\r
651 \r
652         /* return this lil' doggy to the pool */\r
653         cl_qlist_insert_head( &p_pool->free_list, &p_pool_item->list_item );\r
654 }\r
655 /*\r
656 * PARAMETERS\r
657 *       p_pool\r
658 *               [in] Pointer to a cl_qcpool_t structure to which to return\r
659 *               an object.\r
660 *\r
661 *       p_pool_item\r
662 *               [in] Pointer to a cl_pool_item_t structure for the object\r
663 *               being returned.\r
664 *\r
665 * RETURN VALUE\r
666 *       This function does not return a value.\r
667 *\r
668 * NOTES\r
669 *       cl_qcpool_put places the returned object at the head of the pool.\r
670 *\r
671 *       The object specified by the p_pool_item parameter must have been\r
672 *       retrieved from the pool by a previous call to cl_qcpool_get.\r
673 *\r
674 * SEE ALSO\r
675 *       Quick Composite Pool, cl_qcpool_put_tail, cl_qcpool_get\r
676 *********/\r
677 \r
678 \r
679 /****f* Component Library: Quick Composite Pool/cl_qcpool_put_list\r
680 * NAME\r
681 *       cl_qcpool_put_list\r
682 *\r
683 * DESCRIPTION\r
684 *       The cl_qcpool_put_list function returns a list of objects to the head of\r
685 *       a quick composite pool.\r
686 *\r
687 * SYNOPSIS\r
688 */\r
689 CL_INLINE void CL_API\r
690 cl_qcpool_put_list(\r
691         IN      cl_qcpool_t* const      p_pool,\r
692         IN      cl_qlist_t* const       p_list )\r
693 {\r
694 #ifdef _DEBUG_\r
695         cl_list_item_t  *p_item;\r
696 #endif\r
697 \r
698         CL_ASSERT( p_pool );\r
699         CL_ASSERT( p_pool->state == CL_INITIALIZED );\r
700         CL_ASSERT( p_list );\r
701 \r
702 #ifdef _DEBUG_\r
703         /* Chech that all items in the list came from this pool. */\r
704         p_item = cl_qlist_head( p_list );\r
705         while( p_item != cl_qlist_end( p_list ) )\r
706         {\r
707                 CL_ASSERT( ((cl_pool_item_t*)p_item)->p_pool == p_pool );\r
708                 p_item = cl_qlist_next( p_item );\r
709         }\r
710 #endif\r
711 \r
712         /* return these lil' doggies to the pool */\r
713         cl_qlist_insert_list_head( &p_pool->free_list, p_list );\r
714 }\r
715 /*\r
716 * PARAMETERS\r
717 *       p_pool\r
718 *               [in] Pointer to a cl_qcpool_t structure to which to return\r
719 *               a list of objects.\r
720 *\r
721 *       p_list\r
722 *               [in] Pointer to a cl_qlist_t structure for the list of objects\r
723 *               being returned.\r
724 *\r
725 * RETURN VALUE\r
726 *       This function does not return a value.\r
727 *\r
728 * NOTES\r
729 *       cl_qcpool_put_list places the returned objects at the head of the pool.\r
730 *\r
731 *       The objects in the list specified by the p_list parameter must have been\r
732 *       retrieved from the pool by a previous call to cl_qcpool_get.\r
733 *\r
734 * SEE ALSO\r
735 *       Quick Composite Pool, cl_qcpool_put, cl_qcpool_put_tail, cl_qcpool_get\r
736 *********/\r
737 \r
738 \r
739 /****f* Component Library: Quick Composite Pool/cl_qcpool_grow\r
740 * NAME\r
741 *       cl_qcpool_grow\r
742 *\r
743 * DESCRIPTION\r
744 *       The cl_qcpool_grow function grows a quick composite pool by\r
745 *       the specified number of objects.\r
746 *\r
747 * SYNOPSIS\r
748 */\r
749 CL_EXPORT cl_status_t CL_API\r
750 cl_qcpool_grow(\r
751         IN      cl_qcpool_t* const              p_pool,\r
752         IN      size_t                                  obj_count );\r
753 /*\r
754 * PARAMETERS\r
755 *       p_pool\r
756 *               [in] Pointer to a cl_qcpool_t structure whose capacity to grow.\r
757 *\r
758 *       obj_count\r
759 *               [in] Number of objects by which to grow the pool.\r
760 *\r
761 * RETURN VALUES\r
762 *       CL_SUCCESS if the quick composite pool grew successfully.\r
763 *\r
764 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to grow the\r
765 *       quick composite pool.\r
766 *\r
767 *       cl_status_t value returned by optional initialization callback function\r
768 *       specified by the pfn_initializer parameter passed to the\r
769 *       cl_qcpool_init function.\r
770 *\r
771 * NOTES\r
772 *       It is not necessary to call cl_qcpool_grow if the pool is\r
773 *       configured to grow automatically.\r
774 *\r
775 * SEE ALSO\r
776 *       Quick Composite Pool\r
777 *********/\r
778 \r
779 \r
780 #ifdef __cplusplus\r
781 }       /* extern "C" */\r
782 #endif  /* __cplusplus */\r
783 \r
784 \r
785 #endif  /* _CL_QUICK_COMPOSITE_POOL_H_ */\r