contrib/ofed/management/opensm/include/complib/cl_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 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 *       initial_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_ */