1321936Shselasky/* 2321936Shselasky * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3321936Shselasky * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4321936Shselasky * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5321936Shselasky * 6321936Shselasky * This software is available to you under a choice of one of two 7321936Shselasky * licenses. You may choose to be licensed under the terms of the GNU 8321936Shselasky * General Public License (GPL) Version 2, available from the file 9321936Shselasky * COPYING in the main directory of this source tree, or the 10321936Shselasky * OpenIB.org BSD license below: 11321936Shselasky * 12321936Shselasky * Redistribution and use in source and binary forms, with or 13321936Shselasky * without modification, are permitted provided that the following 14321936Shselasky * conditions are met: 15321936Shselasky * 16321936Shselasky * - Redistributions of source code must retain the above 17321936Shselasky * copyright notice, this list of conditions and the following 18321936Shselasky * disclaimer. 19321936Shselasky * 20321936Shselasky * - Redistributions in binary form must reproduce the above 21321936Shselasky * copyright notice, this list of conditions and the following 22321936Shselasky * disclaimer in the documentation and/or other materials 23321936Shselasky * provided with the distribution. 24321936Shselasky * 25321936Shselasky * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26321936Shselasky * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27321936Shselasky * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28321936Shselasky * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29321936Shselasky * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30321936Shselasky * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31321936Shselasky * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32321936Shselasky * SOFTWARE. 33321936Shselasky * 34321936Shselasky */ 35321936Shselasky 36321936Shselasky/* 37321936Shselasky * Abstract: 38321936Shselasky * Declaration of the composite pool. 39321936Shselasky * The composite pool managers a pool of composite objects. A composite object is an object 40321936Shselasky * that is made of multiple sub objects. 41321936Shselasky * The pool can grow to meet demand, limited only by system memory. 42321936Shselasky */ 43321936Shselasky 44321936Shselasky#ifndef _CL_COMP_POOL_H_ 45321936Shselasky#define _CL_COMP_POOL_H_ 46321936Shselasky 47321936Shselasky#include <complib/cl_qcomppool.h> 48321936Shselasky 49321936Shselasky#ifdef __cplusplus 50321936Shselasky# define BEGIN_C_DECLS extern "C" { 51321936Shselasky# define END_C_DECLS } 52321936Shselasky#else /* !__cplusplus */ 53321936Shselasky# define BEGIN_C_DECLS 54321936Shselasky# define END_C_DECLS 55321936Shselasky#endif /* __cplusplus */ 56321936Shselasky 57321936ShselaskyBEGIN_C_DECLS 58321936Shselasky/****h* Component Library/Composite Pool 59321936Shselasky* NAME 60321936Shselasky* Composite Pool 61321936Shselasky* 62321936Shselasky* DESCRIPTION 63321936Shselasky* The Composite Pool provides a self-contained and self-sustaining pool of 64321936Shselasky* user defined composite objects. 65321936Shselasky* 66321936Shselasky* A composite object is an object that is composed of one or more 67321936Shselasky* sub-objects, each of which needs to be treated separately for 68321936Shselasky* initialization. Objects can be retrieved from the pool as long as there 69321936Shselasky* is memory in the system. 70321936Shselasky* 71321936Shselasky* To aid in object oriented design, the composite pool provides the user 72321936Shselasky* the ability to specify callbacks that are invoked for each object for 73321936Shselasky* construction, initialization, and destruction. Constructor and destructor 74321936Shselasky* callback functions may not fail. 75321936Shselasky* 76321936Shselasky* A composite pool does not return memory to the system as the user returns 77321936Shselasky* objects to the pool. The only method of returning memory to the system is 78321936Shselasky* to destroy the pool. 79321936Shselasky* 80321936Shselasky* The composite pool functions operates on a cl_cpool_t structure which 81321936Shselasky* should be treated as opaque and should be manipulated only through the 82321936Shselasky* provided functions. 83321936Shselasky* 84321936Shselasky* SEE ALSO 85321936Shselasky* Structures: 86321936Shselasky* cl_cpool_t 87321936Shselasky* 88321936Shselasky* Callbacks: 89321936Shselasky* cl_pfn_cpool_init_t, cl_pfn_cpool_dtor_t 90321936Shselasky* 91321936Shselasky* Initialization/Destruction: 92321936Shselasky* cl_cpool_construct, cl_cpool_init, cl_cpool_destroy 93321936Shselasky* 94321936Shselasky* Manipulation: 95321936Shselasky* cl_cpool_get, cl_cpool_put, cl_cpool_grow 96321936Shselasky* 97321936Shselasky* Attributes: 98321936Shselasky* cl_is_cpool_inited, cl_cpool_count 99321936Shselasky*********/ 100321936Shselasky/****d* Component Library: Composite Pool/cl_pfn_cpool_init_t 101321936Shselasky* NAME 102321936Shselasky* cl_pfn_cpool_init_t 103321936Shselasky* 104321936Shselasky* DESCRIPTION 105321936Shselasky* The cl_pfn_cpool_init_t function type defines the prototype for 106321936Shselasky* functions used as initializers for objects being allocated by a 107321936Shselasky* composite pool. 108321936Shselasky* 109321936Shselasky* SYNOPSIS 110321936Shselasky*/ 111321936Shselaskytypedef cl_status_t 112321936Shselasky (*cl_pfn_cpool_init_t) (IN void **const p_comp_array, 113321936Shselasky IN const uint32_t num_components, IN void *context); 114321936Shselasky/* 115321936Shselasky* PARAMETERS 116321936Shselasky* p_object 117321936Shselasky* [in] Pointer to an object to initialize. 118321936Shselasky* 119321936Shselasky* context 120321936Shselasky* [in] Context provided in a call to cl_cpool_init. 121321936Shselasky* 122321936Shselasky* RETURN VALUES 123321936Shselasky* Return CL_SUCCESS to indicates that initialization of the object 124321936Shselasky* was successful and that initialization of further objects may continue. 125321936Shselasky* 126321936Shselasky* Other cl_status_t values will be returned by cl_cpool_init 127321936Shselasky* and cl_cpool_grow. 128321936Shselasky* 129321936Shselasky* NOTES 130321936Shselasky* This function type is provided as function prototype reference for 131321936Shselasky* the function provided by the user as an optional parameter to the 132321936Shselasky* cl_cpool_init function. 133321936Shselasky* 134321936Shselasky* The initializer is invoked once per allocated object, allowing the user 135321936Shselasky* to chain components to form a composite object and perform any necessary 136321936Shselasky* initialization. Returning a status other than CL_SUCCESS aborts a grow 137321936Shselasky* operation, initiated either through cl_cpool_init or cl_cpool_grow, and 138321936Shselasky* causes the initiating function to fail. Any non-CL_SUCCESS status will 139321936Shselasky* be returned by the function that initiated the grow operation. 140321936Shselasky* 141321936Shselasky* All memory for the requested number of components is pre-allocated. 142321936Shselasky* 143321936Shselasky* When later performing a cl_cpool_get call, the return value is a pointer 144321936Shselasky* to the first component. 145321936Shselasky* 146321936Shselasky* SEE ALSO 147321936Shselasky* Composite Pool, cl_cpool_init, cl_cpool_grow 148321936Shselasky*********/ 149321936Shselasky 150321936Shselasky/****d* Component Library: Composite Pool/cl_pfn_cpool_dtor_t 151321936Shselasky* NAME 152321936Shselasky* cl_pfn_cpool_dtor_t 153321936Shselasky* 154321936Shselasky* DESCRIPTION 155321936Shselasky* The cl_pfn_cpool_dtor_t function type defines the prototype for 156321936Shselasky* functions used as destructor for objects being deallocated by a 157321936Shselasky* composite pool. 158321936Shselasky* 159321936Shselasky* SYNOPSIS 160321936Shselasky*/ 161321936Shselaskytypedef void 162321936Shselasky (*cl_pfn_cpool_dtor_t) (IN void *const p_object, IN void *context); 163321936Shselasky/* 164321936Shselasky* PARAMETERS 165321936Shselasky* p_object 166321936Shselasky* [in] Pointer to an object to destruct. 167321936Shselasky* 168321936Shselasky* context 169321936Shselasky* [in] Context provided in the call to cl_cpool_init. 170321936Shselasky* 171321936Shselasky* RETURN VALUE 172321936Shselasky* This function does not return a value. 173321936Shselasky* 174321936Shselasky* NOTES 175321936Shselasky* This function type is provided as function prototype reference for 176321936Shselasky* the function provided by the user as an optional parameter to the 177321936Shselasky* cl_cpool_init function. 178321936Shselasky* 179321936Shselasky* The destructor is invoked once per allocated object, allowing the user 180321936Shselasky* to perform any necessary cleanup. Users should not attempt to deallocate 181321936Shselasky* the memory for the composite object, as the composite pool manages 182321936Shselasky* object allocation and deallocation. 183321936Shselasky* 184321936Shselasky* SEE ALSO 185321936Shselasky* Composite Pool, cl_cpool_init 186321936Shselasky*********/ 187321936Shselasky 188321936Shselasky/****s* Component Library: Composite Pool/cl_cpool_t 189321936Shselasky* NAME 190321936Shselasky* cl_cpool_t 191321936Shselasky* 192321936Shselasky* DESCRIPTION 193321936Shselasky* Composite pool structure. 194321936Shselasky* 195321936Shselasky* The cl_cpool_t structure should be treated as opaque and should be 196321936Shselasky* manipulated only through the provided functions. 197321936Shselasky* 198321936Shselasky* SYNOPSIS 199321936Shselasky*/ 200321936Shselaskytypedef struct _cl_cpool { 201321936Shselasky cl_qcpool_t qcpool; 202321936Shselasky cl_pfn_cpool_init_t pfn_init; 203321936Shselasky cl_pfn_cpool_dtor_t pfn_dtor; 204321936Shselasky const void *context; 205321936Shselasky} cl_cpool_t; 206321936Shselasky/* 207321936Shselasky* FIELDS 208321936Shselasky* qcpool 209321936Shselasky* Quick composite pool that manages all objects. 210321936Shselasky* 211321936Shselasky* pfn_init 212321936Shselasky* Pointer to the user's initializer callback, used by the pool 213321936Shselasky* to translate the quick composite pool's initializer callback to 214321936Shselasky* a composite pool initializer callback. 215321936Shselasky* 216321936Shselasky* pfn_dtor 217321936Shselasky* Pointer to the user's destructor callback, used by the pool 218321936Shselasky* to translate the quick composite pool's destructor callback to 219321936Shselasky* a composite pool destructor callback. 220321936Shselasky* 221321936Shselasky* context 222321936Shselasky* User's provided context for callback functions, used by the pool 223321936Shselasky* to when invoking callbacks. 224321936Shselasky* 225321936Shselasky* SEE ALSO 226321936Shselasky* Composite Pool 227321936Shselasky*********/ 228321936Shselasky 229321936Shselasky/****f* Component Library: Composite Pool/cl_cpool_construct 230321936Shselasky* NAME 231321936Shselasky* cl_cpool_construct 232321936Shselasky* 233321936Shselasky* DESCRIPTION 234321936Shselasky* The cl_cpool_construct function constructs a composite pool. 235321936Shselasky* 236321936Shselasky* SYNOPSIS 237321936Shselasky*/ 238321936Shselaskyvoid cl_cpool_construct(IN cl_cpool_t * const p_pool); 239321936Shselasky/* 240321936Shselasky* PARAMETERS 241321936Shselasky* p_pool 242321936Shselasky* [in] Pointer to a cl_cpool_t structure whose state to initialize. 243321936Shselasky* 244321936Shselasky* RETURN VALUE 245321936Shselasky* This function does not return a value. 246321936Shselasky* 247321936Shselasky* NOTES 248321936Shselasky* Allows calling cl_pool_init, cl_cpool_destroy, cl_is_cpool_inited. 249321936Shselasky* 250321936Shselasky* Calling cl_cpool_construct is a prerequisite to calling any other 251321936Shselasky* composite pool function except cl_cpool_init. 252321936Shselasky* 253321936Shselasky* SEE ALSO 254321936Shselasky* Composite Pool, cl_cpool_init, cl_cpool_destroy, cl_is_cpool_inited 255321936Shselasky*********/ 256321936Shselasky 257321936Shselasky/****f* Component Library: Composite Pool/cl_is_cpool_inited 258321936Shselasky* NAME 259321936Shselasky* cl_is_cpool_inited 260321936Shselasky* 261321936Shselasky* DESCRIPTION 262321936Shselasky* The cl_is_cpool_inited function returns whether a composite pool was 263321936Shselasky* successfully initialized. 264321936Shselasky* 265321936Shselasky* SYNOPSIS 266321936Shselasky*/ 267321936Shselaskystatic inline boolean_t cl_is_cpool_inited(IN const cl_cpool_t * const p_pool) 268321936Shselasky{ 269321936Shselasky /* CL_ASSERT that a non-null pointer is provided. */ 270321936Shselasky CL_ASSERT(p_pool); 271321936Shselasky return (cl_is_qcpool_inited(&p_pool->qcpool)); 272321936Shselasky} 273321936Shselasky 274321936Shselasky/* 275321936Shselasky* PARAMETERS 276321936Shselasky* p_pool 277321936Shselasky* [in] Pointer to a cl_cpool_t structure whose initialization state 278321936Shselasky* to check. 279321936Shselasky* 280321936Shselasky* RETURN VALUES 281321936Shselasky* TRUE if the composite pool was initialized successfully. 282321936Shselasky* 283321936Shselasky* FALSE otherwise. 284321936Shselasky* 285321936Shselasky* NOTES 286321936Shselasky* Allows checking the state of a composite pool to determine if invoking 287321936Shselasky* member functions is appropriate. 288321936Shselasky* 289321936Shselasky* SEE ALSO 290321936Shselasky* Composite Pool 291321936Shselasky*********/ 292321936Shselasky 293321936Shselasky/****f* Component Library: Composite Pool/cl_cpool_init 294321936Shselasky* NAME 295321936Shselasky* cl_cpool_init 296321936Shselasky* 297321936Shselasky* DESCRIPTION 298321936Shselasky* The cl_cpool_init function initializes a composite pool for use. 299321936Shselasky* 300321936Shselasky* SYNOPSIS 301321936Shselasky*/ 302321936Shselaskycl_status_t 303321936Shselaskycl_cpool_init(IN cl_cpool_t * const p_pool, 304321936Shselasky IN const size_t min_size, 305321936Shselasky IN const size_t max_size, 306321936Shselasky IN const size_t grow_size, 307321936Shselasky IN size_t * const component_sizes, 308321936Shselasky IN const uint32_t num_components, 309321936Shselasky IN cl_pfn_cpool_init_t pfn_initializer OPTIONAL, 310321936Shselasky IN cl_pfn_cpool_dtor_t pfn_destructor OPTIONAL, 311321936Shselasky IN const void *const context); 312321936Shselasky/* 313321936Shselasky* PARAMETERS 314321936Shselasky* p_pool 315321936Shselasky* [in] Pointer to a cl_cpool_t structure to initialize. 316321936Shselasky* 317321936Shselasky* min_size 318321936Shselasky* [in] Minimum number of objects that the pool should support. All 319321936Shselasky* necessary allocations to allow storing the minimum number of items 320321936Shselasky* are performed at initialization time, and all necessary callbacks 321321936Shselasky* successfully invoked. 322321936Shselasky* 323321936Shselasky* max_size 324321936Shselasky* [in] Maximum number of objects to which the pool is allowed to grow. 325321936Shselasky* A value of zero specifies no maximum. 326321936Shselasky* 327321936Shselasky* grow_size 328321936Shselasky* [in] Number of objects to allocate when incrementally growing the pool. 329321936Shselasky* A value of zero disables automatic growth. 330321936Shselasky* 331321936Shselasky* component_sizes 332321936Shselasky* [in] Pointer to the first entry in an array of sizes describing, 333321936Shselasky* in order, the sizes of the components that make up a composite object. 334321936Shselasky* 335321936Shselasky* num_components 336321936Shselasky* [in] Number of components that make up a composite object. 337321936Shselasky* 338321936Shselasky* pfn_initializer 339321936Shselasky* [in] Initialization callback to invoke for every new object when 340321936Shselasky* growing the pool. This parameter may be NULL only if the objects 341321936Shselasky* stored in the composite pool consist of only one component. 342321936Shselasky* See the cl_pfn_cpool_init function type declaration for details 343321936Shselasky* about the callback function. 344321936Shselasky* 345321936Shselasky* pfn_destructor 346321936Shselasky* [in] Destructor callback to invoke for every object before memory for 347321936Shselasky* that object is freed. This parameter is optional and may be NULL. 348321936Shselasky* See the cl_pfn_cpool_dtor function type declaration for details 349321936Shselasky* about the callback function. 350321936Shselasky* 351321936Shselasky* context 352321936Shselasky* [in] Value to pass to the callback functions to provide context. 353321936Shselasky* 354321936Shselasky* RETURN VALUES 355321936Shselasky* CL_SUCCESS if the composite pool was initialized successfully. 356321936Shselasky* 357321936Shselasky* CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize the 358321936Shselasky* composite pool. 359321936Shselasky* 360321936Shselasky* CL_INVALID_SETTING if a NULL constructor was provided for composite objects 361321936Shselasky* consisting of more than one component. Also returns CL_INVALID_SETTING if 362321936Shselasky* the maximum size is non-zero and less than the minimum size. 363321936Shselasky* 364321936Shselasky* Other cl_status_t value returned by optional initialization callback function 365321936Shselasky* specified by the pfn_initializer parameter. 366321936Shselasky* 367321936Shselasky* NOTES 368321936Shselasky* cl_cpool_init initializes, and if necessary, grows the pool to 369321936Shselasky* the capacity desired. 370321936Shselasky* 371321936Shselasky* SEE ALSO 372321936Shselasky* Composite Pool, cl_cpool_construct, cl_cpool_destroy, 373321936Shselasky* cl_cpool_get, cl_cpool_put, cl_cpool_grow, 374321936Shselasky* cl_cpool_count, cl_pfn_cpool_ctor_t, cl_pfn_cpool_init_t, 375321936Shselasky* cl_pfn_cpool_dtor_t 376321936Shselasky*********/ 377321936Shselasky 378321936Shselasky/****f* Component Library: Composite Pool/cl_cpool_destroy 379321936Shselasky* NAME 380321936Shselasky* cl_cpool_destroy 381321936Shselasky* 382321936Shselasky* DESCRIPTION 383321936Shselasky* The cl_cpool_destroy function destroys a composite pool. 384321936Shselasky* 385321936Shselasky* SYNOPSIS 386321936Shselasky*/ 387321936Shselaskystatic inline void cl_cpool_destroy(IN cl_cpool_t * const p_pool) 388321936Shselasky{ 389321936Shselasky CL_ASSERT(p_pool); 390321936Shselasky 391321936Shselasky cl_qcpool_destroy(&p_pool->qcpool); 392321936Shselasky} 393321936Shselasky 394321936Shselasky/* 395321936Shselasky* PARAMETERS 396321936Shselasky* p_pool 397321936Shselasky* [in] Pointer to a cl_cpool_t structure to destroy. 398321936Shselasky* 399321936Shselasky* RETURN VALUE 400321936Shselasky* This function does not return a value. 401321936Shselasky* 402321936Shselasky* NOTES 403321936Shselasky* All memory allocated for composite objects is freed. The destructor 404321936Shselasky* callback, if any, will be invoked for every allocated object. Further 405321936Shselasky* operations on the composite pool should not be attempted after 406321936Shselasky* cl_cpool_destroy is invoked. 407321936Shselasky* 408321936Shselasky* This function should only be called after a call to cl_cpool_construct. 409321936Shselasky* 410321936Shselasky* In a debug build, cl_cpool_destroy asserts that all objects are in 411321936Shselasky* the pool. 412321936Shselasky* 413321936Shselasky* SEE ALSO 414321936Shselasky* Composite Pool, cl_cpool_construct, cl_cpool_init 415321936Shselasky*********/ 416321936Shselasky 417321936Shselasky/****f* Component Library: Composite Pool/cl_cpool_count 418321936Shselasky* NAME 419321936Shselasky* cl_cpool_count 420321936Shselasky* 421321936Shselasky* DESCRIPTION 422321936Shselasky* The cl_cpool_count function returns the number of available objects 423321936Shselasky* in a composite pool. 424321936Shselasky* 425321936Shselasky* SYNOPSIS 426321936Shselasky*/ 427321936Shselaskystatic inline size_t cl_cpool_count(IN cl_cpool_t * const p_pool) 428321936Shselasky{ 429321936Shselasky CL_ASSERT(p_pool); 430321936Shselasky return (cl_qcpool_count(&p_pool->qcpool)); 431321936Shselasky} 432321936Shselasky 433321936Shselasky/* 434321936Shselasky* PARAMETERS 435321936Shselasky* p_pool 436321936Shselasky* [in] Pointer to a cl_cpool_t structure for which the number of 437321936Shselasky* available objects is requested. 438321936Shselasky* 439321936Shselasky* RETURN VALUE 440321936Shselasky* Returns the number of objects available in the specified 441321936Shselasky* composite pool. 442321936Shselasky* 443321936Shselasky* SEE ALSO 444321936Shselasky* Composite Pool 445321936Shselasky*********/ 446321936Shselasky 447321936Shselasky/****f* Component Library: Composite Pool/cl_cpool_get 448321936Shselasky* NAME 449321936Shselasky* cl_cpool_get 450321936Shselasky* 451321936Shselasky* DESCRIPTION 452321936Shselasky* The cl_cpool_get function retrieves an object from a 453321936Shselasky* composite pool. 454321936Shselasky* 455321936Shselasky* SYNOPSIS 456321936Shselasky*/ 457321936Shselaskystatic inline void *cl_cpool_get(IN cl_cpool_t * const p_pool) 458321936Shselasky{ 459321936Shselasky cl_pool_obj_t *p_pool_obj; 460321936Shselasky 461321936Shselasky CL_ASSERT(p_pool); 462321936Shselasky 463321936Shselasky p_pool_obj = (cl_pool_obj_t *) cl_qcpool_get(&p_pool->qcpool); 464321936Shselasky if (!p_pool_obj) 465321936Shselasky return (NULL); 466321936Shselasky 467321936Shselasky CL_ASSERT(p_pool_obj->p_object); 468321936Shselasky return ((void *)p_pool_obj->p_object); 469321936Shselasky} 470321936Shselasky 471321936Shselasky/* 472321936Shselasky* PARAMETERS 473321936Shselasky* p_pool 474321936Shselasky* [in] Pointer to a cl_cpool_t structure from which to retrieve 475321936Shselasky* an object. 476321936Shselasky* 477321936Shselasky* RETURN VALUES 478321936Shselasky* Returns a pointer to the first component of a composite object. 479321936Shselasky* 480321936Shselasky* Returns NULL if the pool is empty and can not be grown automatically. 481321936Shselasky* 482321936Shselasky* NOTES 483321936Shselasky* cl_cpool_get returns the object at the head of the pool. If the pool is 484321936Shselasky* empty, it is automatically grown to accommodate this request unless the 485321936Shselasky* grow_size parameter passed to the cl_cpool_init function was zero. 486321936Shselasky* 487321936Shselasky* SEE ALSO 488321936Shselasky* Composite Pool, cl_cpool_get_tail, cl_cpool_put, cl_cpool_grow, 489321936Shselasky* cl_cpool_count 490321936Shselasky*********/ 491321936Shselasky 492321936Shselasky/****f* Component Library: Composite Pool/cl_cpool_put 493321936Shselasky* NAME 494321936Shselasky* cl_cpool_put 495321936Shselasky* 496321936Shselasky* DESCRIPTION 497321936Shselasky* The cl_cpool_put function returns an object to a composite pool. 498321936Shselasky* 499321936Shselasky* SYNOPSIS 500321936Shselasky*/ 501321936Shselaskystatic inline void 502321936Shselaskycl_cpool_put(IN cl_cpool_t * const p_pool, IN void *const p_object) 503321936Shselasky{ 504321936Shselasky cl_pool_obj_t *p_pool_obj; 505321936Shselasky 506321936Shselasky CL_ASSERT(p_pool); 507321936Shselasky CL_ASSERT(p_object); 508321936Shselasky 509321936Shselasky /* Calculate the offset to the list object representing this object. */ 510321936Shselasky p_pool_obj = (cl_pool_obj_t *) 511321936Shselasky (((uint8_t *) p_object) - sizeof(cl_pool_obj_t)); 512321936Shselasky 513321936Shselasky /* good sanity check */ 514321936Shselasky CL_ASSERT(p_pool_obj->p_object == p_object); 515321936Shselasky 516321936Shselasky cl_qcpool_put(&p_pool->qcpool, &p_pool_obj->pool_item); 517321936Shselasky} 518321936Shselasky 519321936Shselasky/* 520321936Shselasky* PARAMETERS 521321936Shselasky* p_pool 522321936Shselasky* [in] Pointer to a cl_cpool_t structure to which to return 523321936Shselasky* an object. 524321936Shselasky* 525321936Shselasky* p_object 526321936Shselasky* [in] Pointer to the first component of an object to return to the pool. 527321936Shselasky* 528321936Shselasky* RETURN VALUE 529321936Shselasky* This function does not return a value. 530321936Shselasky* 531321936Shselasky* NOTES 532321936Shselasky* cl_cpool_put places the returned object at the head of the pool. 533321936Shselasky* 534321936Shselasky* The object specified by the p_object parameter must have been 535321936Shselasky* retrieved from the pool by a previous call to cl_cpool_get. 536321936Shselasky* 537321936Shselasky* SEE ALSO 538321936Shselasky* Composite Pool, cl_cpool_put_tail, cl_cpool_get 539321936Shselasky*********/ 540321936Shselasky 541321936Shselasky/****f* Component Library: Composite Pool/cl_cpool_grow 542321936Shselasky* NAME 543321936Shselasky* cl_cpool_grow 544321936Shselasky* 545321936Shselasky* DESCRIPTION 546321936Shselasky* The cl_cpool_grow function grows a composite pool by 547321936Shselasky* the specified number of objects. 548321936Shselasky* 549321936Shselasky* SYNOPSIS 550321936Shselasky*/ 551321936Shselaskystatic inline cl_status_t 552321936Shselaskycl_cpool_grow(IN cl_cpool_t * const p_pool, IN const uint32_t obj_count) 553321936Shselasky{ 554321936Shselasky CL_ASSERT(p_pool); 555321936Shselasky return (cl_qcpool_grow(&p_pool->qcpool, obj_count)); 556321936Shselasky} 557321936Shselasky 558321936Shselasky/* 559321936Shselasky* PARAMETERS 560321936Shselasky* p_pool 561321936Shselasky* [in] Pointer to a cl_cpool_t structure whose capacity to grow. 562321936Shselasky* 563321936Shselasky* obj_count 564321936Shselasky* [in] Number of objects by which to grow the pool. 565321936Shselasky* 566321936Shselasky* RETURN VALUES 567321936Shselasky* CL_SUCCESS if the composite pool grew successfully. 568321936Shselasky* 569321936Shselasky* CL_INSUFFICIENT_MEMORY if there was not enough memory to grow the 570321936Shselasky* composite pool. 571321936Shselasky* 572321936Shselasky* cl_status_t value returned by optional initialization callback function 573321936Shselasky* specified by the pfn_initializer parameter passed to the 574321936Shselasky* cl_cpool_init function. 575321936Shselasky* 576321936Shselasky* NOTES 577321936Shselasky* It is not necessary to call cl_cpool_grow if the pool is 578321936Shselasky* configured to grow automatically. 579321936Shselasky* 580321936Shselasky* SEE ALSO 581321936Shselasky* Composite Pool 582321936Shselasky*********/ 583321936Shselasky 584321936ShselaskyEND_C_DECLS 585321936Shselasky#endif /* _CL_COMP_POOL_H_ */ 586