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