5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2000 - 2006 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/SILC Dynamic List Interface
29 * SILC Dynamic List API can be used to add opaque contexts to list that
30 * will automatically allocate list entries. Normal SILC List API 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 /****s* silcutil/SilcDListAPI/SilcDList
45 * typedef struct { ... } *SilcDList;
49 * This is the actual SilcDList object that is used by application.
50 * Application defines this object and adds contexts to this list with
51 * Dynamic List Interface functions.
55 typedef struct SilcDListStruct {
62 /* SilcDListEntry structure, one entry in the list. This MUST NOT be used
63 directly by the application. */
64 typedef struct SilcDListEntryStruct {
66 struct SilcDListEntryStruct *next;
67 struct SilcDListEntryStruct *prev;
70 /****f* silcutil/SilcDListAPI/silc_dlist_init
75 * SilcDList silc_dlist_init(void);
79 * Initializes SilcDList.
84 SilcDList silc_dlist_init(void)
88 list = (SilcDList)silc_malloc(sizeof(*list));
91 list->current = list->prev = NULL;
92 silc_list_init_prev(list->list, struct SilcDListEntryStruct, next, prev);
97 /****f* silcutil/SilcDListAPI/silc_dlist_uninit
102 * void silc_dlist_uninit(SilcDList list);
106 * Uninits and frees all memory. Must be called to free memory. Does NOT
107 * free the contexts saved by caller.
112 void silc_dlist_uninit(SilcDList list)
116 silc_list_start(list->list);
117 while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
118 silc_list_del(list->list, e);
125 /****f* silcutil/SilcDListAPI/silc_dlist_count
130 * int silc_dlist_count(SilcDList list);
134 * Return the number of entries in the list.
139 int silc_dlist_count(SilcDList list)
141 return silc_list_count(list->list);
144 /****f* silcutil/SilcDListAPI/silc_dlist_start
149 * void silc_dlist_start(SilcDList list);
153 * Set the start of the list. This prepares the list for traversing entries
154 * from the start of the list towards end of the list.
159 void silc_dlist_start(SilcDList list)
161 silc_list_start(list->list);
162 list->current = list->prev = NULL;
165 /****f* silcutil/SilcDListAPI/silc_dlist_end
170 * void silc_dlist_end(SilcDList list);
174 * Set the end of the list. This prepares the list for traversing entries
175 * from the end of the list towards start of the list.
180 void silc_dlist_end(SilcDList list)
182 silc_list_end(list->list);
183 list->current = list->prev = NULL;
186 /****f* silcutil/SilcDListAPI/silc_dlist_add
191 * SilcBool silc_dlist_add(SilcDList list, void *context);
195 * Adds new entry to the list. This is the default function to add new
196 * entries to the list.
201 SilcBool silc_dlist_add(SilcDList list, void *context)
203 SilcDListEntry e = (SilcDListEntry)silc_malloc(sizeof(*e));
204 if (silc_unlikely(!e))
206 e->context = context;
207 silc_list_add(list->list, e);
211 /****f* silcutil/SilcDList/silc_dlist_insert
216 * SilcBool silc_dlist_insert(SilcDList list, void *context);
220 * Insert new entry to the list between current and previous entry.
221 * If list is at the start this adds the entry at head of the list.
222 * Use silc_dlist_add to add at the end of the list.
227 SilcBool silc_dlist_insert(SilcDList list, void *context)
229 SilcDListEntry e = (SilcDListEntry)silc_malloc(sizeof(*e));
230 if (silc_unlikely(!e))
232 e->context = context;
233 silc_list_insert(list->list, list->prev, e);
237 /****f* silcutil/SilcDListAPI/silc_dlist_del
242 * void silc_dlist_del(SilcDList list, void *context);
246 * Remove entry from the list. Returns < 0 on error, 0 otherwise.
251 void silc_dlist_del(SilcDList list, void *context)
255 silc_list_start(list->list);
256 while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
257 if (e->context == context) {
258 silc_list_del(list->list, e);
259 #if defined(SILC_DEBUG)
260 memset(e, 'F', sizeof(*e));
262 if (list->current == e)
263 list->current = NULL;
272 /****f* silcutil/SilcDListAPI/silc_dlist_get
277 * void *silc_dlist_get(SilcDList list);
281 * Returns current entry from the list and moves the list pointer forward
282 * so that calling this next time returns the next entry from the list.
283 * This can be used to traverse the list. Return SILC_LIST_END when the
284 * entire list has been traversed. Later, silc_list_start (or
285 * silc_dlist_end) must be called again when re-starting list traversing.
289 * // Traverse the list from the beginning to the end
290 * silc_dlist_start(list)
291 * while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
298 void *silc_dlist_get(SilcDList list)
301 list->prev = list->current;
302 list->current = e = (SilcDListEntry)silc_list_get(list->list);
303 if (e != SILC_LIST_END)
305 return SILC_LIST_END;