symtab.h revision 290001 
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. */
95typedef 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
102typedef void (*isc_symtabaction_t)(char *key, unsigned int type,
103				   isc_symvalue_t value, void *userarg);
104/*% Symbol table exists. */
105typedef 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
111ISC_LANG_BEGINDECLS
112
113/*% Create a symbol table. */
114isc_result_t
115isc_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. */
120void
121isc_symtab_destroy(isc_symtab_t **symtabp);
122
123/*% Lookup a symbol table. */
124isc_result_t
125isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type,
126		  isc_symvalue_t *value);
127
128/*% Define a symbol table. */
129isc_result_t
130isc_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. */
134isc_result_t
135isc_symtab_undefine(isc_symtab_t *symtab, const char *key, unsigned int type);
136
137ISC_LANG_ENDDECLS
138
139#endif /* ISC_SYMTAB_H */
140