contrib/bind9/lib/isc/include/isc/symtab.h

   1 /*
   2  * Copyright (C) 2004-2007, 2009, 2011, 2012  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1996-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id$ */
  19
  20 #ifndef ISC_SYMTAB_H
  21 #define ISC_SYMTAB_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file isc/symtab.h
  28  * \brief Provides a simple memory-based symbol table.
  29  *
  30  * Keys are C strings, and key comparisons are case-insensitive.  A type may
  31  * be specified when looking up, defining, or undefining.  A type value of
  32  * 0 means "match any type"; any other value will only match the given
  33  * type.
  34  *
  35  * It's possible that a client will attempt to define a <key, type, value>
  36  * tuple when a tuple with the given key and type already exists in the table.
  37  * What to do in this case is specified by the client.  Possible policies are:
  38  *
  39  *\li   #isc_symexists_reject   Disallow the define, returning #ISC_R_EXISTS
  40  *\li   #isc_symexists_replace  Replace the old value with the new.  The
  41  *                              undefine action (if provided) will be called
  42  *                              with the old <key, type, value> tuple.
  43  *\li   #isc_symexists_add      Add the new tuple, leaving the old tuple in
  44  *                              the table.  Subsequent lookups will retrieve
  45  *                              the most-recently-defined tuple.
  46  *
  47  * A lookup of a key using type 0 will return the most-recently defined
  48  * symbol with that key.  An undefine of a key using type 0 will undefine the
  49  * most-recently defined symbol with that key.  Trying to define a key with
  50  * type 0 is illegal.
  51  *
  52  * The symbol table library does not make a copy the key field, so the
  53  * caller must ensure that any key it passes to isc_symtab_define() will not
  54  * change until it calls isc_symtab_undefine() or isc_symtab_destroy().
  55  *
  56  * A user-specified action will be called (if provided) when a symbol is
  57  * undefined.  It can be used to free memory associated with keys and/or
  58  * values.
  59  *
  60  * A symbol table is implemented as a hash table of lists; the size of the
  61  * hash table is set by the 'size' parameter to isc_symtbl_create().  When
  62  * the number of entries in the symbol table reaches three quarters of this
  63  * value, the hash table is reallocated with size doubled, in order to
  64  * optimize lookup performance.  This has a negative effect on insertion
  65  * performance, which can be mitigated by sizing the table appropriately
  66  * when creating it.
  67  *
  68  * \li MP:
  69  *      The callers of this module must ensure any required synchronization.
  70  *
  71  * \li Reliability:
  72  *      No anticipated impact.
  73  *
  74  * \li Resources:
  75  *      TBS
  76  *
  77  * \li Security:
  78  *      No anticipated impact.
  79  *
  80  * \li Standards:
  81  *      None.
  82  */
  83
  84 /***
  85  *** Imports.
  86  ***/
  87
  88 #include <isc/lang.h>
  89 #include <isc/types.h>
  90
  91 /*
  92  *** Symbol Tables.
  93  ***/
  94 /*% Symbol table value. */
  95 typedef union isc_symvalue {
  96         void *                          as_pointer;
  97         const void *                    as_cpointer;
  98         int                             as_integer;
  99         unsigned int                    as_uinteger;
 100 } isc_symvalue_t;
 101
 102 typedef void (*isc_symtabaction_t)(char *key, unsigned int type,
 103                                    isc_symvalue_t value, void *userarg);
 104 /*% Symbol table exists. */
 105 typedef enum {
 106         isc_symexists_reject = 0,       /*%< Disallow the define */
 107         isc_symexists_replace = 1,      /*%< Replace the old value with the new */
 108         isc_symexists_add = 2           /*%< Add the new tuple */
 109 } isc_symexists_t;
 110
 111 ISC_LANG_BEGINDECLS
 112
 113 /*% Create a symbol table. */
 114 isc_result_t
 115 isc_symtab_create(isc_mem_t *mctx, unsigned int size,
 116                   isc_symtabaction_t undefine_action, void *undefine_arg,
 117                   isc_boolean_t case_sensitive, isc_symtab_t **symtabp);
 118
 119 /*% Destroy a symbol table. */
 120 void
 121 isc_symtab_destroy(isc_symtab_t **symtabp);
 122
 123 /*% Lookup a symbol table. */
 124 isc_result_t
 125 isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type,
 126                   isc_symvalue_t *value);
 127
 128 /*% Define a symbol table. */
 129 isc_result_t
 130 isc_symtab_define(isc_symtab_t *symtab, const char *key, unsigned int type,
 131                   isc_symvalue_t value, isc_symexists_t exists_policy);
 132
 133 /*% Undefine a symbol table. */
 134 isc_result_t
 135 isc_symtab_undefine(isc_symtab_t *symtab, const char *key, unsigned int type);
 136
 137 ISC_LANG_ENDDECLS
 138
 139 #endif /* ISC_SYMTAB_H */