SILC Runtime Toolkit 1.2 Beta 1

[runtime.git] / lib / silcutil / silclist.h

diff --git a/lib/silcutil/silclist.h b/lib/silcutil/silclist.h
index 50213491f0b361239d015a5cd08606752499b777..14fab3f54af3aa02c56e7c4dc0b68907dc41240f 100644 (file)
--- a/lib/silcutil/silclist.h
+++ b/lib/silcutil/silclist.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2002 - 2005 Pekka Riikonen
+  Copyright (C) 2002 - 2008 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -17,19 +17,35 @@
 
 */
 
-/****h* silcutil/SILC List Interface
+/****h* silcutil/List Interface
  *
  * DESCRIPTION
  *
- * Implementation of the SilcList interface.  This interface provides
- * simple linked list.
+ * Generic list interface that can turn any structure with list pointers
+ * into a SilcList.  The interface can provide both singly and doubly linked
+ * lists.  The interface does not allocate any memory.
+ *
+ * SILC List is not thread-safe.  If the same list context must be used
+ * in multithreaded environment concurrency control must be employed.
+ *
+ * EXAMPLE
+ *
+ * struct EntryStruct {
+ *   char *dummy;
+ *   struct EntryStruct *next;        // The list member pointer
+ * };
+ *
+ * SilcList list;
+ *
+ * // Initialize list
+ * silc_list_init(list, struct EntryStruct, next);
  *
  ***/
 
 #ifndef SILCLIST_H
 #define SILCLIST_H
 
-/****s* silcutil/SilcList/SilcList
+/****s* silcutil/SilcList
  *
  * NAME
  *
@@ -41,22 +57,22 @@
  *    function silc_list_init.
  *
  ***/
-typedef struct {
+typedef struct SilcListStruct {
   void *head;                       /* Start of the list */
   void *tail;                       /* End of the list */
   void *current;                    /* Current pointer in list */
-  unsigned int next_offset : 16;     /* Offset to 'next' pointer */
-  unsigned int prev_offset : 16;     /* Offset to 'prev' pointer */
+  SilcUInt16 next_offset;           /* Offset to 'next' pointer */
+  SilcUInt16 prev_offset;           /* Offset to 'prev' pointer */
   unsigned int prev_set    : 1;             /* Set if 'prev' exists */
   unsigned int end_set     : 1;             /* Set if silc_list_end was called */
   unsigned int count       : 30;     /* Number of entries in the list */
 } SilcList;
 
-/****d* silcutil/SilcList/SILC_LIST_END
+/****d* silcutil/SILC_LIST_END
  *
  * NAME
  *
- *    #define SILC_LIST_END ...
+ *    #define SILC_LIST_END NULL
  *
  * DESCRIPTION
  *
@@ -68,7 +84,7 @@ typedef struct {
 #define SILC_LIST_END NULL
 /***/
 
-/****f* silcutil/SilcList/silc_list_init
+/****f* silcutil/silc_list_init
  *
  * SYNOPSIS
  *
@@ -101,10 +117,11 @@ do {                                                      \
   (list).next_offset = silc_offsetof(type, nextfield); \
   (list).prev_set = 0;                                 \
   (list).prev_offset = 0;                              \
+  (list).end_set = 0;                                  \
   (list).head = (list).tail = (list).current = NULL;   \
 } while(0)
 
-/****f* silcutil/SilcList/silc_list_init_prev
+/****f* silcutil/silc_list_init_prev
  *
  * SYNOPSIS
  *
@@ -140,10 +157,11 @@ do {                                                              \
   (list).next_offset = silc_offsetof(type, nextfield);         \
   (list).prev_offset = silc_offsetof(type, prevfield);         \
   (list).prev_set = 1;                                         \
+  (list).end_set = 0;                                          \
   (list).head = (list).tail = (list).current = NULL;           \
 } while(0)
 
-/****f* silcutil/SilcList/silc_list_count
+/****f* silcutil/silc_list_count
  *
  * SYNOPSIS
  *
@@ -156,7 +174,7 @@ do {                                                                \
  ***/
 #define silc_list_count(list) (list).count
 
-/****f* silcutil/SilcList/silc_list_start
+/****f* silcutil/silc_list_start
  *
  * SYNOPSIS
  *
@@ -171,7 +189,7 @@ do {                                                                \
 #define silc_list_start(list)                          \
   ((list).current = (list).head, (list).end_set = 0)
 
-/****f* silcutil/SilcList/silc_list_end
+/****f* silcutil/silc_list_end
  *
  * SYNOPSIS
  *
@@ -197,7 +215,7 @@ do {                                                                \
 #define __silc_list_prev(list, pos)                            \
   ((void **)((unsigned char *)(pos) + (list).prev_offset))
 
-/****f* silcutil/SilcList/silc_list_add
+/****f* silcutil/silc_list_add
  *
  * SYNOPSIS
  *
@@ -222,7 +240,7 @@ do {                                                        \
   (list).count++;                                      \
 } while(0)
 
-/****f* silcutil/SilcList/silc_list_insert
+/****f* silcutil/silc_list_insert
  *
  * SYNOPSIS
  *
@@ -264,7 +282,7 @@ do {                                                                         \
   (list).count++;                                                       \
 } while(0)
 
-/****f* silcutil/SilcList/silc_list_del
+/****f* silcutil/silc_list_del
  *
  * SYNOPSIS
  *
@@ -295,7 +313,7 @@ do {                                                                        \
     (list).tail = prev;                                                        \
 } while(0)
 
-/****f* silcutil/SilcList/silc_list_get
+/****f* silcutil/silc_list_get
  *
  * SYNOPSIS
  *