contrib/ofed/management/opensm/include/complib/cl_ptr_vector.h

   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 *       initial_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_ */