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
cl_vector_get_capacity(IN const cl_vector_t * const p_vector)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 */
cl_vector_get_size(IN const cl_vector_t * const p_vector)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 */
cl_vector_get_ptr(IN const cl_vector_t * const p_vector,IN const size_t index)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
cl_vector_get(IN const cl_vector_t * const p_vector,IN const size_t index,OUT void * const p_element)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