src/toolbox/list.h

   1 /* src/toolbox/list.h - synchronized linked list
   2
   3    Copyright (C) 1996-2005, 2006, 2007, 2008
   4    CACAOVM - Verein zur Foerderung der freien virtuellen Maschine CACAO
   5
   6    This file is part of CACAO.
   7
   8    This program is free software; you can redistribute it and/or
   9    modify it under the terms of the GNU General Public License as
  10    published by the Free Software Foundation; either version 2, or (at
  11    your option) any later version.
  12
  13    This program is distributed in the hope that it will be useful, but
  14    WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16    General Public License for more details.
  17
  18    You should have received a copy of the GNU General Public License
  19    along with this program; if not, write to the Free Software
  20    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  21    02110-1301, USA.
  22
  23 */
  24
  25
  26 #ifndef _LIST_H
  27 #define _LIST_H
  28
  29 #include "config.h"
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 #include <stdint.h>
  36
  37 #include "vm/global.h"
  38
  39
  40 /* ---------------------- interface description -----------------------------
  41
  42 The list management with this module works like this:
  43
  44         - to be used in a list, a structure must have an element of type
  45           'listnode'.
  46
  47         - there needs to be a structure of type 'list'.
  48
  49         - the function list_init(l, nodeoffset) initializes the structure.
  50           nodeoffset is the offset of the 'listnode' from the start of the
  51           structure in bytes.
  52
  53         - The remaining functions provide inserting, removing and searching.
  54
  55 This small example aims to demonstrate correct usage:
  56
  57
  58
  59         void bsp() {
  60                 struct node {
  61                         listnode linkage;
  62                         int value;
  63                         } a,b,c, *el;
  64
  65                 list l;
  66
  67                 a.value = 7;
  68                 b.value = 9;
  69                 c.value = 11;
  70
  71                 list_init (&l, OFFSET(struct node,linkage) );
  72                 list_addlast (&l, a);
  73                 list_addlast (&l, b);
  74                 list_addlast (&l, c);
  75
  76                 e = list_first (&l);
  77                 while (e) {
  78                         printf ("Element: %d\n", e->value);
  79                         e = list_next (&l,e);
  80                         }
  81         }
  82
  83
  84         The output from this program should be:
  85                 7
  86                 9
  87                 11
  88
  89
  90
  91 The reason for the usage of 'nodeoffset' is that this way, the same node can
  92 part of different lists (there must be one 'listnode' element for every
  93 distinct list).
  94
  95 */
  96
  97 /* listnode_t *****************************************************************/
  98
  99 typedef struct listnode_t listnode_t;
 100
 101 struct listnode_t {
 102         listnode_t *next;
 103         listnode_t *prev;
 104 };
 105
 106
 107 /* list_t *********************************************************************/
 108
 109 typedef struct list_t list_t;
 110
 111 struct list_t {
 112 #if defined(ENABLE_THREADS)
 113         java_object_t      lock;            /* threads lock object                */
 114 #endif
 115         listnode_t        *first;
 116         listnode_t        *last;
 117         int                nodeoffset;
 118         int                size;            /* number of elements in the list     */
 119 };
 120
 121
 122 /* function prototypes ********************************************************/
 123
 124 list_t *list_create(int nodeoffset);
 125 list_t *list_create_dump(int nodeoffset);
 126
 127 void    list_free(list_t *l);
 128
 129 void    list_lock(list_t *l);
 130 void    list_unlock(list_t *l);
 131
 132 void    list_add_first(list_t *l, void *element);
 133 void    list_add_last(list_t *l, void *element);
 134 void    list_add_before(list_t *l, void *element, void *newelement);
 135
 136 void    list_remove(list_t *l, void *element);
 137
 138 void   *list_first(list_t *l);
 139 void   *list_last(list_t *l);
 140
 141 void   *list_next(list_t *l, void *element);
 142 void   *list_prev(list_t *l, void *element);
 143
 144 #ifdef __cplusplus
 145 }
 146 #endif
 147
 148 #endif /* _LIST_H */
 149
 150
 151 /*
 152  * These are local overrides for various environment variables in Emacs.
 153  * Please do not remove this and leave it at the end of the file, where
 154  * Emacs will automagically detect them.
 155  * ---------------------------------------------------------------------
 156  * Local variables:
 157  * mode: c
 158  * indent-tabs-mode: t
 159  * c-basic-offset: 4
 160  * tab-width: 4
 161  * End:
 162  */