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 55 BEGIN_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 */ 101 typedef 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 */ 137 typedef 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 */ 180 typedef 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 */ 220 void 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 */ 249 cl_status_t 250 cl_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 */ 283 void 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 */ 312 static inline size_t 313 cl_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 */ 347 static inline uint32_t 348 cl_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 */ 378 static 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 */ 421 cl_status_t 422 cl_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 */ 462 cl_status_t 463 cl_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 */ 501 static inline cl_status_t 502 cl_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 */ 560 void *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 */ 593 cl_status_t 594 cl_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 */ 632 cl_status_t 633 cl_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 */ 671 cl_status_t 672 cl_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 */ 711 void 712 cl_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 */ 750 size_t 751 cl_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 */ 792 size_t 793 cl_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 824 END_C_DECLS 825 #endif /* _CL_PTR_VECTOR_H_ */ 826