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