/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef ISC_SYMTAB_H

[12] Fix | Delete

#define ISC_SYMTAB_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file isc/symtab.h

[19] Fix | Delete

* \brief Provides a simple memory-based symbol table.

[20] Fix | Delete

*

[21] Fix | Delete

* Keys are C strings, and key comparisons are case-insensitive. A type may

[22] Fix | Delete

* be specified when looking up, defining, or undefining. A type value of

[23] Fix | Delete

* 0 means "match any type"; any other value will only match the given

[24] Fix | Delete

* type.

[25] Fix | Delete

*

[26] Fix | Delete

* It's possible that a client will attempt to define a <key, type, value>

[27] Fix | Delete

* tuple when a tuple with the given key and type already exists in the table.

[28] Fix | Delete

* What to do in this case is specified by the client. Possible policies are:

[29] Fix | Delete

*

[30] Fix | Delete

*\li #isc_symexists_reject Disallow the define, returning #ISC_R_EXISTS

[31] Fix | Delete

*\li #isc_symexists_replace Replace the old value with the new. The

[32] Fix | Delete

* undefine action (if provided) will be called

[33] Fix | Delete

* with the old <key, type, value> tuple.

[34] Fix | Delete

*\li #isc_symexists_add Add the new tuple, leaving the old tuple in

[35] Fix | Delete

* the table. Subsequent lookups will retrieve

[36] Fix | Delete

* the most-recently-defined tuple.

[37] Fix | Delete

*

[38] Fix | Delete

* A lookup of a key using type 0 will return the most-recently defined

[39] Fix | Delete

* symbol with that key. An undefine of a key using type 0 will undefine the

[40] Fix | Delete

* most-recently defined symbol with that key. Trying to define a key with

[41] Fix | Delete

* type 0 is illegal.

[42] Fix | Delete

*

[43] Fix | Delete

* The symbol table library does not make a copy the key field, so the

[44] Fix | Delete

* caller must ensure that any key it passes to isc_symtab_define() will not

[45] Fix | Delete

* change until it calls isc_symtab_undefine() or isc_symtab_destroy().

[46] Fix | Delete

*

[47] Fix | Delete

* A user-specified action will be called (if provided) when a symbol is

[48] Fix | Delete

* undefined. It can be used to free memory associated with keys and/or

[49] Fix | Delete

* values.

[50] Fix | Delete

*

[51] Fix | Delete

* A symbol table is implemented as a hash table of lists; the size of the

[52] Fix | Delete

* hash table is set by the 'size' parameter to isc_symtbl_create(). When

[53] Fix | Delete

* the number of entries in the symbol table reaches three quarters of this

[54] Fix | Delete

* value, the hash table is reallocated with size doubled, in order to

[55] Fix | Delete

* optimize lookup performance. This has a negative effect on insertion

[56] Fix | Delete

* performance, which can be mitigated by sizing the table appropriately

[57] Fix | Delete

* when creating it.

[58] Fix | Delete

*

[59] Fix | Delete

* \li MP:

[60] Fix | Delete

* The callers of this module must ensure any required synchronization.

[61] Fix | Delete

*

[62] Fix | Delete

* \li Reliability:

[63] Fix | Delete

* No anticipated impact.

[64] Fix | Delete

*

[65] Fix | Delete

* \li Resources:

[66] Fix | Delete

* TBS

[67] Fix | Delete

*

[68] Fix | Delete

* \li Security:

[69] Fix | Delete

* No anticipated impact.

[70] Fix | Delete

*

[71] Fix | Delete

* \li Standards:

[72] Fix | Delete

* None.

[73] Fix | Delete

*/

[74] Fix | Delete

[75] Fix | Delete

/***

[76] Fix | Delete

*** Imports.

[77] Fix | Delete

***/

[78] Fix | Delete

[79] Fix | Delete

#include <stdbool.h>

[80] Fix | Delete

[81] Fix | Delete

#include <isc/lang.h>

[82] Fix | Delete

#include <isc/types.h>

[83] Fix | Delete

[84] Fix | Delete

/*

[85] Fix | Delete

*** Symbol Tables.

[86] Fix | Delete

***/

[87] Fix | Delete

/*% Symbol table value. */

[88] Fix | Delete

typedef union isc_symvalue {

[89] Fix | Delete

void * as_pointer;

[90] Fix | Delete

const void * as_cpointer;

[91] Fix | Delete

int as_integer;

[92] Fix | Delete

unsigned int as_uinteger;

[93] Fix | Delete

} isc_symvalue_t;

[94] Fix | Delete

[95] Fix | Delete

typedef void (*isc_symtabaction_t)(char *key, unsigned int type,

[96] Fix | Delete

isc_symvalue_t value, void *userarg);

[97] Fix | Delete

/*% Symbol table exists. */

[98] Fix | Delete

typedef enum {

[99] Fix | Delete

isc_symexists_reject = 0, /*%< Disallow the define */

[100] Fix | Delete

isc_symexists_replace = 1, /*%< Replace the old value with the new */

[101] Fix | Delete

isc_symexists_add = 2 /*%< Add the new tuple */

[102] Fix | Delete

} isc_symexists_t;

[103] Fix | Delete

[104] Fix | Delete

ISC_LANG_BEGINDECLS

[105] Fix | Delete

[106] Fix | Delete

/*% Create a symbol table. */

[107] Fix | Delete

isc_result_t

[108] Fix | Delete

isc_symtab_create(isc_mem_t *mctx, unsigned int size,

[109] Fix | Delete

isc_symtabaction_t undefine_action, void *undefine_arg,

[110] Fix | Delete

bool case_sensitive, isc_symtab_t **symtabp);

[111] Fix | Delete

[112] Fix | Delete

/*% Destroy a symbol table. */

[113] Fix | Delete

void

[114] Fix | Delete

isc_symtab_destroy(isc_symtab_t **symtabp);

[115] Fix | Delete

[116] Fix | Delete

/*% Lookup a symbol table. */

[117] Fix | Delete

isc_result_t

[118] Fix | Delete

isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type,

[119] Fix | Delete

isc_symvalue_t *value);

[120] Fix | Delete

[121] Fix | Delete

/*% Define a symbol table. */

[122] Fix | Delete

isc_result_t

[123] Fix | Delete

isc_symtab_define(isc_symtab_t *symtab, const char *key, unsigned int type,

[124] Fix | Delete

isc_symvalue_t value, isc_symexists_t exists_policy);

[125] Fix | Delete

[126] Fix | Delete

/*% Undefine a symbol table. */

[127] Fix | Delete

isc_result_t

[128] Fix | Delete

isc_symtab_undefine(isc_symtab_t *symtab, const char *key, unsigned int type);

[129] Fix | Delete

[130] Fix | Delete

/*% Return the number of items in a symbol table. */

[131] Fix | Delete

unsigned int

[132] Fix | Delete

isc_symtab_count(isc_symtab_t *symtab);

[133] Fix | Delete

ISC_LANG_ENDDECLS

[134] Fix | Delete

[135] Fix | Delete

#endif /* ISC_SYMTAB_H */

[136] Fix | Delete

[137] Fix | Delete