unit-tests: Add a simple thread_cancel() test
[strongswan.git] / src / libstrongswan / collections / array.h
1 /*
2 * Copyright (C) 2013 Martin Willi
3 * Copyright (C) 2013 revosec AG
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup array array
18 * @{ @ingroup collections
19 */
20
21 #ifndef ARRAY_H_
22 #define ARRAY_H_
23
24 #include <collections/enumerator.h>
25
26 /**
27 * Variable sized array with fixed size elements.
28 *
29 * An array is a primitive object with associated functions to avoid the
30 * overhead of an object with methods. It is efficient in memory usage, but
31 * less efficient than a linked list in manipulating elements.
32 */
33 typedef struct array_t array_t;
34
35 typedef enum array_idx_t array_idx_t;
36
37 /**
38 * Special array index values for insert/remove.
39 */
40 enum array_idx_t {
41 ARRAY_HEAD = 0,
42 ARRAY_TAIL = -1,
43 };
44
45 /**
46 * Callback function invoked for each array element.
47 *
48 * Data is a pointer to the array element. If this is a pointer based array,
49 * (esize is zero), data is the pointer itself.
50 *
51 * @param data pointer to array data, or the pointer itself
52 * @param idx array index
53 * @param user user data passed with callback
54 */
55 typedef void (*array_callback_t)(void *data, int idx, void *user);
56
57 /**
58 * Create a array instance.
59 *
60 * Elements get tight packed to each other. If any alignment is required, pass
61 * appropriate padding to each element. The reserved space does not affect
62 * array_count(), but just preallocates buffer space.
63 *
64 * @param esize element size for this array, use 0 for a pointer array
65 * @param reserve number of items to allocate space for
66 * @return array instance
67 */
68 array_t *array_create(u_int esize, u_int8_t reserve);
69
70 /**
71 * Get the number of elements currently in the array.
72 *
73 * @return number of elements
74 */
75 int array_count(array_t *array);
76
77 /**
78 * Compress an array, remove unused head/tail space.
79 *
80 * @param array array to compress, or NULL
81 */
82 void array_compress(array_t *array);
83
84 /**
85 * Create an enumerator over an array.
86 *
87 * The enumerater enumerates directly over the array element (pass a pointer to
88 * element types), unless the array is pointer based. If zero is passed as
89 * element size during construction, the enumerator enumerates over the
90 * deferenced pointer values.
91 *
92 * @param array array to create enumerator for, or NULL
93 * @return enumerator, over elements or pointers
94 */
95 enumerator_t* array_create_enumerator(array_t *array);
96
97 /**
98 * Remove an element at enumerator position.
99 *
100 * @param array array to remove element in
101 * @param enumerator enumerator position, from array_create_enumerator()
102 */
103 void array_remove_at(array_t *array, enumerator_t *enumerator);
104
105 /**
106 * Insert an element to an array.
107 *
108 * If the array is pointer based (esize = 0), the pointer itself is appended.
109 * Otherwise the element gets copied from the pointer.
110 * The idx must be either within array_count() or one above to append the item.
111 * Passing -1 has the same effect as passing array_count(), i.e. appends the
112 * item. It is always valid to pass idx 0 to prepend the item.
113 *
114 * @param array array to append element to
115 * @param idx index to insert item at
116 * @param data pointer to array element to copy
117 */
118 void array_insert(array_t *array, int idx, void *data);
119
120 /**
121 * Create an pointer based array if it does not exist, insert pointer.
122 *
123 * This is a convenience function for insert a pointer and implicitly
124 * create a pointer based array if array is NULL. Array is set the the newly
125 * created array, if any.
126 *
127 * @param array pointer to array reference, potentially NULL
128 * @param idx index to insert item at
129 * @param ptr pointer to append
130 */
131 void array_insert_create(array_t **array, int idx, void *ptr);
132
133 /**
134 * Insert all items from an enumerator to an array.
135 *
136 * @param array array to add items to
137 * @param idx index to insert each item with
138 * @param enumerator enumerator over void*, gets destroyed
139 */
140 void array_insert_enumerator(array_t *array, int idx, enumerator_t *enumerator);
141
142 /**
143 * Remove an element from the array.
144 *
145 * If data is given, the element is copied to that position.
146 *
147 * @param array array to remove element from, or NULL
148 * @param idx index of the item to remove
149 * @param data data to copy element to, or NULL
150 * @return TRUE if idx existed and item removed
151 */
152 bool array_remove(array_t *array, int idx, void *data);
153
154 /**
155 * Invoke a callback for all array members.
156 *
157 * @param array array to traverse, or NULL
158 * @param cb callback function to invoke each element with
159 * @param user user data to pass to callback
160 */
161 void array_invoke(array_t *array, array_callback_t cb, void *user);
162
163 /**
164 * Invoke a method of each element defined with offset.
165 *
166 * @param array array to traverse, or NULL
167 * @param offset offset of element method, use offsetof()
168 */
169 void array_invoke_offset(array_t *array, size_t offset);
170
171 /**
172 * Destroy an array.
173 *
174 * @param array array to destroy, or NULL
175 */
176 void array_destroy(array_t *array);
177
178 /**
179 * Destroy an array, call a function to clean up all elements.
180 *
181 * @param array array to destroy, or NULL
182 * @param cb callback function to free element data
183 * @param user user data to pass to callback
184 */
185 void array_destroy_function(array_t *array, array_callback_t cb, void *user);
186
187 /**
188 * Destroy an array, call element method defined with offset.
189 *
190 * @param array array to destroy, or NULL
191 * @param offset offset of element method, use offsetof()
192 */
193 void array_destroy_offset(array_t *array, size_t offset);
194
195 #endif /** ARRAY_H_ @}*/