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.
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:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
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.
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
38 * Declaration of the pool.
39 * The pool manages a pool of objects.
40 * The pool can grow to meet demand, limited only by system memory.
46 #include <complib/cl_qcomppool.h>
49 # define BEGIN_C_DECLS extern "C" {
50 # define END_C_DECLS }
51 #else /* !__cplusplus */
52 # define BEGIN_C_DECLS
54 #endif /* __cplusplus */
57 /****h* Component Library/Pool
62 * The pool provides a self-contained and self-sustaining pool
63 * of user defined objects.
65 * To aid in object oriented design, the pool provides the user
66 * the ability to specify callbacks that are invoked for each object for
67 * construction, initialization, and destruction. Constructor and destructor
68 * callback functions may not fail.
70 * A pool does not return memory to the system as the user returns
71 * objects to the pool. The only method of returning memory to the system is
72 * to destroy the pool.
74 * The Pool functions operate on a cl_pool_t structure which should be treated
75 * as opaque and should be manipulated only through the provided functions.
82 * cl_pfn_pool_init_t, cl_pfn_pool_dtor_t
84 * Initialization/Destruction:
85 * cl_pool_construct, cl_pool_init, cl_pool_destroy
88 * cl_pool_get, cl_pool_put, cl_pool_grow
91 * cl_is_pool_inited, cl_pool_count
93 /****d* Component Library: Pool/cl_pfn_pool_init_t
98 * The cl_pfn_pool_init_t function type defines the prototype for
99 * functions used as initializers for objects being allocated by a
105 (*cl_pfn_pool_init_t) (IN void *const p_object, IN void *context);
109 * [in] Pointer to an object to initialize.
112 * [in] Context provided in a call to cl_pool_init.
115 * Return CL_SUCCESS to indicates that initialization of the object
116 * was successful and initialization of further objects may continue.
118 * Other cl_status_t values will be returned by cl_pool_init
122 * This function type is provided as function prototype reference for
123 * the function provided by the user as an optional parameter to the
124 * cl_pool_init function.
126 * The initializer is invoked once per allocated object, allowing the user
127 * to trap initialization failures. Returning a status other than CL_SUCCESS
128 * aborts a grow operation, initiated either through cl_pool_init or
129 * cl_pool_grow, and causes the initiating function to fail.
130 * Any non-CL_SUCCESS status will be returned by the function that initiated
131 * the grow operation.
134 * Pool, cl_pool_init, cl_pool_grow
137 /****d* Component Library: Pool/cl_pfn_pool_dtor_t
142 * The cl_pfn_pool_dtor_t function type defines the prototype for
143 * functions used as destructor for objects being deallocated by a
149 (*cl_pfn_pool_dtor_t) (IN void *const p_object, IN void *context);
153 * [in] Pointer to an object to destruct.
156 * [in] Context provided in the call to cl_pool_init.
159 * This function does not return a value.
162 * This function type is provided as function prototype reference for
163 * the function provided by the user as an optional parameter to the
164 * cl_pool_init function.
166 * The destructor is invoked once per allocated object, allowing the user
167 * to perform any necessary cleanup. Users should not attempt to deallocate
168 * the memory for the object, as the pool manages object
169 * allocation and deallocation.
175 /****s* Component Library: Pool/cl_pool_t
182 * The cl_pool_t structure should be treated as opaque and should be
183 * manipulated only through the provided functions.
187 typedef struct _cl_pool {
189 cl_pfn_pool_init_t pfn_init;
190 cl_pfn_pool_dtor_t pfn_dtor;
196 * Quick composite pool that manages all objects.
199 * Pointer to the user's initializer callback, used by the pool
200 * to translate the quick composite pool's initializer callback to
201 * a pool initializer callback.
204 * Pointer to the user's destructor callback, used by the pool
205 * to translate the quick composite pool's destructor callback to
206 * a pool destructor callback.
209 * User's provided context for callback functions, used by the pool
210 * to when invoking callbacks.
216 /****f* Component Library: Pool/cl_pool_construct
221 * The cl_pool_construct function constructs a pool.
225 void cl_pool_construct(IN cl_pool_t * const p_pool);
229 * [in] Pointer to a cl_pool_t structure whose state to initialize.
232 * This function does not return a value.
235 * Allows calling cl_pool_init, cl_pool_destroy, and cl_is_pool_inited.
237 * Calling cl_pool_construct is a prerequisite to calling any other
238 * pool function except cl_pool_init.
241 * Pool, cl_pool_init, cl_pool_destroy, cl_is_pool_inited
244 /****f* Component Library: Pool/cl_is_pool_inited
249 * The cl_is_pool_inited function returns whether a pool was successfully
254 static inline uint32_t cl_is_pool_inited(IN const cl_pool_t * const p_pool)
256 /* CL_ASSERT that a non-null pointer is provided. */
258 return (cl_is_qcpool_inited(&p_pool->qcpool));
264 * [in] Pointer to a cl_pool_t structure whose initialization state
268 * TRUE if the pool was initialized successfully.
273 * Allows checking the state of a pool to determine if invoking member
274 * functions is appropriate.
280 /****f* Component Library: Pool/cl_pool_init
285 * The cl_pool_init function initializes a pool for use.
290 cl_pool_init(IN cl_pool_t * const p_pool,
291 IN const size_t min_count,
292 IN const size_t max_count,
293 IN const size_t grow_size,
294 IN const size_t object_size,
295 IN cl_pfn_pool_init_t pfn_initializer OPTIONAL,
296 IN cl_pfn_pool_dtor_t pfn_destructor OPTIONAL,
297 IN const void *const context);
301 * [in] Pointer to a cl_pool_t structure to initialize.
304 * [in] Minimum number of objects that the pool should support. All
305 * necessary allocations to allow storing the minimum number of items
306 * are performed at initialization time, and all necessary callbacks
310 * [in] Maximum number of objects to which the pool is allowed to grow.
311 * A value of zero specifies no maximum.
314 * [in] Number of objects to allocate when incrementally growing the pool.
315 * A value of zero disables automatic growth.
318 * [in] Size, in bytes, of each object.
321 * [in] Initialization callback to invoke for every new object when
322 * growing the pool. This parameter is optional and may be NULL.
323 * See the cl_pfn_pool_init_t function type declaration for details
324 * about the callback function.
327 * [in] Destructor callback to invoke for every object before memory for
328 * that object is freed. This parameter is optional and may be NULL.
329 * See the cl_pfn_pool_dtor_t function type declaration for details
330 * about the callback function.
333 * [in] Value to pass to the callback functions to provide context.
336 * CL_SUCCESS if the pool was initialized successfully.
338 * CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize the
341 * CL_INVALID_SETTING if a the maximum size is non-zero and less than the
344 * Other cl_status_t value returned by optional initialization callback function
345 * specified by the pfn_initializer parameter.
348 * cl_pool_init initializes, and if necessary, grows the pool to
349 * the capacity desired.
352 * Pool, cl_pool_construct, cl_pool_destroy,
353 * cl_pool_get, cl_pool_put, cl_pool_grow,
354 * cl_pool_count, cl_pfn_pool_init_t, cl_pfn_pool_dtor_t
357 /****f* Component Library: Pool/cl_pool_destroy
362 * The cl_pool_destroy function destroys a pool.
366 static inline void cl_pool_destroy(IN cl_pool_t * const p_pool)
369 cl_qcpool_destroy(&p_pool->qcpool);
375 * [in] Pointer to a cl_pool_t structure to destroy.
378 * This function does not return a value.
381 * All memory allocated for objects is freed. The destructor callback,
382 * if any, will be invoked for every allocated object. Further operations
383 * on the pool should not be attempted after cl_pool_destroy
386 * This function should only be called after a call to
387 * cl_pool_construct or cl_pool_init.
389 * In a debug build, cl_pool_destroy asserts that all objects are in
393 * Pool, cl_pool_construct, cl_pool_init
396 /****f* Component Library: Pool/cl_pool_count
401 * The cl_pool_count function returns the number of available objects
406 static inline size_t cl_pool_count(IN cl_pool_t * const p_pool)
409 return (cl_qcpool_count(&p_pool->qcpool));
415 * [in] Pointer to a cl_pool_t structure for which the number of
416 * available objects is requested.
419 * Returns the number of objects available in the specified pool.
425 /****f* Component Library: Pool/cl_pool_get
430 * The cl_pool_get function retrieves an object from a pool.
434 static inline void *cl_pool_get(IN cl_pool_t * const p_pool)
436 cl_pool_obj_t *p_pool_obj;
440 p_pool_obj = (cl_pool_obj_t *) cl_qcpool_get(&p_pool->qcpool);
444 CL_ASSERT(p_pool_obj->p_object);
445 return ((void *)p_pool_obj->p_object);
451 * [in] Pointer to a cl_pool_t structure from which to retrieve
455 * Returns a pointer to an object.
457 * Returns NULL if the pool is empty and can not be grown automatically.
460 * cl_pool_get returns the object at the head of the pool. If the pool is
461 * empty, it is automatically grown to accommodate this request unless the
462 * grow_size parameter passed to the cl_pool_init function was zero.
465 * Pool, cl_pool_get_tail, cl_pool_put, cl_pool_grow, cl_pool_count
468 /****f* Component Library: Pool/cl_pool_put
473 * The cl_pool_put function returns an object to a pool.
478 cl_pool_put(IN cl_pool_t * const p_pool, IN void *const p_object)
480 cl_pool_obj_t *p_pool_obj;
485 /* Calculate the offset to the list object representing this object. */
486 p_pool_obj = (cl_pool_obj_t *)
487 (((uint8_t *) p_object) - sizeof(cl_pool_obj_t));
489 /* good sanity check */
490 CL_ASSERT(p_pool_obj->p_object == p_object);
492 cl_qcpool_put(&p_pool->qcpool, &p_pool_obj->pool_item);
498 * [in] Pointer to a cl_pool_t structure to which to return
502 * [in] Pointer to an object to return to the pool.
505 * This function does not return a value.
508 * cl_pool_put places the returned object at the head of the pool.
510 * The object specified by the p_object parameter must have been
511 * retrieved from the pool by a previous call to cl_pool_get.
514 * Pool, cl_pool_put_tail, cl_pool_get
517 /****f* Component Library: Pool/cl_pool_grow
522 * The cl_pool_grow function grows a pool by
523 * the specified number of objects.
527 static inline cl_status_t
528 cl_pool_grow(IN cl_pool_t * const p_pool, IN const size_t obj_count)
531 return (cl_qcpool_grow(&p_pool->qcpool, obj_count));
537 * [in] Pointer to a cl_pool_t structure whose capacity to grow.
540 * [in] Number of objects by which to grow the pool.
543 * CL_SUCCESS if the pool grew successfully.
545 * CL_INSUFFICIENT_MEMORY if there was not enough memory to grow the
548 * cl_status_t value returned by optional initialization callback function
549 * specified by the pfn_initializer parameter passed to the
550 * cl_pool_init function.
553 * It is not necessary to call cl_pool_grow if the pool is
554 * configured to grow automatically.
561 #endif /* _CL_POOL_H_ */