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 56 BEGIN_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 */ 115 typedef 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 */ 154 typedef 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 */ 186 typedef 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 */ 222 typedef 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 */ 261 typedef 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 */ 294 typedef 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 */ 355 void 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 */ 383 cl_status_t 384 cl_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 */ 445 void 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 */ 474 static inline size_t 475 cl_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 */ 509 static 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 */ 539 static 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 */ 580 static inline void 581 cl_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 */ 636 cl_status_t 637 cl_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 */ 676 cl_status_t 677 cl_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 */ 716 cl_status_t 717 cl_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 */ 754 cl_status_t 755 cl_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 */ 794 cl_status_t 795 cl_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 */ 832 void 833 cl_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 */ 871 size_t 872 cl_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 */ 912 size_t 913 cl_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 944 END_C_DECLS 945 #endif /* _CL_VECTOR_H_ */ 946