1/* 2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5 * 6 * This software is available to you under a choice of one of two 7 * licenses. You may choose to be licensed under the terms of the GNU 8 * General Public License (GPL) Version 2, available from the file 9 * COPYING in the main directory of this source tree, or the 10 * OpenIB.org BSD license below: 11 * 12 * Redistribution and use in source and binary forms, with or 13 * without modification, are permitted provided that the following 14 * conditions are met: 15 * 16 * - Redistributions of source code must retain the above 17 * copyright notice, this list of conditions and the following 18 * disclaimer. 19 * 20 * - Redistributions in binary form must reproduce the above 21 * copyright notice, this list of conditions and the following 22 * disclaimer in the documentation and/or other materials 23 * provided with the distribution. 24 * 25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32 * SOFTWARE. 33 * 34 */ 35 36/* 37 * Abstract: 38 * This file contains pointer vector definitions. Pointer Vector provides 39 * dynmically resizable array functionality. 40 */ 41 42#ifndef _CL_PTR_VECTOR_H_ 43#define _CL_PTR_VECTOR_H_ 44 45#include <complib/cl_types.h> 46 47#ifdef __cplusplus 48# define BEGIN_C_DECLS extern "C" { 49# define END_C_DECLS } 50#else /* !__cplusplus */ 51# define BEGIN_C_DECLS 52# define END_C_DECLS 53#endif /* __cplusplus */ 54 55BEGIN_C_DECLS 56/****h* Component Library/Pointer Vector 57* NAME 58* Pointer Vector 59* 60* DESCRIPTION 61* The Pointer Vector is a self-sizing array of pointers. Like a traditonal 62* array, a pointer vector allows efficient constant time access to elements 63* with a specified index. A pointer vector grows transparently as the 64* user adds elements to the array. 65* 66* The cl_pointer vector_t structure should be treated as opaque and should be 67* manipulated only through the provided functions. 68* 69* SEE ALSO 70* Structures: 71* cl_ptr_vector_t 72* 73* Callbacks: 74* cl_pfn_ptr_vec_apply_t, cl_pfn_ptr_vec_find_t 75* 76* Item Manipulation: 77* cl_ptr_vector_set, cl_ptr_vector_obj 78* 79* Initialization: 80* cl_ptr_vector_construct, cl_ptr_vector_init, cl_ptr_vector_destroy 81* 82* Manipulation: 83* cl_ptr_vector_get_capacity, cl_ptr_vector_set_capacity, 84* cl_ptr_vector_get_size, cl_ptr_vector_set_size, cl_ptr_vector_set_min_size 85* cl_ptr_vector_get_ptr, cl_ptr_vector_get, cl_ptr_vector_at, cl_ptr_vector_set 86* 87* Search: 88* cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end 89* cl_ptr_vector_apply_func 90*********/ 91/****d* Component Library: Pointer Vector/cl_pfn_ptr_vec_apply_t 92* NAME 93* cl_pfn_ptr_vec_apply_t 94* 95* DESCRIPTION 96* The cl_pfn_ptr_vec_apply_t function type defines the prototype for 97* functions used to iterate elements in a pointer vector. 98* 99* SYNOPSIS 100*/ 101typedef void 102 (*cl_pfn_ptr_vec_apply_t) (IN const size_t index, 103 IN void *const element, IN void *context); 104/* 105* PARAMETERS 106* index 107* [in] Index of the element. 108* 109* p_element 110* [in] Pointer to an element at the specified index in the pointer vector. 111* 112* context 113* [in] Context provided in a call to cl_ptr_vector_apply_func. 114* 115* RETURN VALUE 116* This function does not return a value. 117* 118* NOTES 119* This function type is provided as function prototype reference for 120* the function passed by users as a parameter to the cl_ptr_vector_apply_func 121* function. 122* 123* SEE ALSO 124* Pointer Vector, cl_ptr_vector_apply_func 125*********/ 126 127/****d* Component Library: Pointer Vector/cl_pfn_ptr_vec_find_t 128* NAME 129* cl_pfn_ptr_vec_find_t 130* 131* DESCRIPTION 132* The cl_pfn_ptr_vec_find_t function type defines the prototype for 133* functions used to find elements in a pointer vector. 134* 135* SYNOPSIS 136*/ 137typedef cl_status_t 138 (*cl_pfn_ptr_vec_find_t) (IN const size_t index, 139 IN const void *const element, IN void *context); 140/* 141* PARAMETERS 142* index 143* [in] Index of the element. 144* 145* p_element 146* [in] Pointer to an element at the specified index in the 147* pointer vector. 148* 149* context 150* [in] Context provided in a call to cl_ptr_vector_find_from_start or 151* cl_ptr_vector_find_from_end. 152* 153* RETURN VALUES 154* Return CL_SUCCESS if the element was found. This stops pointer vector 155* iteration. 156* 157* CL_NOT_FOUND to continue the pointer vector iteration. 158* 159* NOTES 160* This function type is provided as function prototype reference for the 161* function provided by users as a parameter to the 162* cl_ptr_vector_find_from_start and cl_ptr_vector_find_from_end functions. 163* 164* SEE ALSO 165* Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end 166*********/ 167 168/****s* Component Library: Pointer Vector/cl_ptr_vector_t 169* NAME 170* cl_ptr_vector_t 171* 172* DESCRIPTION 173* Pointer Vector structure. 174* 175* The cl_ptr_vector_t structure should be treated as opaque and should be 176* manipulated only through the provided functions. 177* 178* SYNOPSIS 179*/ 180typedef struct _cl_ptr_vector { 181 size_t size; 182 size_t grow_size; 183 size_t capacity; 184 const void **p_ptr_array; 185 cl_state_t state; 186} cl_ptr_vector_t; 187/* 188* FIELDS 189* size 190* Number of elements successfully initialized in the pointer vector. 191* 192* grow_size 193* Number of elements to allocate when growing. 194* 195* capacity 196* total # of elements allocated. 197* 198* alloc_list 199* List of allocations. 200* 201* p_ptr_array 202* Internal array of pointers to elements. 203* 204* state 205* State of the pointer vector. 206* 207* SEE ALSO 208* Pointer Vector 209*********/ 210 211/****f* Component Library: Pointer Vector/cl_ptr_vector_construct 212* NAME 213* cl_ptr_vector_construct 214* 215* DESCRIPTION 216* The cl_ptr_vector_construct function constructs a pointer vector. 217* 218* SYNOPSIS 219*/ 220void cl_ptr_vector_construct(IN cl_ptr_vector_t * const p_vector); 221/* 222* PARAMETERS 223* p_vector 224* [in] Pointer to a cl_ptr_vector_t structure to construct. 225* 226* RETURN VALUE 227* This function does not return a value. 228* 229* NOTES 230* Allows calling cl_ptr_vector_destroy without first calling 231* cl_ptr_vector_init. 232* 233* Calling cl_ptr_vector_construct is a prerequisite to calling any other 234* pointer vector function except cl_ptr_vector_init. 235* 236* SEE ALSO 237* Pointer Vector, cl_ptr_vector_init, cl_ptr_vector_destroy 238*********/ 239 240/****f* Component Library: Pointer Vector/cl_ptr_vector_init 241* NAME 242* cl_ptr_vector_init 243* 244* DESCRIPTION 245* The cl_ptr_vector_init function initializes a pointer vector for use. 246* 247* SYNOPSIS 248*/ 249cl_status_t 250cl_ptr_vector_init(IN cl_ptr_vector_t * const p_vector, 251 IN const size_t min_size, IN const size_t grow_size); 252/* 253* PARAMETERS 254* p_vector 255* [in] Pointer to a cl_ptr_vector_t structure to inititalize. 256* 257* min_size 258* [in] Initial number of elements. 259* 260* grow_size 261* [in] Number of elements to allocate when incrementally growing 262* the pointer vector. A value of zero disables automatic growth. 263* 264* RETURN VALUES 265* CL_SUCCESS if the pointer vector was initialized successfully. 266* 267* CL_INSUFFICIENT_MEMORY if the initialization failed. 268* 269* SEE ALSO 270* Pointer Vector, cl_ptr_vector_construct, cl_ptr_vector_destroy, 271* cl_ptr_vector_set, cl_ptr_vector_get, cl_ptr_vector_at 272*********/ 273 274/****f* Component Library: Pointer Vector/cl_ptr_vector_destroy 275* NAME 276* cl_ptr_vector_destroy 277* 278* DESCRIPTION 279* The cl_ptr_vector_destroy function destroys a pointer vector. 280* 281* SYNOPSIS 282*/ 283void cl_ptr_vector_destroy(IN cl_ptr_vector_t * const p_vector); 284/* 285* PARAMETERS 286* p_vector 287* [in] Pointer to a cl_ptr_vector_t structure to destroy. 288* 289* RETURN VALUE 290* This function does not return a value. 291* 292* NOTES 293* cl_ptr_vector_destroy frees all memory allocated for the pointer vector. 294* 295* This function should only be called after a call to cl_ptr_vector_construct 296* or cl_ptr_vector_init. 297* 298* SEE ALSO 299* Pointer Vector, cl_ptr_vector_construct, cl_ptr_vector_init 300*********/ 301 302/****f* Component Library: Pointer Vector/cl_ptr_vector_get_capacity 303* NAME 304* cl_ptr_vector_get_capacity 305* 306* DESCRIPTION 307* The cl_ptr_vector_get_capacity function returns the capacity of 308* a pointer vector. 309* 310* SYNOPSIS 311*/ 312static inline size_t 313cl_ptr_vector_get_capacity(IN const cl_ptr_vector_t * const p_vector) 314{ 315 CL_ASSERT(p_vector); 316 CL_ASSERT(p_vector->state == CL_INITIALIZED); 317 318 return (p_vector->capacity); 319} 320 321/* 322* PARAMETERS 323* p_vector 324* [in] Pointer to a cl_ptr_vector_t structure whose capacity to return. 325* 326* RETURN VALUE 327* Capacity, in elements, of the pointer vector. 328* 329* NOTES 330* The capacity is the number of elements that the pointer vector can store, 331* and can be greater than the number of elements stored. To get the number 332* of elements stored in the pointer vector, use cl_ptr_vector_get_size. 333* 334* SEE ALSO 335* Pointer Vector, cl_ptr_vector_set_capacity, cl_ptr_vector_get_size 336*********/ 337 338/****f* Component Library: Pointer Vector/cl_ptr_vector_get_size 339* NAME 340* cl_ptr_vector_get_size 341* 342* DESCRIPTION 343* The cl_ptr_vector_get_size function returns the size of a pointer vector. 344* 345* SYNOPSIS 346*/ 347static inline uint32_t 348cl_ptr_vector_get_size(IN const cl_ptr_vector_t * const p_vector) 349{ 350 CL_ASSERT(p_vector); 351 CL_ASSERT(p_vector->state == CL_INITIALIZED); 352 return ((uint32_t) p_vector->size); 353 354} 355 356/* 357* PARAMETERS 358* p_vector 359* [in] Pointer to a cl_ptr_vector_t structure whose size to return. 360* 361* RETURN VALUE 362* Size, in elements, of the pointer vector. 363* 364* SEE ALSO 365* Pointer Vector, cl_ptr_vector_set_size, cl_ptr_vector_get_capacity 366*********/ 367 368/****f* Component Library: Pointer Vector/cl_ptr_vector_get 369* NAME 370* cl_ptr_vector_get 371* 372* DESCRIPTION 373* The cl_ptr_vector_get function returns the pointer stored in a 374* pointer vector at a specified index. 375* 376* SYNOPSIS 377*/ 378static inline void *cl_ptr_vector_get(IN const cl_ptr_vector_t * const p_vector, 379 IN const size_t index) 380{ 381 CL_ASSERT(p_vector); 382 CL_ASSERT(p_vector->state == CL_INITIALIZED); 383 CL_ASSERT(p_vector->size > index); 384 385 return ((void *)p_vector->p_ptr_array[index]); 386} 387 388/* 389* PARAMETERS 390* p_vector 391* [in] Pointer to a cl_ptr_vector_t structure from which to get an 392* element. 393* 394* index 395* [in] Index of the element. 396* 397* RETURN VALUE 398* Value of the pointer stored at the specified index. 399* 400* NOTES 401* cl_ptr_vector_get provides constant access times regardless of the index. 402* 403* cl_ptr_vector_get does not perform boundary checking. Callers are 404* responsible for providing an index that is within the range of the pointer 405* vector. 406* 407* SEE ALSO 408* Pointer Vector, cl_ptr_vector_at, cl_ptr_vector_set, cl_ptr_vector_get_size 409*********/ 410 411/****f* Component Library: Pointer Vector/cl_ptr_vector_at 412* NAME 413* cl_ptr_vector_at 414* 415* DESCRIPTION 416* The cl_ptr_vector_at function copies an element stored in a pointer 417* vector at a specified index, performing boundary checks. 418* 419* SYNOPSIS 420*/ 421cl_status_t 422cl_ptr_vector_at(IN const cl_ptr_vector_t * const p_vector, 423 IN const size_t index, OUT void **const p_element); 424/* 425* PARAMETERS 426* p_vector 427* [in] Pointer to a cl_ptr_vector_t structure from which to get a copy of 428* an element. 429* 430* index 431* [in] Index of the element. 432* 433* p_element 434* [out] Pointer to storage for the pointer element. Contains a copy of 435* the desired pointer upon successful completion of the call. 436* 437* RETURN VALUES 438* CL_SUCCESS if an element was found at the specified index. 439* 440* CL_INVALID_SETTING if the index was out of range. 441* 442* NOTES 443* cl_ptr_vector_at provides constant time access regardless of 444* the index, and performs boundary checking on the pointer vector. 445* 446* Upon success, the p_element parameter contains a copy of the 447* desired element. 448* 449* SEE ALSO 450* Pointer Vector, cl_ptr_vector_get 451*********/ 452 453/****f* Component Library: Pointer Vector/cl_ptr_vector_set 454* NAME 455* cl_ptr_vector_set 456* 457* DESCRIPTION 458* The cl_ptr_vector_set function sets the element at the specified index. 459* 460* SYNOPSIS 461*/ 462cl_status_t 463cl_ptr_vector_set(IN cl_ptr_vector_t * const p_vector, 464 IN const size_t index, IN const void *const element); 465/* 466* PARAMETERS 467* p_vector 468* [in] Pointer to a cl_ptr_vector_t structure into which to store 469* an element. 470* 471* index 472* [in] Index of the element. 473* 474* element 475* [in] Pointer to store in the pointer vector. 476* 477* RETURN VALUES 478* CL_SUCCESS if the element was successfully set. 479* 480* CL_INSUFFICIENT_MEMORY if the pointer vector could not be resized to 481* accommodate the new element. 482* 483* NOTES 484* cl_ptr_vector_set grows the pointer vector as needed to accommodate 485* the new element, unless the grow_size parameter passed into the 486* cl_ptr_vector_init function was zero. 487* 488* SEE ALSO 489* Pointer Vector, cl_ptr_vector_get 490*********/ 491 492/****f* Component Library: Pointer Vector/cl_ptr_vector_insert 493* NAME 494* cl_ptr_vector_insert 495* 496* DESCRIPTION 497* The cl_ptr_vector_insert function inserts an element into a pointer vector. 498* 499* SYNOPSIS 500*/ 501static inline cl_status_t 502cl_ptr_vector_insert(IN cl_ptr_vector_t * const p_vector, 503 IN const void *const element, 504 OUT size_t * const p_index OPTIONAL) 505{ 506 cl_status_t status; 507 508 CL_ASSERT(p_vector); 509 CL_ASSERT(p_vector->state == CL_INITIALIZED); 510 511 status = cl_ptr_vector_set(p_vector, p_vector->size, element); 512 if (status == CL_SUCCESS && p_index) 513 *p_index = p_vector->size - 1; 514 515 return (status); 516} 517 518/* 519* PARAMETERS 520* p_vector 521* [in] Pointer to a cl_ptr_vector_t structure into which to store 522* an element. 523* 524* element 525* [in] Pointer to store in the pointer vector. 526* 527* p_index 528* [out] Pointer to the index of the element. Valid only if 529* insertion was successful. 530* 531* RETURN VALUES 532* CL_SUCCESS if the element was successfully inserted. 533* 534* CL_INSUFFICIENT_MEMORY if the pointer vector could not be resized to 535* accommodate the new element. 536* 537* NOTES 538* cl_ptr_vector_insert places the new element at the end of 539* the pointer vector. 540* 541* cl_ptr_vector_insert grows the pointer vector as needed to accommodate 542* the new element, unless the grow_size parameter passed into the 543* cl_ptr_vector_init function was zero. 544* 545* SEE ALSO 546* Pointer Vector, cl_ptr_vector_remove, cl_ptr_vector_set 547*********/ 548 549/****f* Component Library: Pointer Vector/cl_ptr_vector_remove 550* NAME 551* cl_ptr_vector_remove 552* 553* DESCRIPTION 554* The cl_ptr_vector_remove function removes and returns the pointer stored 555* in a pointer vector at a specified index. Items beyond the removed item 556* are shifted down and the size of the pointer vector is decremented. 557* 558* SYNOPSIS 559*/ 560void *cl_ptr_vector_remove(IN cl_ptr_vector_t * const p_vector, 561 IN const size_t index); 562/* 563* PARAMETERS 564* p_vector 565* [in] Pointer to a cl_ptr_vector_t structure from which to get an 566* element. 567* 568* index 569* [in] Index of the element. 570* 571* RETURN VALUE 572* Value of the pointer stored at the specified index. 573* 574* NOTES 575* cl_ptr_vector_get does not perform boundary checking. Callers are 576* responsible for providing an index that is within the range of the pointer 577* vector. 578* 579* SEE ALSO 580* Pointer Vector, cl_ptr_vector_insert, cl_ptr_vector_get_size 581*********/ 582 583/****f* Component Library: Pointer Vector/cl_ptr_vector_set_capacity 584* NAME 585* cl_ptr_vector_set_capacity 586* 587* DESCRIPTION 588* The cl_ptr_vector_set_capacity function reserves memory in a 589* pointer vector for a specified number of pointers. 590* 591* SYNOPSIS 592*/ 593cl_status_t 594cl_ptr_vector_set_capacity(IN cl_ptr_vector_t * const p_vector, 595 IN const size_t new_capacity); 596/* 597* PARAMETERS 598* p_vector 599* [in] Pointer to a cl_ptr_vector_t structure whose capacity to set. 600* 601* new_capacity 602* [in] Total number of elements for which the pointer vector should 603* allocate memory. 604* 605* RETURN VALUES 606* CL_SUCCESS if the capacity was successfully set. 607* 608* CL_INSUFFICIENT_MEMORY if there was not enough memory to satisfy the 609* operation. The pointer vector is left unchanged. 610* 611* NOTES 612* cl_ptr_vector_set_capacity increases the capacity of the pointer vector. 613* It does not change the size of the pointer vector. If the requested 614* capacity is less than the current capacity, the pointer vector is left 615* unchanged. 616* 617* SEE ALSO 618* Pointer Vector, cl_ptr_vector_get_capacity, cl_ptr_vector_set_size, 619* cl_ptr_vector_set_min_size 620*********/ 621 622/****f* Component Library: Pointer Vector/cl_ptr_vector_set_size 623* NAME 624* cl_ptr_vector_set_size 625* 626* DESCRIPTION 627* The cl_ptr_vector_set_size function resizes a pointer vector, either 628* increasing or decreasing its size. 629* 630* SYNOPSIS 631*/ 632cl_status_t 633cl_ptr_vector_set_size(IN cl_ptr_vector_t * const p_vector, 634 IN const size_t size); 635/* 636* PARAMETERS 637* p_vector 638* [in] Pointer to a cl_ptr_vector_t structure whose size to set. 639* 640* size 641* [in] Number of elements desired in the pointer vector. 642* 643* RETURN VALUES 644* CL_SUCCESS if the size of the pointer vector was set successfully. 645* 646* CL_INSUFFICIENT_MEMORY if there was not enough memory to complete the 647* operation. The pointer vector is left unchanged. 648* 649* NOTES 650* cl_ptr_vector_set_size sets the pointer vector to the specified size. 651* If size is smaller than the current size of the pointer vector, the size 652* is reduced. 653* 654* This function can only fail if size is larger than the current capacity. 655* 656* SEE ALSO 657* Pointer Vector, cl_ptr_vector_get_size, cl_ptr_vector_set_min_size, 658* cl_ptr_vector_set_capacity 659*********/ 660 661/****f* Component Library: Pointer Vector/cl_ptr_vector_set_min_size 662* NAME 663* cl_ptr_vector_set_min_size 664* 665* DESCRIPTION 666* The cl_ptr_vector_set_min_size function resizes a pointer vector to a 667* specified size if the pointer vector is smaller than the specified size. 668* 669* SYNOPSIS 670*/ 671cl_status_t 672cl_ptr_vector_set_min_size(IN cl_ptr_vector_t * const p_vector, 673 IN const size_t min_size); 674/* 675* PARAMETERS 676* p_vector 677* [in] Pointer to a cl_ptr_vector_t structure whose minimum size to set. 678* 679* min_size 680* [in] Minimum number of elements that the pointer vector should contain. 681* 682* RETURN VALUES 683* CL_SUCCESS if the pointer vector size is greater than or equal to min_size. 684* This could indicate that the pointer vector's capacity was increased to 685* min_size or that the pointer vector was already of sufficient size. 686* 687* CL_INSUFFICIENT_MEMORY if there was not enough memory to resize the 688* pointer vector. The pointer vector is left unchanged. 689* 690* NOTES 691* If min_size is smaller than the current size of the pointer vector, 692* the pointer vector is unchanged. The pointer vector is unchanged if the 693* size could not be changed due to insufficient memory being available to 694* perform the operation. 695* 696* SEE ALSO 697* Pointer Vector, cl_ptr_vector_get_size, cl_ptr_vector_set_size, 698* cl_ptr_vector_set_capacity 699*********/ 700 701/****f* Component Library: Pointer Vector/cl_ptr_vector_apply_func 702* NAME 703* cl_ptr_vector_apply_func 704* 705* DESCRIPTION 706* The cl_ptr_vector_apply_func function invokes a specified function for 707* every element in a pointer vector. 708* 709* SYNOPSIS 710*/ 711void 712cl_ptr_vector_apply_func(IN const cl_ptr_vector_t * const p_vector, 713 IN cl_pfn_ptr_vec_apply_t pfn_callback, 714 IN const void *const context); 715/* 716* PARAMETERS 717* p_vector 718* [in] Pointer to a cl_ptr_vector_t structure whose elements to iterate. 719* 720* pfn_callback 721* [in] Function invoked for every element in the array. 722* See the cl_pfn_ptr_vec_apply_t function type declaration for details 723* about the callback function. 724* 725* context 726* [in] Value to pass to the callback function. 727* 728* RETURN VALUE 729* This function does not return a value. 730* 731* NOTES 732* cl_ptr_vector_apply_func invokes the specified function for every element 733* in the pointer vector, starting from the beginning of the pointer vector. 734* 735* SEE ALSO 736* Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end, 737* cl_pfn_ptr_vec_apply_t 738*********/ 739 740/****f* Component Library: Pointer Vector/cl_ptr_vector_find_from_start 741* NAME 742* cl_ptr_vector_find_from_start 743* 744* DESCRIPTION 745* The cl_ptr_vector_find_from_start function uses a specified function to 746* search for elements in a pointer vector starting from the lowest index. 747* 748* SYNOPSIS 749*/ 750size_t 751cl_ptr_vector_find_from_start(IN const cl_ptr_vector_t * const p_vector, 752 IN cl_pfn_ptr_vec_find_t pfn_callback, 753 IN const void *const context); 754/* 755* PARAMETERS 756* p_vector 757* [in] Pointer to a cl_ptr_vector_t structure to inititalize. 758* 759* pfn_callback 760* [in] Function invoked to determine if a match was found. 761* See the cl_pfn_ptr_vec_find_t function type declaration for details 762* about the callback function. 763* 764* context 765* [in] Value to pass to the callback function. 766* 767* RETURN VALUES 768* Index of the element, if found. 769* 770* Size of the pointer vector if the element was not found. 771* 772* NOTES 773* cl_ptr_vector_find_from_start does not remove the found element from 774* the pointer vector. The index of the element is returned when the function 775* provided by the pfn_callback parameter returns CL_SUCCESS. 776* 777* SEE ALSO 778* Pointer Vector, cl_ptr_vector_find_from_end, cl_ptr_vector_apply_func, 779* cl_pfn_ptr_vec_find_t 780*********/ 781 782/****f* Component Library: Pointer Vector/cl_ptr_vector_find_from_end 783* NAME 784* cl_ptr_vector_find_from_end 785* 786* DESCRIPTION 787* The cl_ptr_vector_find_from_end function uses a specified function to 788* search for elements in a pointer vector starting from the highest index. 789* 790* SYNOPSIS 791*/ 792size_t 793cl_ptr_vector_find_from_end(IN const cl_ptr_vector_t * const p_vector, 794 IN cl_pfn_ptr_vec_find_t pfn_callback, 795 IN const void *const context); 796/* 797* PARAMETERS 798* p_vector 799* [in] Pointer to a cl_ptr_vector_t structure to inititalize. 800* 801* pfn_callback 802* [in] Function invoked to determine if a match was found. 803* See the cl_pfn_ptr_vec_find_t function type declaration for details 804* about the callback function. 805* 806* context 807* [in] Value to pass to the callback function. 808* 809* RETURN VALUES 810* Index of the element, if found. 811* 812* Size of the pointer vector if the element was not found. 813* 814* NOTES 815* cl_ptr_vector_find_from_end does not remove the found element from 816* the pointer vector. The index of the element is returned when the function 817* provided by the pfn_callback parameter returns CL_SUCCESS. 818* 819* SEE ALSO 820* Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_apply_func, 821* cl_pfn_ptr_vec_find_t 822*********/ 823 824END_C_DECLS 825#endif /* _CL_PTR_VECTOR_H_ */ 826