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