functions invoked on all linked list items now support up to five additional arguments
[strongswan.git] / src / libstrongswan / utils / linked_list.h
1 /*
2 * Copyright (C) 2007-2008 Tobias Brunner
3 * Copyright (C) 2005-2006 Martin Willi
4 * Copyright (C) 2005 Jan Hutter
5 * Hochschule fuer Technik Rapperswil
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * for more details.
16 *
17 * $Id$
18 */
19
20 /**
21 * @defgroup linked_list linked_list
22 * @{ @ingroup utils
23 */
24
25 #ifndef LINKED_LIST_H_
26 #define LINKED_LIST_H_
27
28 typedef struct linked_list_t linked_list_t;
29
30 #include <pthread.h>
31
32 #include <library.h>
33 #include <utils/iterator.h>
34 #include <utils/enumerator.h>
35
36
37 /**
38 * Method to match elements in a linked list (used in find_* functions)
39 *
40 * @param item current list item
41 * @param ... user supplied data (only pointers, at most 5)
42 * @return
43 * - TRUE, if the item matched
44 * - FALSE, otherwise
45 */
46 typedef bool (*linked_list_match_t)(void *item, ...);
47
48 /**
49 * Method to be invoked on elements in a linked list (used in invoke_* functions)
50 *
51 * @param item current list item
52 * @param ... user supplied data (only pointers, at most 5)
53 */
54 typedef void (*linked_list_invoke_t)(void *item, ...);
55
56 /**
57 * Class implementing a double linked list.
58 *
59 * General purpose linked list. This list is not synchronized.
60 */
61 struct linked_list_t {
62
63 /**
64 * Gets the count of items in the list.
65 *
66 * @return number of items in list
67 */
68 int (*get_count) (linked_list_t *this);
69
70 /**
71 * Creates a iterator for the given list.
72 *
73 * @warning Created iterator_t object has to get destroyed by the caller.
74 *
75 * @deprecated Iterator is obsolete and will disappear, it is too
76 * complicated to implement. Use enumerator instead.
77 *
78 * @param forward iterator direction (TRUE: front to end)
79 * @return new iterator_t object
80 */
81 iterator_t *(*create_iterator) (linked_list_t *this, bool forward);
82
83 /**
84 * Creates a iterator, locking a mutex.
85 *
86 * The supplied mutex is acquired immediately, and released
87 * when the iterator gets destroyed.
88 *
89 * @param mutex mutex to use for exclusive access
90 * @return new iterator_t object
91 */
92 iterator_t *(*create_iterator_locked) (linked_list_t *this,
93 pthread_mutex_t *mutex);
94
95 /**
96 * Create an enumerator over the list.
97 *
98 * The enumerator is a "lightweight" iterator. It only has two methods
99 * and should therefore be much easier to implement.
100 *
101 * @return enumerator over list items
102 */
103 enumerator_t* (*create_enumerator)(linked_list_t *this);
104
105 /**
106 * Inserts a new item at the beginning of the list.
107 *
108 * @param item item value to insert in list
109 */
110 void (*insert_first) (linked_list_t *this, void *item);
111
112 /**
113 * Removes the first item in the list and returns its value.
114 *
115 * @param item returned value of first item, or NULL
116 * @return SUCCESS, or NOT_FOUND if list is empty
117 */
118 status_t (*remove_first) (linked_list_t *this, void **item);
119
120 /**
121 * Remove an item from the list where the enumerator points to.
122 *
123 * @param enumerator enumerator with position
124 */
125 void (*remove_at)(linked_list_t *this, enumerator_t *enumerator);
126
127 /**
128 * Remove items from the list matching item.
129 *
130 * If a compare function is given, it is called for each item, where
131 * the first parameter is the current list item and the second parameter
132 * is the supplied item parameter.
133 * If compare is NULL, compare is is done by pointer.
134 *
135 * @param item item to remove/pass to comparator
136 * @param compare compare function, or NULL
137 * @return number of removed items
138 */
139 int (*remove)(linked_list_t *this, void *item, bool (*compare)(void *,void*));
140
141 /**
142 * Returns the value of the first list item without removing it.
143 *
144 * @param this calling object
145 * @param item returned value of first item
146 * @return SUCCESS, NOT_FOUND if list is empty
147 */
148 status_t (*get_first) (linked_list_t *this, void **item);
149
150 /**
151 * Inserts a new item at the end of the list.
152 *
153 * @param item value to insert into list
154 */
155 void (*insert_last) (linked_list_t *this, void *item);
156
157 /**
158 * Removes the last item in the list and returns its value.
159 *
160 * @param this calling object
161 * @param item returned value of last item, or NULL
162 * @return SUCCESS, NOT_FOUND if list is empty
163 */
164 status_t (*remove_last) (linked_list_t *this, void **item);
165
166 /**
167 * Returns the value of the last list item without removing it.
168 *
169 * @param this calling object
170 * @param item returned value of last item
171 * @return SUCCESS, NOT_FOUND if list is empty
172 */
173 status_t (*get_last) (linked_list_t *this, void **item);
174
175 /** Find the first matching element in the list.
176 *
177 * The first object passed to the match function is the current list item,
178 * followed by the user supplied data.
179 * If the supplied function returns TRUE this function returns SUCCESS, and
180 * the current object is returned in the third parameter, otherwise,
181 * the next item is checked.
182 *
183 * @warning Only use pointers as user supplied data.
184 *
185 * @param match comparison function to call on each object
186 * @param item the list item, if found
187 * @param ... user data to supply to match function (limited to 5 arguments)
188 * @return SUCCESS if found, NOT_FOUND otherwise
189 */
190 status_t (*find_first) (linked_list_t *this, linked_list_match_t match,
191 void **item, ...);
192
193 /** Find the last matching element in the list.
194 *
195 * The first object passed to the match function is the current list item,
196 * followed by the user supplied data.
197 * If the supplied function returns TRUE this function returns SUCCESS, and
198 * the current object is returned in the third parameter, otherwise,
199 * the next item is checked.
200 *
201 * @warning Only use pointers as user supplied data.
202 *
203 * @param match comparison function to call on each object
204 * @param item the list item, if found
205 * @param ... user data to supply to match function (limited to 5 arguments)
206 * @return SUCCESS if found, NOT_FOUND otherwise
207 */
208 status_t (*find_last) (linked_list_t *this, linked_list_match_t match,
209 void **item, ...);
210
211 /**
212 * Invoke a method on all of the contained objects.
213 *
214 * If a linked list contains objects with function pointers,
215 * invoke() can call a method on each of the objects. The
216 * method is specified by an offset of the function pointer,
217 * which can be evalutated at compile time using the offsetof
218 * macro, e.g.: list->invoke(list, offsetof(object_t, method));
219 *
220 * @param offset offset of the method to invoke on objects
221 * @param ... user data to supply to called function (limited to 5 arguments)
222 */
223 void (*invoke_offset) (linked_list_t *this, size_t offset, ...);
224
225 /**
226 * Invoke a function on all of the contained objects.
227 *
228 * @param function offset of the method to invoke on objects
229 * @param ... user data to supply to called function (limited to 5 arguments)
230 */
231 void (*invoke_function) (linked_list_t *this, linked_list_invoke_t function, ...);
232
233 /**
234 * Clones a list and its objects using the objects' clone method.
235 *
236 * @param offset offset ot the objects clone function
237 * @return cloned list
238 */
239 linked_list_t *(*clone_offset) (linked_list_t *this, size_t offset);
240
241 /**
242 * Clones a list and its objects using a given function.
243 *
244 * @param function function that clones an object
245 * @return cloned list
246 */
247 linked_list_t *(*clone_function) (linked_list_t *this, void*(*)(void*));
248
249 /**
250 * Destroys a linked_list object.
251 */
252 void (*destroy) (linked_list_t *this);
253
254 /**
255 * Destroys a list and its objects using the destructor.
256 *
257 * If a linked list and the contained objects should be destroyed, use
258 * destroy_offset. The supplied offset specifies the destructor to
259 * call on each object. The offset may be calculated using the offsetof
260 * macro, e.g.: list->destroy_offset(list, offsetof(object_t, destroy));
261 *
262 * @param offset offset of the objects destructor
263 */
264 void (*destroy_offset) (linked_list_t *this, size_t offset);
265
266 /**
267 * Destroys a list and its contents using a a cleanup function.
268 *
269 * If a linked list and its contents should get destroyed using a specific
270 * cleanup function, use destroy_function. This is useful when the
271 * list contains malloc()-ed blocks which should get freed,
272 * e.g.: list->destroy_function(list, free);
273 *
274 * @param function function to call on each object
275 */
276 void (*destroy_function) (linked_list_t *this, void (*)(void*));
277 };
278
279 /**
280 * Creates an empty linked list object.
281 *
282 * @return linked_list_t object.
283 */
284 linked_list_t *linked_list_create(void);
285
286 #endif /*LINKED_LIST_H_ @} */