[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_ptr_vector.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      This file contains pointer vector definitions.  Pointer Vector provides\r
37  *  dynmically resizable array functionality.\r
38  *\r
39  * Environment:\r
40  *      All\r
41  */\r
42 \r
43 \r
44 #ifndef _CL_PTR_VECTOR_H_\r
45 #define _CL_PTR_VECTOR_H_\r
46 \r
47 \r
48 #include <complib/cl_types.h>\r
49 \r
50 \r
51 /****h* Component Library/Pointer Vector\r
52 * NAME\r
53 *       Pointer Vector\r
54 *\r
55 * DESCRIPTION\r
56 *       The Pointer Vector is a self-sizing array of pointers. Like a traditonal\r
57 *       array, a pointer vector allows efficient constant time access to elements\r
58 *       with a specified index.  A pointer vector grows transparently as the\r
59 *       user adds elements to the array.\r
60 *\r
61 *       The cl_pointer vector_t structure should be treated as opaque and should be\r
62 *       manipulated only through the provided functions.\r
63 *\r
64 * SEE ALSO\r
65 *       Structures:\r
66 *               cl_ptr_vector_t\r
67 *\r
68 *       Callbacks:\r
69 *               cl_pfn_ptr_vec_apply_t, cl_pfn_ptr_vec_find_t\r
70 *\r
71 *       Item Manipulation:\r
72 *               cl_ptr_vector_set_obj, cl_ptr_vector_obj\r
73 *\r
74 *       Initialization:\r
75 *               cl_ptr_vector_construct, cl_ptr_vector_init, cl_ptr_vector_destroy\r
76 *\r
77 *       Manipulation:\r
78 *               cl_ptr_vector_get_capacity, cl_ptr_vector_set_capacity,\r
79 *               cl_ptr_vector_get_size, cl_ptr_vector_set_size, cl_ptr_vector_set_min_size\r
80 *               cl_ptr_vector_get_ptr, cl_ptr_vector_get, cl_ptr_vector_at, cl_ptr_vector_set\r
81 *\r
82 *       Search:\r
83 *               cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end\r
84 *               cl_ptr_vector_apply_func\r
85 *********/\r
86 \r
87 \r
88 /****d* Component Library: Pointer Vector/cl_pfn_ptr_vec_apply_t\r
89 * NAME\r
90 *       cl_pfn_ptr_vec_apply_t\r
91 *\r
92 * DESCRIPTION\r
93 *       The cl_pfn_ptr_vec_apply_t function type defines the prototype for\r
94 *       functions used to iterate elements in a pointer vector.\r
95 *\r
96 * SYNOPSIS\r
97 */\r
98 typedef void\r
99 (CL_API *cl_pfn_ptr_vec_apply_t)(\r
100         IN      const size_t            index,\r
101         IN      void* const                     element,\r
102         IN      void*                           context );\r
103 /*\r
104 * PARAMETERS\r
105 *       index\r
106 *               [in] Index of the element.\r
107 *\r
108 *       p_element\r
109 *               [in] Pointer to an element at the specified index in the pointer vector.\r
110 *\r
111 *       context\r
112 *               [in] Context provided in a call to cl_ptr_vector_apply_func.\r
113 *\r
114 * RETURN VALUE\r
115 *       This function does not return a value.\r
116 *\r
117 * NOTES\r
118 *       This function type is provided as function prototype reference for\r
119 *       the function passed by users as a parameter to the cl_ptr_vector_apply_func\r
120 *       function.\r
121 *\r
122 * SEE ALSO\r
123 *       Pointer Vector, cl_ptr_vector_apply_func\r
124 *********/\r
125 \r
126 \r
127 /****d* Component Library: Pointer Vector/cl_pfn_ptr_vec_find_t\r
128 * NAME\r
129 *       cl_pfn_ptr_vec_find_t\r
130 *\r
131 * DESCRIPTION\r
132 *       The cl_pfn_ptr_vec_find_t function type defines the prototype for\r
133 *       functions used to find elements in a pointer vector.\r
134 *\r
135 * SYNOPSIS\r
136 */\r
137 typedef cl_status_t\r
138 (CL_API *cl_pfn_ptr_vec_find_t)(\r
139         IN      const size_t            index,\r
140         IN      const void* const       element,\r
141         IN      void*                           context );\r
142 /*\r
143 * PARAMETERS\r
144 *       index\r
145 *               [in] Index of the element.\r
146 *\r
147 *       p_element\r
148 *               [in] Pointer to an element at the specified index in the\r
149 *               pointer vector.\r
150 *\r
151 *       context\r
152 *               [in] Context provided in a call to cl_ptr_vector_find_from_start or\r
153 *               cl_ptr_vector_find_from_end.\r
154 *\r
155 * RETURN VALUES\r
156 *       Return CL_SUCCESS if the element was found. This stops pointer vector\r
157 *       iteration.\r
158 *\r
159 *       CL_NOT_FOUND to continue the pointer vector iteration.\r
160 *\r
161 * NOTES\r
162 *       This function type is provided as function prototype reference for the\r
163 *       function provided by users as a parameter to the\r
164 *       cl_ptr_vector_find_from_start and cl_ptr_vector_find_from_end functions.\r
165 *\r
166 * SEE ALSO\r
167 *       Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end\r
168 *********/\r
169 \r
170 \r
171 /****s* Component Library: Pointer Vector/cl_ptr_vector_t\r
172 * NAME\r
173 *       cl_ptr_vector_t\r
174 *\r
175 * DESCRIPTION\r
176 *       Pointer Vector structure.\r
177 *\r
178 *       The cl_ptr_vector_t structure should be treated as opaque and should be\r
179 *       manipulated only through the provided functions.\r
180 *\r
181 * SYNOPSIS\r
182 */\r
183 typedef struct _cl_ptr_vector\r
184 {\r
185         size_t                          size;\r
186         size_t                          grow_size;\r
187         size_t                          capacity;\r
188         const void                      **p_ptr_array;\r
189         cl_state_t                      state;\r
190 \r
191 } cl_ptr_vector_t;\r
192 /*\r
193 * FIELDS\r
194 *       size\r
195 *                Number of elements successfully initialized in the pointer vector.\r
196 *\r
197 *       grow_size\r
198 *                Number of elements to allocate when growing.\r
199 *\r
200 *       capacity\r
201 *                total # of elements allocated.\r
202 *\r
203 *       alloc_list\r
204 *                List of allocations.\r
205 *\r
206 *       p_ptr_array\r
207 *                Internal array of pointers to elements.\r
208 *\r
209 *       state\r
210 *               State of the pointer vector.\r
211 *\r
212 * SEE ALSO\r
213 *       Pointer Vector\r
214 *********/\r
215 \r
216 \r
217 #ifdef __cplusplus\r
218 extern "C"\r
219 {\r
220 #endif\r
221 \r
222 \r
223 /****f* Component Library: Pointer Vector/cl_ptr_vector_construct\r
224 * NAME\r
225 *       cl_ptr_vector_construct\r
226 *\r
227 * DESCRIPTION\r
228 *       The cl_ptr_vector_construct function constructs a pointer vector.\r
229 *\r
230 * SYNOPSIS\r
231 */\r
232 CL_EXPORT void CL_API\r
233 cl_ptr_vector_construct(\r
234         IN      cl_ptr_vector_t* const  p_vector );\r
235 /*\r
236 * PARAMETERS\r
237 *       p_vector\r
238 *               [in] Pointer to a cl_ptr_vector_t structure to construct.\r
239 *\r
240 * RETURN VALUE\r
241 *       This function does not return a value.\r
242 *\r
243 * NOTES\r
244 *       Allows calling cl_ptr_vector_destroy without first calling\r
245 *       cl_ptr_vector_init.\r
246 *\r
247 *       Calling cl_ptr_vector_construct is a prerequisite to calling any other\r
248 *       pointer vector function except cl_ptr_vector_init.\r
249 *\r
250 * SEE ALSO\r
251 *       Pointer Vector, cl_ptr_vector_init, cl_ptr_vector_destroy\r
252 *********/\r
253 \r
254 \r
255 /****f* Component Library: Pointer Vector/cl_ptr_vector_init\r
256 * NAME\r
257 *       cl_ptr_vector_init\r
258 *\r
259 * DESCRIPTION\r
260 *       The cl_ptr_vector_init function initializes a pointer vector for use.\r
261 *\r
262 * SYNOPSIS\r
263 */\r
264 CL_EXPORT cl_status_t CL_API\r
265 cl_ptr_vector_init(\r
266         IN      cl_ptr_vector_t* const  p_vector,\r
267         IN      const size_t                    min_cap,\r
268         IN      const size_t                    grow_size );\r
269 /*\r
270 * PARAMETERS\r
271 *       p_vector\r
272 *               [in] Pointer to a cl_ptr_vector_t structure to inititalize.\r
273 *\r
274 *       min_cap\r
275 *               [in] Initial number of elements the vector will support.\r
276 *               The vector is always initialized with a size of zero.\r
277 *\r
278 *       grow_size\r
279 *               [in] Number of elements to allocate when incrementally growing\r
280 *               the pointer vector.  A value of zero disables automatic growth.\r
281 *\r
282 * RETURN VALUES\r
283 *       CL_SUCCESS if the pointer vector was initialized successfully.\r
284 *\r
285 *       CL_INSUFFICIENT_MEMORY if the initialization failed.\r
286 *\r
287 * SEE ALSO\r
288 *       Pointer Vector, cl_ptr_vector_construct, cl_ptr_vector_destroy,\r
289 *       cl_ptr_vector_set, cl_ptr_vector_get, cl_ptr_vector_at\r
290 *********/\r
291 \r
292 \r
293 /****f* Component Library: Pointer Vector/cl_ptr_vector_destroy\r
294 * NAME\r
295 *       cl_ptr_vector_destroy\r
296 *\r
297 * DESCRIPTION\r
298 *       The cl_ptr_vector_destroy function destroys a pointer vector.\r
299 *\r
300 * SYNOPSIS\r
301 */\r
302 CL_EXPORT void CL_API\r
303 cl_ptr_vector_destroy(\r
304         IN      cl_ptr_vector_t* const  p_vector );\r
305 /*\r
306 * PARAMETERS\r
307 *       p_vector\r
308 *               [in] Pointer to a cl_ptr_vector_t structure to destroy.\r
309 *\r
310 * RETURN VALUE\r
311 *       This function does not return a value.\r
312 *\r
313 * NOTES\r
314 *       cl_ptr_vector_destroy frees all memory allocated for the pointer vector.\r
315 *\r
316 *       This function should only be called after a call to cl_ptr_vector_construct\r
317 *       or cl_ptr_vector_init.\r
318 *\r
319 * SEE ALSO\r
320 *       Pointer Vector, cl_ptr_vector_construct, cl_ptr_vector_init\r
321 *********/\r
322 \r
323 \r
324 /****f* Component Library: Pointer Vector/cl_ptr_vector_get_capacity\r
325 * NAME\r
326 *       cl_ptr_vector_get_capacity\r
327 *\r
328 * DESCRIPTION\r
329 *       The cl_ptr_vector_get_capacity function returns the capacity of\r
330 *       a pointer vector.\r
331 *\r
332 * SYNOPSIS\r
333 */\r
334 CL_INLINE size_t CL_API\r
335 cl_ptr_vector_get_capacity(\r
336         IN      const cl_ptr_vector_t* const    p_vector )\r
337 {\r
338         CL_ASSERT( p_vector );\r
339         CL_ASSERT( p_vector->state == CL_INITIALIZED );\r
340 \r
341         return( p_vector->capacity );\r
342 }\r
343 /*\r
344 * PARAMETERS\r
345 *       p_vector\r
346 *               [in] Pointer to a cl_ptr_vector_t structure whose capacity to return.\r
347 *\r
348 * RETURN VALUE\r
349 *       Capacity, in elements, of the pointer vector.\r
350 *\r
351 * NOTES\r
352 *       The capacity is the number of elements that the pointer vector can store,\r
353 *       and can be greater than the number of elements stored. To get the number\r
354 *       of elements stored in the pointer vector, use cl_ptr_vector_get_size.\r
355 *\r
356 * SEE ALSO\r
357 *       Pointer Vector, cl_ptr_vector_set_capacity, cl_ptr_vector_get_size\r
358 *********/\r
359 \r
360 \r
361 /****f* Component Library: Pointer Vector/cl_ptr_vector_get_size\r
362 * NAME\r
363 *       cl_ptr_vector_get_size\r
364 *\r
365 * DESCRIPTION\r
366 *       The cl_ptr_vector_get_size function returns the size of a pointer vector.\r
367 *\r
368 * SYNOPSIS\r
369 */\r
370 CL_INLINE size_t CL_API\r
371 cl_ptr_vector_get_size(\r
372         IN      const cl_ptr_vector_t* const    p_vector )\r
373 {\r
374         CL_ASSERT( p_vector );\r
375         CL_ASSERT( p_vector->state == CL_UNINITIALIZED ||\r
376                 p_vector->state == CL_INITIALIZED );\r
377 \r
378         return( p_vector->size );\r
379 }\r
380 /*\r
381 * PARAMETERS\r
382 *       p_vector\r
383 *               [in] Pointer to a cl_ptr_vector_t structure whose size to return.\r
384 *\r
385 * RETURN VALUE\r
386 *       Size, in elements, of the pointer vector.\r
387 *\r
388 * SEE ALSO\r
389 *       Pointer Vector, cl_ptr_vector_set_size, cl_ptr_vector_get_capacity\r
390 *********/\r
391 \r
392 \r
393 /****f* Component Library: Pointer Vector/cl_ptr_vector_get\r
394 * NAME\r
395 *       cl_ptr_vector_get\r
396 *\r
397 * DESCRIPTION\r
398 *       The cl_ptr_vector_get function returns the pointer stored in a\r
399 *       pointer vector at a specified index.\r
400 *\r
401 * SYNOPSIS\r
402 */\r
403 CL_INLINE void* CL_API\r
404 cl_ptr_vector_get(\r
405         IN      const cl_ptr_vector_t* const    p_vector,\r
406         IN      const size_t                                    index )\r
407 {\r
408         CL_ASSERT( p_vector );\r
409         CL_ASSERT( p_vector->state == CL_INITIALIZED );\r
410         CL_ASSERT( p_vector->size > index );\r
411 \r
412         return( (void*)p_vector->p_ptr_array[index] );\r
413 }\r
414 /*\r
415 * PARAMETERS\r
416 *       p_vector\r
417 *               [in] Pointer to a cl_ptr_vector_t structure from which to get an\r
418 *               element.\r
419 *\r
420 *       index\r
421 *               [in] Index of the element.\r
422 *\r
423 * RETURN VALUE\r
424 *       Value of the pointer stored at the specified index.\r
425 *\r
426 * NOTES\r
427 *       cl_ptr_vector_get provides constant access times regardless of the index.\r
428 *\r
429 *       cl_ptr_vector_get does not perform boundary checking. Callers are\r
430 *       responsible for providing an index that is within the range of the pointer\r
431 *       vector.\r
432 *\r
433 * SEE ALSO\r
434 *       Pointer Vector, cl_ptr_vector_at, cl_ptr_vector_set, cl_ptr_vector_get_size\r
435 *********/\r
436 \r
437 \r
438 /****f* Component Library: Pointer Vector/cl_ptr_vector_at\r
439 * NAME\r
440 *       cl_ptr_vector_at\r
441 *\r
442 * DESCRIPTION\r
443 *       The cl_ptr_vector_at function copies an element stored in a pointer\r
444 *       vector at a specified index, performing boundary checks.\r
445 *\r
446 * SYNOPSIS\r
447 */\r
448 CL_EXPORT cl_status_t CL_API\r
449 cl_ptr_vector_at(\r
450         IN      const cl_ptr_vector_t* const    p_vector,\r
451         IN      const size_t                                    index,\r
452         OUT     void** const                                    p_element );\r
453 /*\r
454 * PARAMETERS\r
455 *       p_vector\r
456 *               [in] Pointer to a cl_ptr_vector_t structure from which to get a copy of\r
457 *               an element.\r
458 *\r
459 *       index\r
460 *               [in] Index of the element.\r
461 *\r
462 *       p_element\r
463 *               [out] Pointer to storage for the pointer element. Contains a copy of\r
464 *               the desired pointer upon successful completion of the call.\r
465 *\r
466 * RETURN VALUES\r
467 *       CL_SUCCESS if an element was found at the specified index.\r
468 *\r
469 *       CL_INVALID_SETTING if the index was out of range.\r
470 *\r
471 * NOTES\r
472 *       cl_ptr_vector_at provides constant time access regardless of\r
473 *       the index, and performs boundary checking on the pointer vector.\r
474 *\r
475 *       Upon success, the p_element parameter contains a copy of the\r
476 *       desired element.\r
477 *\r
478 * SEE ALSO\r
479 *       Pointer Vector, cl_ptr_vector_get\r
480 *********/\r
481 \r
482 \r
483 /****f* Component Library: Pointer Vector/cl_ptr_vector_set\r
484 * NAME\r
485 *       cl_ptr_vector_set\r
486 *\r
487 * DESCRIPTION\r
488 *       The cl_ptr_vector_set function sets the element at the specified index.\r
489 *\r
490 * SYNOPSIS\r
491 */\r
492 CL_EXPORT cl_status_t CL_API\r
493 cl_ptr_vector_set(\r
494         IN      cl_ptr_vector_t* const  p_vector,\r
495         IN      const size_t                    index,\r
496         IN      const void* const               element );\r
497 /*\r
498 * PARAMETERS\r
499 *       p_vector\r
500 *               [in] Pointer to a cl_ptr_vector_t structure into which to store\r
501 *               an element.\r
502 *\r
503 *       index\r
504 *               [in] Index of the element.\r
505 *\r
506 *       element\r
507 *               [in] Pointer to store in the pointer vector.\r
508 *\r
509 * RETURN VALUES\r
510 *       CL_SUCCESS if the element was successfully set.\r
511 *\r
512 *       CL_INSUFFICIENT_MEMORY if the pointer vector could not be resized to\r
513 *       accommodate the new element.\r
514 *\r
515 * NOTES\r
516 *       cl_ptr_vector_set grows the pointer vector as needed to accommodate\r
517 *       the new element, unless the grow_size parameter passed into the\r
518 *       cl_ptr_vector_init function was zero.\r
519 *\r
520 * SEE ALSO\r
521 *       Pointer Vector, cl_ptr_vector_get\r
522 *********/\r
523 \r
524 \r
525 /****f* Component Library: Pointer Vector/cl_ptr_vector_insert\r
526 * NAME\r
527 *       cl_ptr_vector_insert\r
528 *\r
529 * DESCRIPTION\r
530 *       The cl_ptr_vector_insert function inserts an element into a pointer vector.\r
531 *\r
532 * SYNOPSIS\r
533 */\r
534 CL_INLINE cl_status_t CL_API\r
535 cl_ptr_vector_insert(\r
536         IN      cl_ptr_vector_t* const  p_vector,\r
537         IN      const void* const               element,\r
538         OUT     size_t* const                   p_index OPTIONAL )\r
539 {\r
540         cl_status_t             status;\r
541 \r
542         CL_ASSERT( p_vector );\r
543         CL_ASSERT( p_vector->state == CL_INITIALIZED );\r
544 \r
545         status = cl_ptr_vector_set( p_vector, p_vector->size, element );\r
546         if( status == CL_SUCCESS && p_index )\r
547                 *p_index = p_vector->size - 1;\r
548 \r
549         return( status );\r
550 }\r
551 /*\r
552 * PARAMETERS\r
553 *       p_vector\r
554 *               [in] Pointer to a cl_ptr_vector_t structure into which to store\r
555 *               an element.\r
556 *\r
557 *       element\r
558 *               [in] Pointer to store in the pointer vector.\r
559 *\r
560 *       p_index\r
561 *               [out] Pointer to the index of the element.  Valid only if\r
562 *               insertion was successful.\r
563 *\r
564 * RETURN VALUES\r
565 *       CL_SUCCESS if the element was successfully inserted.\r
566 *\r
567 *       CL_INSUFFICIENT_MEMORY if the pointer vector could not be resized to\r
568 *       accommodate the new element.\r
569 *\r
570 * NOTES\r
571 *       cl_ptr_vector_insert places the new element at the end of\r
572 *       the pointer vector.\r
573 *\r
574 *       cl_ptr_vector_insert grows the pointer vector as needed to accommodate\r
575 *       the new element, unless the grow_size parameter passed into the\r
576 *       cl_ptr_vector_init function was zero.\r
577 *\r
578 * SEE ALSO\r
579 *       Pointer Vector, cl_ptr_vector_remove, cl_ptr_vector_set\r
580 *********/\r
581 \r
582 \r
583 /****f* Component Library: Pointer Vector/cl_ptr_vector_remove\r
584 * NAME\r
585 *       cl_ptr_vector_remove\r
586 *\r
587 * DESCRIPTION\r
588 *       The cl_ptr_vector_remove function removes and returns the pointer stored\r
589 *       in a pointer vector at a specified index.  Items beyond the removed item\r
590 *       are shifted down and the size of the pointer vector is decremented.\r
591 *\r
592 * SYNOPSIS\r
593 */\r
594 CL_EXPORT void* CL_API\r
595 cl_ptr_vector_remove(\r
596         IN      cl_ptr_vector_t* const  p_vector,\r
597         IN      const size_t                    index );\r
598 /*\r
599 * PARAMETERS\r
600 *       p_vector\r
601 *               [in] Pointer to a cl_ptr_vector_t structure from which to get an\r
602 *               element.\r
603 *\r
604 *       index\r
605 *               [in] Index of the element.\r
606 *\r
607 * RETURN VALUE\r
608 *       Value of the pointer stored at the specified index.\r
609 *\r
610 * NOTES\r
611 *       cl_ptr_vector_get does not perform boundary checking. Callers are\r
612 *       responsible for providing an index that is within the range of the pointer\r
613 *       vector.\r
614 *\r
615 * SEE ALSO\r
616 *       Pointer Vector, cl_ptr_vector_insert, cl_ptr_vector_get_size\r
617 *********/\r
618 \r
619 \r
620 /****f* Component Library: Pointer Vector/cl_ptr_vector_set_capacity\r
621 * NAME\r
622 *       cl_ptr_vector_set_capacity\r
623 *\r
624 * DESCRIPTION\r
625 *       The cl_ptr_vector_set_capacity function reserves memory in a\r
626 *       pointer vector for a specified number of pointers.\r
627 *\r
628 * SYNOPSIS\r
629 */\r
630 CL_EXPORT cl_status_t CL_API\r
631 cl_ptr_vector_set_capacity(\r
632         IN      cl_ptr_vector_t* const  p_vector,\r
633         IN      const size_t                    new_capacity );\r
634 /*\r
635 * PARAMETERS\r
636 *       p_vector\r
637 *               [in] Pointer to a cl_ptr_vector_t structure whose capacity to set.\r
638 *\r
639 *       new_capacity\r
640 *               [in] Total number of elements for which the pointer vector should\r
641 *               allocate memory.\r
642 *\r
643 * RETURN VALUES\r
644 *       CL_SUCCESS if the capacity was successfully set.\r
645 *\r
646 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to satisfy the\r
647 *       operation. The pointer vector is left unchanged.\r
648 *\r
649 * NOTES\r
650 *       cl_ptr_vector_set_capacity increases the capacity of the pointer vector.\r
651 *       It does not change the size of the pointer vector. If the requested\r
652 *       capacity is less than the current capacity, the pointer vector is left\r
653 *       unchanged.\r
654 *\r
655 * SEE ALSO\r
656 *       Pointer Vector, cl_ptr_vector_get_capacity, cl_ptr_vector_set_size,\r
657 *       cl_ptr_vector_set_min_size\r
658 *********/\r
659 \r
660 \r
661 /****f* Component Library: Pointer Vector/cl_ptr_vector_set_size\r
662 * NAME\r
663 *       cl_ptr_vector_set_size\r
664 *\r
665 * DESCRIPTION\r
666 *       The cl_ptr_vector_set_size function resizes a pointer vector, either\r
667 *       increasing or decreasing its size.\r
668 *\r
669 * SYNOPSIS\r
670 */\r
671 CL_EXPORT cl_status_t CL_API\r
672 cl_ptr_vector_set_size(\r
673         IN      cl_ptr_vector_t* const  p_vector,\r
674         IN      const size_t                    size );\r
675 /*\r
676 * PARAMETERS\r
677 *       p_vector\r
678 *               [in] Pointer to a cl_ptr_vector_t structure whose size to set.\r
679 *\r
680 *       size\r
681 *               [in] Number of elements desired in the pointer vector.\r
682 *\r
683 * RETURN VALUES\r
684 *       CL_SUCCESS if the size of the pointer vector was set successfully.\r
685 *\r
686 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to complete the\r
687 *       operation. The pointer vector is left unchanged.\r
688 *\r
689 * NOTES\r
690 *       cl_ptr_vector_set_size sets the pointer vector to the specified size.\r
691 *       If size is smaller than the current size of the pointer vector, the size\r
692 *       is reduced.\r
693 *\r
694 *       This function can only fail if size is larger than the current capacity.\r
695 *\r
696 * SEE ALSO\r
697 *       Pointer Vector, cl_ptr_vector_get_size, cl_ptr_vector_set_min_size,\r
698 *       cl_ptr_vector_set_capacity\r
699 *********/\r
700 \r
701 \r
702 /****f* Component Library: Pointer Vector/cl_ptr_vector_set_min_size\r
703 * NAME\r
704 *       cl_ptr_vector_set_min_size\r
705 *\r
706 * DESCRIPTION\r
707 *       The cl_ptr_vector_set_min_size function resizes a pointer vector to a\r
708 *       specified size if the pointer vector is smaller than the specified size.\r
709 *\r
710 * SYNOPSIS\r
711 */\r
712 CL_EXPORT cl_status_t CL_API\r
713 cl_ptr_vector_set_min_size(\r
714         IN      cl_ptr_vector_t* const  p_vector,\r
715         IN      const size_t                    min_size );\r
716 /*\r
717 * PARAMETERS\r
718 *       p_vector\r
719 *               [in] Pointer to a cl_ptr_vector_t structure whose minimum size to set.\r
720 *\r
721 *       min_size\r
722 *               [in] Minimum number of elements that the pointer vector should contain.\r
723 *\r
724 * RETURN VALUES\r
725 *       CL_SUCCESS if the pointer vector size is greater than or equal to min_size.\r
726 *       This could indicate that the pointer vector's capacity was increased to\r
727 *       min_size or that the pointer vector was already of sufficient size.\r
728 *\r
729 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to resize the\r
730 *       pointer vector.  The pointer vector is left unchanged.\r
731 *\r
732 * NOTES\r
733 *       If min_size is smaller than the current size of the pointer vector,\r
734 *       the pointer vector is unchanged. The pointer vector is unchanged if the\r
735 *       size could not be changed due to insufficient memory being available to\r
736 *       perform the operation.\r
737 *\r
738 * SEE ALSO\r
739 *       Pointer Vector, cl_ptr_vector_get_size, cl_ptr_vector_set_size,\r
740 *       cl_ptr_vector_set_capacity\r
741 *********/\r
742 \r
743 \r
744 /****f* Component Library: Pointer Vector/cl_ptr_vector_apply_func\r
745 * NAME\r
746 *       cl_ptr_vector_apply_func\r
747 *\r
748 * DESCRIPTION\r
749 *       The cl_ptr_vector_apply_func function invokes a specified function for\r
750 *       every element in a pointer vector.\r
751 *\r
752 * SYNOPSIS\r
753 */\r
754 CL_EXPORT void CL_API\r
755 cl_ptr_vector_apply_func(\r
756         IN      const cl_ptr_vector_t* const    p_vector,\r
757         IN      cl_pfn_ptr_vec_apply_t                  pfn_callback,\r
758         IN      const void* const                               context );\r
759 /*\r
760 * PARAMETERS\r
761 *       p_vector\r
762 *               [in] Pointer to a cl_ptr_vector_t structure whose elements to iterate.\r
763 *\r
764 *       pfn_callback\r
765 *               [in] Function invoked for every element in the array.\r
766 *               See the cl_pfn_ptr_vec_apply_t function type declaration for details\r
767 *               about the callback function.\r
768 *\r
769 *       context\r
770 *               [in] Value to pass to the callback function.\r
771 *\r
772 * RETURN VALUE\r
773 *       This function does not return a value.\r
774 *\r
775 * NOTES\r
776 *       cl_ptr_vector_apply_func invokes the specified function for every element\r
777 *       in the pointer vector, starting from the beginning of the pointer vector.\r
778 *\r
779 * SEE ALSO\r
780 *       Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_find_from_end,\r
781 *       cl_pfn_ptr_vec_apply_t\r
782 *********/\r
783 \r
784 \r
785 /****f* Component Library: Pointer Vector/cl_ptr_vector_find_from_start\r
786 * NAME\r
787 *       cl_ptr_vector_find_from_start\r
788 *\r
789 * DESCRIPTION\r
790 *       The cl_ptr_vector_find_from_start function uses a specified function to\r
791 *       search for elements in a pointer vector starting from the lowest index.\r
792 *\r
793 * SYNOPSIS\r
794 */\r
795 CL_EXPORT size_t CL_API\r
796 cl_ptr_vector_find_from_start(\r
797         IN      const cl_ptr_vector_t* const    p_vector,\r
798         IN      cl_pfn_ptr_vec_find_t                   pfn_callback,\r
799         IN      const void* const                               context );\r
800 /*\r
801 * PARAMETERS\r
802 *       p_vector\r
803 *               [in] Pointer to a cl_ptr_vector_t structure to inititalize.\r
804 *\r
805 *       pfn_callback\r
806 *               [in] Function invoked to determine if a match was found.\r
807 *               See the cl_pfn_ptr_vec_find_t function type declaration for details\r
808 *               about the callback function.\r
809 *\r
810 *       context\r
811 *               [in] Value to pass to the callback function.\r
812 *\r
813 * RETURN VALUES\r
814 *       Index of the element, if found.\r
815 *\r
816 *       Size of the pointer vector if the element was not found.\r
817 *\r
818 * NOTES\r
819 *       cl_ptr_vector_find_from_start does not remove the found element from\r
820 *       the pointer vector. The index of the element is returned when the function\r
821 *       provided by the pfn_callback parameter returns CL_SUCCESS.\r
822 *\r
823 * SEE ALSO\r
824 *       Pointer Vector, cl_ptr_vector_find_from_end, cl_ptr_vector_apply_func,\r
825 *       cl_pfn_ptr_vec_find_t\r
826 *********/\r
827 \r
828 \r
829 /****f* Component Library: Pointer Vector/cl_ptr_vector_find_from_end\r
830 * NAME\r
831 *       cl_ptr_vector_find_from_end\r
832 *\r
833 * DESCRIPTION\r
834 *       The cl_ptr_vector_find_from_end function uses a specified function to\r
835 *       search for elements in a pointer vector starting from the highest index.\r
836 *\r
837 * SYNOPSIS\r
838 */\r
839 CL_EXPORT size_t CL_API\r
840 cl_ptr_vector_find_from_end(\r
841         IN      const cl_ptr_vector_t* const    p_vector,\r
842         IN      cl_pfn_ptr_vec_find_t                   pfn_callback,\r
843         IN      const void* const                               context );\r
844 /*\r
845 * PARAMETERS\r
846 *       p_vector\r
847 *               [in] Pointer to a cl_ptr_vector_t structure to inititalize.\r
848 *\r
849 *       pfn_callback\r
850 *               [in] Function invoked to determine if a match was found.\r
851 *               See the cl_pfn_ptr_vec_find_t function type declaration for details\r
852 *               about the callback function.\r
853 *\r
854 *       context\r
855 *               [in] Value to pass to the callback function.\r
856 *\r
857 * RETURN VALUES\r
858 *       Index of the element, if found.\r
859 *\r
860 *       Size of the pointer vector if the element was not found.\r
861 *\r
862 * NOTES\r
863 *       cl_ptr_vector_find_from_end does not remove the found element from\r
864 *       the pointer vector. The index of the element is returned when the function\r
865 *       provided by the pfn_callback parameter returns CL_SUCCESS.\r
866 *\r
867 * SEE ALSO\r
868 *       Pointer Vector, cl_ptr_vector_find_from_start, cl_ptr_vector_apply_func,\r
869 *       cl_pfn_ptr_vec_find_t\r
870 *********/\r
871 \r
872 \r
873 #ifdef __cplusplus\r
874 }       /* extern "C" */\r
875 #endif\r
876 \r
877 \r
878 #endif  /* _CL_PTR_VECTOR_H_ */\r