1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * Declaration of the composite pool. 39219820Sjeff * The composite pool managers a pool of composite objects. A composite object is an object 40219820Sjeff * that is made of multiple sub objects. 41219820Sjeff * The pool can grow to meet demand, limited only by system memory. 42219820Sjeff */ 43219820Sjeff 44219820Sjeff#ifndef _CL_COMP_POOL_H_ 45219820Sjeff#define _CL_COMP_POOL_H_ 46219820Sjeff 47219820Sjeff#include <complib/cl_qcomppool.h> 48219820Sjeff 49219820Sjeff#ifdef __cplusplus 50219820Sjeff# define BEGIN_C_DECLS extern "C" { 51219820Sjeff# define END_C_DECLS } 52219820Sjeff#else /* !__cplusplus */ 53219820Sjeff# define BEGIN_C_DECLS 54219820Sjeff# define END_C_DECLS 55219820Sjeff#endif /* __cplusplus */ 56219820Sjeff 57219820SjeffBEGIN_C_DECLS 58219820Sjeff/****h* Component Library/Composite Pool 59219820Sjeff* NAME 60219820Sjeff* Composite Pool 61219820Sjeff* 62219820Sjeff* DESCRIPTION 63219820Sjeff* The Composite Pool provides a self-contained and self-sustaining pool of 64219820Sjeff* user defined composite objects. 65219820Sjeff* 66219820Sjeff* A composite object is an object that is composed of one or more 67219820Sjeff* sub-objects, each of which needs to be treated separately for 68219820Sjeff* initialization. Objects can be retrieved from the pool as long as there 69219820Sjeff* is memory in the system. 70219820Sjeff* 71219820Sjeff* To aid in object oriented design, the composite pool provides the user 72219820Sjeff* the ability to specify callbacks that are invoked for each object for 73219820Sjeff* construction, initialization, and destruction. Constructor and destructor 74219820Sjeff* callback functions may not fail. 75219820Sjeff* 76219820Sjeff* A composite pool does not return memory to the system as the user returns 77219820Sjeff* objects to the pool. The only method of returning memory to the system is 78219820Sjeff* to destroy the pool. 79219820Sjeff* 80219820Sjeff* The composite pool functions operates on a cl_cpool_t structure which 81219820Sjeff* should be treated as opaque and should be manipulated only through the 82219820Sjeff* provided functions. 83219820Sjeff* 84219820Sjeff* SEE ALSO 85219820Sjeff* Structures: 86219820Sjeff* cl_cpool_t 87219820Sjeff* 88219820Sjeff* Callbacks: 89219820Sjeff* cl_pfn_cpool_init_t, cl_pfn_cpool_dtor_t 90219820Sjeff* 91219820Sjeff* Initialization/Destruction: 92219820Sjeff* cl_cpool_construct, cl_cpool_init, cl_cpool_destroy 93219820Sjeff* 94219820Sjeff* Manipulation: 95219820Sjeff* cl_cpool_get, cl_cpool_put, cl_cpool_grow 96219820Sjeff* 97219820Sjeff* Attributes: 98219820Sjeff* cl_is_cpool_inited, cl_cpool_count 99219820Sjeff*********/ 100219820Sjeff/****d* Component Library: Composite Pool/cl_pfn_cpool_init_t 101219820Sjeff* NAME 102219820Sjeff* cl_pfn_cpool_init_t 103219820Sjeff* 104219820Sjeff* DESCRIPTION 105219820Sjeff* The cl_pfn_cpool_init_t function type defines the prototype for 106219820Sjeff* functions used as initializers for objects being allocated by a 107219820Sjeff* composite pool. 108219820Sjeff* 109219820Sjeff* SYNOPSIS 110219820Sjeff*/ 111219820Sjefftypedef cl_status_t 112219820Sjeff (*cl_pfn_cpool_init_t) (IN void **const p_comp_array, 113219820Sjeff IN const uint32_t num_components, IN void *context); 114219820Sjeff/* 115219820Sjeff* PARAMETERS 116219820Sjeff* p_object 117219820Sjeff* [in] Pointer to an object to initialize. 118219820Sjeff* 119219820Sjeff* context 120219820Sjeff* [in] Context provided in a call to cl_cpool_init. 121219820Sjeff* 122219820Sjeff* RETURN VALUES 123219820Sjeff* Return CL_SUCCESS to indicates that initialization of the object 124219820Sjeff* was successful and that initialization of further objects may continue. 125219820Sjeff* 126219820Sjeff* Other cl_status_t values will be returned by cl_cpool_init 127219820Sjeff* and cl_cpool_grow. 128219820Sjeff* 129219820Sjeff* NOTES 130219820Sjeff* This function type is provided as function prototype reference for 131219820Sjeff* the function provided by the user as an optional parameter to the 132219820Sjeff* cl_cpool_init function. 133219820Sjeff* 134219820Sjeff* The initializer is invoked once per allocated object, allowing the user 135219820Sjeff* to chain components to form a composite object and perform any necessary 136219820Sjeff* initialization. Returning a status other than CL_SUCCESS aborts a grow 137219820Sjeff* operation, initiated either through cl_cpool_init or cl_cpool_grow, and 138219820Sjeff* causes the initiating function to fail. Any non-CL_SUCCESS status will 139219820Sjeff* be returned by the function that initiated the grow operation. 140219820Sjeff* 141219820Sjeff* All memory for the requested number of components is pre-allocated. 142219820Sjeff* 143219820Sjeff* When later performing a cl_cpool_get call, the return value is a pointer 144219820Sjeff* to the first component. 145219820Sjeff* 146219820Sjeff* SEE ALSO 147219820Sjeff* Composite Pool, cl_cpool_init, cl_cpool_grow 148219820Sjeff*********/ 149219820Sjeff 150219820Sjeff/****d* Component Library: Composite Pool/cl_pfn_cpool_dtor_t 151219820Sjeff* NAME 152219820Sjeff* cl_pfn_cpool_dtor_t 153219820Sjeff* 154219820Sjeff* DESCRIPTION 155219820Sjeff* The cl_pfn_cpool_dtor_t function type defines the prototype for 156219820Sjeff* functions used as destructor for objects being deallocated by a 157219820Sjeff* composite pool. 158219820Sjeff* 159219820Sjeff* SYNOPSIS 160219820Sjeff*/ 161219820Sjefftypedef void 162219820Sjeff (*cl_pfn_cpool_dtor_t) (IN void *const p_object, IN void *context); 163219820Sjeff/* 164219820Sjeff* PARAMETERS 165219820Sjeff* p_object 166219820Sjeff* [in] Pointer to an object to destruct. 167219820Sjeff* 168219820Sjeff* context 169219820Sjeff* [in] Context provided in the call to cl_cpool_init. 170219820Sjeff* 171219820Sjeff* RETURN VALUE 172219820Sjeff* This function does not return a value. 173219820Sjeff* 174219820Sjeff* NOTES 175219820Sjeff* This function type is provided as function prototype reference for 176219820Sjeff* the function provided by the user as an optional parameter to the 177219820Sjeff* cl_cpool_init function. 178219820Sjeff* 179219820Sjeff* The destructor is invoked once per allocated object, allowing the user 180219820Sjeff* to perform any necessary cleanup. Users should not attempt to deallocate 181219820Sjeff* the memory for the composite object, as the composite pool manages 182219820Sjeff* object allocation and deallocation. 183219820Sjeff* 184219820Sjeff* SEE ALSO 185219820Sjeff* Composite Pool, cl_cpool_init 186219820Sjeff*********/ 187219820Sjeff 188219820Sjeff/****s* Component Library: Composite Pool/cl_cpool_t 189219820Sjeff* NAME 190219820Sjeff* cl_cpool_t 191219820Sjeff* 192219820Sjeff* DESCRIPTION 193219820Sjeff* Composite pool structure. 194219820Sjeff* 195219820Sjeff* The cl_cpool_t structure should be treated as opaque and should be 196219820Sjeff* manipulated only through the provided functions. 197219820Sjeff* 198219820Sjeff* SYNOPSIS 199219820Sjeff*/ 200219820Sjefftypedef struct _cl_cpool { 201219820Sjeff cl_qcpool_t qcpool; 202219820Sjeff cl_pfn_cpool_init_t pfn_init; 203219820Sjeff cl_pfn_cpool_dtor_t pfn_dtor; 204219820Sjeff const void *context; 205219820Sjeff} cl_cpool_t; 206219820Sjeff/* 207219820Sjeff* FIELDS 208219820Sjeff* qcpool 209219820Sjeff* Quick composite pool that manages all objects. 210219820Sjeff* 211219820Sjeff* pfn_init 212219820Sjeff* Pointer to the user's initializer callback, used by the pool 213219820Sjeff* to translate the quick composite pool's initializer callback to 214219820Sjeff* a composite pool initializer callback. 215219820Sjeff* 216219820Sjeff* pfn_dtor 217219820Sjeff* Pointer to the user's destructor callback, used by the pool 218219820Sjeff* to translate the quick composite pool's destructor callback to 219219820Sjeff* a composite pool destructor callback. 220219820Sjeff* 221219820Sjeff* context 222219820Sjeff* User's provided context for callback functions, used by the pool 223219820Sjeff* to when invoking callbacks. 224219820Sjeff* 225219820Sjeff* SEE ALSO 226219820Sjeff* Composite Pool 227219820Sjeff*********/ 228219820Sjeff 229219820Sjeff/****f* Component Library: Composite Pool/cl_cpool_construct 230219820Sjeff* NAME 231219820Sjeff* cl_cpool_construct 232219820Sjeff* 233219820Sjeff* DESCRIPTION 234219820Sjeff* The cl_cpool_construct function constructs a composite pool. 235219820Sjeff* 236219820Sjeff* SYNOPSIS 237219820Sjeff*/ 238219820Sjeffvoid cl_cpool_construct(IN cl_cpool_t * const p_pool); 239219820Sjeff/* 240219820Sjeff* PARAMETERS 241219820Sjeff* p_pool 242219820Sjeff* [in] Pointer to a cl_cpool_t structure whose state to initialize. 243219820Sjeff* 244219820Sjeff* RETURN VALUE 245219820Sjeff* This function does not return a value. 246219820Sjeff* 247219820Sjeff* NOTES 248219820Sjeff* Allows calling cl_pool_init, cl_cpool_destroy, cl_is_cpool_inited. 249219820Sjeff* 250219820Sjeff* Calling cl_cpool_construct is a prerequisite to calling any other 251219820Sjeff* composite pool function except cl_cpool_init. 252219820Sjeff* 253219820Sjeff* SEE ALSO 254219820Sjeff* Composite Pool, cl_cpool_init, cl_cpool_destroy, cl_is_cpool_inited 255219820Sjeff*********/ 256219820Sjeff 257219820Sjeff/****f* Component Library: Composite Pool/cl_is_cpool_inited 258219820Sjeff* NAME 259219820Sjeff* cl_is_cpool_inited 260219820Sjeff* 261219820Sjeff* DESCRIPTION 262219820Sjeff* The cl_is_cpool_inited function returns whether a composite pool was 263219820Sjeff* successfully initialized. 264219820Sjeff* 265219820Sjeff* SYNOPSIS 266219820Sjeff*/ 267219820Sjeffstatic inline boolean_t cl_is_cpool_inited(IN const cl_cpool_t * const p_pool) 268219820Sjeff{ 269219820Sjeff /* CL_ASSERT that a non-null pointer is provided. */ 270219820Sjeff CL_ASSERT(p_pool); 271219820Sjeff return (cl_is_qcpool_inited(&p_pool->qcpool)); 272219820Sjeff} 273219820Sjeff 274219820Sjeff/* 275219820Sjeff* PARAMETERS 276219820Sjeff* p_pool 277219820Sjeff* [in] Pointer to a cl_cpool_t structure whose initialization state 278219820Sjeff* to check. 279219820Sjeff* 280219820Sjeff* RETURN VALUES 281219820Sjeff* TRUE if the composite pool was initialized successfully. 282219820Sjeff* 283219820Sjeff* FALSE otherwise. 284219820Sjeff* 285219820Sjeff* NOTES 286219820Sjeff* Allows checking the state of a composite pool to determine if invoking 287219820Sjeff* member functions is appropriate. 288219820Sjeff* 289219820Sjeff* SEE ALSO 290219820Sjeff* Composite Pool 291219820Sjeff*********/ 292219820Sjeff 293219820Sjeff/****f* Component Library: Composite Pool/cl_cpool_init 294219820Sjeff* NAME 295219820Sjeff* cl_cpool_init 296219820Sjeff* 297219820Sjeff* DESCRIPTION 298219820Sjeff* The cl_cpool_init function initializes a composite pool for use. 299219820Sjeff* 300219820Sjeff* SYNOPSIS 301219820Sjeff*/ 302219820Sjeffcl_status_t 303219820Sjeffcl_cpool_init(IN cl_cpool_t * const p_pool, 304219820Sjeff IN const size_t min_size, 305219820Sjeff IN const size_t max_size, 306219820Sjeff IN const size_t grow_size, 307219820Sjeff IN size_t * const component_sizes, 308219820Sjeff IN const uint32_t num_components, 309219820Sjeff IN cl_pfn_cpool_init_t pfn_initializer OPTIONAL, 310219820Sjeff IN cl_pfn_cpool_dtor_t pfn_destructor OPTIONAL, 311219820Sjeff IN const void *const context); 312219820Sjeff/* 313219820Sjeff* PARAMETERS 314219820Sjeff* p_pool 315219820Sjeff* [in] Pointer to a cl_cpool_t structure to initialize. 316219820Sjeff* 317219820Sjeff* min_size 318219820Sjeff* [in] Minimum number of objects that the pool should support. All 319219820Sjeff* necessary allocations to allow storing the minimum number of items 320219820Sjeff* are performed at initialization time, and all necessary callbacks 321219820Sjeff* successfully invoked. 322219820Sjeff* 323219820Sjeff* max_size 324219820Sjeff* [in] Maximum number of objects to which the pool is allowed to grow. 325219820Sjeff* A value of zero specifies no maximum. 326219820Sjeff* 327219820Sjeff* grow_size 328219820Sjeff* [in] Number of objects to allocate when incrementally growing the pool. 329219820Sjeff* A value of zero disables automatic growth. 330219820Sjeff* 331219820Sjeff* component_sizes 332219820Sjeff* [in] Pointer to the first entry in an array of sizes describing, 333219820Sjeff* in order, the sizes of the components that make up a composite object. 334219820Sjeff* 335219820Sjeff* num_components 336219820Sjeff* [in] Number of components that make up a composite object. 337219820Sjeff* 338219820Sjeff* pfn_initializer 339219820Sjeff* [in] Initialization callback to invoke for every new object when 340219820Sjeff* growing the pool. This parameter may be NULL only if the objects 341219820Sjeff* stored in the composite pool consist of only one component. 342219820Sjeff* See the cl_pfn_cpool_init function type declaration for details 343219820Sjeff* about the callback function. 344219820Sjeff* 345219820Sjeff* pfn_destructor 346219820Sjeff* [in] Destructor callback to invoke for every object before memory for 347219820Sjeff* that object is freed. This parameter is optional and may be NULL. 348219820Sjeff* See the cl_pfn_cpool_dtor function type declaration for details 349219820Sjeff* about the callback function. 350219820Sjeff* 351219820Sjeff* context 352219820Sjeff* [in] Value to pass to the callback functions to provide context. 353219820Sjeff* 354219820Sjeff* RETURN VALUES 355219820Sjeff* CL_SUCCESS if the composite pool was initialized successfully. 356219820Sjeff* 357219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize the 358219820Sjeff* composite pool. 359219820Sjeff* 360219820Sjeff* CL_INVALID_SETTING if a NULL constructor was provided for composite objects 361219820Sjeff* consisting of more than one component. Also returns CL_INVALID_SETTING if 362219820Sjeff* the maximum size is non-zero and less than the minimum size. 363219820Sjeff* 364219820Sjeff* Other cl_status_t value returned by optional initialization callback function 365219820Sjeff* specified by the pfn_initializer parameter. 366219820Sjeff* 367219820Sjeff* NOTES 368219820Sjeff* cl_cpool_init initializes, and if necessary, grows the pool to 369219820Sjeff* the capacity desired. 370219820Sjeff* 371219820Sjeff* SEE ALSO 372219820Sjeff* Composite Pool, cl_cpool_construct, cl_cpool_destroy, 373219820Sjeff* cl_cpool_get, cl_cpool_put, cl_cpool_grow, 374219820Sjeff* cl_cpool_count, cl_pfn_cpool_ctor_t, cl_pfn_cpool_init_t, 375219820Sjeff* cl_pfn_cpool_dtor_t 376219820Sjeff*********/ 377219820Sjeff 378219820Sjeff/****f* Component Library: Composite Pool/cl_cpool_destroy 379219820Sjeff* NAME 380219820Sjeff* cl_cpool_destroy 381219820Sjeff* 382219820Sjeff* DESCRIPTION 383219820Sjeff* The cl_cpool_destroy function destroys a composite pool. 384219820Sjeff* 385219820Sjeff* SYNOPSIS 386219820Sjeff*/ 387219820Sjeffstatic inline void cl_cpool_destroy(IN cl_cpool_t * const p_pool) 388219820Sjeff{ 389219820Sjeff CL_ASSERT(p_pool); 390219820Sjeff 391219820Sjeff cl_qcpool_destroy(&p_pool->qcpool); 392219820Sjeff} 393219820Sjeff 394219820Sjeff/* 395219820Sjeff* PARAMETERS 396219820Sjeff* p_pool 397219820Sjeff* [in] Pointer to a cl_cpool_t structure to destroy. 398219820Sjeff* 399219820Sjeff* RETURN VALUE 400219820Sjeff* This function does not return a value. 401219820Sjeff* 402219820Sjeff* NOTES 403219820Sjeff* All memory allocated for composite objects is freed. The destructor 404219820Sjeff* callback, if any, will be invoked for every allocated object. Further 405219820Sjeff* operations on the composite pool should not be attempted after 406219820Sjeff* cl_cpool_destroy is invoked. 407219820Sjeff* 408219820Sjeff* This function should only be called after a call to cl_cpool_construct. 409219820Sjeff* 410219820Sjeff* In a debug build, cl_cpool_destroy asserts that all objects are in 411219820Sjeff* the pool. 412219820Sjeff* 413219820Sjeff* SEE ALSO 414219820Sjeff* Composite Pool, cl_cpool_construct, cl_cpool_init 415219820Sjeff*********/ 416219820Sjeff 417219820Sjeff/****f* Component Library: Composite Pool/cl_cpool_count 418219820Sjeff* NAME 419219820Sjeff* cl_cpool_count 420219820Sjeff* 421219820Sjeff* DESCRIPTION 422219820Sjeff* The cl_cpool_count function returns the number of available objects 423219820Sjeff* in a composite pool. 424219820Sjeff* 425219820Sjeff* SYNOPSIS 426219820Sjeff*/ 427219820Sjeffstatic inline size_t cl_cpool_count(IN cl_cpool_t * const p_pool) 428219820Sjeff{ 429219820Sjeff CL_ASSERT(p_pool); 430219820Sjeff return (cl_qcpool_count(&p_pool->qcpool)); 431219820Sjeff} 432219820Sjeff 433219820Sjeff/* 434219820Sjeff* PARAMETERS 435219820Sjeff* p_pool 436219820Sjeff* [in] Pointer to a cl_cpool_t structure for which the number of 437219820Sjeff* available objects is requested. 438219820Sjeff* 439219820Sjeff* RETURN VALUE 440219820Sjeff* Returns the number of objects available in the specified 441219820Sjeff* composite pool. 442219820Sjeff* 443219820Sjeff* SEE ALSO 444219820Sjeff* Composite Pool 445219820Sjeff*********/ 446219820Sjeff 447219820Sjeff/****f* Component Library: Composite Pool/cl_cpool_get 448219820Sjeff* NAME 449219820Sjeff* cl_cpool_get 450219820Sjeff* 451219820Sjeff* DESCRIPTION 452219820Sjeff* The cl_cpool_get function retrieves an object from a 453219820Sjeff* composite pool. 454219820Sjeff* 455219820Sjeff* SYNOPSIS 456219820Sjeff*/ 457219820Sjeffstatic inline void *cl_cpool_get(IN cl_cpool_t * const p_pool) 458219820Sjeff{ 459219820Sjeff cl_pool_obj_t *p_pool_obj; 460219820Sjeff 461219820Sjeff CL_ASSERT(p_pool); 462219820Sjeff 463219820Sjeff p_pool_obj = (cl_pool_obj_t *) cl_qcpool_get(&p_pool->qcpool); 464219820Sjeff if (!p_pool_obj) 465219820Sjeff return (NULL); 466219820Sjeff 467219820Sjeff CL_ASSERT(p_pool_obj->p_object); 468219820Sjeff return ((void *)p_pool_obj->p_object); 469219820Sjeff} 470219820Sjeff 471219820Sjeff/* 472219820Sjeff* PARAMETERS 473219820Sjeff* p_pool 474219820Sjeff* [in] Pointer to a cl_cpool_t structure from which to retrieve 475219820Sjeff* an object. 476219820Sjeff* 477219820Sjeff* RETURN VALUES 478219820Sjeff* Returns a pointer to the first component of a composite object. 479219820Sjeff* 480219820Sjeff* Returns NULL if the pool is empty and can not be grown automatically. 481219820Sjeff* 482219820Sjeff* NOTES 483219820Sjeff* cl_cpool_get returns the object at the head of the pool. If the pool is 484219820Sjeff* empty, it is automatically grown to accommodate this request unless the 485219820Sjeff* grow_size parameter passed to the cl_cpool_init function was zero. 486219820Sjeff* 487219820Sjeff* SEE ALSO 488219820Sjeff* Composite Pool, cl_cpool_get_tail, cl_cpool_put, cl_cpool_grow, 489219820Sjeff* cl_cpool_count 490219820Sjeff*********/ 491219820Sjeff 492219820Sjeff/****f* Component Library: Composite Pool/cl_cpool_put 493219820Sjeff* NAME 494219820Sjeff* cl_cpool_put 495219820Sjeff* 496219820Sjeff* DESCRIPTION 497219820Sjeff* The cl_cpool_put function returns an object to a composite pool. 498219820Sjeff* 499219820Sjeff* SYNOPSIS 500219820Sjeff*/ 501219820Sjeffstatic inline void 502219820Sjeffcl_cpool_put(IN cl_cpool_t * const p_pool, IN void *const p_object) 503219820Sjeff{ 504219820Sjeff cl_pool_obj_t *p_pool_obj; 505219820Sjeff 506219820Sjeff CL_ASSERT(p_pool); 507219820Sjeff CL_ASSERT(p_object); 508219820Sjeff 509219820Sjeff /* Calculate the offset to the list object representing this object. */ 510219820Sjeff p_pool_obj = (cl_pool_obj_t *) 511219820Sjeff (((uint8_t *) p_object) - sizeof(cl_pool_obj_t)); 512219820Sjeff 513219820Sjeff /* good sanity check */ 514219820Sjeff CL_ASSERT(p_pool_obj->p_object == p_object); 515219820Sjeff 516219820Sjeff cl_qcpool_put(&p_pool->qcpool, &p_pool_obj->pool_item); 517219820Sjeff} 518219820Sjeff 519219820Sjeff/* 520219820Sjeff* PARAMETERS 521219820Sjeff* p_pool 522219820Sjeff* [in] Pointer to a cl_cpool_t structure to which to return 523219820Sjeff* an object. 524219820Sjeff* 525219820Sjeff* p_object 526219820Sjeff* [in] Pointer to the first component of an object to return to the pool. 527219820Sjeff* 528219820Sjeff* RETURN VALUE 529219820Sjeff* This function does not return a value. 530219820Sjeff* 531219820Sjeff* NOTES 532219820Sjeff* cl_cpool_put places the returned object at the head of the pool. 533219820Sjeff* 534219820Sjeff* The object specified by the p_object parameter must have been 535219820Sjeff* retrieved from the pool by a previous call to cl_cpool_get. 536219820Sjeff* 537219820Sjeff* SEE ALSO 538219820Sjeff* Composite Pool, cl_cpool_put_tail, cl_cpool_get 539219820Sjeff*********/ 540219820Sjeff 541219820Sjeff/****f* Component Library: Composite Pool/cl_cpool_grow 542219820Sjeff* NAME 543219820Sjeff* cl_cpool_grow 544219820Sjeff* 545219820Sjeff* DESCRIPTION 546219820Sjeff* The cl_cpool_grow function grows a composite pool by 547219820Sjeff* the specified number of objects. 548219820Sjeff* 549219820Sjeff* SYNOPSIS 550219820Sjeff*/ 551219820Sjeffstatic inline cl_status_t 552219820Sjeffcl_cpool_grow(IN cl_cpool_t * const p_pool, IN const uint32_t obj_count) 553219820Sjeff{ 554219820Sjeff CL_ASSERT(p_pool); 555219820Sjeff return (cl_qcpool_grow(&p_pool->qcpool, obj_count)); 556219820Sjeff} 557219820Sjeff 558219820Sjeff/* 559219820Sjeff* PARAMETERS 560219820Sjeff* p_pool 561219820Sjeff* [in] Pointer to a cl_cpool_t structure whose capacity to grow. 562219820Sjeff* 563219820Sjeff* obj_count 564219820Sjeff* [in] Number of objects by which to grow the pool. 565219820Sjeff* 566219820Sjeff* RETURN VALUES 567219820Sjeff* CL_SUCCESS if the composite pool grew successfully. 568219820Sjeff* 569219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to grow the 570219820Sjeff* composite pool. 571219820Sjeff* 572219820Sjeff* cl_status_t value returned by optional initialization callback function 573219820Sjeff* specified by the pfn_initializer parameter passed to the 574219820Sjeff* cl_cpool_init function. 575219820Sjeff* 576219820Sjeff* NOTES 577219820Sjeff* It is not necessary to call cl_cpool_grow if the pool is 578219820Sjeff* configured to grow automatically. 579219820Sjeff* 580219820Sjeff* SEE ALSO 581219820Sjeff* Composite Pool 582219820Sjeff*********/ 583219820Sjeff 584219820SjeffEND_C_DECLS 585219820Sjeff#endif /* _CL_COMP_POOL_H_ */ 586