5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2000 - 2008 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.
25 /****h* silcutil/Dynamic List Interface
29 * SILC Dynamic List API can be used to add opaque contexts to list that
30 * will automatically allocate list entries. The simpler SilcList cannot
31 * be used for this purpose because in that case the context passed to the
32 * list must be defined as list structure already. This is not the case in
33 * SilcDList. But SilcDList is a bit slower than SilcList because it
34 * requires memory allocation when adding new entries to the list.
36 * SILC Dynamic List is not thread-safe. If the same list context must be
37 * used in multithreaded environment concurrency control must be employed.
41 * SilcDList list = silc_dlist_init();
43 * silc_dlist_add(list, entry1);
44 * silc_dlist_add(list, entry2);
46 * // Traverse the list from the beginning to the end
47 * silc_dlist_start(list)
48 * while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
52 * silc_dlist_uninit(list);
56 /****s* silcutil/SilcDList
60 * typedef struct { ... } *SilcDList, SilcDListStruct;
64 * This is the actual SilcDList object that is used by application.
65 * Application defines this object and adds contexts to this list with
66 * Dynamic List Interface functions.
69 typedef struct SilcDListObject {
74 } *SilcDList, SilcDListStruct;
76 /* SilcDListEntry structure, one entry in the list. This MUST NOT be used
77 directly by the application. */
78 typedef struct SilcDListEntryStruct {
80 struct SilcDListEntryStruct *next;
81 struct SilcDListEntryStruct *prev;
84 /****f* silcutil/silc_dlist_init
89 * SilcDList silc_dlist_init(void);
93 * Initializes SilcDList. Returns the SilcDList context or NULL if system
99 SilcDList silc_dlist_init(void)
103 list = (SilcDList)silc_malloc(sizeof(*list));
106 list->stack = list->current = list->prev = NULL;
107 silc_list_init_prev(list->list, struct SilcDListEntryStruct, next, prev);
112 /****f* silcutil/silc_dlist_sinit
117 * SilcDList silc_dlist_sinit(SilcStack stack);
121 * Initializes SilcDList. Returns the SilcDList context or NULL on error.
122 * This is same as silc_dlist_init but allocates the memory from `stack'
123 * if `stack' is non-NULL.
128 SilcDList silc_dlist_sinit(SilcStack stack)
133 stack = silc_stack_alloc(0, stack);
134 list = (SilcDList)silc_smalloc(stack, sizeof(*list));
136 silc_stack_free(stack);
140 list->current = list->prev = NULL;
141 silc_list_init_prev(list->list, struct SilcDListEntryStruct, next, prev);
146 /****f* silcutil/silc_dlist_init_static
151 * void silc_dlist_init_static(SilcDlist list);
155 * Initialize a pre-allocated allocated SilcDList.
160 void silc_dlist_init_static(SilcDList list)
162 list->stack = list->current = list->prev = NULL;
163 silc_list_init_prev(list->list, struct SilcDListEntryStruct, next, prev);
166 /****f* silcutil/silc_dlist_uninit
171 * void silc_dlist_uninit(SilcDList list);
175 * Uninits and frees all memory. Must be called to free memory. Does NOT
176 * free the contexts saved by caller. If the silc_dlist_sinit was used
177 * with SilcStack this will release all memory allocated by the SilcDList
178 * back to the SilcStack.
183 void silc_dlist_uninit(SilcDList list)
187 SilcStack stack = list->stack;
188 silc_list_start(list->list);
189 while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
190 silc_list_del(list->list, e);
191 silc_sfree(stack, e);
193 silc_sfree(stack, list);
194 silc_stack_free(stack);
198 /****f* silcutil/silc_dlist_uninit_static
203 * void silc_dlist_uninit_static(SilcDList list);
207 * Uninits and frees all memory. Must be called to free memory. Does NOT
208 * free the contexts saved by caller. Used to uninit a list initialized
209 * with silc_dlist_init_static.
214 void silc_dlist_uninit_static(SilcDList list)
218 silc_list_start(list->list);
219 while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
220 silc_list_del(list->list, e);
226 /****f* silcutil/silc_dlist_count
231 * int silc_dlist_count(SilcDList list);
235 * Return the number of entries in the list.
240 int silc_dlist_count(SilcDList list)
242 return silc_list_count(list->list);
245 /****f* silcutil/silc_dlist_start
250 * void silc_dlist_start(SilcDList list);
254 * Set the start of the list. This prepares the list for traversing entries
255 * from the start of the list towards end of the list.
260 void silc_dlist_start(SilcDList list)
262 silc_list_start(list->list);
263 list->current = list->prev = NULL;
266 /****f* silcutil/silc_dlist_end
271 * void silc_dlist_end(SilcDList list);
275 * Set the end of the list. This prepares the list for traversing entries
276 * from the end of the list towards start of the list.
281 void silc_dlist_end(SilcDList list)
283 silc_list_end(list->list);
284 list->current = list->prev = NULL;
287 /****f* silcutil/silc_dlist_add
292 * SilcBool silc_dlist_add(SilcDList list, void *context);
296 * Adds new entry to the list. This is the default function to add new
297 * entries to the list.
302 SilcBool silc_dlist_add(SilcDList list, void *context)
304 SilcDListEntry e = (SilcDListEntry)silc_smalloc(list->stack, sizeof(*e));
305 if (silc_unlikely(!e))
307 e->context = context;
308 silc_list_add(list->list, e);
312 /****f* silcutil/silc_dlist_insert
317 * SilcBool silc_dlist_insert(SilcDList list, void *context);
321 * Insert new entry to the list between current and previous entry.
322 * If list is at the start this adds the entry at head of the list.
323 * Use silc_dlist_add to add at the end of the list.
328 SilcBool silc_dlist_insert(SilcDList list, void *context)
330 SilcDListEntry e = (SilcDListEntry)silc_smalloc(list->stack, sizeof(*e));
331 if (silc_unlikely(!e))
333 e->context = context;
334 silc_list_insert(list->list, list->prev, e);
338 /****f* silcutil/silc_dlist_del
343 * void silc_dlist_del(SilcDList list, void *entry);
347 * Remove entry from the list.
352 void silc_dlist_del(SilcDList list, void *entry)
356 silc_list_start(list->list);
357 while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
358 if (e->context == entry) {
359 silc_list_del(list->list, e);
360 #if defined(SILC_DEBUG)
361 memset(e, 'F', sizeof(*e));
363 if (list->current == e)
364 list->current = NULL;
367 silc_sfree(list->stack, e);
373 /****f* silcutil/silc_dlist_get
378 * void *silc_dlist_get(SilcDList list);
382 * Returns current entry from the list and moves the list pointer forward
383 * so that calling this next time returns the next entry from the list.
384 * This can be used to traverse the list. Return SILC_LIST_END when the
385 * entire list has been traversed. Later, silc_list_start (or
386 * silc_dlist_end) must be called again when re-starting list traversing.
390 * // Traverse the list from the beginning to the end
391 * silc_dlist_start(list)
392 * while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
399 void *silc_dlist_get(SilcDList list)
402 list->prev = list->current;
403 list->current = e = (SilcDListEntry)silc_list_get(list->list);
404 if (e != SILC_LIST_END)
406 return SILC_LIST_END;