1 /*
2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
5 *
6 * This software is available to you under a choice of one of two
7 * licenses. You may choose to be licensed under the terms of the GNU
8 * General Public License (GPL) Version 2, available from the file
9 * COPYING in the main directory of this source tree, or the
10 * OpenIB.org BSD license below:
11 *
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
14 * conditions are met:
15 *
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
18 * disclaimer.
19 *
20 * - Redistributions in binary form must reproduce the above
21 * copyright notice, this list of conditions and the following
22 * disclaimer in the documentation and/or other materials
23 * provided with the distribution.
24 *
25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
32 * SOFTWARE.
33 *
34 */
35
36 /*
37 * Abstract:
38 * This file contains pointer vector definitions. Pointer Vector provides
39 * dynmically resizable array functionality.
40 */
41
42 #ifndef _CL_PTR_VECTOR_H_
43 #define _CL_PTR_VECTOR_H_
44
45 #include <complib/cl_types.h>
46
47 #ifdef __cplusplus
48 # define BEGIN_C_DECLS extern "C" {
49 # define END_C_DECLS }
50 #else /* !__cplusplus */
51 # define BEGIN_C_DECLS
52 # define END_C_DECLS
53 #endif /* __cplusplus */
54
55 BEGIN_C_DECLS
56 /****h* Component Library/Pointer Vector
57 * NAME
58 * Pointer Vector
59 *
60 * DESCRIPTION
61 * The Pointer Vector is a self-sizing array of pointers. Like a traditonal
62 * array, a pointer vector allows efficient constant time access to elements
63 * with a specified index. A pointer vector grows transparently as the
64 * user adds elements to the array.
65 *
66 * The cl_pointer vector_t structure should be treated as opaque and should be
67 * manipulated only through the provided functions.
68 *
69 * SEE ALSO
70 * Structures:
71 * cl_ptr_vector_t
72 *
73 * Callbacks:
74 * cl_pfn_ptr_vec_apply_t, cl_pfn_ptr_vec_find_t
75 *
76 * Item Manipulation:
77 * cl_ptr_vector_set, cl_ptr_vector_obj
78 *
79 * Initialization:
80 * cl_ptr_vector_construct, cl_ptr_vector_init, cl_ptr_vector_destroy
81 *
82 * Manipulation:
83 * cl_ptr_vector_get_capacity, cl_ptr_vector_set_capacity,
84 * cl_ptr_vector_get_size, cl_ptr_vector_set_size, cl_ptr_vector_set_min_size
85 * cl_ptr_vector_get_ptr, cl_ptr_vector_get, cl_ptr_vector_at, cl_ptr_vector_set
86 *
87 * Search:
88 * cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end
89 * cl_ptr_vector_apply_func
90 *********/
91 /****d* Component Library: Pointer Vector/cl_pfn_ptr_vec_apply_t
92 * NAME
93 * cl_pfn_ptr_vec_apply_t
94 *
95 * DESCRIPTION
96 * The cl_pfn_ptr_vec_apply_t function type defines the prototype for
97 * functions used to iterate elements in a pointer vector.
98 *
99 * SYNOPSIS
100 */
101 typedef void
102 (*cl_pfn_ptr_vec_apply_t) (IN const size_t index,
103 IN void *const element, IN void *context);
104 /*
105 * PARAMETERS
106 * index
107 * [in] Index of the element.
108 *
109 * p_element
110 * [in] Pointer to an element at the specified index in the pointer vector.
111 *
112 * context
113 * [in] Context provided in a call to cl_ptr_vector_apply_func.
114 *
115 * RETURN VALUE
116 * This function does not return a value.
117 *
118 * NOTES
119 * This function type is provided as function prototype reference for
120 * the function passed by users as a parameter to the cl_ptr_vector_apply_func
121 * function.
122 *
123 * SEE ALSO
124 * Pointer Vector, cl_ptr_vector_apply_func
125 *********/
126
127 /****d* Component Library: Pointer Vector/cl_pfn_ptr_vec_find_t
128 * NAME
129 * cl_pfn_ptr_vec_find_t
130 *
131 * DESCRIPTION
132 * The cl_pfn_ptr_vec_find_t function type defines the prototype for
133 * functions used to find elements in a pointer vector.
134 *
135 * SYNOPSIS
136 */
137 typedef cl_status_t
138 (*cl_pfn_ptr_vec_find_t) (IN const size_t index,
139 IN const void *const element, IN void *context);
140 /*
141 * PARAMETERS
142 * index
143 * [in] Index of the element.
144 *
145 * p_element
146 * [in] Pointer to an element at the specified index in the
147 * pointer vector.
148 *
149 * context
150 * [in] Context provided in a call to cl_ptr_vector_find_from_start or
151 * cl_ptr_vector_find_from_end.
152 *
153 * RETURN VALUES
154 * Return CL_SUCCESS if the element was found. This stops pointer vector
155 * iteration.
156 *
157 * CL_NOT_FOUND to continue the pointer vector iteration.
158 *
159 * NOTES
160 * This function type is provided as function prototype reference for the
161 * function provided by users as a parameter to the
162 * cl_ptr_vector_find_from_start and cl_ptr_vector_find_from_end functions.
163 *
164 * SEE ALSO
165 * Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end
166 *********/
167
168 /****s* Component Library: Pointer Vector/cl_ptr_vector_t
169 * NAME
170 * cl_ptr_vector_t
171 *
172 * DESCRIPTION
173 * Pointer Vector structure.
174 *
175 * The cl_ptr_vector_t structure should be treated as opaque and should be
176 * manipulated only through the provided functions.
177 *
178 * SYNOPSIS
179 */
180 typedef struct _cl_ptr_vector {
181 size_t size;
182 size_t grow_size;
183 size_t capacity;
184 const void **p_ptr_array;
185 cl_state_t state;
186 } cl_ptr_vector_t;
187 /*
188 * FIELDS
189 * size
190 * Number of elements successfully initialized in the pointer vector.
191 *
192 * grow_size
193 * Number of elements to allocate when growing.
194 *
195 * capacity
196 * total # of elements allocated.
197 *
198 * alloc_list
199 * List of allocations.
200 *
201 * p_ptr_array
202 * Internal array of pointers to elements.
203 *
204 * state
205 * State of the pointer vector.
206 *
207 * SEE ALSO
208 * Pointer Vector
209 *********/
210
211 /****f* Component Library: Pointer Vector/cl_ptr_vector_construct
212 * NAME
213 * cl_ptr_vector_construct
214 *
215 * DESCRIPTION
216 * The cl_ptr_vector_construct function constructs a pointer vector.
217 *
218 * SYNOPSIS
219 */
220 void cl_ptr_vector_construct(IN cl_ptr_vector_t * const p_vector);
221 /*
222 * PARAMETERS
223 * p_vector
224 * [in] Pointer to a cl_ptr_vector_t structure to construct.
225 *
226 * RETURN VALUE
227 * This function does not return a value.
228 *
229 * NOTES
230 * Allows calling cl_ptr_vector_destroy without first calling
231 * cl_ptr_vector_init.
232 *
233 * Calling cl_ptr_vector_construct is a prerequisite to calling any other
234 * pointer vector function except cl_ptr_vector_init.
235 *
236 * SEE ALSO
237 * Pointer Vector, cl_ptr_vector_init, cl_ptr_vector_destroy
238 *********/
239
240 /****f* Component Library: Pointer Vector/cl_ptr_vector_init
241 * NAME
242 * cl_ptr_vector_init
243 *
244 * DESCRIPTION
245 * The cl_ptr_vector_init function initializes a pointer vector for use.
246 *
247 * SYNOPSIS
248 */
249 cl_status_t
250 cl_ptr_vector_init(IN cl_ptr_vector_t * const p_vector,
251 IN const size_t min_size, IN const size_t grow_size);
252 /*
253 * PARAMETERS
254 * p_vector
255 * [in] Pointer to a cl_ptr_vector_t structure to inititalize.
256 *
257 * min_size
258 * [in] Initial number of elements.
259 *
260 * grow_size
261 * [in] Number of elements to allocate when incrementally growing
262 * the pointer vector. A value of zero disables automatic growth.
263 *
264 * RETURN VALUES
265 * CL_SUCCESS if the pointer vector was initialized successfully.
266 *
267 * CL_INSUFFICIENT_MEMORY if the initialization failed.
268 *
269 * SEE ALSO
270 * Pointer Vector, cl_ptr_vector_construct, cl_ptr_vector_destroy,
271 * cl_ptr_vector_set, cl_ptr_vector_get, cl_ptr_vector_at
272 *********/
273
274 /****f* Component Library: Pointer Vector/cl_ptr_vector_destroy
275 * NAME
276 * cl_ptr_vector_destroy
277 *
278 * DESCRIPTION
279 * The cl_ptr_vector_destroy function destroys a pointer vector.
280 *
281 * SYNOPSIS
282 */
283 void cl_ptr_vector_destroy(IN cl_ptr_vector_t * const p_vector);
284 /*
285 * PARAMETERS
286 * p_vector
287 * [in] Pointer to a cl_ptr_vector_t structure to destroy.
288 *
289 * RETURN VALUE
290 * This function does not return a value.
291 *
292 * NOTES
293 * cl_ptr_vector_destroy frees all memory allocated for the pointer vector.
294 *
295 * This function should only be called after a call to cl_ptr_vector_construct
296 * or cl_ptr_vector_init.
297 *
298 * SEE ALSO
299 * Pointer Vector, cl_ptr_vector_construct, cl_ptr_vector_init
300 *********/
301
302 /****f* Component Library: Pointer Vector/cl_ptr_vector_get_capacity
303 * NAME
304 * cl_ptr_vector_get_capacity
305 *
306 * DESCRIPTION
307 * The cl_ptr_vector_get_capacity function returns the capacity of
308 * a pointer vector.
309 *
310 * SYNOPSIS
311 */
312 static inline size_t
cl_ptr_vector_get_capacity(IN const cl_ptr_vector_t * const p_vector)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
cl_ptr_vector_get_size(IN const cl_ptr_vector_t * const p_vector)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 */
cl_ptr_vector_get(IN const cl_ptr_vector_t * const p_vector,IN const size_t index)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
cl_ptr_vector_insert(IN cl_ptr_vector_t * const p_vector,IN const void * const element,OUT size_t * const p_index OPTIONAL)502 cl_ptr_vector_insert(IN cl_ptr_vector_t * const p_vector,
503 IN const void *const element,
504 OUT size_t * const p_index OPTIONAL)
505 {
506 cl_status_t status;
507
508 CL_ASSERT(p_vector);
509 CL_ASSERT(p_vector->state == CL_INITIALIZED);
510
511 status = cl_ptr_vector_set(p_vector, p_vector->size, element);
512 if (status == CL_SUCCESS && p_index)
513 *p_index = p_vector->size - 1;
514
515 return (status);
516 }
517
518 /*
519 * PARAMETERS
520 * p_vector
521 * [in] Pointer to a cl_ptr_vector_t structure into which to store
522 * an element.
523 *
524 * element
525 * [in] Pointer to store in the pointer vector.
526 *
527 * p_index
528 * [out] Pointer to the index of the element. Valid only if
529 * insertion was successful.
530 *
531 * RETURN VALUES
532 * CL_SUCCESS if the element was successfully inserted.
533 *
534 * CL_INSUFFICIENT_MEMORY if the pointer vector could not be resized to
535 * accommodate the new element.
536 *
537 * NOTES
538 * cl_ptr_vector_insert places the new element at the end of
539 * the pointer vector.
540 *
541 * cl_ptr_vector_insert grows the pointer vector as needed to accommodate
542 * the new element, unless the grow_size parameter passed into the
543 * cl_ptr_vector_init function was zero.
544 *
545 * SEE ALSO
546 * Pointer Vector, cl_ptr_vector_remove, cl_ptr_vector_set
547 *********/
548
549 /****f* Component Library: Pointer Vector/cl_ptr_vector_remove
550 * NAME
551 * cl_ptr_vector_remove
552 *
553 * DESCRIPTION
554 * The cl_ptr_vector_remove function removes and returns the pointer stored
555 * in a pointer vector at a specified index. Items beyond the removed item
556 * are shifted down and the size of the pointer vector is decremented.
557 *
558 * SYNOPSIS
559 */
560 void *cl_ptr_vector_remove(IN cl_ptr_vector_t * const p_vector,
561 IN const size_t index);
562 /*
563 * PARAMETERS
564 * p_vector
565 * [in] Pointer to a cl_ptr_vector_t structure from which to get an
566 * element.
567 *
568 * index
569 * [in] Index of the element.
570 *
571 * RETURN VALUE
572 * Value of the pointer stored at the specified index.
573 *
574 * NOTES
575 * cl_ptr_vector_get does not perform boundary checking. Callers are
576 * responsible for providing an index that is within the range of the pointer
577 * vector.
578 *
579 * SEE ALSO
580 * Pointer Vector, cl_ptr_vector_insert, cl_ptr_vector_get_size
581 *********/
582
583 /****f* Component Library: Pointer Vector/cl_ptr_vector_set_capacity
584 * NAME
585 * cl_ptr_vector_set_capacity
586 *
587 * DESCRIPTION
588 * The cl_ptr_vector_set_capacity function reserves memory in a
589 * pointer vector for a specified number of pointers.
590 *
591 * SYNOPSIS
592 */
593 cl_status_t
594 cl_ptr_vector_set_capacity(IN cl_ptr_vector_t * const p_vector,
595 IN const size_t new_capacity);
596 /*
597 * PARAMETERS
598 * p_vector
599 * [in] Pointer to a cl_ptr_vector_t structure whose capacity to set.
600 *
601 * new_capacity
602 * [in] Total number of elements for which the pointer vector should
603 * allocate memory.
604 *
605 * RETURN VALUES
606 * CL_SUCCESS if the capacity was successfully set.
607 *
608 * CL_INSUFFICIENT_MEMORY if there was not enough memory to satisfy the
609 * operation. The pointer vector is left unchanged.
610 *
611 * NOTES
612 * cl_ptr_vector_set_capacity increases the capacity of the pointer vector.
613 * It does not change the size of the pointer vector. If the requested
614 * capacity is less than the current capacity, the pointer vector is left
615 * unchanged.
616 *
617 * SEE ALSO
618 * Pointer Vector, cl_ptr_vector_get_capacity, cl_ptr_vector_set_size,
619 * cl_ptr_vector_set_min_size
620 *********/
621
622 /****f* Component Library: Pointer Vector/cl_ptr_vector_set_size
623 * NAME
624 * cl_ptr_vector_set_size
625 *
626 * DESCRIPTION
627 * The cl_ptr_vector_set_size function resizes a pointer vector, either
628 * increasing or decreasing its size.
629 *
630 * SYNOPSIS
631 */
632 cl_status_t
633 cl_ptr_vector_set_size(IN cl_ptr_vector_t * const p_vector,
634 IN const size_t size);
635 /*
636 * PARAMETERS
637 * p_vector
638 * [in] Pointer to a cl_ptr_vector_t structure whose size to set.
639 *
640 * size
641 * [in] Number of elements desired in the pointer vector.
642 *
643 * RETURN VALUES
644 * CL_SUCCESS if the size of the pointer vector was set successfully.
645 *
646 * CL_INSUFFICIENT_MEMORY if there was not enough memory to complete the
647 * operation. The pointer vector is left unchanged.
648 *
649 * NOTES
650 * cl_ptr_vector_set_size sets the pointer vector to the specified size.
651 * If size is smaller than the current size of the pointer vector, the size
652 * is reduced.
653 *
654 * This function can only fail if size is larger than the current capacity.
655 *
656 * SEE ALSO
657 * Pointer Vector, cl_ptr_vector_get_size, cl_ptr_vector_set_min_size,
658 * cl_ptr_vector_set_capacity
659 *********/
660
661 /****f* Component Library: Pointer Vector/cl_ptr_vector_set_min_size
662 * NAME
663 * cl_ptr_vector_set_min_size
664 *
665 * DESCRIPTION
666 * The cl_ptr_vector_set_min_size function resizes a pointer vector to a
667 * specified size if the pointer vector is smaller than the specified size.
668 *
669 * SYNOPSIS
670 */
671 cl_status_t
672 cl_ptr_vector_set_min_size(IN cl_ptr_vector_t * const p_vector,
673 IN const size_t min_size);
674 /*
675 * PARAMETERS
676 * p_vector
677 * [in] Pointer to a cl_ptr_vector_t structure whose minimum size to set.
678 *
679 * min_size
680 * [in] Minimum number of elements that the pointer vector should contain.
681 *
682 * RETURN VALUES
683 * CL_SUCCESS if the pointer vector size is greater than or equal to min_size.
684 * This could indicate that the pointer vector's capacity was increased to
685 * min_size or that the pointer vector was already of sufficient size.
686 *
687 * CL_INSUFFICIENT_MEMORY if there was not enough memory to resize the
688 * pointer vector. The pointer vector is left unchanged.
689 *
690 * NOTES
691 * If min_size is smaller than the current size of the pointer vector,
692 * the pointer vector is unchanged. The pointer vector is unchanged if the
693 * size could not be changed due to insufficient memory being available to
694 * perform the operation.
695 *
696 * SEE ALSO
697 * Pointer Vector, cl_ptr_vector_get_size, cl_ptr_vector_set_size,
698 * cl_ptr_vector_set_capacity
699 *********/
700
701 /****f* Component Library: Pointer Vector/cl_ptr_vector_apply_func
702 * NAME
703 * cl_ptr_vector_apply_func
704 *
705 * DESCRIPTION
706 * The cl_ptr_vector_apply_func function invokes a specified function for
707 * every element in a pointer vector.
708 *
709 * SYNOPSIS
710 */
711 void
712 cl_ptr_vector_apply_func(IN const cl_ptr_vector_t * const p_vector,
713 IN cl_pfn_ptr_vec_apply_t pfn_callback,
714 IN const void *const context);
715 /*
716 * PARAMETERS
717 * p_vector
718 * [in] Pointer to a cl_ptr_vector_t structure whose elements to iterate.
719 *
720 * pfn_callback
721 * [in] Function invoked for every element in the array.
722 * See the cl_pfn_ptr_vec_apply_t function type declaration for details
723 * about the callback function.
724 *
725 * context
726 * [in] Value to pass to the callback function.
727 *
728 * RETURN VALUE
729 * This function does not return a value.
730 *
731 * NOTES
732 * cl_ptr_vector_apply_func invokes the specified function for every element
733 * in the pointer vector, starting from the beginning of the pointer vector.
734 *
735 * SEE ALSO
736 * Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end,
737 * cl_pfn_ptr_vec_apply_t
738 *********/
739
740 /****f* Component Library: Pointer Vector/cl_ptr_vector_find_from_start
741 * NAME
742 * cl_ptr_vector_find_from_start
743 *
744 * DESCRIPTION
745 * The cl_ptr_vector_find_from_start function uses a specified function to
746 * search for elements in a pointer vector starting from the lowest index.
747 *
748 * SYNOPSIS
749 */
750 size_t
751 cl_ptr_vector_find_from_start(IN const cl_ptr_vector_t * const p_vector,
752 IN cl_pfn_ptr_vec_find_t pfn_callback,
753 IN const void *const context);
754 /*
755 * PARAMETERS
756 * p_vector
757 * [in] Pointer to a cl_ptr_vector_t structure to inititalize.
758 *
759 * pfn_callback
760 * [in] Function invoked to determine if a match was found.
761 * See the cl_pfn_ptr_vec_find_t function type declaration for details
762 * about the callback function.
763 *
764 * context
765 * [in] Value to pass to the callback function.
766 *
767 * RETURN VALUES
768 * Index of the element, if found.
769 *
770 * Size of the pointer vector if the element was not found.
771 *
772 * NOTES
773 * cl_ptr_vector_find_from_start does not remove the found element from
774 * the pointer vector. The index of the element is returned when the function
775 * provided by the pfn_callback parameter returns CL_SUCCESS.
776 *
777 * SEE ALSO
778 * Pointer Vector, cl_ptr_vector_find_from_end, cl_ptr_vector_apply_func,
779 * cl_pfn_ptr_vec_find_t
780 *********/
781
782 /****f* Component Library: Pointer Vector/cl_ptr_vector_find_from_end
783 * NAME
784 * cl_ptr_vector_find_from_end
785 *
786 * DESCRIPTION
787 * The cl_ptr_vector_find_from_end function uses a specified function to
788 * search for elements in a pointer vector starting from the highest index.
789 *
790 * SYNOPSIS
791 */
792 size_t
793 cl_ptr_vector_find_from_end(IN const cl_ptr_vector_t * const p_vector,
794 IN cl_pfn_ptr_vec_find_t pfn_callback,
795 IN const void *const context);
796 /*
797 * PARAMETERS
798 * p_vector
799 * [in] Pointer to a cl_ptr_vector_t structure to inititalize.
800 *
801 * pfn_callback
802 * [in] Function invoked to determine if a match was found.
803 * See the cl_pfn_ptr_vec_find_t function type declaration for details
804 * about the callback function.
805 *
806 * context
807 * [in] Value to pass to the callback function.
808 *
809 * RETURN VALUES
810 * Index of the element, if found.
811 *
812 * Size of the pointer vector if the element was not found.
813 *
814 * NOTES
815 * cl_ptr_vector_find_from_end does not remove the found element from
816 * the pointer vector. The index of the element is returned when the function
817 * provided by the pfn_callback parameter returns CL_SUCCESS.
818 *
819 * SEE ALSO
820 * Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_apply_func,
821 * cl_pfn_ptr_vec_find_t
822 *********/
823
824 END_C_DECLS
825 #endif /* _CL_PTR_VECTOR_H_ */
826