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