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