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 vector definitions. Vector provides dynmically 39 * resizable array functionality. Objects in a Vector are not relocated 40 * when the array is resized. 41 */ 42 43#ifndef _CL_VECTOR_H_ 44#define _CL_VECTOR_H_ 45 46#include <complib/cl_qlist.h> 47 48#ifdef __cplusplus 49# define BEGIN_C_DECLS extern "C" { 50# define END_C_DECLS } 51#else /* !__cplusplus */ 52# define BEGIN_C_DECLS 53# define END_C_DECLS 54#endif /* __cplusplus */ 55 56BEGIN_C_DECLS 57/****h* Component Library/Vector 58* NAME 59* Vector 60* 61* DESCRIPTION 62* The Vector is a self-sizing array. Like a traditonal array, a vector 63* allows efficient constant time access to elements with a specified index. 64* A vector grows transparently as the user adds elements to the array. 65* 66* As the vector grows in size, it does not relocate existing elements in 67* memory. This allows using pointers to elements stored in a Vector. 68* 69* Users can supply an initializer functions that allow a vector to ensure 70* that new items added to the vector are properly initialized. A vector 71* calls the initializer function on a per object basis when growing the 72* array. The initializer is optional. 73* 74* The initializer function can fail, and returns a cl_status_t. The vector 75* will call the destructor function, if provided, for an element that 76* failed initialization. If an initializer fails, a vector does not call 77* the initializer for objects in the remainder of the new memory allocation. 78* 79* The cl_vector_t structure should be treated as opaque and should be 80* manipulated only through the provided functions. 81* 82* SEE ALSO 83* Structures: 84* cl_vector_t 85* 86* Callbacks: 87* cl_pfn_vec_init_t, cl_pfn_vec_dtor_t, cl_pfn_vec_apply_t, 88* cl_pfn_vec_find_t 89* 90* Item Manipulation: 91* cl_vector_set_obj, cl_vector_obj 92* 93* Initialization: 94* cl_vector_construct, cl_vector_init, cl_vector_destroy 95* 96* Manipulation: 97* cl_vector_get_capacity, cl_vector_set_capacity, 98* cl_vector_get_size, cl_vector_set_size, cl_vector_set_min_size 99* cl_vector_get_ptr, cl_vector_get, cl_vector_at, cl_vector_set 100* 101* Search: 102* cl_vector_find_from_start, cl_vector_find_from_end 103* cl_vector_apply_func 104*********/ 105/****d* Component Library: Vector/cl_pfn_vec_init_t 106* NAME 107* cl_pfn_vec_init_t 108* 109* DESCRIPTION 110* The cl_pfn_vec_init_t function type defines the prototype for functions 111* used as initializer for elements being allocated by a vector. 112* 113* SYNOPSIS 114*/ 115typedef cl_status_t 116 (*cl_pfn_vec_init_t) (IN void *const p_element, IN void *context); 117/* 118* PARAMETERS 119* p_element 120* [in] Pointer to an element being added to a vector. 121* 122* context 123* [in] Context provided in a call to cl_vector_init. 124* 125* RETURN VALUES 126* Return CL_SUCCESS to indicate that the element was initialized successfully. 127* 128* Other cl_status_t values will be returned by the cl_vector_init, 129* cl_vector_set_size, and cl_vector_set_min_size functions. 130* 131* In situations where the vector's size needs to grows in order to satisfy 132* a call to cl_vector_set, a non-successful status returned by the 133* initializer callback causes the growth to stop. 134* 135* NOTES 136* This function type is provided as function prototype reference for 137* the initializer function provided by users as an optional parameter to 138* the cl_vector_init function. 139* 140* SEE ALSO 141* Vector, cl_vector_init 142*********/ 143 144/****d* Component Library: Vector/cl_pfn_vec_dtor_t 145* NAME 146* cl_pfn_vec_dtor_t 147* 148* DESCRIPTION 149* The cl_pfn_vec_dtor_t function type defines the prototype for functions 150* used as destructor for elements being deallocated from a vector. 151* 152* SYNOPSIS 153*/ 154typedef void 155 (*cl_pfn_vec_dtor_t) (IN void *const p_element, IN void *context); 156/* 157* PARAMETERS 158* p_element 159* [in] Pointer to an element being deallocated from a vector. 160* 161* context 162* [in] Context provided in a call to cl_vector_init. 163* 164* RETURN VALUE 165* This function does not return a value. 166* 167* NOTES 168* This function type is provided as function prototype reference for 169* the destructor function provided by users as an optional parameter to 170* the cl_vector_init function. 171* 172* SEE ALSO 173* Vector, cl_vector_init 174*********/ 175 176/****d* Component Library: Vector/cl_pfn_vec_apply_t 177* NAME 178* cl_pfn_vec_apply_t 179* 180* DESCRIPTION 181* The cl_pfn_vec_apply_t function type defines the prototype for functions 182* used to iterate elements in a vector. 183* 184* SYNOPSIS 185*/ 186typedef void 187 (*cl_pfn_vec_apply_t) (IN const size_t index, 188 IN void *const p_element, IN void *context); 189/* 190* PARAMETERS 191* index 192* [in] Index of the element. 193* 194* p_element 195* [in] Pointer to an element at the specified index in the vector. 196* 197* context 198* [in] Context provided in a call to cl_vector_apply_func. 199* 200* RETURN VALUE 201* This function does not return a value. 202* 203* NOTES 204* This function type is provided as function prototype reference for 205* the function passed by users as a parameter to the cl_vector_apply_func 206* function. 207* 208* SEE ALSO 209* Vector, cl_vector_apply_func 210*********/ 211 212/****d* Component Library: Vector/cl_pfn_vec_find_t 213* NAME 214* cl_pfn_vec_find_t 215* 216* DESCRIPTION 217* The cl_pfn_vec_find_t function type defines the prototype for functions 218* used to find elements in a vector. 219* 220* SYNOPSIS 221*/ 222typedef cl_status_t 223 (*cl_pfn_vec_find_t) (IN const size_t index, 224 IN const void *const p_element, IN void *context); 225/* 226* PARAMETERS 227* index 228* [in] Index of the element. 229* 230* p_element 231* [in] Pointer to an element at the specified index in the vector. 232* 233* context 234* [in] Context provided in a call to cl_vector_find_from_start or 235* cl_vector_find_from_end. 236* 237* RETURN VALUES 238* Return CL_SUCCESS if the element was found. This stops vector iteration. 239* 240* CL_NOT_FOUND to continue the vector iteration. 241* 242* NOTES 243* This function type is provided as function prototype reference for the 244* function provided by users as a parameter to the cl_vector_find_from_start 245* and cl_vector_find_from_end functions. 246* 247* SEE ALSO 248* Vector, cl_vector_find_from_start, cl_vector_find_from_end 249*********/ 250 251/****i* Component Library: Vector/cl_pfn_vec_copy_t 252* NAME 253* cl_pfn_vec_copy_t 254* 255* DESCRIPTION 256* The cl_pfn_vec_copy_t function type defines the prototype for functions 257* used to copy elements in a vector. 258* 259* SYNOPSIS 260*/ 261typedef void 262 (*cl_pfn_vec_copy_t) (IN void *const p_dest, 263 IN const void *const p_src, IN const size_t size); 264/* 265* PARAMETERS 266* p_dest 267* [in] Pointer to the destination buffer into which to copy p_src. 268* 269* p_src 270* [in] Pointer to the destination buffer from which to copy. 271* 272* size 273* [in] Number of bytes to copy. 274* 275* RETURN VALUE 276* This function does not return a value. 277* 278* SEE ALSO 279* Vector 280*********/ 281 282/****s* Component Library: Vector/cl_vector_t 283* NAME 284* cl_vector_t 285* 286* DESCRIPTION 287* Vector structure. 288* 289* The cl_vector_t structure should be treated as opaque and should be 290* manipulated only through the provided functions. 291* 292* SYNOPSIS 293*/ 294typedef struct _cl_vector { 295 size_t size; 296 size_t grow_size; 297 size_t capacity; 298 size_t element_size; 299 cl_pfn_vec_init_t pfn_init; 300 cl_pfn_vec_dtor_t pfn_dtor; 301 cl_pfn_vec_copy_t pfn_copy; 302 const void *context; 303 cl_qlist_t alloc_list; 304 void **p_ptr_array; 305 cl_state_t state; 306} cl_vector_t; 307/* 308* FIELDS 309* size 310* Number of elements successfully initialized in the vector. 311* 312* grow_size 313* Number of elements to allocate when growing. 314* 315* capacity 316* total # of elements allocated. 317* 318* element_size 319* Size of each element. 320* 321* pfn_init 322* User supplied element initializer. 323* 324* pfn_dtor 325* User supplied element destructor. 326* 327* pfn_copy 328* Copy operator. 329* 330* context 331* User context for callbacks. 332* 333* alloc_list 334* List of allocations. 335* 336* p_ptr_array 337* Internal array of pointers to elements. 338* 339* state 340* State of the vector. 341* 342* SEE ALSO 343* Vector 344*********/ 345 346/****f* Component Library: Vector/cl_vector_construct 347* NAME 348* cl_vector_construct 349* 350* DESCRIPTION 351* The cl_vector_construct function constructs a vector. 352* 353* SYNOPSIS 354*/ 355void cl_vector_construct(IN cl_vector_t * const p_vector); 356/* 357* PARAMETERS 358* p_vector 359* [in] Pointer to a cl_vector_t structure to construct. 360* 361* RETURN VALUE 362* This function does not return a value. 363* 364* NOTES 365* Allows calling cl_vector_destroy without first calling cl_vector_init. 366* 367* Calling cl_vector_construct is a prerequisite to calling any other 368* vector function except cl_vector_init. 369* 370* SEE ALSO 371* Vector, cl_vector_init, cl_vector_destroy 372*********/ 373 374/****f* Component Library: Vector/cl_vector_init 375* NAME 376* cl_vector_init 377* 378* DESCRIPTION 379* The cl_vector_init function initializes a vector for use. 380* 381* SYNOPSIS 382*/ 383cl_status_t 384cl_vector_init(IN cl_vector_t * const p_vector, 385 IN const size_t min_size, 386 IN const size_t grow_size, 387 IN const size_t element_size, 388 IN cl_pfn_vec_init_t pfn_init OPTIONAL, 389 IN cl_pfn_vec_dtor_t pfn_dtor OPTIONAL, 390 IN const void *const context); 391/* 392* PARAMETERS 393* p_vector 394* [in] Pointer to a cl_vector_t structure to inititalize. 395* 396* min_size 397* [in] Initial number of elements. 398* 399* grow_size 400* [in] Number of elements to allocate when incrementally growing 401* the vector. A value of zero disables automatic growth. 402* 403* element_size 404* [in] Size of each element. 405* 406* pfn_init 407* [in] Initializer callback to invoke for every new element. 408* See the cl_pfn_vec_init_t function type declaration for details about 409* the callback function. 410* 411* pfn_dtor 412* [in] Destructor callback to invoke for elements being deallocated. 413* See the cl_pfn_vec_dtor_t function type declaration for details about 414* the callback function. 415* 416* context 417* [in] Value to pass to the callback functions to provide context. 418* 419* RETURN VALUES 420* CL_SUCCESS if the vector was initialized successfully. 421* 422* CL_INSUFFICIENT_MEMORY if the initialization failed. 423* 424* cl_status_t value returned by optional initializer function specified by 425* the pfn_init parameter. 426* 427* NOTES 428* The constructor and initializer functions, if any, are invoked for every 429* new element in the array. 430* 431* SEE ALSO 432* Vector, cl_vector_construct, cl_vector_destroy, cl_vector_set, 433* cl_vector_get, cl_vector_get_ptr, cl_vector_at 434*********/ 435 436/****f* Component Library: Vector/cl_vector_destroy 437* NAME 438* cl_vector_destroy 439* 440* DESCRIPTION 441* The cl_vector_destroy function destroys a vector. 442* 443* SYNOPSIS 444*/ 445void cl_vector_destroy(IN cl_vector_t * const p_vector); 446/* 447* PARAMETERS 448* p_vector 449* [in] Pointer to a cl_vector_t structure to destroy. 450* 451* RETURN VALUE 452* This function does not return a value. 453* 454* NOTES 455* cl_vector_destroy frees all memory allocated for the vector. The vector 456* is left initialized to a zero capacity and size. 457* 458* This function should only be called after a call to cl_vector_construct 459* or cl_vector_init. 460* 461* SEE ALSO 462* Vector, cl_vector_construct, cl_vector_init 463*********/ 464 465/****f* Component Library: Vector/cl_vector_get_capacity 466* NAME 467* cl_vector_get_capacity 468* 469* DESCRIPTION 470* The cl_vector_get_capacity function returns the capacity of a vector. 471* 472* SYNOPSIS 473*/ 474static inline size_t 475cl_vector_get_capacity(IN const cl_vector_t * const p_vector) 476{ 477 CL_ASSERT(p_vector); 478 CL_ASSERT(p_vector->state == CL_INITIALIZED); 479 480 return (p_vector->capacity); 481} 482 483/* 484* PARAMETERS 485* p_vector 486* [in] Pointer to a cl_vector_t structure whose capacity to return. 487* 488* RETURN VALUE 489* Capacity, in elements, of the vector. 490* 491* NOTES 492* The capacity is the number of elements that the vector can store, and 493* can be greater than the number of elements stored. To get the number of 494* elements stored in the vector, use cl_vector_get_size. 495* 496* SEE ALSO 497* Vector, cl_vector_set_capacity, cl_vector_get_size 498*********/ 499 500/****f* Component Library: Vector/cl_vector_get_size 501* NAME 502* cl_vector_get_size 503* 504* DESCRIPTION 505* The cl_vector_get_size function returns the size of a vector. 506* 507* SYNOPSIS 508*/ 509static inline size_t cl_vector_get_size(IN const cl_vector_t * const p_vector) 510{ 511 CL_ASSERT(p_vector); 512 CL_ASSERT(p_vector->state == CL_INITIALIZED); 513 514 return (p_vector->size); 515} 516 517/* 518* PARAMETERS 519* p_vector 520* [in] Pointer to a cl_vector_t structure whose size to return. 521* 522* RETURN VALUE 523* Size, in elements, of the vector. 524* 525* SEE ALSO 526* Vector, cl_vector_set_size, cl_vector_get_capacity 527*********/ 528 529/****f* Component Library: Vector/cl_vector_get_ptr 530* NAME 531* cl_vector_get_ptr 532* 533* DESCRIPTION 534* The cl_vector_get_ptr function returns a pointer to an element 535* stored in a vector at a specified index. 536* 537* SYNOPSIS 538*/ 539static inline void *cl_vector_get_ptr(IN const cl_vector_t * const p_vector, 540 IN const size_t index) 541{ 542 CL_ASSERT(p_vector); 543 CL_ASSERT(p_vector->state == CL_INITIALIZED); 544 545 return (p_vector->p_ptr_array[index]); 546} 547 548/* 549* PARAMETERS 550* p_vector 551* [in] Pointer to a cl_vector_t structure from which to get a 552* pointer to an element. 553* 554* index 555* [in] Index of the element. 556* 557* RETURN VALUE 558* Pointer to the element stored at specified index. 559* 560* NOTES 561* cl_vector_get_ptr provides constant access times regardless of the index. 562* 563* cl_vector_get_ptr does not perform boundary checking. Callers are 564* responsible for providing an index that is within the range of the vector. 565* 566* SEE ALSO 567* Vector, cl_vector_get, cl_vector_at, cl_vector_set, cl_vector_get_size 568*********/ 569 570/****f* Component Library: Vector/cl_vector_get 571* NAME 572* cl_vector_get 573* 574* DESCRIPTION 575* The cl_vector_get function copies an element stored in a vector at a 576* specified index. 577* 578* SYNOPSIS 579*/ 580static inline void 581cl_vector_get(IN const cl_vector_t * const p_vector, 582 IN const size_t index, OUT void *const p_element) 583{ 584 void *p_src; 585 586 CL_ASSERT(p_vector); 587 CL_ASSERT(p_vector->state == CL_INITIALIZED); 588 CL_ASSERT(p_element); 589 590 /* Get a pointer to the element. */ 591 p_src = cl_vector_get_ptr(p_vector, index); 592 p_vector->pfn_copy(p_src, p_element, p_vector->element_size); 593} 594 595/* 596* PARAMETERS 597* p_vector 598* [in] Pointer to a cl_vector_t structure from which to get a copy of 599* an element. 600* 601* index 602* [in] Index of the element. 603* 604* p_element 605* [out] Pointer to storage for the element. Contains a copy of the 606* desired element upon successful completion of the call. 607* 608* RETURN VALUE 609* This function does not return a value. 610* 611* NOTES 612* cl_vector_get provides constant time access regardless of the index. 613* 614* cl_vector_get does not perform boundary checking on the vector, and 615* callers are responsible for providing an index that is within the range 616* of the vector. To access elements after performing boundary checks, 617* use cl_vector_at. 618* 619* The p_element parameter contains a copy of the desired element upon 620* return from this function. 621* 622* SEE ALSO 623* Vector, cl_vector_get_ptr, cl_vector_at 624*********/ 625 626/****f* Component Library: Vector/cl_vector_at 627* NAME 628* cl_vector_at 629* 630* DESCRIPTION 631* The cl_vector_at function copies an element stored in a vector at a 632* specified index, performing boundary checks. 633* 634* SYNOPSIS 635*/ 636cl_status_t 637cl_vector_at(IN const cl_vector_t * const p_vector, 638 IN const size_t index, OUT void *const p_element); 639/* 640* PARAMETERS 641* p_vector 642* [in] Pointer to a cl_vector_t structure from which to get a copy of 643* an element. 644* 645* index 646* [in] Index of the element. 647* 648* p_element 649* [out] Pointer to storage for the element. Contains a copy of the 650* desired element upon successful completion of the call. 651* 652* RETURN VALUES 653* CL_SUCCESS if an element was found at the specified index. 654* 655* CL_INVALID_SETTING if the index was out of range. 656* 657* NOTES 658* cl_vector_at provides constant time access regardless of the index, and 659* performs boundary checking on the vector. 660* 661* Upon success, the p_element parameter contains a copy of the desired element. 662* 663* SEE ALSO 664* Vector, cl_vector_get, cl_vector_get_ptr 665*********/ 666 667/****f* Component Library: Vector/cl_vector_set 668* NAME 669* cl_vector_set 670* 671* DESCRIPTION 672* The cl_vector_set function sets the element at the specified index. 673* 674* SYNOPSIS 675*/ 676cl_status_t 677cl_vector_set(IN cl_vector_t * const p_vector, 678 IN const size_t index, IN void *const p_element); 679/* 680* PARAMETERS 681* p_vector 682* [in] Pointer to a cl_vector_t structure into which to store 683* an element. 684* 685* index 686* [in] Index of the element. 687* 688* p_element 689* [in] Pointer to an element to store in the vector. 690* 691* RETURN VALUES 692* CL_SUCCESS if the element was successfully set. 693* 694* CL_INSUFFICIENT_MEMORY if the vector could not be resized to accommodate 695* the new element. 696* 697* NOTES 698* cl_vector_set grows the vector as needed to accommodate the new element, 699* unless the grow_size parameter passed into the cl_vector_init function 700* was zero. 701* 702* SEE ALSO 703* Vector, cl_vector_get 704*********/ 705 706/****f* Component Library: Vector/cl_vector_set_capacity 707* NAME 708* cl_vector_set_capacity 709* 710* DESCRIPTION 711* The cl_vector_set_capacity function reserves memory in a vector for a 712* specified number of elements. 713* 714* SYNOPSIS 715*/ 716cl_status_t 717cl_vector_set_capacity(IN cl_vector_t * const p_vector, 718 IN const size_t new_capacity); 719/* 720* PARAMETERS 721* p_vector 722* [in] Pointer to a cl_vector_t structure whose capacity to set. 723* 724* new_capacity 725* [in] Total number of elements for which the vector should 726* allocate memory. 727* 728* RETURN VALUES 729* CL_SUCCESS if the capacity was successfully set. 730* 731* CL_INSUFFICIENT_MEMORY if there was not enough memory to satisfy the 732* operation. The vector is left unchanged. 733* 734* NOTES 735* cl_vector_set_capacity increases the capacity of the vector. It does 736* not change the size of the vector. If the requested capacity is less 737* than the current capacity, the vector is left unchanged. 738* 739* SEE ALSO 740* Vector, cl_vector_get_capacity, cl_vector_set_size, 741* cl_vector_set_min_size 742*********/ 743 744/****f* Component Library: Vector/cl_vector_set_size 745* NAME 746* cl_vector_set_size 747* 748* DESCRIPTION 749* The cl_vector_set_size function resizes a vector, either increasing or 750* decreasing its size. 751* 752* SYNOPSIS 753*/ 754cl_status_t 755cl_vector_set_size(IN cl_vector_t * const p_vector, IN const size_t size); 756/* 757* PARAMETERS 758* p_vector 759* [in] Pointer to a cl_vector_t structure whose size to set. 760* 761* size 762* [in] Number of elements desired in the vector. 763* 764* RETURN VALUES 765* CL_SUCCESS if the size of the vector was set successfully. 766* 767* CL_INSUFFICIENT_MEMORY if there was not enough memory to complete the 768* operation. The vector is left unchanged. 769* 770* NOTES 771* cl_vector_set_size sets the vector to the specified size. If size is 772* smaller than the current size of the vector, the size is reduced. 773* The destructor function, if any, will be invoked for all elements that 774* are above size. Likewise, the constructor and initializer, if any, will 775* be invoked for all new elements. 776* 777* This function can only fail if size is larger than the current capacity. 778* 779* SEE ALSO 780* Vector, cl_vector_get_size, cl_vector_set_min_size, 781* cl_vector_set_capacity 782*********/ 783 784/****f* Component Library: Vector/cl_vector_set_min_size 785* NAME 786* cl_vector_set_min_size 787* 788* DESCRIPTION 789* The cl_vector_set_min_size function resizes a vector to a specified size 790* if the vector is smaller than the specified size. 791* 792* SYNOPSIS 793*/ 794cl_status_t 795cl_vector_set_min_size(IN cl_vector_t * const p_vector, 796 IN const size_t min_size); 797/* 798* PARAMETERS 799* p_vector 800* [in] Pointer to a cl_vector_t structure whose minimum size to set. 801* 802* min_size 803* [in] Minimum number of elements that the vector should contain. 804* 805* RETURN VALUES 806* CL_SUCCESS if the vector size is greater than or equal to min_size. This 807* could indicate that the vector's capacity was increased to min_size or 808* that the vector was already of sufficient size. 809* 810* CL_INSUFFICIENT_MEMORY if there was not enough memory to resize the vector. 811* The vector is left unchanged. 812* 813* NOTES 814* If min_size is smaller than the current size of the vector, the vector is 815* unchanged. The vector is unchanged if the size could not be changed due 816* to insufficient memory being available to perform the operation. 817* 818* SEE ALSO 819* Vector, cl_vector_get_size, cl_vector_set_size, cl_vector_set_capacity 820*********/ 821 822/****f* Component Library: Vector/cl_vector_apply_func 823* NAME 824* cl_vector_apply_func 825* 826* DESCRIPTION 827* The cl_vector_apply_func function invokes a specified function for every 828* element in a vector. 829* 830* SYNOPSIS 831*/ 832void 833cl_vector_apply_func(IN const cl_vector_t * const p_vector, 834 IN cl_pfn_vec_apply_t pfn_callback, 835 IN const void *const context); 836/* 837* PARAMETERS 838* p_vector 839* [in] Pointer to a cl_vector_t structure whose elements to iterate. 840* 841* pfn_callback 842* [in] Function invoked for every element in the array. 843* See the cl_pfn_vec_apply_t function type declaration for details 844* about the callback function. 845* 846* context 847* [in] Value to pass to the callback function. 848* 849* RETURN VALUE 850* This function does not return a value. 851* 852* NOTES 853* cl_vector_apply_func invokes the specified function for every element 854* in the vector, starting from the beginning of the vector. 855* 856* SEE ALSO 857* Vector, cl_vector_find_from_start, cl_vector_find_from_end, 858* cl_pfn_vec_apply_t 859*********/ 860 861/****f* Component Library: Vector/cl_vector_find_from_start 862* NAME 863* cl_vector_find_from_start 864* 865* DESCRIPTION 866* The cl_vector_find_from_start function uses a specified function to 867* search for elements in a vector starting from the lowest index. 868* 869* SYNOPSIS 870*/ 871size_t 872cl_vector_find_from_start(IN const cl_vector_t * const p_vector, 873 IN cl_pfn_vec_find_t pfn_callback, 874 IN const void *const context); 875/* 876* PARAMETERS 877* p_vector 878* [in] Pointer to a cl_vector_t structure to inititalize. 879* 880* pfn_callback 881* [in] Function invoked to determine if a match was found. 882* See the cl_pfn_vec_find_t function type declaration for details 883* about the callback function. 884* 885* context 886* [in] Value to pass to the callback function. 887* 888* RETURN VALUES 889* Index of the element, if found. 890* 891* Size of the vector if the element was not found. 892* 893* NOTES 894* cl_vector_find_from_start does not remove the found element from 895* the vector. The index of the element is returned when the function 896* provided by the pfn_callback parameter returns CL_SUCCESS. 897* 898* SEE ALSO 899* Vector, cl_vector_find_from_end, cl_vector_apply_func, cl_pfn_vec_find_t 900*********/ 901 902/****f* Component Library: Vector/cl_vector_find_from_end 903* NAME 904* cl_vector_find_from_end 905* 906* DESCRIPTION 907* The cl_vector_find_from_end function uses a specified function to search 908* for elements in a vector starting from the highest index. 909* 910* SYNOPSIS 911*/ 912size_t 913cl_vector_find_from_end(IN const cl_vector_t * const p_vector, 914 IN cl_pfn_vec_find_t pfn_callback, 915 IN const void *const context); 916/* 917* PARAMETERS 918* p_vector 919* [in] Pointer to a cl_vector_t structure to inititalize. 920* 921* pfn_callback 922* [in] Function invoked to determine if a match was found. 923* See the cl_pfn_vec_find_t function type declaration for details 924* about the callback function. 925* 926* context 927* [in] Value to pass to the callback function. 928* 929* RETURN VALUES 930* Index of the element, if found. 931* 932* Size of the vector if the element was not found. 933* 934* NOTES 935* cl_vector_find_from_end does not remove the found element from 936* the vector. The index of the element is returned when the function 937* provided by the pfn_callback parameter returns CL_SUCCESS. 938* 939* SEE ALSO 940* Vector, cl_vector_find_from_start, cl_vector_apply_func, 941* cl_pfn_vec_find_t 942*********/ 943 944END_C_DECLS 945#endif /* _CL_VECTOR_H_ */ 946