4f313ded6d2e789cba5893fbe3b7adadf36f8748
[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
35 /**
36 * @brief Class implementing a double linked list.
37 *
38 * General purpose linked list. This list is not synchronized.
39 *
40 * @b Costructors:
41 * - linked_list_create()
42 *
43 * @ingroup utils
44 */
45 struct linked_list_t {
46
47 /**
48 * @brief Gets the count of items in the list.
49 *
50 * @param this calling object
51 * @return number of items in list
52 */
53 int (*get_count) (linked_list_t *this);
54
55 /**
56 * @brief Creates a iterator for the given list.
57 *
58 * @warning Created iterator_t object has to get destroyed by the caller.
59 *
60 * @param this calling object
61 * @param forward iterator direction (TRUE: front to end)
62 * @return new iterator_t object
63 */
64 iterator_t *(*create_iterator) (linked_list_t *this, bool forward);
65
66 /**
67 * @brief Creates a iterator, locking a mutex.
68 *
69 * The supplied mutex is acquired immediately, and released
70 * when the iterator gets destroyed.
71 *
72 * @param this calling object
73 * @param mutex mutex to use for exclusive access
74 * @return new iterator_t object
75 */
76 iterator_t *(*create_iterator_locked) (linked_list_t *this,
77 pthread_mutex_t *mutex);
78
79 /**
80 * @brief Inserts a new item at the beginning of the list.
81 *
82 * @param this calling object
83 * @param[in] item item value to insert in list
84 */
85 void (*insert_first) (linked_list_t *this, void *item);
86
87 /**
88 * @brief Removes the first item in the list and returns its value.
89 *
90 * @param this calling object
91 * @param[out] item returned value of first item, or NULL
92 * @return
93 * - SUCCESS
94 * - NOT_FOUND, if list is empty
95 */
96 status_t (*remove_first) (linked_list_t *this, void **item);
97
98 /**
99 * @brief Returns the value of the first list item without removing it.
100 *
101 * @param this calling object
102 * @param[out] item returned value of first item
103 * @return
104 * - SUCCESS
105 * - NOT_FOUND, if list is empty
106 */
107 status_t (*get_first) (linked_list_t *this, void **item);
108
109 /**
110 * @brief Inserts a new item at the end of the list.
111 *
112 * @param this calling object
113 * @param[in] item value to insert into list
114 */
115 void (*insert_last) (linked_list_t *this, void *item);
116
117 /**
118 * @brief Inserts a new item at a given position in the list.
119 *
120 * @param this calling object
121 * @param position position starting at 0 to insert new entry
122 * @param[in] item value to insert into list
123 * @return
124 * - SUCCESS
125 * - INVALID_ARG if position not existing
126 */
127 status_t (*insert_at_position) (linked_list_t *this,size_t position, void *item);
128
129 /**
130 * @brief Removes an item from a given position in the list.
131 *
132 * @param this calling object
133 * @param position position starting at 0 to remove entry from
134 * @param[out] item removed item will be stored at this location
135 * @return
136 * - SUCCESS
137 * - INVALID_ARG if position not existing
138 */
139 status_t (*remove_at_position) (linked_list_t *this, size_t position, void **item);
140
141 /**
142 * @brief Get an item from a given position in the list.
143 *
144 * @param this calling object
145 * @param position position starting at 0 to get entry from
146 * @param[out] item item will be stored at this location
147 * @return
148 * - SUCCESS
149 * - INVALID_ARG if position not existing
150 */
151 status_t (*get_at_position) (linked_list_t *this, size_t position, void **item);
152
153 /**
154 * @brief Removes the last item in the list and returns its value.
155 *
156 * @param this calling object
157 * @param[out] item returned value of last item, or NULL
158 * @return
159 * - SUCCESS
160 * - NOT_FOUND if list is empty
161 */
162 status_t (*remove_last) (linked_list_t *this, void **item);
163
164 /**
165 * @brief Returns the value of the last list item without removing it.
166 *
167 * @param this calling object
168 * @param[out] item returned value of last item
169 * @return
170 * - SUCCESS
171 * - NOT_FOUND if list is empty
172 */
173 status_t (*get_last) (linked_list_t *this, void **item);
174
175 /**
176 * @brief Invoke a method on all of the contained objects.
177 *
178 * If a linked list contains objects with function pointers,
179 * invoke() can call a method on each of the objects. The
180 * method is specified by an offset of the function pointer,
181 * which can be evalutated at compile time using the offsetof
182 * macro, e.g.: list->invoke(list, offsetof(object_t, method));
183 *
184 * @param this calling object
185 * @param offset offset of the method to invoke on objects
186 */
187 void (*invoke) (linked_list_t *this, size_t offset);
188
189 /**
190 * @brief Clones a list and its objects using the objects' clone method.
191 *
192 * @param this calling object
193 * @param offset offset ot the objects clone function
194 * @return cloned list
195 */
196 linked_list_t *(*clone_offset) (linked_list_t *this, size_t offset);
197
198 /**
199 * @brief Clones a list and its objects using a given function.
200 *
201 * @param this calling object
202 * @param function function that clones an object
203 * @return cloned list
204 */
205 linked_list_t *(*clone_function) (linked_list_t *this, void*(*)(void*));
206
207 /**
208 * @brief Destroys a linked_list object.
209 *
210 * @param this calling object
211 */
212 void (*destroy) (linked_list_t *this);
213
214 /**
215 * @brief Destroys a list and its objects using the destructor.
216 *
217 * If a linked list and the contained objects should be destroyed, use
218 * destroy_offset. The supplied offset specifies the destructor to
219 * call on each object. The offset may be calculated using the offsetof
220 * macro, e.g.: list->destroy_offset(list, offsetof(object_t, destroy));
221 *
222 * @param this calling object
223 * @param offset offset of the objects destructor
224 */
225 void (*destroy_offset) (linked_list_t *this, size_t offset);
226
227 /**
228 * @brief Destroys a list and its contents using a a cleanup function.
229 *
230 * If a linked list and its contents should get destroyed using a specific
231 * cleanup function, use destroy_function. This is useful when the
232 * list contains malloc()-ed blocks which should get freed,
233 * e.g.: list->destroy_function(list, free);
234 *
235 * @param this calling object
236 * @param function function to call on each object
237 */
238 void (*destroy_function) (linked_list_t *this, void (*)(void*));
239 };
240
241 /**
242 * @brief Creates an empty linked list object.
243 *
244 * @return linked_list_t object.
245 *
246 * @ingroup utils
247 */
248 linked_list_t *linked_list_create(void);
249
250
251 #endif /*LINKED_LIST_H_*/