symtab.h 4.22 KB
Newer Older
Bob Halley's avatar
Bob Halley committed
1
/*
2
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3
 *
4
5
6
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7
8
9
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
Bob Halley's avatar
Bob Halley committed
10
11
 */

David Lawrence's avatar
David Lawrence committed
12

13
14
#ifndef ISC_SYMTAB_H
#define ISC_SYMTAB_H 1
Bob Halley's avatar
Bob Halley committed
15

16
17
18
19
/*****
 ***** Module Info
 *****/

20
/*! \file isc/symtab.h
21
 * \brief Provides a simple memory-based symbol table.
22
 *
Francis Dupont's avatar
Francis Dupont committed
23
 * Keys are C strings, and key comparisons are case-insensitive.  A type may
24
25
26
27
28
29
30
31
 * be specified when looking up, defining, or undefining.  A type value of
 * 0 means "match any type"; any other value will only match the given
 * type.
 *
 * It's possible that a client will attempt to define a <key, type, value>
 * tuple when a tuple with the given key and type already exists in the table.
 * What to do in this case is specified by the client.  Possible policies are:
 *
32
33
 *\li	#isc_symexists_reject	Disallow the define, returning #ISC_R_EXISTS
 *\li	#isc_symexists_replace	Replace the old value with the new.  The
34
35
 *				undefine action (if provided) will be called
 *				with the old <key, type, value> tuple.
36
 *\li	#isc_symexists_add	Add the new tuple, leaving the old tuple in
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 *				the table.  Subsequent lookups will retrieve
 *				the most-recently-defined tuple.
 *
 * A lookup of a key using type 0 will return the most-recently defined
 * symbol with that key.  An undefine of a key using type 0 will undefine the
 * most-recently defined symbol with that key.  Trying to define a key with
 * type 0 is illegal.
 *
 * The symbol table library does not make a copy the key field, so the
 * caller must ensure that any key it passes to isc_symtab_define() will not
 * change until it calls isc_symtab_undefine() or isc_symtab_destroy().
 *
 * A user-specified action will be called (if provided) when a symbol is
 * undefined.  It can be used to free memory associated with keys and/or
 * values.
 *
53
54
55
56
57
58
59
60
 * A symbol table is implemented as a hash table of lists; the size of the
 * hash table is set by the 'size' parameter to isc_symtbl_create().  When
 * the number of entries in the symbol table reaches three quarters of this
 * value, the hash table is reallocated with size doubled, in order to
 * optimize lookup performance.  This has a negative effect on insertion
 * performance, which can be mitigated by sizing the table appropriately
 * when creating it.
 *
61
 * \li MP:
62
63
 *	The callers of this module must ensure any required synchronization.
 *
64
 * \li Reliability:
65
66
 *	No anticipated impact.
 *
67
68
 * \li Resources:
 *	TBS
69
 *
70
 * \li Security:
71
72
 *	No anticipated impact.
 *
73
 * \li Standards:
74
75
76
77
78
79
80
 *	None.
 */

/***
 *** Imports.
 ***/

81
82
#include <stdbool.h>

Bob Halley's avatar
Bob Halley committed
83
#include <isc/lang.h>
84
#include <isc/types.h>
Bob Halley's avatar
Bob Halley committed
85

86
/*
87
88
 *** Symbol Tables.
 ***/
89
/*% Symbol table value. */
Bob Halley's avatar
Bob Halley committed
90
91
typedef union isc_symvalue {
	void *				as_pointer;
92
	const void *			as_cpointer;
Bob Halley's avatar
Bob Halley committed
93
94
95
96
97
	int				as_integer;
	unsigned int			as_uinteger;
} isc_symvalue_t;

typedef void (*isc_symtabaction_t)(char *key, unsigned int type,
98
				   isc_symvalue_t value, void *userarg);
99
/*% Symbol table exists. */
100
typedef enum {
101
102
103
	isc_symexists_reject = 0,	/*%< Disallow the define */
	isc_symexists_replace = 1,	/*%< Replace the old value with the new */
	isc_symexists_add = 2		/*%< Add the new tuple */
104
105
} isc_symexists_t;

106
ISC_LANG_BEGINDECLS
Bob Halley's avatar
Bob Halley committed
107

108
/*% Create a symbol table. */
Bob Halley's avatar
Bob Halley committed
109
110
isc_result_t
isc_symtab_create(isc_mem_t *mctx, unsigned int size,
111
		  isc_symtabaction_t undefine_action, void *undefine_arg,
112
		  bool case_sensitive, isc_symtab_t **symtabp);
Bob Halley's avatar
Bob Halley committed
113

114
/*% Destroy a symbol table. */
Bob Halley's avatar
Bob Halley committed
115
116
117
void
isc_symtab_destroy(isc_symtab_t **symtabp);

118
/*% Lookup a symbol table. */
Bob Halley's avatar
Bob Halley committed
119
120
121
122
isc_result_t
isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type,
		  isc_symvalue_t *value);

123
/*% Define a symbol table. */
Bob Halley's avatar
Bob Halley committed
124
isc_result_t
David Lawrence's avatar
David Lawrence committed
125
isc_symtab_define(isc_symtab_t *symtab, const char *key, unsigned int type,
126
		  isc_symvalue_t value, isc_symexists_t exists_policy);
Bob Halley's avatar
Bob Halley committed
127

128
/*% Undefine a symbol table. */
Bob Halley's avatar
Bob Halley committed
129
isc_result_t
David Lawrence's avatar
David Lawrence committed
130
isc_symtab_undefine(isc_symtab_t *symtab, const char *key, unsigned int type);
Bob Halley's avatar
Bob Halley committed
131

Evan Hunt's avatar
Evan Hunt committed
132
133
134
/*% Return the number of items in a symbol table. */
unsigned int
isc_symtab_count(isc_symtab_t *symtab);
Bob Halley's avatar
Bob Halley committed
135
136
ISC_LANG_ENDDECLS

137
#endif /* ISC_SYMTAB_H */