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