lib/silcutil/silcdlist.h

   1 /*
   2
   3   silcdlist.h
   4
   5   Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
   6
   7   Copyright (C) 2000 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; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 #ifndef SILDCLIST_H
  22 #define SILDCLIST_H
  23
  24 #include "silclist.h"
  25
  26 /*
  27    SILC Dynamic List API
  28
  29    SILC Dynamic List API can be used to add opaque contexts to list that will
  30    automatically allocate list entries.  Normal SILC List API cannot be used
  31    for this purpose because in that case the context passed to the list must
  32    be defined as list structure already.  This is not the case in SilcDList.
  33
  34    This is slower than SilcList because this requires one extra memory
  35    allocation when adding new entries to the list.  The context is probably
  36    allocated already and the new list entry requires one additional memory
  37    allocation.  The memory allocation and free'ing is done automatically in
  38    the API and does not show to the caller.
  39 */
  40
  41 /* SilcDList object. This is the actual SilcDList object that is used by
  42    application. Application defines this object and adds context's to this
  43    list with functions defined below. */
  44 typedef struct {
  45   SilcList list;
  46 } *SilcDList;
  47
  48 /* SilcDListEntry structure, one entry in the list. This MUST NOT be used
  49    directly by the application. */
  50 typedef struct SilcDListEntryStruct {
  51   void *context;
  52   struct SilcDListEntryStruct *next;
  53 } *SilcDListEntry;
  54
  55 /* Initializes SilcDList. */
  56
  57 static inline
  58 SilcDList silc_dlist_init()
  59 {
  60   SilcDList list;
  61
  62   list = (SilcDList)silc_calloc(1, sizeof(*list));
  63   silc_list_init(list->list, struct SilcDListEntryStruct, next);
  64
  65   return list;
  66 }
  67
  68 /* Uninits and free's all memory. Must be called to free memory. Does NOT
  69    free the contexts saved by caller. */
  70
  71 static inline
  72 void silc_dlist_uninit(SilcDList list)
  73 {
  74   if (list) {
  75     SilcDListEntry e;
  76     silc_list_start(list->list);
  77     while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
  78       silc_list_del(list->list, e);
  79       silc_free(e);
  80     }
  81     silc_free(list);
  82   }
  83 }
  84
  85 /* Return the number of entries in the list */
  86
  87 static inline
  88 int silc_dlist_count(SilcDList list)
  89 {
  90   return silc_list_count(list->list);
  91 }
  92
  93 /* Set the start of the list. This prepares the list for traversing entries
  94    from the start of the list. */
  95
  96 static inline
  97 void silc_dlist_start(SilcDList list)
  98 {
  99   silc_list_start(list->list);
 100 }
 101
 102 /* Adds new entry to the list. This is the default function to add new
 103    entries to the list. */
 104
 105 static inline
 106 void silc_dlist_add(SilcDList list, void *context)
 107 {
 108   SilcDListEntry e = (SilcDListEntry)silc_calloc(1, sizeof(*e));
 109   e->context = context;
 110   silc_list_add(list->list, e);
 111 }
 112
 113 /* Remove entry from the list. Returns < 0 on error, 0 otherwise. */
 114
 115 static inline
 116 void silc_dlist_del(SilcDList list, void *context)
 117 {
 118   SilcDListEntry e;
 119
 120   silc_list_start(list->list);
 121   while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
 122     if (e->context == context) {
 123       silc_list_del(list->list, e);
 124       silc_free(e);
 125       break;
 126     }
 127   }
 128 }
 129
 130 /* Returns current entry from the list and moves the list pointer forward
 131    so that calling this next time returns the next entry from the list. This
 132    can be used to traverse the list. Return SILC_LIST_END when the entire
 133    list has ben traversed. Later, silc_list_start must be called again when
 134    re-starting list traversing. Example:
 135
 136    // Traverse the list from the beginning to the end
 137    silc_dlist_start(list)
 138    while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
 139      ...
 140    }
 141
 142 */
 143 static inline
 144 void *silc_dlist_get(SilcDList list)
 145 {
 146   SilcDListEntry e = (SilcDListEntry)silc_list_get(list->list);
 147   if (e != SILC_LIST_END)
 148     return e->context;
 149   return SILC_LIST_END;
 150 }
 151
 152 #endif