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 * This file contains pointer vector definitions. Pointer Vector provides 39219820Sjeff * dynmically resizable array functionality. 40219820Sjeff */ 41219820Sjeff 42219820Sjeff#ifndef _CL_PTR_VECTOR_H_ 43219820Sjeff#define _CL_PTR_VECTOR_H_ 44219820Sjeff 45219820Sjeff#include <complib/cl_types.h> 46219820Sjeff 47219820Sjeff#ifdef __cplusplus 48219820Sjeff# define BEGIN_C_DECLS extern "C" { 49219820Sjeff# define END_C_DECLS } 50219820Sjeff#else /* !__cplusplus */ 51219820Sjeff# define BEGIN_C_DECLS 52219820Sjeff# define END_C_DECLS 53219820Sjeff#endif /* __cplusplus */ 54219820Sjeff 55219820SjeffBEGIN_C_DECLS 56219820Sjeff/****h* Component Library/Pointer Vector 57219820Sjeff* NAME 58219820Sjeff* Pointer Vector 59219820Sjeff* 60219820Sjeff* DESCRIPTION 61219820Sjeff* The Pointer Vector is a self-sizing array of pointers. Like a traditonal 62219820Sjeff* array, a pointer vector allows efficient constant time access to elements 63219820Sjeff* with a specified index. A pointer vector grows transparently as the 64219820Sjeff* user adds elements to the array. 65219820Sjeff* 66219820Sjeff* The cl_pointer vector_t structure should be treated as opaque and should be 67219820Sjeff* manipulated only through the provided functions. 68219820Sjeff* 69219820Sjeff* SEE ALSO 70219820Sjeff* Structures: 71219820Sjeff* cl_ptr_vector_t 72219820Sjeff* 73219820Sjeff* Callbacks: 74219820Sjeff* cl_pfn_ptr_vec_apply_t, cl_pfn_ptr_vec_find_t 75219820Sjeff* 76219820Sjeff* Item Manipulation: 77219820Sjeff* cl_ptr_vector_set, cl_ptr_vector_obj 78219820Sjeff* 79219820Sjeff* Initialization: 80219820Sjeff* cl_ptr_vector_construct, cl_ptr_vector_init, cl_ptr_vector_destroy 81219820Sjeff* 82219820Sjeff* Manipulation: 83219820Sjeff* cl_ptr_vector_get_capacity, cl_ptr_vector_set_capacity, 84219820Sjeff* cl_ptr_vector_get_size, cl_ptr_vector_set_size, cl_ptr_vector_set_min_size 85219820Sjeff* cl_ptr_vector_get_ptr, cl_ptr_vector_get, cl_ptr_vector_at, cl_ptr_vector_set 86219820Sjeff* 87219820Sjeff* Search: 88219820Sjeff* cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end 89219820Sjeff* cl_ptr_vector_apply_func 90219820Sjeff*********/ 91219820Sjeff/****d* Component Library: Pointer Vector/cl_pfn_ptr_vec_apply_t 92219820Sjeff* NAME 93219820Sjeff* cl_pfn_ptr_vec_apply_t 94219820Sjeff* 95219820Sjeff* DESCRIPTION 96219820Sjeff* The cl_pfn_ptr_vec_apply_t function type defines the prototype for 97219820Sjeff* functions used to iterate elements in a pointer vector. 98219820Sjeff* 99219820Sjeff* SYNOPSIS 100219820Sjeff*/ 101219820Sjefftypedef void 102219820Sjeff (*cl_pfn_ptr_vec_apply_t) (IN const size_t index, 103219820Sjeff IN void *const element, IN void *context); 104219820Sjeff/* 105219820Sjeff* PARAMETERS 106219820Sjeff* index 107219820Sjeff* [in] Index of the element. 108219820Sjeff* 109219820Sjeff* p_element 110219820Sjeff* [in] Pointer to an element at the specified index in the pointer vector. 111219820Sjeff* 112219820Sjeff* context 113219820Sjeff* [in] Context provided in a call to cl_ptr_vector_apply_func. 114219820Sjeff* 115219820Sjeff* RETURN VALUE 116219820Sjeff* This function does not return a value. 117219820Sjeff* 118219820Sjeff* NOTES 119219820Sjeff* This function type is provided as function prototype reference for 120219820Sjeff* the function passed by users as a parameter to the cl_ptr_vector_apply_func 121219820Sjeff* function. 122219820Sjeff* 123219820Sjeff* SEE ALSO 124219820Sjeff* Pointer Vector, cl_ptr_vector_apply_func 125219820Sjeff*********/ 126219820Sjeff 127219820Sjeff/****d* Component Library: Pointer Vector/cl_pfn_ptr_vec_find_t 128219820Sjeff* NAME 129219820Sjeff* cl_pfn_ptr_vec_find_t 130219820Sjeff* 131219820Sjeff* DESCRIPTION 132219820Sjeff* The cl_pfn_ptr_vec_find_t function type defines the prototype for 133219820Sjeff* functions used to find elements in a pointer vector. 134219820Sjeff* 135219820Sjeff* SYNOPSIS 136219820Sjeff*/ 137219820Sjefftypedef cl_status_t 138219820Sjeff (*cl_pfn_ptr_vec_find_t) (IN const size_t index, 139219820Sjeff IN const void *const element, IN void *context); 140219820Sjeff/* 141219820Sjeff* PARAMETERS 142219820Sjeff* index 143219820Sjeff* [in] Index of the element. 144219820Sjeff* 145219820Sjeff* p_element 146219820Sjeff* [in] Pointer to an element at the specified index in the 147219820Sjeff* pointer vector. 148219820Sjeff* 149219820Sjeff* context 150219820Sjeff* [in] Context provided in a call to cl_ptr_vector_find_from_start or 151219820Sjeff* cl_ptr_vector_find_from_end. 152219820Sjeff* 153219820Sjeff* RETURN VALUES 154219820Sjeff* Return CL_SUCCESS if the element was found. This stops pointer vector 155219820Sjeff* iteration. 156219820Sjeff* 157219820Sjeff* CL_NOT_FOUND to continue the pointer vector iteration. 158219820Sjeff* 159219820Sjeff* NOTES 160219820Sjeff* This function type is provided as function prototype reference for the 161219820Sjeff* function provided by users as a parameter to the 162219820Sjeff* cl_ptr_vector_find_from_start and cl_ptr_vector_find_from_end functions. 163219820Sjeff* 164219820Sjeff* SEE ALSO 165219820Sjeff* Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end 166219820Sjeff*********/ 167219820Sjeff 168219820Sjeff/****s* Component Library: Pointer Vector/cl_ptr_vector_t 169219820Sjeff* NAME 170219820Sjeff* cl_ptr_vector_t 171219820Sjeff* 172219820Sjeff* DESCRIPTION 173219820Sjeff* Pointer Vector structure. 174219820Sjeff* 175219820Sjeff* The cl_ptr_vector_t structure should be treated as opaque and should be 176219820Sjeff* manipulated only through the provided functions. 177219820Sjeff* 178219820Sjeff* SYNOPSIS 179219820Sjeff*/ 180219820Sjefftypedef struct _cl_ptr_vector { 181219820Sjeff size_t size; 182219820Sjeff size_t grow_size; 183219820Sjeff size_t capacity; 184219820Sjeff const void **p_ptr_array; 185219820Sjeff cl_state_t state; 186219820Sjeff} cl_ptr_vector_t; 187219820Sjeff/* 188219820Sjeff* FIELDS 189219820Sjeff* size 190219820Sjeff* Number of elements successfully initialized in the pointer vector. 191219820Sjeff* 192219820Sjeff* grow_size 193219820Sjeff* Number of elements to allocate when growing. 194219820Sjeff* 195219820Sjeff* capacity 196219820Sjeff* total # of elements allocated. 197219820Sjeff* 198219820Sjeff* alloc_list 199219820Sjeff* List of allocations. 200219820Sjeff* 201219820Sjeff* p_ptr_array 202219820Sjeff* Internal array of pointers to elements. 203219820Sjeff* 204219820Sjeff* state 205219820Sjeff* State of the pointer vector. 206219820Sjeff* 207219820Sjeff* SEE ALSO 208219820Sjeff* Pointer Vector 209219820Sjeff*********/ 210219820Sjeff 211219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_construct 212219820Sjeff* NAME 213219820Sjeff* cl_ptr_vector_construct 214219820Sjeff* 215219820Sjeff* DESCRIPTION 216219820Sjeff* The cl_ptr_vector_construct function constructs a pointer vector. 217219820Sjeff* 218219820Sjeff* SYNOPSIS 219219820Sjeff*/ 220219820Sjeffvoid cl_ptr_vector_construct(IN cl_ptr_vector_t * const p_vector); 221219820Sjeff/* 222219820Sjeff* PARAMETERS 223219820Sjeff* p_vector 224219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure to construct. 225219820Sjeff* 226219820Sjeff* RETURN VALUE 227219820Sjeff* This function does not return a value. 228219820Sjeff* 229219820Sjeff* NOTES 230219820Sjeff* Allows calling cl_ptr_vector_destroy without first calling 231219820Sjeff* cl_ptr_vector_init. 232219820Sjeff* 233219820Sjeff* Calling cl_ptr_vector_construct is a prerequisite to calling any other 234219820Sjeff* pointer vector function except cl_ptr_vector_init. 235219820Sjeff* 236219820Sjeff* SEE ALSO 237219820Sjeff* Pointer Vector, cl_ptr_vector_init, cl_ptr_vector_destroy 238219820Sjeff*********/ 239219820Sjeff 240219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_init 241219820Sjeff* NAME 242219820Sjeff* cl_ptr_vector_init 243219820Sjeff* 244219820Sjeff* DESCRIPTION 245219820Sjeff* The cl_ptr_vector_init function initializes a pointer vector for use. 246219820Sjeff* 247219820Sjeff* SYNOPSIS 248219820Sjeff*/ 249219820Sjeffcl_status_t 250219820Sjeffcl_ptr_vector_init(IN cl_ptr_vector_t * const p_vector, 251219820Sjeff IN const size_t min_size, IN const size_t grow_size); 252219820Sjeff/* 253219820Sjeff* PARAMETERS 254219820Sjeff* p_vector 255219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure to inititalize. 256219820Sjeff* 257219820Sjeff* initial_size 258219820Sjeff* [in] Initial number of elements. 259219820Sjeff* 260219820Sjeff* grow_size 261219820Sjeff* [in] Number of elements to allocate when incrementally growing 262219820Sjeff* the pointer vector. A value of zero disables automatic growth. 263219820Sjeff* 264219820Sjeff* RETURN VALUES 265219820Sjeff* CL_SUCCESS if the pointer vector was initialized successfully. 266219820Sjeff* 267219820Sjeff* CL_INSUFFICIENT_MEMORY if the initialization failed. 268219820Sjeff* 269219820Sjeff* SEE ALSO 270219820Sjeff* Pointer Vector, cl_ptr_vector_construct, cl_ptr_vector_destroy, 271219820Sjeff* cl_ptr_vector_set, cl_ptr_vector_get, cl_ptr_vector_at 272219820Sjeff*********/ 273219820Sjeff 274219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_destroy 275219820Sjeff* NAME 276219820Sjeff* cl_ptr_vector_destroy 277219820Sjeff* 278219820Sjeff* DESCRIPTION 279219820Sjeff* The cl_ptr_vector_destroy function destroys a pointer vector. 280219820Sjeff* 281219820Sjeff* SYNOPSIS 282219820Sjeff*/ 283219820Sjeffvoid cl_ptr_vector_destroy(IN cl_ptr_vector_t * const p_vector); 284219820Sjeff/* 285219820Sjeff* PARAMETERS 286219820Sjeff* p_vector 287219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure to destroy. 288219820Sjeff* 289219820Sjeff* RETURN VALUE 290219820Sjeff* This function does not return a value. 291219820Sjeff* 292219820Sjeff* NOTES 293219820Sjeff* cl_ptr_vector_destroy frees all memory allocated for the pointer vector. 294219820Sjeff* 295219820Sjeff* This function should only be called after a call to cl_ptr_vector_construct 296219820Sjeff* or cl_ptr_vector_init. 297219820Sjeff* 298219820Sjeff* SEE ALSO 299219820Sjeff* Pointer Vector, cl_ptr_vector_construct, cl_ptr_vector_init 300219820Sjeff*********/ 301219820Sjeff 302219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_get_capacity 303219820Sjeff* NAME 304219820Sjeff* cl_ptr_vector_get_capacity 305219820Sjeff* 306219820Sjeff* DESCRIPTION 307219820Sjeff* The cl_ptr_vector_get_capacity function returns the capacity of 308219820Sjeff* a pointer vector. 309219820Sjeff* 310219820Sjeff* SYNOPSIS 311219820Sjeff*/ 312219820Sjeffstatic inline size_t 313219820Sjeffcl_ptr_vector_get_capacity(IN const cl_ptr_vector_t * const p_vector) 314219820Sjeff{ 315219820Sjeff CL_ASSERT(p_vector); 316219820Sjeff CL_ASSERT(p_vector->state == CL_INITIALIZED); 317219820Sjeff 318219820Sjeff return (p_vector->capacity); 319219820Sjeff} 320219820Sjeff 321219820Sjeff/* 322219820Sjeff* PARAMETERS 323219820Sjeff* p_vector 324219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure whose capacity to return. 325219820Sjeff* 326219820Sjeff* RETURN VALUE 327219820Sjeff* Capacity, in elements, of the pointer vector. 328219820Sjeff* 329219820Sjeff* NOTES 330219820Sjeff* The capacity is the number of elements that the pointer vector can store, 331219820Sjeff* and can be greater than the number of elements stored. To get the number 332219820Sjeff* of elements stored in the pointer vector, use cl_ptr_vector_get_size. 333219820Sjeff* 334219820Sjeff* SEE ALSO 335219820Sjeff* Pointer Vector, cl_ptr_vector_set_capacity, cl_ptr_vector_get_size 336219820Sjeff*********/ 337219820Sjeff 338219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_get_size 339219820Sjeff* NAME 340219820Sjeff* cl_ptr_vector_get_size 341219820Sjeff* 342219820Sjeff* DESCRIPTION 343219820Sjeff* The cl_ptr_vector_get_size function returns the size of a pointer vector. 344219820Sjeff* 345219820Sjeff* SYNOPSIS 346219820Sjeff*/ 347219820Sjeffstatic inline uint32_t 348219820Sjeffcl_ptr_vector_get_size(IN const cl_ptr_vector_t * const p_vector) 349219820Sjeff{ 350219820Sjeff CL_ASSERT(p_vector); 351219820Sjeff CL_ASSERT(p_vector->state == CL_INITIALIZED); 352219820Sjeff return ((uint32_t) p_vector->size); 353219820Sjeff 354219820Sjeff} 355219820Sjeff 356219820Sjeff/* 357219820Sjeff* PARAMETERS 358219820Sjeff* p_vector 359219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure whose size to return. 360219820Sjeff* 361219820Sjeff* RETURN VALUE 362219820Sjeff* Size, in elements, of the pointer vector. 363219820Sjeff* 364219820Sjeff* SEE ALSO 365219820Sjeff* Pointer Vector, cl_ptr_vector_set_size, cl_ptr_vector_get_capacity 366219820Sjeff*********/ 367219820Sjeff 368219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_get 369219820Sjeff* NAME 370219820Sjeff* cl_ptr_vector_get 371219820Sjeff* 372219820Sjeff* DESCRIPTION 373219820Sjeff* The cl_ptr_vector_get function returns the pointer stored in a 374219820Sjeff* pointer vector at a specified index. 375219820Sjeff* 376219820Sjeff* SYNOPSIS 377219820Sjeff*/ 378219820Sjeffstatic inline void *cl_ptr_vector_get(IN const cl_ptr_vector_t * const p_vector, 379219820Sjeff IN const size_t index) 380219820Sjeff{ 381219820Sjeff CL_ASSERT(p_vector); 382219820Sjeff CL_ASSERT(p_vector->state == CL_INITIALIZED); 383219820Sjeff CL_ASSERT(p_vector->size > index); 384219820Sjeff 385219820Sjeff return ((void *)p_vector->p_ptr_array[index]); 386219820Sjeff} 387219820Sjeff 388219820Sjeff/* 389219820Sjeff* PARAMETERS 390219820Sjeff* p_vector 391219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure from which to get an 392219820Sjeff* element. 393219820Sjeff* 394219820Sjeff* index 395219820Sjeff* [in] Index of the element. 396219820Sjeff* 397219820Sjeff* RETURN VALUE 398219820Sjeff* Value of the pointer stored at the specified index. 399219820Sjeff* 400219820Sjeff* NOTES 401219820Sjeff* cl_ptr_vector_get provides constant access times regardless of the index. 402219820Sjeff* 403219820Sjeff* cl_ptr_vector_get does not perform boundary checking. Callers are 404219820Sjeff* responsible for providing an index that is within the range of the pointer 405219820Sjeff* vector. 406219820Sjeff* 407219820Sjeff* SEE ALSO 408219820Sjeff* Pointer Vector, cl_ptr_vector_at, cl_ptr_vector_set, cl_ptr_vector_get_size 409219820Sjeff*********/ 410219820Sjeff 411219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_at 412219820Sjeff* NAME 413219820Sjeff* cl_ptr_vector_at 414219820Sjeff* 415219820Sjeff* DESCRIPTION 416219820Sjeff* The cl_ptr_vector_at function copies an element stored in a pointer 417219820Sjeff* vector at a specified index, performing boundary checks. 418219820Sjeff* 419219820Sjeff* SYNOPSIS 420219820Sjeff*/ 421219820Sjeffcl_status_t 422219820Sjeffcl_ptr_vector_at(IN const cl_ptr_vector_t * const p_vector, 423219820Sjeff IN const size_t index, OUT void **const p_element); 424219820Sjeff/* 425219820Sjeff* PARAMETERS 426219820Sjeff* p_vector 427219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure from which to get a copy of 428219820Sjeff* an element. 429219820Sjeff* 430219820Sjeff* index 431219820Sjeff* [in] Index of the element. 432219820Sjeff* 433219820Sjeff* p_element 434219820Sjeff* [out] Pointer to storage for the pointer element. Contains a copy of 435219820Sjeff* the desired pointer upon successful completion of the call. 436219820Sjeff* 437219820Sjeff* RETURN VALUES 438219820Sjeff* CL_SUCCESS if an element was found at the specified index. 439219820Sjeff* 440219820Sjeff* CL_INVALID_SETTING if the index was out of range. 441219820Sjeff* 442219820Sjeff* NOTES 443219820Sjeff* cl_ptr_vector_at provides constant time access regardless of 444219820Sjeff* the index, and performs boundary checking on the pointer vector. 445219820Sjeff* 446219820Sjeff* Upon success, the p_element parameter contains a copy of the 447219820Sjeff* desired element. 448219820Sjeff* 449219820Sjeff* SEE ALSO 450219820Sjeff* Pointer Vector, cl_ptr_vector_get 451219820Sjeff*********/ 452219820Sjeff 453219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_set 454219820Sjeff* NAME 455219820Sjeff* cl_ptr_vector_set 456219820Sjeff* 457219820Sjeff* DESCRIPTION 458219820Sjeff* The cl_ptr_vector_set function sets the element at the specified index. 459219820Sjeff* 460219820Sjeff* SYNOPSIS 461219820Sjeff*/ 462219820Sjeffcl_status_t 463219820Sjeffcl_ptr_vector_set(IN cl_ptr_vector_t * const p_vector, 464219820Sjeff IN const size_t index, IN const void *const element); 465219820Sjeff/* 466219820Sjeff* PARAMETERS 467219820Sjeff* p_vector 468219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure into which to store 469219820Sjeff* an element. 470219820Sjeff* 471219820Sjeff* index 472219820Sjeff* [in] Index of the element. 473219820Sjeff* 474219820Sjeff* element 475219820Sjeff* [in] Pointer to store in the pointer vector. 476219820Sjeff* 477219820Sjeff* RETURN VALUES 478219820Sjeff* CL_SUCCESS if the element was successfully set. 479219820Sjeff* 480219820Sjeff* CL_INSUFFICIENT_MEMORY if the pointer vector could not be resized to 481219820Sjeff* accommodate the new element. 482219820Sjeff* 483219820Sjeff* NOTES 484219820Sjeff* cl_ptr_vector_set grows the pointer vector as needed to accommodate 485219820Sjeff* the new element, unless the grow_size parameter passed into the 486219820Sjeff* cl_ptr_vector_init function was zero. 487219820Sjeff* 488219820Sjeff* SEE ALSO 489219820Sjeff* Pointer Vector, cl_ptr_vector_get 490219820Sjeff*********/ 491219820Sjeff 492219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_insert 493219820Sjeff* NAME 494219820Sjeff* cl_ptr_vector_insert 495219820Sjeff* 496219820Sjeff* DESCRIPTION 497219820Sjeff* The cl_ptr_vector_insert function inserts an element into a pointer vector. 498219820Sjeff* 499219820Sjeff* SYNOPSIS 500219820Sjeff*/ 501219820Sjeffstatic inline cl_status_t 502219820Sjeffcl_ptr_vector_insert(IN cl_ptr_vector_t * const p_vector, 503219820Sjeff IN const void *const element, 504219820Sjeff OUT size_t * const p_index OPTIONAL) 505219820Sjeff{ 506219820Sjeff cl_status_t status; 507219820Sjeff 508219820Sjeff CL_ASSERT(p_vector); 509219820Sjeff CL_ASSERT(p_vector->state == CL_INITIALIZED); 510219820Sjeff 511219820Sjeff status = cl_ptr_vector_set(p_vector, p_vector->size, element); 512219820Sjeff if (status == CL_SUCCESS && p_index) 513219820Sjeff *p_index = p_vector->size - 1; 514219820Sjeff 515219820Sjeff return (status); 516219820Sjeff} 517219820Sjeff 518219820Sjeff/* 519219820Sjeff* PARAMETERS 520219820Sjeff* p_vector 521219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure into which to store 522219820Sjeff* an element. 523219820Sjeff* 524219820Sjeff* element 525219820Sjeff* [in] Pointer to store in the pointer vector. 526219820Sjeff* 527219820Sjeff* p_index 528219820Sjeff* [out] Pointer to the index of the element. Valid only if 529219820Sjeff* insertion was successful. 530219820Sjeff* 531219820Sjeff* RETURN VALUES 532219820Sjeff* CL_SUCCESS if the element was successfully inserted. 533219820Sjeff* 534219820Sjeff* CL_INSUFFICIENT_MEMORY if the pointer vector could not be resized to 535219820Sjeff* accommodate the new element. 536219820Sjeff* 537219820Sjeff* NOTES 538219820Sjeff* cl_ptr_vector_insert places the new element at the end of 539219820Sjeff* the pointer vector. 540219820Sjeff* 541219820Sjeff* cl_ptr_vector_insert grows the pointer vector as needed to accommodate 542219820Sjeff* the new element, unless the grow_size parameter passed into the 543219820Sjeff* cl_ptr_vector_init function was zero. 544219820Sjeff* 545219820Sjeff* SEE ALSO 546219820Sjeff* Pointer Vector, cl_ptr_vector_remove, cl_ptr_vector_set 547219820Sjeff*********/ 548219820Sjeff 549219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_remove 550219820Sjeff* NAME 551219820Sjeff* cl_ptr_vector_remove 552219820Sjeff* 553219820Sjeff* DESCRIPTION 554219820Sjeff* The cl_ptr_vector_remove function removes and returns the pointer stored 555219820Sjeff* in a pointer vector at a specified index. Items beyond the removed item 556219820Sjeff* are shifted down and the size of the pointer vector is decremented. 557219820Sjeff* 558219820Sjeff* SYNOPSIS 559219820Sjeff*/ 560219820Sjeffvoid *cl_ptr_vector_remove(IN cl_ptr_vector_t * const p_vector, 561219820Sjeff IN const size_t index); 562219820Sjeff/* 563219820Sjeff* PARAMETERS 564219820Sjeff* p_vector 565219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure from which to get an 566219820Sjeff* element. 567219820Sjeff* 568219820Sjeff* index 569219820Sjeff* [in] Index of the element. 570219820Sjeff* 571219820Sjeff* RETURN VALUE 572219820Sjeff* Value of the pointer stored at the specified index. 573219820Sjeff* 574219820Sjeff* NOTES 575219820Sjeff* cl_ptr_vector_get does not perform boundary checking. Callers are 576219820Sjeff* responsible for providing an index that is within the range of the pointer 577219820Sjeff* vector. 578219820Sjeff* 579219820Sjeff* SEE ALSO 580219820Sjeff* Pointer Vector, cl_ptr_vector_insert, cl_ptr_vector_get_size 581219820Sjeff*********/ 582219820Sjeff 583219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_set_capacity 584219820Sjeff* NAME 585219820Sjeff* cl_ptr_vector_set_capacity 586219820Sjeff* 587219820Sjeff* DESCRIPTION 588219820Sjeff* The cl_ptr_vector_set_capacity function reserves memory in a 589219820Sjeff* pointer vector for a specified number of pointers. 590219820Sjeff* 591219820Sjeff* SYNOPSIS 592219820Sjeff*/ 593219820Sjeffcl_status_t 594219820Sjeffcl_ptr_vector_set_capacity(IN cl_ptr_vector_t * const p_vector, 595219820Sjeff IN const size_t new_capacity); 596219820Sjeff/* 597219820Sjeff* PARAMETERS 598219820Sjeff* p_vector 599219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure whose capacity to set. 600219820Sjeff* 601219820Sjeff* new_capacity 602219820Sjeff* [in] Total number of elements for which the pointer vector should 603219820Sjeff* allocate memory. 604219820Sjeff* 605219820Sjeff* RETURN VALUES 606219820Sjeff* CL_SUCCESS if the capacity was successfully set. 607219820Sjeff* 608219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to satisfy the 609219820Sjeff* operation. The pointer vector is left unchanged. 610219820Sjeff* 611219820Sjeff* NOTES 612219820Sjeff* cl_ptr_vector_set_capacity increases the capacity of the pointer vector. 613219820Sjeff* It does not change the size of the pointer vector. If the requested 614219820Sjeff* capacity is less than the current capacity, the pointer vector is left 615219820Sjeff* unchanged. 616219820Sjeff* 617219820Sjeff* SEE ALSO 618219820Sjeff* Pointer Vector, cl_ptr_vector_get_capacity, cl_ptr_vector_set_size, 619219820Sjeff* cl_ptr_vector_set_min_size 620219820Sjeff*********/ 621219820Sjeff 622219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_set_size 623219820Sjeff* NAME 624219820Sjeff* cl_ptr_vector_set_size 625219820Sjeff* 626219820Sjeff* DESCRIPTION 627219820Sjeff* The cl_ptr_vector_set_size function resizes a pointer vector, either 628219820Sjeff* increasing or decreasing its size. 629219820Sjeff* 630219820Sjeff* SYNOPSIS 631219820Sjeff*/ 632219820Sjeffcl_status_t 633219820Sjeffcl_ptr_vector_set_size(IN cl_ptr_vector_t * const p_vector, 634219820Sjeff IN const size_t size); 635219820Sjeff/* 636219820Sjeff* PARAMETERS 637219820Sjeff* p_vector 638219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure whose size to set. 639219820Sjeff* 640219820Sjeff* size 641219820Sjeff* [in] Number of elements desired in the pointer vector. 642219820Sjeff* 643219820Sjeff* RETURN VALUES 644219820Sjeff* CL_SUCCESS if the size of the pointer vector was set successfully. 645219820Sjeff* 646219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to complete the 647219820Sjeff* operation. The pointer vector is left unchanged. 648219820Sjeff* 649219820Sjeff* NOTES 650219820Sjeff* cl_ptr_vector_set_size sets the pointer vector to the specified size. 651219820Sjeff* If size is smaller than the current size of the pointer vector, the size 652219820Sjeff* is reduced. 653219820Sjeff* 654219820Sjeff* This function can only fail if size is larger than the current capacity. 655219820Sjeff* 656219820Sjeff* SEE ALSO 657219820Sjeff* Pointer Vector, cl_ptr_vector_get_size, cl_ptr_vector_set_min_size, 658219820Sjeff* cl_ptr_vector_set_capacity 659219820Sjeff*********/ 660219820Sjeff 661219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_set_min_size 662219820Sjeff* NAME 663219820Sjeff* cl_ptr_vector_set_min_size 664219820Sjeff* 665219820Sjeff* DESCRIPTION 666219820Sjeff* The cl_ptr_vector_set_min_size function resizes a pointer vector to a 667219820Sjeff* specified size if the pointer vector is smaller than the specified size. 668219820Sjeff* 669219820Sjeff* SYNOPSIS 670219820Sjeff*/ 671219820Sjeffcl_status_t 672219820Sjeffcl_ptr_vector_set_min_size(IN cl_ptr_vector_t * const p_vector, 673219820Sjeff IN const size_t min_size); 674219820Sjeff/* 675219820Sjeff* PARAMETERS 676219820Sjeff* p_vector 677219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure whose minimum size to set. 678219820Sjeff* 679219820Sjeff* min_size 680219820Sjeff* [in] Minimum number of elements that the pointer vector should contain. 681219820Sjeff* 682219820Sjeff* RETURN VALUES 683219820Sjeff* CL_SUCCESS if the pointer vector size is greater than or equal to min_size. 684219820Sjeff* This could indicate that the pointer vector's capacity was increased to 685219820Sjeff* min_size or that the pointer vector was already of sufficient size. 686219820Sjeff* 687219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to resize the 688219820Sjeff* pointer vector. The pointer vector is left unchanged. 689219820Sjeff* 690219820Sjeff* NOTES 691219820Sjeff* If min_size is smaller than the current size of the pointer vector, 692219820Sjeff* the pointer vector is unchanged. The pointer vector is unchanged if the 693219820Sjeff* size could not be changed due to insufficient memory being available to 694219820Sjeff* perform the operation. 695219820Sjeff* 696219820Sjeff* SEE ALSO 697219820Sjeff* Pointer Vector, cl_ptr_vector_get_size, cl_ptr_vector_set_size, 698219820Sjeff* cl_ptr_vector_set_capacity 699219820Sjeff*********/ 700219820Sjeff 701219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_apply_func 702219820Sjeff* NAME 703219820Sjeff* cl_ptr_vector_apply_func 704219820Sjeff* 705219820Sjeff* DESCRIPTION 706219820Sjeff* The cl_ptr_vector_apply_func function invokes a specified function for 707219820Sjeff* every element in a pointer vector. 708219820Sjeff* 709219820Sjeff* SYNOPSIS 710219820Sjeff*/ 711219820Sjeffvoid 712219820Sjeffcl_ptr_vector_apply_func(IN const cl_ptr_vector_t * const p_vector, 713219820Sjeff IN cl_pfn_ptr_vec_apply_t pfn_callback, 714219820Sjeff IN const void *const context); 715219820Sjeff/* 716219820Sjeff* PARAMETERS 717219820Sjeff* p_vector 718219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure whose elements to iterate. 719219820Sjeff* 720219820Sjeff* pfn_callback 721219820Sjeff* [in] Function invoked for every element in the array. 722219820Sjeff* See the cl_pfn_ptr_vec_apply_t function type declaration for details 723219820Sjeff* about the callback function. 724219820Sjeff* 725219820Sjeff* context 726219820Sjeff* [in] Value to pass to the callback function. 727219820Sjeff* 728219820Sjeff* RETURN VALUE 729219820Sjeff* This function does not return a value. 730219820Sjeff* 731219820Sjeff* NOTES 732219820Sjeff* cl_ptr_vector_apply_func invokes the specified function for every element 733219820Sjeff* in the pointer vector, starting from the beginning of the pointer vector. 734219820Sjeff* 735219820Sjeff* SEE ALSO 736219820Sjeff* Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end, 737219820Sjeff* cl_pfn_ptr_vec_apply_t 738219820Sjeff*********/ 739219820Sjeff 740219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_find_from_start 741219820Sjeff* NAME 742219820Sjeff* cl_ptr_vector_find_from_start 743219820Sjeff* 744219820Sjeff* DESCRIPTION 745219820Sjeff* The cl_ptr_vector_find_from_start function uses a specified function to 746219820Sjeff* search for elements in a pointer vector starting from the lowest index. 747219820Sjeff* 748219820Sjeff* SYNOPSIS 749219820Sjeff*/ 750219820Sjeffsize_t 751219820Sjeffcl_ptr_vector_find_from_start(IN const cl_ptr_vector_t * const p_vector, 752219820Sjeff IN cl_pfn_ptr_vec_find_t pfn_callback, 753219820Sjeff IN const void *const context); 754219820Sjeff/* 755219820Sjeff* PARAMETERS 756219820Sjeff* p_vector 757219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure to inititalize. 758219820Sjeff* 759219820Sjeff* pfn_callback 760219820Sjeff* [in] Function invoked to determine if a match was found. 761219820Sjeff* See the cl_pfn_ptr_vec_find_t function type declaration for details 762219820Sjeff* about the callback function. 763219820Sjeff* 764219820Sjeff* context 765219820Sjeff* [in] Value to pass to the callback function. 766219820Sjeff* 767219820Sjeff* RETURN VALUES 768219820Sjeff* Index of the element, if found. 769219820Sjeff* 770219820Sjeff* Size of the pointer vector if the element was not found. 771219820Sjeff* 772219820Sjeff* NOTES 773219820Sjeff* cl_ptr_vector_find_from_start does not remove the found element from 774219820Sjeff* the pointer vector. The index of the element is returned when the function 775219820Sjeff* provided by the pfn_callback parameter returns CL_SUCCESS. 776219820Sjeff* 777219820Sjeff* SEE ALSO 778219820Sjeff* Pointer Vector, cl_ptr_vector_find_from_end, cl_ptr_vector_apply_func, 779219820Sjeff* cl_pfn_ptr_vec_find_t 780219820Sjeff*********/ 781219820Sjeff 782219820Sjeff/****f* Component Library: Pointer Vector/cl_ptr_vector_find_from_end 783219820Sjeff* NAME 784219820Sjeff* cl_ptr_vector_find_from_end 785219820Sjeff* 786219820Sjeff* DESCRIPTION 787219820Sjeff* The cl_ptr_vector_find_from_end function uses a specified function to 788219820Sjeff* search for elements in a pointer vector starting from the highest index. 789219820Sjeff* 790219820Sjeff* SYNOPSIS 791219820Sjeff*/ 792219820Sjeffsize_t 793219820Sjeffcl_ptr_vector_find_from_end(IN const cl_ptr_vector_t * const p_vector, 794219820Sjeff IN cl_pfn_ptr_vec_find_t pfn_callback, 795219820Sjeff IN const void *const context); 796219820Sjeff/* 797219820Sjeff* PARAMETERS 798219820Sjeff* p_vector 799219820Sjeff* [in] Pointer to a cl_ptr_vector_t structure to inititalize. 800219820Sjeff* 801219820Sjeff* pfn_callback 802219820Sjeff* [in] Function invoked to determine if a match was found. 803219820Sjeff* See the cl_pfn_ptr_vec_find_t function type declaration for details 804219820Sjeff* about the callback function. 805219820Sjeff* 806219820Sjeff* context 807219820Sjeff* [in] Value to pass to the callback function. 808219820Sjeff* 809219820Sjeff* RETURN VALUES 810219820Sjeff* Index of the element, if found. 811219820Sjeff* 812219820Sjeff* Size of the pointer vector if the element was not found. 813219820Sjeff* 814219820Sjeff* NOTES 815219820Sjeff* cl_ptr_vector_find_from_end does not remove the found element from 816219820Sjeff* the pointer vector. The index of the element is returned when the function 817219820Sjeff* provided by the pfn_callback parameter returns CL_SUCCESS. 818219820Sjeff* 819219820Sjeff* SEE ALSO 820219820Sjeff* Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_apply_func, 821219820Sjeff* cl_pfn_ptr_vec_find_t 822219820Sjeff*********/ 823219820Sjeff 824219820SjeffEND_C_DECLS 825219820Sjeff#endif /* _CL_PTR_VECTOR_H_ */ 826