cde/lib/DtSvc/include/bms/Symbolic.h

   1 /*
   2  * CDE - Common Desktop Environment
   3  *
   4  * Copyright (c) 1993-2012, The Open Group. All rights reserved.
   5  *
   6  * These libraries and programs are free software; you can
   7  * redistribute them and/or modify them under the terms of the GNU
   8  * Lesser General Public License as published by the Free Software
   9  * Foundation; either version 2 of the License, or (at your option)
  10  * any later version.
  11  *
  12  * These libraries and programs are distributed in the hope that
  13  * they will be useful, but WITHOUT ANY WARRANTY; without even the
  14  * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE. See the GNU Lesser General Public License for more
  16  * details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with these librararies and programs; if not, write
  20  * to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
  21  * Floor, Boston, MA 02110-1301 USA
  22  */
  23 /*
  24  * File:         Symbolic.h $XConsortium: Symbolic.h /main/3 1995/10/26 15:45:51 rswiston $
  25  * Language:     C
  26  *
  27  * (c) Copyright 1988, Hewlett-Packard Company, all rights reserved.
  28  *
  29  * (c) Copyright 1993, 1994 Hewlett-Packard Company                     *
  30  * (c) Copyright 1993, 1994 International Business Machines Corp.       *
  31  * (c) Copyright 1993, 1994 Sun Microsystems, Inc.                      *
  32  * (c) Copyright 1993, 1994 Novell, Inc.                                *
  33  */
  34
  35 /*  SYMBOLS */
  36
  37 #ifndef _Symbolic_h_
  38 #define _Symbolic_h_
  39
  40 /* -------------------------------------------- */
  41 /* Requires:                                    */
  42 #ifdef __recursive_includes
  43 #include <bms/bms.h>
  44 #endif
  45 /* -------------------------------------------- */
  46
  47 /****************************************************************************/
  48 /*  Symbol (hash) Tables                                                    */
  49
  50 /*
  51
  52 There are two types of symbol (hash) tables.  The common case is where the
  53 key (index) is ascii string.  The Xe_intern() and XeRegisterSymbol()
  54 routines assume this type of table.  In these cases an "XeSymbol" entry is
  55 created in the symbol table (see type below). After it is created a COPY of
  56 the string is made and stored in the "name" field.  The "value" field is
  57 free for the user to fill in on his own.
  58
  59 */
  60
  61 typedef struct _XeSymbol {
  62     XeString   name;
  63     void       *value;
  64 } *XeSymbol;
  65
  66 /*
  67 This type is used for the XeRegisterFunction() routine.
  68 */
  69
  70 typedef void (*XeAnyFunction) ();
  71
  72
  73 /*
  74 The second type of table is where the user defines his own type of
  75 data, hash functions, compare functions, etc.
  76 */
  77
  78 /* The following types for the the user configurable functions that */
  79 /* are set with the Xe_set_syms_fns() routine.                      */
  80 /* ---------------------------------------------------------------- */
  81
  82
  83 /* CMP_FN:                                                              */
  84 /*                                                                      */
  85 /*   Any user defined function should return "0" for a "match"          */
  86 /*                                                                      */
  87 /*   Used for Xe_intern() and XeRegisterSymbol()                        */
  88 /*                                                                      */
  89 /*   If NO "cmp_fn", strcmp("next_table_entry"->name, "name")           */
  90 /*   If    "cmp_fn", cmp_fn("next_table_entry"->name, "name")           */
  91 /*                                                                      */
  92 /*   Used for Xe_intern_anysym()                                        */
  93 /*                                                                      */
  94 /*   If NO "cmp_fn", strcmp("next_table_entry"->name, "data"->name)     */
  95 /*   If    "cmp_fn", cmp_fn("next_table_entry",       "data")           */
  96 /* -------------------------------------------------------------------- */
  97
  98 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
  99    typedef int (*XeSymFn_cmp) (void *, void *);     /* 0 mean match */
 100 #else
 101    typedef int (*XeSymFn_cmp) ();
 102 #endif
 103
 104
 105 /* HASH_FN:                                                                */
 106 /*                                                                         */
 107 /*   Note, the internal hash function in not user accesable.               */
 108 /*                                                                         */
 109 /*   Used for Xe_intern() and XeRegisterSymbol()                           */
 110 /*                                                                         */
 111 /*   If NO "hash_fn", internal_hash("next_table_entry"->name, "name")      */
 112 /*   If    "hash_fn",       hash_fn("next_table_entry"->name, "name")      */
 113 /*                                                                         */
 114 /*   Used for Xe_intern_anysym()                                           */
 115 /*                                                                         */
 116 /*   If NO "hash_fn", internal_hash("next_table_entry"->name, "data"->name)*/
 117 /*   If    "hash_fn",       hash_fn("next_table_entry"      , "data")      */
 118 /* ----------------------------------------------------------------------- */
 119
 120 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 121    typedef unsigned int (*XeSymFn_hash)  (void *, unsigned int);
 122 #else
 123    typedef unsigned int (*XeSymFn_hash)  ();
 124 #endif
 125
 126 /* INIT_FN:                                                             */
 127 /*                                                                      */
 128 /*   Used for Xe_intern() and XeRegisterSymbol()                        */
 129 /*                                                                      */
 130 /*     1) A XeSymbol entry is created,                                  */
 131 /*        - XeSymbol->name = strdup("name"),                            */
 132 /*        - XeSymbol->value = NULL                                      */
 133 /*     2) If a "init_fn" is configured,                                 */
 134 /*        -  XeSymbol->value = init_fn( XeSymbol, 0 )                   */
 135 /*                                                                      */
 136 /*   Used for Xe_intern_anysym()                                        */
 137 /*                                                                      */
 138 /*     1) If "size" != 0,                                               */
 139 /*        - malloc "size" bytes,                                        */
 140 /*        - copy "size" bytes from "data" into malloced space,          */
 141 /*        - Save pointer to malloc space as user's data pointer         */
 142 /*        Else                                                          */
 143 /*        - Save "data" as pointer to user's data                       */
 144 /*     3) If a "init_fn" is configured,                                 */
 145 /*        - call init_fn( user's data pointer, "size" )                 */
 146 /*        - set user's data pointer to return value of init_fn          */
 147 /*          ONLY if "size" was zero.                                    */
 148 /*                                                                      */
 149 /*        If size is non zero AND there is a user's malloc function,    */
 150 /*        beware that the return value from the malloc function is not  */
 151 /*        save anywhere by these routines.  If size was zero, the       */
 152 /*        return value of the user's function is kept.                  */
 153 /*                                                                      */
 154 /* -------------------------------------------------------------------- */
 155
 156 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 157    typedef void * (*XeSymFn_init)(void *, unsigned int);
 158 #else
 159    typedef void * (*XeSymFn_init)();
 160 #endif
 161
 162 /* CLEAN_FN:                                                            */
 163 /*                                                                      */
 164 /*   If created by Xe_intern() or XeRegisterSymbol()                    */
 165 /*                                                                      */
 166 /*     1) free(XeSymbol->name)                                          */
 167 /*     2) If a "clean_fn" is configured,                                */
 168 /*        - clean_fn(XeSymbol->value),                                  */
 169 /*        - the XeSymbol entry is deleted.                              */
 170 /*                                                                      */
 171 /*   If created by Xe_intern_anysym()                                   */
 172 /*                                                                      */
 173 /*     1) If a "clean_fn" is configured,                                        */
 174 /*        - init_fn( user's data pointer, "size" )                      */
 175 /*     2) If "size" != 0 during at creation time,                       */
 176 /*        - free( user's data pointer )                                 */
 177 /*                                                                      */
 178 /*     Take note of the what happens during creation with "size" is     */
 179 /*     non-zero and there is a user's malloc function.  The result of   */
 180 /*     the user's malloc function will be passed to this clean function */
 181 /*     only if "size" was zero at creation time.  Otherwise, the memory */
 182 /*     malloc'ed by this routine due to the non-zero size parameter is  */
 183 /*     what is passed to the user's clean function.                     */
 184 /* -------------------------------------------------------------------- */
 185
 186 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 187    typedef void (*XeSymFn_clean)  (void *);
 188 #else
 189    typedef void (*XeSymFn_clean)  ();
 190 #endif
 191
 192 /* This is what an internal symbol table entry looks like: */
 193 /* ------------------------------------------------------- */
 194 typedef struct _XeSymtabList {
 195     struct _XeSymtabList *rest;
 196     void                 *data;
 197     Boolean              data_is_XeSymbol;
 198     Boolean              data_is_malloc_mem;
 199 } *XeSymtabList;
 200
 201
 202 /* This is the master record for a symbol table */
 203 /* -------------------------------------------- */
 204
 205 typedef struct _XeSymTable
 206 {
 207     unsigned int   hashsize;    /* # of hash buckets.                   */
 208     XeSymtabList   *list;       /* Hash buckets.                        */
 209
 210     XeSymtabList   curr_list;   /* Used to dump/traver the table.       */
 211     unsigned int   curr_hash;
 212
 213     XeSymFn_cmp    cmp_fn;      /* Read above description with each     */
 214     XeSymFn_hash   hash_fn;     /* function typedef for more info.      */
 215     XeSymFn_init   init_fn;
 216     XeSymFn_clean  clean_fn;
 217 } *XeSymTable;
 218
 219
 220 /* Create a new hashtable. "hashsize must be power of 2 if using default */
 221 /* hash function (no checking is done to ensure this).                   */
 222 /* --------------------------------------------------------------------- */
 223 XeSymTable Xe_new_symtab
 224 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 225    (unsigned int hashsize);
 226 #else
 227    ();
 228 #endif
 229
 230
 231 /* Create the default symbol table.  If already created, just */
 232 /* return the symtable pointer.                               */
 233 /* ---------------------------------------------------------- */
 234 XeSymTable Xe_default_symtab
 235 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 236    (void);
 237 #else
 238    ();
 239 #endif
 240
 241
 242 /* Configure user defined function for use with symtab routines.   */
 243 /* NOTE: Be sure you understand the interaction of these functions */
 244 /*       Read the decriptions with each of the typdef's above.  A  */
 245 /*       null function pointer will overwrite any previously       */
 246 /*       installed value.                                          */
 247 /* --------------------------------------------------------------- */
 248 XeSymTable Xe_set_sym_fns
 249 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 250    (XeSymTable     t,
 251     XeSymFn_cmp    cmp_fn,
 252     XeSymFn_init   init_fn,
 253     XeSymFn_clean  clean_fn,
 254     XeSymFn_hash   hash_fn);
 255 #else
 256    ();
 257 #endif
 258
 259
 260 /* Find or create a symbol for "name".  Its "value" is set to NULL.  */
 261 /* None of the user defined init/cmp, etc functions are honored by   */
 262 /* this routine                                                      */
 263 /* WARNING: Read the notes for the function typedef's above.         */
 264 /* ----------------------------------------------------------------- */
 265 XeSymbol Xe_intern
 266 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 267    (XeSymTable t, ConstXeString const name);
 268 #else
 269    ();
 270 #endif
 271
 272
 273 /* Find the symbol for "name".  NULL is returned if not found.       */
 274 /* None of the user defined init/cmp, etc functions are honored by   */
 275 /* this routine                                                      */
 276 /* WARNING: Read the notes for the function typedef's above.         */
 277 /* ----------------------------------------------------------------- */
 278 XeSymbol Xe_lookup
 279 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 280    (XeSymTable t, ConstXeString const name);
 281 #else
 282    ();
 283 #endif
 284
 285
 286 /****************************************************************************/
 287 /*  LISTS                                                                   */
 288
 289 typedef struct _XeList {
 290    struct _XeList *rest;
 291    void           *data;
 292 } *XeList;
 293
 294 /* make a list from data and rest */
 295 /* ------------------------------ */
 296 XeList Xe_make_list
 297 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 298    (void *data, XeList rest);
 299 #else
 300    ();
 301 #endif
 302
 303
 304 /****************************************************************************/
 305 /* QUEUES                                                                   */
 306
 307 typedef struct _XeQueue {
 308   XeList head;
 309   XeList tail;
 310   void * null;
 311 } *XeQueue;
 312
 313 /* for static or auto struct queues */
 314 /* -------------------------------- */
 315 XeQueue Xe_init_queue
 316 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 317    (XeQueue q, void * nullval);
 318 #else
 319    ();
 320 #endif
 321
 322 XeQueue Xe_make_queue
 323 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 324    (void * nullval);
 325 #else
 326    ();
 327 #endif
 328
 329 void Xe_release_queue
 330 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 331    (XeQueue q);
 332 #else
 333    ();
 334 #endif
 335
 336 /* nullval returned if queue empty */
 337 /* ------------------------------- */
 338 void * Xe_pop_queue
 339 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 340    (XeQueue q);
 341 #else
 342    ();
 343 #endif
 344
 345 /* nullval returned if not found   */
 346 /* ------------------------------- */
 347 void * Xe_delete_queue_element
 348 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 349    (XeQueue q, void * val);
 350 #else
 351    ();
 352 #endif
 353
 354 void Xe_push_queue
 355 #if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
 356    (XeQueue q, void * val);
 357 #else
 358    ();
 359 #endif
 360
 361 /* user declares his own "type var" */
 362 /* -------------------------------- */
 363 #define Xe_for_queue(type,var,q)        \
 364         XeList q_next, q_list;          \
 365         for(q_list = q->head;           \
 366             q_list && (var = (type) q_list->data, q_next = q_list->rest , 1);\
 367             q_list = q_next)
 368
 369
 370 /*  PUT NOTHING AFTER THIS endif */
 371 #endif /* _Symbolic_h_ */
 372