Fixed initialization.
[silc.git] / lib / silcutil / silcdlist.h
1 /*
2
3   silcdlist.h
4
5   Author: Pekka Riikonen <priikone@silcnet.org>
6
7   Copyright (C) 2000 - 2007 Pekka Riikonen
8
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.
12
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.
17
18 */
19
20 #ifndef SILDCLIST_H
21 #define SILDCLIST_H
22
23 #include "silclist.h"
24
25 /****h* silcutil/SILC Dynamic List Interface
26  *
27  * DESCRIPTION
28  *
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.
35  *
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.
38  *
39  ***/
40
41 /****s* silcutil/SilcDListAPI/SilcDList
42  *
43  * NAME
44  *
45  *    typedef struct { ... } *SilcDList;
46  *
47  * DESCRIPTION
48  *
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.
52  *
53  ***/
54 typedef struct SilcDListStruct {
55   SilcStack stack;
56   SilcList list;
57   void *current;
58   void *prev;
59 } *SilcDList;
60
61 /* SilcDListEntry structure, one entry in the list. This MUST NOT be used
62    directly by the application. */
63 typedef struct SilcDListEntryStruct {
64   void *context;
65   struct SilcDListEntryStruct *next;
66   struct SilcDListEntryStruct *prev;
67 } *SilcDListEntry;
68
69 /****f* silcutil/SilcDListAPI/silc_dlist_init
70  *
71  * SYNOPSIS
72  *
73  *    static inline
74  *    SilcDList silc_dlist_init(void);
75  *
76  * DESCRIPTION
77  *
78  *    Initializes SilcDList.  Returns the SilcDList context or NULL on error.
79  *
80  ***/
81
82 static inline
83 SilcDList silc_dlist_init(void)
84 {
85   SilcDList list;
86
87   list = (SilcDList)silc_malloc(sizeof(*list));
88   if (!list)
89     return NULL;
90   list->stack = list->current = list->prev = NULL;
91   silc_list_init_prev(list->list, struct SilcDListEntryStruct, next, prev);
92
93   return list;
94 }
95
96 /****f* silcutil/SilcDListAPI/silc_dlist_sinit
97  *
98  * SYNOPSIS
99  *
100  *    static inline
101  *    SilcDList silc_dlist_sinit(SilcStack stack);
102  *
103  * DESCRIPTION
104  *
105  *    Initializes SilcDList.  Returns the SilcDList context or NULL on error.
106  *    This is same as silc_dlist_init but allocates the memory from `stack'
107  *    if `stack' is non-NULL.
108  *
109  ***/
110
111 static inline
112 SilcDList silc_dlist_sinit(SilcStack stack)
113 {
114   SilcDList list;
115
116   if (stack)
117     stack = silc_stack_alloc(0, stack);
118   list = (SilcDList)silc_smalloc(stack, sizeof(*list));
119   if (!list) {
120     silc_stack_free(stack);
121     return NULL;
122   }
123   list->stack = stack;
124   list->current = list->prev = NULL;
125   silc_list_init_prev(list->list, struct SilcDListEntryStruct, next, prev);
126
127   return list;
128 }
129
130 /****f* silcutil/SilcDListAPI/silc_dlist_uninit
131  *
132  * SYNOPSIS
133  *
134  *    static inline
135  *    void silc_dlist_uninit(SilcDList list);
136  *
137  * DESCRIPTION
138  *
139  *    Uninits and frees all memory. Must be called to free memory. Does NOT
140  *    free the contexts saved by caller.  If the silc_dlist_sinit was used
141  *    with SilcStack this will release all memory allocated by the SilcDList
142  *    back to the SilcStack.
143  *
144  ***/
145
146 static inline
147 void silc_dlist_uninit(SilcDList list)
148 {
149   if (list) {
150     SilcDListEntry e;
151     SilcStack stack = list->stack;
152     silc_list_start(list->list);
153     while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
154       silc_list_del(list->list, e);
155       silc_sfree(stack, e);
156     }
157     silc_sfree(stack, list);
158     silc_stack_free(stack);
159   }
160 }
161
162 /****f* silcutil/SilcDListAPI/silc_dlist_count
163  *
164  * SYNOPSIS
165  *
166  *    static inline
167  *    int silc_dlist_count(SilcDList list);
168  *
169  * DESCRIPTION
170  *
171  * Return the number of entries in the list.
172  *
173  ***/
174
175 static inline
176 int silc_dlist_count(SilcDList list)
177 {
178   return silc_list_count(list->list);
179 }
180
181 /****f* silcutil/SilcDListAPI/silc_dlist_start
182  *
183  * SYNOPSIS
184  *
185  *    static inline
186  *    void silc_dlist_start(SilcDList list);
187  *
188  * DESCRIPTION
189  *
190  *    Set the start of the list. This prepares the list for traversing entries
191  *    from the start of the list towards end of the list.
192  *
193  ***/
194
195 static inline
196 void silc_dlist_start(SilcDList list)
197 {
198   silc_list_start(list->list);
199   list->current = list->prev = NULL;
200 }
201
202 /****f* silcutil/SilcDListAPI/silc_dlist_end
203  *
204  * SYNOPSIS
205  *
206  *    static inline
207  *    void silc_dlist_end(SilcDList list);
208  *
209  * DESCRIPTION
210  *
211  *    Set the end of the list. This prepares the list for traversing entries
212  *    from the end of the list towards start of the list.
213  *
214  ***/
215
216 static inline
217 void silc_dlist_end(SilcDList list)
218 {
219   silc_list_end(list->list);
220   list->current = list->prev = NULL;
221 }
222
223 /****f* silcutil/SilcDListAPI/silc_dlist_add
224  *
225  * SYNOPSIS
226  *
227  *    static inline
228  *    SilcBool silc_dlist_add(SilcDList list, void *context);
229  *
230  * DESCRIPTION
231  *
232  *    Adds new entry to the list. This is the default function to add new
233  *    entries to the list.
234  *
235  ***/
236
237 static inline
238 SilcBool silc_dlist_add(SilcDList list, void *context)
239 {
240   SilcDListEntry e = (SilcDListEntry)silc_smalloc(list->stack, sizeof(*e));
241   if (silc_unlikely(!e))
242     return FALSE;
243   e->context = context;
244   silc_list_add(list->list, e);
245   return TRUE;
246 }
247
248 /****f* silcutil/SilcDList/silc_dlist_insert
249  *
250  * SYNOPSIS
251  *
252  *    static inline
253  *    SilcBool silc_dlist_insert(SilcDList list, void *context);
254  *
255  * DESCRIPTION
256  *
257  *    Insert new entry to the list between current and previous entry.
258  *    If list is at the start this adds the entry at head of the list.
259  *    Use silc_dlist_add to add at the end of the list.
260  *
261  ***/
262
263 static inline
264 SilcBool silc_dlist_insert(SilcDList list, void *context)
265 {
266   SilcDListEntry e = (SilcDListEntry)silc_smalloc(list->stack, sizeof(*e));
267   if (silc_unlikely(!e))
268     return FALSE;
269   e->context = context;
270   silc_list_insert(list->list, list->prev, e);
271   return TRUE;
272 }
273
274 /****f* silcutil/SilcDListAPI/silc_dlist_del
275  *
276  * SYNOPSIS
277  *
278  *    static inline
279  *    void silc_dlist_del(SilcDList list, void *entry);
280  *
281  * DESCRIPTION
282  *
283  *    Remove entry from the list.
284  *
285  ***/
286
287 static inline
288 void silc_dlist_del(SilcDList list, void *entry)
289 {
290   SilcDListEntry e;
291
292   silc_list_start(list->list);
293   while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
294     if (e->context == entry) {
295       silc_list_del(list->list, e);
296 #if defined(SILC_DEBUG)
297       memset(e, 'F', sizeof(*e));
298 #endif
299       if (list->current == e)
300         list->current = NULL;
301       if (list->prev == e)
302         list->prev = NULL;
303       silc_sfree(list->stack, e);
304       break;
305     }
306   }
307 }
308
309 /****f* silcutil/SilcDListAPI/silc_dlist_get
310  *
311  * SYNOPSIS
312  *
313  *    static inline
314  *    void *silc_dlist_get(SilcDList list);
315  *
316  * DESCRIPTION
317  *
318  *    Returns current entry from the list and moves the list pointer forward
319  *    so that calling this next time returns the next entry from the list.
320  *    This can be used to traverse the list. Return SILC_LIST_END when the
321  *    entire list has been traversed. Later, silc_list_start (or
322  *    silc_dlist_end) must be called again when re-starting list traversing.
323  *
324  * EXAMPLE
325  *
326  *    // Traverse the list from the beginning to the end
327  *    silc_dlist_start(list)
328  *    while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
329  *      ...
330  *    }
331  *
332  ***/
333
334 static inline
335 void *silc_dlist_get(SilcDList list)
336 {
337   SilcDListEntry e;
338   list->prev = list->current;
339   list->current = e = (SilcDListEntry)silc_list_get(list->list);
340   if (e != SILC_LIST_END)
341     return e->context;
342   return SILC_LIST_END;
343 }
344
345 #endif