5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2002 - 2005 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/SILC List Interface
24 * Implementation of the SilcList interface. This interface provides
27 * SILC List is not thread-safe. If the same list context must be used
28 * in multithreaded environment concurrency control must be employed.
35 /****s* silcutil/SilcList/SilcList
39 * typedef struct { ... } SilcList;
43 * This is the SilcList context, and is initialized by calling the
44 * function silc_list_init.
48 void *head; /* Start of the list */
49 void *tail; /* End of the list */
50 void *current; /* Current pointer in list */
51 SilcUInt16 next_offset; /* Offset to 'next' pointer */
52 SilcUInt16 prev_offset; /* Offset to 'prev' pointer */
53 unsigned int prev_set : 1; /* Set if 'prev' exists */
54 unsigned int end_set : 1; /* Set if silc_list_end was called */
55 unsigned int count : 30; /* Number of entries in the list */
58 /****d* silcutil/SilcList/SILC_LIST_END
62 * #define SILC_LIST_END ...
66 * Functions return this when the list is invalid or when traversing
67 * the list there is no more entires in the list.
71 #define SILC_LIST_END NULL
74 /****f* silcutil/SilcList/silc_list_init
78 * #define silc_list_init(list, type, nextfield) ...
82 * This macro initializes the SilcList list. The `list' is the defined
83 * list, second argument is the structure of the entries in the list,
84 * and last argument is the pointer in the structure that is used
85 * as next list members. When using SilcList you must not touch the
86 * structure member pointers manually. If your list has also a prev
87 * pointer should use silc_list_init_prev instead of this call if
88 * you need to be able traverse the list backwards as well.
92 * struct SilcInternalEntryStruct {
94 * struct SilcInternalEntryStruct *next; // The list member pointer
98 * silc_list_init(list, struct SilcInternalEntryStruct, next);
101 #define silc_list_init(list, type, nextfield) \
104 (list).next_offset = silc_offsetof(type, nextfield); \
105 (list).prev_set = 0; \
106 (list).prev_offset = 0; \
107 (list).head = (list).tail = (list).current = NULL; \
110 /****f* silcutil/SilcList/silc_list_init_prev
114 * #define silc_list_init_prev(list, type, nextfield, prevfield) ...
118 * This macro initializes the SilcList list. The `list' is the defined
119 * list, second argument is the structure of the entries in the list,
120 * and last two arguments are the pointers in the structure that is used
121 * as next and prev list members. When using SilcList you must not
122 * touch the structure member pointers manually.
124 * Having both next and prev pointers makes it possible to traverse
125 * list from both ends of the list (from start to end, and from end
130 * struct SilcInternalEntryStruct {
132 * struct SilcInternalEntryStruct *next; // The list member pointer
133 * struct SilcInternalEntryStruct *prev; // The list member pointer
137 * silc_list_init_prev(list, struct SilcInternalEntryStruct, next, prev);
140 #define silc_list_init_prev(list, type, nextfield, prevfield) \
143 (list).next_offset = silc_offsetof(type, nextfield); \
144 (list).prev_offset = silc_offsetof(type, prevfield); \
145 (list).prev_set = 1; \
146 (list).head = (list).tail = (list).current = NULL; \
149 /****f* silcutil/SilcList/silc_list_count
153 * #define silc_list_count(list) ...
157 * Returns the number of entries in the list indicated by `list'.
160 #define silc_list_count(list) (list).count
162 /****f* silcutil/SilcList/silc_list_start
166 * #define silc_list_start(list) ...
170 * Sets the start of the list. This prepares the list for traversing
171 * the entries from the start of the list towards end of the list.
174 #define silc_list_start(list) \
175 ((list).current = (list).head, (list).end_set = 0)
177 /****f* silcutil/SilcList/silc_list_end
181 * #define silc_list_end(list) ...
185 * Sets the end of the list. This prepares the list for traversing
186 * the entries from the end of the list towards start of the list.
190 * You can use this call only if you initialized the list with
191 * silc_list_init_prev.
194 #define silc_list_end(list) \
195 ((list).current = (list).tail, (list).end_set = 1)
197 /* Macros to get position to next and prev list pointers */
198 #define __silc_list_next(list, pos) \
199 ((void **)((unsigned char *)(pos) + (list).next_offset))
200 #define __silc_list_prev(list, pos) \
201 ((void **)((unsigned char *)(pos) + (list).prev_offset))
203 /****f* silcutil/SilcList/silc_list_add
207 * #define silc_list_add(list, entry) ...
211 * Adds new entry indicated by `entry' to the end of the list indicated
215 #define silc_list_add(list, entry) \
218 (list).head = (entry); \
220 *__silc_list_next(list, (list).tail) = (entry); \
221 if ((list).prev_set) \
222 *__silc_list_prev(list, entry) = (list).tail; \
223 (list).tail = (entry); \
224 *__silc_list_next(list, entry) = NULL; \
228 /****f* silcutil/SilcList/silc_list_insert
232 * #define silc_list_insert(list, current, entry) ...
236 * Insert new entry indicated by `entry' after the entry `current'
237 * to the list indicated by `list'. If `current' is NULL, then the
238 * `entry' is added at the head of the list. Use the silc_list_add
239 * to add at the end of the list.
242 #define silc_list_insert(list, current, entry) \
246 *__silc_list_next(list, entry) = (list).head; \
248 *__silc_list_next(list, entry) = NULL; \
249 if ((list).prev_set && (list).head) \
250 *__silc_list_prev(list, (list).head) = entry; \
252 (list).tail = (entry); \
253 (list).head = (entry); \
254 if ((list).prev_set) \
255 *__silc_list_prev(list, entry) = NULL; \
257 *__silc_list_next(list, entry) = *__silc_list_next(list, current); \
258 *__silc_list_next(list, current) = entry; \
259 if ((list).prev_set) { \
260 *__silc_list_prev(list, entry) = current; \
261 if (*__silc_list_next(list, entry)) \
262 *__silc_list_prev(list, *__silc_list_next(list, entry)) = entry; \
264 if ((list).tail == (current)) \
265 (list).tail = (entry); \
270 /****f* silcutil/SilcList/silc_list_del
274 * #define silc_list_del(list, entry) ...
278 * Remove entry indicated by `entry' from the list indicated by `list'.
281 #define silc_list_del(list, entry) \
285 for (p = &(list).head; *p; p = __silc_list_next(list, *p)) { \
286 if (*p == (entry)) { \
287 *p = *__silc_list_next(list, entry); \
288 if (*p && (list).prev_set) \
289 *__silc_list_prev(list, *p) = *__silc_list_prev(list, entry); \
290 if ((list).current == (entry)) \
291 (list).current = *p; \
297 if (entry == (list).tail) \
298 (list).tail = prev; \
301 /****f* silcutil/SilcList/silc_list_get
305 * #define silc_list_get(list) ...
309 * Returns the current entry from the list indicated by `list' and
310 * moves the list pointer forward so that calling this next time will
311 * return the next entry from the list. This can be used to traverse
312 * the list. Returns SILC_LIST_END when the entire list has been
313 * tarversed and no additional entries exist in the list. Later,
314 * silc_list_start (or silc_list_end) must be called again when
315 * re-starting the list tarversing.
319 * // Traverse the list from the beginning to the end
320 * silc_list_start(list);
321 * while ((entry = silc_list_get(list)) != SILC_LIST_END) {
325 * // Traverse the list from the end to the beginning
326 * silc_list_end(list);
327 * while ((entry = silc_list_get(list)) != SILC_LIST_END) {
332 #define silc_list_get(x) __silc_list_get(&(x))
334 void *__silc_list_get(SilcList *list)
336 void *pos = list->current;
338 list->current = (list->end_set ? *__silc_list_prev(*list, pos) :
339 *__silc_list_next(*list, pos));