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 quick composite pool. The quick composite pool 39219820Sjeff * manages a pool of composite objects. A composite object is an object 40219820Sjeff * that is made of multiple sub objects. 41219820Sjeff * It can grow to meet demand, limited only by system memory. 42219820Sjeff */ 43219820Sjeff 44219820Sjeff#ifndef _CL_QUICK_COMPOSITE_POOL_H_ 45219820Sjeff#define _CL_QUICK_COMPOSITE_POOL_H_ 46219820Sjeff 47219820Sjeff#include <complib/cl_types.h> 48219820Sjeff#include <complib/cl_qlist.h> 49219820Sjeff 50219820Sjeff#ifdef __cplusplus 51219820Sjeff# define BEGIN_C_DECLS extern "C" { 52219820Sjeff# define END_C_DECLS } 53219820Sjeff#else /* !__cplusplus */ 54219820Sjeff# define BEGIN_C_DECLS 55219820Sjeff# define END_C_DECLS 56219820Sjeff#endif /* __cplusplus */ 57219820Sjeff 58219820SjeffBEGIN_C_DECLS 59219820Sjeff/****h* Component Library/Quick Composite Pool 60219820Sjeff* NAME 61219820Sjeff* Quick Composite Pool 62219820Sjeff* 63219820Sjeff* DESCRIPTION 64219820Sjeff* The Quick Composite Pool provides a self-contained and self-sustaining 65219820Sjeff* pool of user defined composite objects. 66219820Sjeff* 67219820Sjeff* A composite object is an object that is composed of one or more 68219820Sjeff* sub-objects, each of which needs to be treated separately for 69219820Sjeff* initialization. Objects can be retrieved from the pool as long as there 70219820Sjeff* is memory in the system. 71219820Sjeff* 72219820Sjeff* To aid in object oriented design, the Quick Composite Pool provides users 73219820Sjeff* the ability to specify callbacks that are invoked for each object for 74219820Sjeff* construction, initialization, and destruction. Constructor and destructor 75219820Sjeff* callback functions may not fail. 76219820Sjeff* 77219820Sjeff* A Quick Composite Pool does not return memory to the system as the user 78219820Sjeff* returns objects to the pool. The only method of returning memory to the 79219820Sjeff* system is to destroy the pool. 80219820Sjeff* 81219820Sjeff* The Quick Composite Pool operates on cl_pool_item_t structures that 82219820Sjeff* describe composite objects. This provides for more efficient memory use. 83219820Sjeff* If using a cl_pool_item_t is not desired, the Composite Pool provides 84219820Sjeff* similar functionality but operates on opaque objects. 85219820Sjeff* 86219820Sjeff* The Quick Composit Pool functions operate on a cl_qcpool_t structure 87219820Sjeff* which should be treated as opaque and should be manipulated only through 88219820Sjeff* the provided functions. 89219820Sjeff* 90219820Sjeff* SEE ALSO 91219820Sjeff* Structures: 92219820Sjeff* cl_qcpool_t, cl_pool_item_t 93219820Sjeff* 94219820Sjeff* Callbacks: 95219820Sjeff* cl_pfn_qcpool_init_t, cl_pfn_qcpool_dtor_t 96219820Sjeff* 97219820Sjeff* Initialization/Destruction: 98219820Sjeff* cl_qcpool_construct, cl_qcpool_init, cl_qcpool_destroy 99219820Sjeff* 100219820Sjeff* Manipulation: 101219820Sjeff* cl_qcpool_get, cl_qcpool_put, cl_qcpool_put_list, cl_qcpool_grow 102219820Sjeff* 103219820Sjeff* Attributes: 104219820Sjeff* cl_is_qcpool_inited, cl_qcpool_count 105219820Sjeff*********/ 106219820Sjeff/****s* Component Library: Quick Composite Pool/cl_pool_item_t 107219820Sjeff* NAME 108219820Sjeff* cl_pool_item_t 109219820Sjeff* 110219820Sjeff* DESCRIPTION 111219820Sjeff* The cl_pool_item_t structure is used by pools to store objects. 112219820Sjeff* 113219820Sjeff* SYNOPSIS 114219820Sjeff*/ 115219820Sjefftypedef struct _cl_pool_item { 116219820Sjeff cl_list_item_t list_item; 117219820Sjeff#ifdef _DEBUG_ 118219820Sjeff /* Pointer to the owner pool used for sanity checks. */ 119219820Sjeff struct _cl_qcpool *p_pool; 120219820Sjeff#endif 121219820Sjeff} cl_pool_item_t; 122219820Sjeff/* 123219820Sjeff* FIELDS 124219820Sjeff* list_item 125219820Sjeff* Used internally by the pool. Users should not use this field. 126219820Sjeff* 127219820Sjeff* p_pool 128219820Sjeff* Used internally by the pool in debug builds to check for consistency. 129219820Sjeff* 130219820Sjeff* NOTES 131219820Sjeff* The pool item structure is defined in such a way as to safely allow 132219820Sjeff* users to cast from a pool item to a list item for storing items 133219820Sjeff* retrieved from a quick pool in a quick list. 134219820Sjeff* 135219820Sjeff* SEE ALSO 136219820Sjeff* Quick Composite Pool, cl_list_item_t 137219820Sjeff*********/ 138219820Sjeff 139219820Sjeff/****i* Component Library: Quick List/cl_pool_obj_t 140219820Sjeff* NAME 141219820Sjeff* cl_pool_obj_t 142219820Sjeff* 143219820Sjeff* DESCRIPTION 144219820Sjeff* The cl_pool_obj_t structure is used by pools to store objects. 145219820Sjeff* 146219820Sjeff* SYNOPSIS 147219820Sjeff*/ 148219820Sjefftypedef struct _cl_pool_obj { 149219820Sjeff /* The pool item must be the first item to allow casting. */ 150219820Sjeff cl_pool_item_t pool_item; 151219820Sjeff const void *p_object; 152219820Sjeff} cl_pool_obj_t; 153219820Sjeff/* 154219820Sjeff* FIELDS 155219820Sjeff* pool_item 156219820Sjeff* Used internally by the pool. Users should not use this field. 157219820Sjeff* 158219820Sjeff* p_object 159219820Sjeff* Pointer to the user's object being stored in the pool. 160219820Sjeff* 161219820Sjeff* NOTES 162219820Sjeff* The pool object structure is used by non-quick pools to store object. 163219820Sjeff* 164219820Sjeff* SEE ALSO 165219820Sjeff* cl_pool_item_t 166219820Sjeff*********/ 167219820Sjeff 168219820Sjeff/****d* Component Library: Quick Composite Pool/cl_pfn_qcpool_init_t 169219820Sjeff* NAME 170219820Sjeff* cl_pfn_qcpool_init_t 171219820Sjeff* 172219820Sjeff* DESCRIPTION 173219820Sjeff* The cl_pfn_qcpool_init_t function type defines the prototype for 174219820Sjeff* functions used as initializer for objects being allocated by a 175219820Sjeff* quick composite pool. 176219820Sjeff* 177219820Sjeff* SYNOPSIS 178219820Sjeff*/ 179219820Sjefftypedef cl_status_t 180219820Sjeff (*cl_pfn_qcpool_init_t) (IN void **const p_comp_array, 181219820Sjeff IN const uint32_t num_components, 182219820Sjeff IN void *context, 183219820Sjeff OUT cl_pool_item_t ** const pp_pool_item); 184219820Sjeff/* 185219820Sjeff* PARAMETERS 186219820Sjeff* p_comp_array 187219820Sjeff* [in] Pointer to the first entry in an array of pointers, each of 188219820Sjeff* which points to a component that makes up a composite object. 189219820Sjeff* 190219820Sjeff* num_components 191219820Sjeff* [in] Number of components that in the component array. 192219820Sjeff* 193219820Sjeff* context 194219820Sjeff* [in] Context provided in a call to cl_qcpool_init. 195219820Sjeff* 196219820Sjeff* pp_pool_item 197219820Sjeff* [out] Users should set this pointer to reference the cl_pool_item_t 198219820Sjeff* structure that represents the composite object. This pointer must 199219820Sjeff* not be NULL if the function returns CL_SUCCESS. 200219820Sjeff* 201219820Sjeff* RETURN VALUE 202219820Sjeff* Return CL_SUCCESS to indicate that initialization of the object 203219820Sjeff* was successful and that initialization of further objects may continue. 204219820Sjeff* 205219820Sjeff* Other cl_status_t values will be returned by cl_qcpool_init 206219820Sjeff* and cl_qcpool_grow. 207219820Sjeff* 208219820Sjeff* NOTES 209219820Sjeff* This function type is provided as function prototype reference for 210219820Sjeff* the function provided by the user as a parameter to the 211219820Sjeff* cl_qcpool_init function. 212219820Sjeff* 213219820Sjeff* The initializer is invoked once per allocated object, allowing the user 214219820Sjeff* to chain components to form a composite object and perform any necessary 215219820Sjeff* initialization. Returning a status other than CL_SUCCESS aborts a grow 216219820Sjeff* operation, initiated either through cl_qcpool_init or cl_qcpool_grow, 217219820Sjeff* and causes the initiating function to fail. Any non-CL_SUCCESS status 218219820Sjeff* will be returned by the function that initiated the grow operation. 219219820Sjeff* 220219820Sjeff* All memory for the requested number of components is pre-allocated. Users 221219820Sjeff* should include space in one of their components for the cl_pool_item_t 222219820Sjeff* structure that will represent the composite object to avoid having to 223219820Sjeff* allocate that structure in the initialization callback. Alternatively, 224219820Sjeff* users may specify an additional component for the cl_pool_item_t structure. 225219820Sjeff* 226219820Sjeff* When later performing a cl_qcpool_get call, the return value is a pointer 227219820Sjeff* to the cl_pool_item_t returned by this function in the pp_pool_item 228219820Sjeff* parameter. Users must set pp_pool_item to a valid pointer to the 229219820Sjeff* cl_pool_item_t representing the object if they return CL_SUCCESS. 230219820Sjeff* 231219820Sjeff* SEE ALSO 232219820Sjeff* Quick Composite Pool, cl_qcpool_init 233219820Sjeff*********/ 234219820Sjeff 235219820Sjeff/****d* Component Library: Quick Composite Pool/cl_pfn_qcpool_dtor_t 236219820Sjeff* NAME 237219820Sjeff* cl_pfn_qcpool_dtor_t 238219820Sjeff* 239219820Sjeff* DESCRIPTION 240219820Sjeff* The cl_pfn_qcpool_dtor_t function type defines the prototype for 241219820Sjeff* functions used as destructor for objects being deallocated by a 242219820Sjeff* quick composite pool. 243219820Sjeff* 244219820Sjeff* SYNOPSIS 245219820Sjeff*/ 246219820Sjefftypedef void 247219820Sjeff (*cl_pfn_qcpool_dtor_t) (IN const cl_pool_item_t * const p_pool_item, 248219820Sjeff IN void *context); 249219820Sjeff/* 250219820Sjeff* PARAMETERS 251219820Sjeff* p_pool_item 252219820Sjeff* [in] Pointer to a cl_pool_item_t structure representing an object. 253219820Sjeff* 254219820Sjeff* context 255219820Sjeff* [in] Context provided in a call to cl_qcpool_init. 256219820Sjeff* 257219820Sjeff* RETURN VALUE 258219820Sjeff* This function does not return a value. 259219820Sjeff* 260219820Sjeff* NOTES 261219820Sjeff* This function type is provided as function prototype reference for 262219820Sjeff* the function provided by the user as an optional parameter to the 263219820Sjeff* cl_qcpool_init function. 264219820Sjeff* 265219820Sjeff* The destructor is invoked once per allocated object, allowing the user 266219820Sjeff* to perform any necessary cleanup. Users should not attempt to deallocate 267219820Sjeff* the memory for the composite object, as the quick composite pool manages 268219820Sjeff* object allocation and deallocation. 269219820Sjeff* 270219820Sjeff* SEE ALSO 271219820Sjeff* Quick Composite Pool, cl_qcpool_init 272219820Sjeff*********/ 273219820Sjeff 274219820Sjeff/****s* Component Library: Quick Composite Pool/cl_qcpool_t 275219820Sjeff* NAME 276219820Sjeff* cl_qcpool_t 277219820Sjeff* 278219820Sjeff* DESCRIPTION 279219820Sjeff* Quick composite pool structure. 280219820Sjeff* 281219820Sjeff* The cl_qcpool_t structure should be treated as opaque and should be 282219820Sjeff* manipulated only through the provided functions. 283219820Sjeff* 284219820Sjeff* SYNOPSIS 285219820Sjeff*/ 286219820Sjefftypedef struct _cl_qcpool { 287219820Sjeff uint32_t num_components; 288219820Sjeff size_t *component_sizes; 289219820Sjeff void **p_components; 290219820Sjeff size_t num_objects; 291219820Sjeff size_t max_objects; 292219820Sjeff size_t grow_size; 293219820Sjeff cl_pfn_qcpool_init_t pfn_init; 294219820Sjeff cl_pfn_qcpool_dtor_t pfn_dtor; 295219820Sjeff const void *context; 296219820Sjeff cl_qlist_t free_list; 297219820Sjeff cl_qlist_t alloc_list; 298219820Sjeff cl_state_t state; 299219820Sjeff} cl_qcpool_t; 300219820Sjeff/* 301219820Sjeff* FIELDS 302219820Sjeff* num_components 303219820Sjeff* Number of components per object. 304219820Sjeff* 305219820Sjeff* component_sizes 306219820Sjeff* Array of sizes, one for each component. 307219820Sjeff* 308219820Sjeff* p_components 309219820Sjeff* Array of pointers to components, used for the constructor callback. 310219820Sjeff* 311219820Sjeff* num_objects 312219820Sjeff* Number of objects managed by the pool 313219820Sjeff* 314219820Sjeff* grow_size 315219820Sjeff* Number of objects to add when automatically growing the pool. 316219820Sjeff* 317219820Sjeff* pfn_init 318219820Sjeff* Pointer to the user's initializer callback to invoke when initializing 319219820Sjeff* new objects. 320219820Sjeff* 321219820Sjeff* pfn_dtor 322219820Sjeff* Pointer to the user's destructor callback to invoke before deallocating 323219820Sjeff* memory allocated for objects. 324219820Sjeff* 325219820Sjeff* context 326219820Sjeff* User's provided context for callback functions, used by the pool 327219820Sjeff* when invoking callbacks. 328219820Sjeff* 329219820Sjeff* free_list 330219820Sjeff* Quick list of objects available. 331219820Sjeff* 332219820Sjeff* alloc_list 333219820Sjeff* Quick list used to store information about allocations. 334219820Sjeff* 335219820Sjeff* state 336219820Sjeff* State of the pool. 337219820Sjeff* 338219820Sjeff* SEE ALSO 339219820Sjeff* Quick Composite Pool 340219820Sjeff*********/ 341219820Sjeff 342219820Sjeff/****f* Component Library: Quick Composite Pool/cl_qcpool_construct 343219820Sjeff* NAME 344219820Sjeff* cl_qcpool_construct 345219820Sjeff* 346219820Sjeff* DESCRIPTION 347219820Sjeff* The cl_qcpool_construct function constructs a quick composite pool. 348219820Sjeff* 349219820Sjeff* SYNOPSIS 350219820Sjeff*/ 351219820Sjeffvoid cl_qcpool_construct(IN cl_qcpool_t * const p_pool); 352219820Sjeff/* 353219820Sjeff* PARAMETERS 354219820Sjeff* p_pool 355219820Sjeff* [in] Pointer to a cl_qcpool_t structure whose state to initialize. 356219820Sjeff* 357219820Sjeff* RETURN VALUE 358219820Sjeff* This function does not return a value. 359219820Sjeff* 360219820Sjeff* NOTES 361219820Sjeff* Allows calling cl_qcpool_init, cl_qcpool_destroy, cl_is_qcpool_inited. 362219820Sjeff* 363219820Sjeff* Calling cl_qcpool_construct is a prerequisite to calling any other 364219820Sjeff* quick composite pool function except cl_qcpool_init. 365219820Sjeff* 366219820Sjeff* SEE ALSO 367219820Sjeff* Quick Composite Pool, cl_qcpool_init, cl_qcpool_destroy, 368219820Sjeff* cl_is_qcpool_inited 369219820Sjeff*********/ 370219820Sjeff 371219820Sjeff/****f* Component Library: Quick Composite Pool/cl_is_qcpool_inited 372219820Sjeff* NAME 373219820Sjeff* cl_is_qcpool_inited 374219820Sjeff* 375219820Sjeff* DESCRIPTION 376219820Sjeff* The cl_is_qcpool_inited function returns whether a quick composite pool was 377219820Sjeff* successfully initialized. 378219820Sjeff* 379219820Sjeff* SYNOPSIS 380219820Sjeff*/ 381219820Sjeffstatic inline uint32_t cl_is_qcpool_inited(IN const cl_qcpool_t * const p_pool) 382219820Sjeff{ 383219820Sjeff /* CL_ASSERT that a non-null pointer is provided. */ 384219820Sjeff CL_ASSERT(p_pool); 385219820Sjeff /* CL_ASSERT that the pool is not in some invalid state. */ 386219820Sjeff CL_ASSERT(cl_is_state_valid(p_pool->state)); 387219820Sjeff 388219820Sjeff return (p_pool->state == CL_INITIALIZED); 389219820Sjeff} 390219820Sjeff 391219820Sjeff/* 392219820Sjeff* PARAMETERS 393219820Sjeff* p_pool 394219820Sjeff* [in] Pointer to a cl_qcpool_t structure to check. 395219820Sjeff* 396219820Sjeff* RETURN VALUES 397219820Sjeff* TRUE if the quick composite pool was initialized successfully. 398219820Sjeff* 399219820Sjeff* FALSE otherwise. 400219820Sjeff* 401219820Sjeff* NOTES 402219820Sjeff* Allows checking the state of a quick composite pool to determine if 403219820Sjeff* invoking member functions is appropriate. 404219820Sjeff* 405219820Sjeff* SEE ALSO 406219820Sjeff* Quick Composite Pool 407219820Sjeff*********/ 408219820Sjeff 409219820Sjeff/****f* Component Library: Quick Composite Pool/cl_qcpool_init 410219820Sjeff* NAME 411219820Sjeff* cl_qcpool_init 412219820Sjeff* 413219820Sjeff* DESCRIPTION 414219820Sjeff* The cl_qcpool_init function initializes a quick composite pool for use. 415219820Sjeff* 416219820Sjeff* SYNOPSIS 417219820Sjeff*/ 418219820Sjeffcl_status_t 419219820Sjeffcl_qcpool_init(IN cl_qcpool_t * const p_pool, 420219820Sjeff IN const size_t min_size, 421219820Sjeff IN const size_t max_size, 422219820Sjeff IN const size_t grow_size, 423219820Sjeff IN const size_t * const component_sizes, 424219820Sjeff IN const uint32_t num_components, 425219820Sjeff IN cl_pfn_qcpool_init_t pfn_initializer OPTIONAL, 426219820Sjeff IN cl_pfn_qcpool_dtor_t pfn_destructor OPTIONAL, 427219820Sjeff IN const void *const context); 428219820Sjeff/* 429219820Sjeff* PARAMETERS 430219820Sjeff* p_pool 431219820Sjeff* [in] Pointer to a cl_qcpool_t structure to initialize. 432219820Sjeff* 433219820Sjeff* min_size 434219820Sjeff* [in] Minimum number of objects that the pool should support. All 435219820Sjeff* necessary allocations to allow storing the minimum number of items 436219820Sjeff* are performed at initialization time, and all necessary callbacks 437219820Sjeff* successfully invoked. 438219820Sjeff* 439219820Sjeff* max_size 440219820Sjeff* [in] Maximum number of objects to which the pool is allowed to grow. 441219820Sjeff* A value of zero specifies no maximum. 442219820Sjeff* 443219820Sjeff* grow_size 444219820Sjeff* [in] Number of objects to allocate when incrementally growing the pool. 445219820Sjeff* A value of zero disables automatic growth. 446219820Sjeff* 447219820Sjeff* component_sizes 448219820Sjeff* [in] Pointer to the first entry in an array of sizes describing, 449219820Sjeff* in order, the sizes of the components that make up a composite object. 450219820Sjeff* 451219820Sjeff* num_components 452219820Sjeff* [in] Number of components that make up a composite object. 453219820Sjeff* 454219820Sjeff* pfn_initializer 455219820Sjeff* [in] Initializer callback to invoke for every new object when growing 456219820Sjeff* the pool. This parameter may be NULL only if the objects stored in 457219820Sjeff* the quick composite pool consist of only one component. If NULL, the 458219820Sjeff* pool assumes the cl_pool_item_t structure describing objects is 459219820Sjeff* located at the head of each object. See the cl_pfn_qcpool_init_t 460219820Sjeff* function type declaration for details about the callback function. 461219820Sjeff* 462219820Sjeff* pfn_destructor 463219820Sjeff* [in] Destructor callback to invoke for every object before memory for 464219820Sjeff* that object is freed. This parameter is optional and may be NULL. 465219820Sjeff* See the cl_pfn_qcpool_dtor_t function type declaration for details 466219820Sjeff* about the callback function. 467219820Sjeff* 468219820Sjeff* context 469219820Sjeff* [in] Value to pass to the callback functions to provide context. 470219820Sjeff* 471219820Sjeff* RETURN VALUES 472219820Sjeff* CL_SUCCESS if the quick composite pool was initialized successfully. 473219820Sjeff* 474219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize the 475219820Sjeff* quick composite pool. 476219820Sjeff* 477219820Sjeff* CL_INVALID_SETTING if a NULL constructor was provided for composite objects 478219820Sjeff* consisting of more than one component. Also returns CL_INVALID_SETTING if 479219820Sjeff* the maximum size is non-zero and less than the minimum size. 480219820Sjeff* 481219820Sjeff* Other cl_status_t value returned by optional initialization callback function 482219820Sjeff* specified by the pfn_initializer parameter. 483219820Sjeff* 484219820Sjeff* If initialization fails, the pool is left in a destroyed state. Callers 485219820Sjeff* may still safely call cl_qcpool_destroy. 486219820Sjeff* 487219820Sjeff* NOTES 488219820Sjeff* cl_qcpool_init initializes, and if necessary, grows the pool to 489219820Sjeff* the capacity desired. 490219820Sjeff* 491219820Sjeff* SEE ALSO 492219820Sjeff* Quick Composite Pool, cl_qcpool_construct, cl_qcpool_destroy, 493219820Sjeff* cl_qcpool_get, cl_qcpool_put, cl_qcpool_grow, 494219820Sjeff* cl_qcpool_count, cl_pfn_qcpool_init_t, cl_pfn_qcpool_dtor_t 495219820Sjeff*********/ 496219820Sjeff 497219820Sjeff/****f* Component Library: Quick Composite Pool/cl_qcpool_destroy 498219820Sjeff* NAME 499219820Sjeff* cl_qcpool_destroy 500219820Sjeff* 501219820Sjeff* DESCRIPTION 502219820Sjeff* The cl_qcpool_destroy function destroys a quick composite pool. 503219820Sjeff* 504219820Sjeff* SYNOPSIS 505219820Sjeff*/ 506219820Sjeffvoid cl_qcpool_destroy(IN cl_qcpool_t * const p_pool); 507219820Sjeff/* 508219820Sjeff* PARAMETERS 509219820Sjeff* p_pool 510219820Sjeff* [in] Pointer to a cl_qcpool_t structure to destroy. 511219820Sjeff* 512219820Sjeff* RETURN VALUE 513219820Sjeff* This function does not return a value. 514219820Sjeff* 515219820Sjeff* NOTES 516219820Sjeff* All memory allocated for composite objects is freed. The destructor 517219820Sjeff* callback, if any, will be invoked for every allocated object. Further 518219820Sjeff* operations on the composite pool should not be attempted after 519219820Sjeff* cl_qcpool_destroy is invoked. 520219820Sjeff* 521219820Sjeff* This function should only be called after a call to 522219820Sjeff* cl_qcpool_construct or cl_qcpool_init. 523219820Sjeff* 524219820Sjeff* In a debug build, cl_qcpool_destroy asserts that all objects are in 525219820Sjeff* the pool. 526219820Sjeff* 527219820Sjeff* SEE ALSO 528219820Sjeff* Quick Composite Pool, cl_qcpool_construct, cl_qcpool_init 529219820Sjeff*********/ 530219820Sjeff 531219820Sjeff/****f* Component Library: Quick Composite Pool/cl_qcpool_count 532219820Sjeff* NAME 533219820Sjeff* cl_qcpool_count 534219820Sjeff* 535219820Sjeff* DESCRIPTION 536219820Sjeff* The cl_qcpool_count function returns the number of available objects 537219820Sjeff* in a quick composite pool. 538219820Sjeff* 539219820Sjeff* SYNOPSIS 540219820Sjeff*/ 541219820Sjeffstatic inline size_t cl_qcpool_count(IN cl_qcpool_t * const p_pool) 542219820Sjeff{ 543219820Sjeff CL_ASSERT(p_pool); 544219820Sjeff CL_ASSERT(p_pool->state == CL_INITIALIZED); 545219820Sjeff 546219820Sjeff return (cl_qlist_count(&p_pool->free_list)); 547219820Sjeff} 548219820Sjeff 549219820Sjeff/* 550219820Sjeff* PARAMETERS 551219820Sjeff* p_pool 552219820Sjeff* [in] Pointer to a cl_qcpool_t structure for which the number of 553219820Sjeff* available objects is requested. 554219820Sjeff* 555219820Sjeff* RETURN VALUE 556219820Sjeff* Returns the number of objects available in the specified 557219820Sjeff* quick composite pool. 558219820Sjeff* 559219820Sjeff* SEE ALSO 560219820Sjeff* Quick Composite Pool 561219820Sjeff*********/ 562219820Sjeff 563219820Sjeff/****f* Component Library: Quick Composite Pool/cl_qcpool_get 564219820Sjeff* NAME 565219820Sjeff* cl_qcpool_get 566219820Sjeff* 567219820Sjeff* DESCRIPTION 568219820Sjeff* The cl_qcpool_get function retrieves an object from a 569219820Sjeff* quick composite pool. 570219820Sjeff* 571219820Sjeff* SYNOPSIS 572219820Sjeff*/ 573219820Sjeffcl_pool_item_t *cl_qcpool_get(IN cl_qcpool_t * const p_pool); 574219820Sjeff/* 575219820Sjeff* PARAMETERS 576219820Sjeff* p_pool 577219820Sjeff* [in] Pointer to a cl_qcpool_t structure from which to retrieve 578219820Sjeff* an object. 579219820Sjeff* 580219820Sjeff* RETURN VALUES 581219820Sjeff* Returns a pointer to a cl_pool_item_t for a composite object. 582219820Sjeff* 583219820Sjeff* Returns NULL if the pool is empty and can not be grown automatically. 584219820Sjeff* 585219820Sjeff* NOTES 586219820Sjeff* cl_qcpool_get returns the object at the head of the pool. If the pool is 587219820Sjeff* empty, it is automatically grown to accommodate this request unless the 588219820Sjeff* grow_size parameter passed to the cl_qcpool_init function was zero. 589219820Sjeff* 590219820Sjeff* SEE ALSO 591219820Sjeff* Quick Composite Pool, cl_qcpool_get_tail, cl_qcpool_put, 592219820Sjeff* cl_qcpool_grow, cl_qcpool_count 593219820Sjeff*********/ 594219820Sjeff 595219820Sjeff/****f* Component Library: Quick Composite Pool/cl_qcpool_put 596219820Sjeff* NAME 597219820Sjeff* cl_qcpool_put 598219820Sjeff* 599219820Sjeff* DESCRIPTION 600219820Sjeff* The cl_qcpool_put function returns an object to a quick composite pool. 601219820Sjeff* 602219820Sjeff* SYNOPSIS 603219820Sjeff*/ 604219820Sjeffstatic inline void 605219820Sjeffcl_qcpool_put(IN cl_qcpool_t * const p_pool, 606219820Sjeff IN cl_pool_item_t * const p_pool_item) 607219820Sjeff{ 608219820Sjeff CL_ASSERT(p_pool); 609219820Sjeff CL_ASSERT(p_pool->state == CL_INITIALIZED); 610219820Sjeff CL_ASSERT(p_pool_item); 611219820Sjeff /* Make sure items being returned came from the specified pool. */ 612219820Sjeff CL_ASSERT(p_pool_item->p_pool == p_pool); 613219820Sjeff 614219820Sjeff /* return this lil' doggy to the pool */ 615219820Sjeff cl_qlist_insert_head(&p_pool->free_list, &p_pool_item->list_item); 616219820Sjeff} 617219820Sjeff 618219820Sjeff/* 619219820Sjeff* PARAMETERS 620219820Sjeff* p_pool 621219820Sjeff* [in] Pointer to a cl_qcpool_t structure to which to return 622219820Sjeff* an object. 623219820Sjeff* 624219820Sjeff* p_pool_item 625219820Sjeff* [in] Pointer to a cl_pool_item_t structure for the object 626219820Sjeff* being returned. 627219820Sjeff* 628219820Sjeff* RETURN VALUE 629219820Sjeff* This function does not return a value. 630219820Sjeff* 631219820Sjeff* NOTES 632219820Sjeff* cl_qcpool_put places the returned object at the head of the pool. 633219820Sjeff* 634219820Sjeff* The object specified by the p_pool_item parameter must have been 635219820Sjeff* retrieved from the pool by a previous call to cl_qcpool_get. 636219820Sjeff* 637219820Sjeff* SEE ALSO 638219820Sjeff* Quick Composite Pool, cl_qcpool_put_tail, cl_qcpool_get 639219820Sjeff*********/ 640219820Sjeff 641219820Sjeff/****f* Component Library: Quick Composite Pool/cl_qcpool_put_list 642219820Sjeff* NAME 643219820Sjeff* cl_qcpool_put_list 644219820Sjeff* 645219820Sjeff* DESCRIPTION 646219820Sjeff* The cl_qcpool_put_list function returns a list of objects to the head of 647219820Sjeff* a quick composite pool. 648219820Sjeff* 649219820Sjeff* SYNOPSIS 650219820Sjeff*/ 651219820Sjeffstatic inline void 652219820Sjeffcl_qcpool_put_list(IN cl_qcpool_t * const p_pool, IN cl_qlist_t * const p_list) 653219820Sjeff{ 654219820Sjeff#ifdef _DEBUG_ 655219820Sjeff cl_list_item_t *p_item; 656219820Sjeff#endif 657219820Sjeff 658219820Sjeff CL_ASSERT(p_pool); 659219820Sjeff CL_ASSERT(p_pool->state == CL_INITIALIZED); 660219820Sjeff CL_ASSERT(p_list); 661219820Sjeff 662219820Sjeff#ifdef _DEBUG_ 663219820Sjeff /* Chech that all items in the list came from this pool. */ 664219820Sjeff p_item = cl_qlist_head(p_list); 665219820Sjeff while (p_item != cl_qlist_end(p_list)) { 666219820Sjeff CL_ASSERT(((cl_pool_item_t *) p_item)->p_pool == p_pool); 667219820Sjeff p_item = cl_qlist_next(p_item); 668219820Sjeff } 669219820Sjeff#endif 670219820Sjeff 671219820Sjeff /* return these lil' doggies to the pool */ 672219820Sjeff cl_qlist_insert_list_head(&p_pool->free_list, p_list); 673219820Sjeff} 674219820Sjeff 675219820Sjeff/* 676219820Sjeff* PARAMETERS 677219820Sjeff* p_pool 678219820Sjeff* [in] Pointer to a cl_qcpool_t structure to which to return 679219820Sjeff* a list of objects. 680219820Sjeff* 681219820Sjeff* p_list 682219820Sjeff* [in] Pointer to a cl_qlist_t structure for the list of objects 683219820Sjeff* being returned. 684219820Sjeff* 685219820Sjeff* RETURN VALUE 686219820Sjeff* This function does not return a value. 687219820Sjeff* 688219820Sjeff* NOTES 689219820Sjeff* cl_qcpool_put_list places the returned objects at the head of the pool. 690219820Sjeff* 691219820Sjeff* The objects in the list specified by the p_list parameter must have been 692219820Sjeff* retrieved from the pool by a previous call to cl_qcpool_get. 693219820Sjeff* 694219820Sjeff* SEE ALSO 695219820Sjeff* Quick Composite Pool, cl_qcpool_put, cl_qcpool_put_tail, cl_qcpool_get 696219820Sjeff*********/ 697219820Sjeff 698219820Sjeff/****f* Component Library: Quick Composite Pool/cl_qcpool_grow 699219820Sjeff* NAME 700219820Sjeff* cl_qcpool_grow 701219820Sjeff* 702219820Sjeff* DESCRIPTION 703219820Sjeff* The cl_qcpool_grow function grows a quick composite pool by 704219820Sjeff* the specified number of objects. 705219820Sjeff* 706219820Sjeff* SYNOPSIS 707219820Sjeff*/ 708219820Sjeffcl_status_t cl_qcpool_grow(IN cl_qcpool_t * const p_pool, IN size_t obj_count); 709219820Sjeff/* 710219820Sjeff* PARAMETERS 711219820Sjeff* p_pool 712219820Sjeff* [in] Pointer to a cl_qcpool_t structure whose capacity to grow. 713219820Sjeff* 714219820Sjeff* obj_count 715219820Sjeff* [in] Number of objects by which to grow the pool. 716219820Sjeff* 717219820Sjeff* RETURN VALUES 718219820Sjeff* CL_SUCCESS if the quick composite pool grew successfully. 719219820Sjeff* 720219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to grow the 721219820Sjeff* quick composite pool. 722219820Sjeff* 723219820Sjeff* cl_status_t value returned by optional initialization callback function 724219820Sjeff* specified by the pfn_initializer parameter passed to the 725219820Sjeff* cl_qcpool_init function. 726219820Sjeff* 727219820Sjeff* NOTES 728219820Sjeff* It is not necessary to call cl_qcpool_grow if the pool is 729219820Sjeff* configured to grow automatically. 730219820Sjeff* 731219820Sjeff* SEE ALSO 732219820Sjeff* Quick Composite Pool 733219820Sjeff*********/ 734219820Sjeff 735219820SjeffEND_C_DECLS 736219820Sjeff#endif /* _CL_QUICK_COMPOSITE_POOL_H_ */ 737