1*c0b5d9fbSchristos /* $NetBSD: ht.h,v 1.6 2022/09/23 12:15:33 christos Exp $ */ 2e2b1b9c0Schristos 3e2b1b9c0Schristos /* 4e2b1b9c0Schristos * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5e2b1b9c0Schristos * 6*c0b5d9fbSchristos * SPDX-License-Identifier: MPL-2.0 7*c0b5d9fbSchristos * 8e2b1b9c0Schristos * This Source Code Form is subject to the terms of the Mozilla Public 9e2b1b9c0Schristos * License, v. 2.0. If a copy of the MPL was not distributed with this 1073584a28Schristos * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11e2b1b9c0Schristos * 12e2b1b9c0Schristos * See the COPYRIGHT file distributed with this work for additional 13e2b1b9c0Schristos * information regarding copyright ownership. 14e2b1b9c0Schristos */ 15e2b1b9c0Schristos 16e2b1b9c0Schristos /* ! \file */ 17e2b1b9c0Schristos 18e2b1b9c0Schristos #ifndef ISC_HT_H 19e2b1b9c0Schristos #define ISC_HT_H 1 20e2b1b9c0Schristos 21f2e20987Schristos #include <inttypes.h> 22e2b1b9c0Schristos #include <string.h> 23f2e20987Schristos 24e2b1b9c0Schristos #include <isc/result.h> 259742fdb4Schristos #include <isc/types.h> 26e2b1b9c0Schristos 27e2b1b9c0Schristos typedef struct isc_ht isc_ht_t; 28e2b1b9c0Schristos typedef struct isc_ht_iter isc_ht_iter_t; 29e2b1b9c0Schristos 30e2b1b9c0Schristos /*% 31e2b1b9c0Schristos * Initialize hashtable at *htp, using memory context and size of (1<<bits) 32e2b1b9c0Schristos * 33e2b1b9c0Schristos * Requires: 34f2e20987Schristos *\li 'htp' is not NULL and '*htp' is NULL. 35f2e20987Schristos *\li 'mctx' is a valid memory context. 36f2e20987Schristos *\li 'bits' >=1 and 'bits' <=32 37e2b1b9c0Schristos * 38e2b1b9c0Schristos */ 39*c0b5d9fbSchristos void 40f2e20987Schristos isc_ht_init(isc_ht_t **htp, isc_mem_t *mctx, uint8_t bits); 41e2b1b9c0Schristos 42e2b1b9c0Schristos /*% 43e2b1b9c0Schristos * Destroy hashtable, freeing everything 44e2b1b9c0Schristos * 45e2b1b9c0Schristos * Requires: 46f2e20987Schristos * \li '*htp' is valid hashtable 47e2b1b9c0Schristos */ 48e2b1b9c0Schristos void 49e2b1b9c0Schristos isc_ht_destroy(isc_ht_t **htp); 50e2b1b9c0Schristos 51e2b1b9c0Schristos /*% 52e2b1b9c0Schristos * Add a node to hashtable, pointed by binary key 'key' of size 'keysize'; 53e2b1b9c0Schristos * set its value to 'value' 54e2b1b9c0Schristos * 55e2b1b9c0Schristos * Requires: 56f2e20987Schristos *\li 'ht' is a valid hashtable 57e2b1b9c0Schristos * 58e2b1b9c0Schristos * Returns: 59e2b1b9c0Schristos *\li #ISC_R_NOMEMORY -- not enough memory to create pool 60e2b1b9c0Schristos *\li #ISC_R_EXISTS -- node of the same key already exists 61e2b1b9c0Schristos *\li #ISC_R_SUCCESS -- all is well. 62e2b1b9c0Schristos */ 63e2b1b9c0Schristos isc_result_t 64f2e20987Schristos isc_ht_add(isc_ht_t *ht, const unsigned char *key, uint32_t keysize, 65e2b1b9c0Schristos void *value); 66e2b1b9c0Schristos 67e2b1b9c0Schristos /*% 68e2b1b9c0Schristos * Find a node matching 'key'/'keysize' in hashtable 'ht'; 69e2b1b9c0Schristos * if found, set '*valuep' to its value. (If 'valuep' is NULL, 70e2b1b9c0Schristos * then simply return SUCCESS or NOTFOUND to indicate whether the 71e2b1b9c0Schristos * key exists in the hashtable.) 72e2b1b9c0Schristos * 73e2b1b9c0Schristos * Requires: 74e2b1b9c0Schristos * \li 'ht' is a valid hashtable 75e2b1b9c0Schristos * 76e2b1b9c0Schristos * Returns: 77e2b1b9c0Schristos * \li #ISC_R_SUCCESS -- success 78e2b1b9c0Schristos * \li #ISC_R_NOTFOUND -- key not found 79e2b1b9c0Schristos */ 80e2b1b9c0Schristos isc_result_t 819742fdb4Schristos isc_ht_find(const isc_ht_t *ht, const unsigned char *key, uint32_t keysize, 829742fdb4Schristos void **valuep); 83e2b1b9c0Schristos 84e2b1b9c0Schristos /*% 85e2b1b9c0Schristos * Delete node from hashtable 86f2e20987Schristos * 87e2b1b9c0Schristos * Requires: 88e2b1b9c0Schristos *\li ht is a valid hashtable 89e2b1b9c0Schristos * 90e2b1b9c0Schristos * Returns: 91e2b1b9c0Schristos *\li #ISC_R_NOTFOUND -- key not found 92e2b1b9c0Schristos *\li #ISC_R_SUCCESS -- all is well 93e2b1b9c0Schristos */ 94e2b1b9c0Schristos isc_result_t 95f2e20987Schristos isc_ht_delete(isc_ht_t *ht, const unsigned char *key, uint32_t keysize); 96e2b1b9c0Schristos 97e2b1b9c0Schristos /*% 98e2b1b9c0Schristos * Create an iterator for the hashtable; point '*itp' to it. 99f2e20987Schristos * 100f2e20987Schristos * Requires: 101f2e20987Schristos *\li 'ht' is a valid hashtable 102f2e20987Schristos *\li 'itp' is non NULL and '*itp' is NULL. 103e2b1b9c0Schristos */ 104*c0b5d9fbSchristos void 105e2b1b9c0Schristos isc_ht_iter_create(isc_ht_t *ht, isc_ht_iter_t **itp); 106e2b1b9c0Schristos 107e2b1b9c0Schristos /*% 108e2b1b9c0Schristos * Destroy the iterator '*itp', set it to NULL 109f2e20987Schristos * 110f2e20987Schristos * Requires: 111f2e20987Schristos *\li 'itp' is non NULL and '*itp' is non NULL. 112e2b1b9c0Schristos */ 113e2b1b9c0Schristos void 114e2b1b9c0Schristos isc_ht_iter_destroy(isc_ht_iter_t **itp); 115e2b1b9c0Schristos 116e2b1b9c0Schristos /*% 117e2b1b9c0Schristos * Set an iterator to the first entry. 118e2b1b9c0Schristos * 119f2e20987Schristos * Requires: 120f2e20987Schristos *\li 'it' is non NULL. 121f2e20987Schristos * 122e2b1b9c0Schristos * Returns: 123e2b1b9c0Schristos * \li #ISC_R_SUCCESS -- success 124e2b1b9c0Schristos * \li #ISC_R_NOMORE -- no data in the hashtable 125e2b1b9c0Schristos */ 126e2b1b9c0Schristos isc_result_t 127e2b1b9c0Schristos isc_ht_iter_first(isc_ht_iter_t *it); 128e2b1b9c0Schristos 129e2b1b9c0Schristos /*% 130e2b1b9c0Schristos * Set an iterator to the next entry. 131e2b1b9c0Schristos * 132f2e20987Schristos * Requires: 133f2e20987Schristos *\li 'it' is non NULL. 134f2e20987Schristos * 135e2b1b9c0Schristos * Returns: 136e2b1b9c0Schristos * \li #ISC_R_SUCCESS -- success 137e2b1b9c0Schristos * \li #ISC_R_NOMORE -- end of hashtable reached 138e2b1b9c0Schristos */ 139e2b1b9c0Schristos isc_result_t 140e2b1b9c0Schristos isc_ht_iter_next(isc_ht_iter_t *it); 141e2b1b9c0Schristos 142e2b1b9c0Schristos /*% 143e2b1b9c0Schristos * Delete current entry and set an iterator to the next entry. 144e2b1b9c0Schristos * 145f2e20987Schristos * Requires: 146f2e20987Schristos *\li 'it' is non NULL. 147f2e20987Schristos * 148e2b1b9c0Schristos * Returns: 149e2b1b9c0Schristos * \li #ISC_R_SUCCESS -- success 150e2b1b9c0Schristos * \li #ISC_R_NOMORE -- end of hashtable reached 151e2b1b9c0Schristos */ 152e2b1b9c0Schristos isc_result_t 153e2b1b9c0Schristos isc_ht_iter_delcurrent_next(isc_ht_iter_t *it); 154e2b1b9c0Schristos 155e2b1b9c0Schristos /*% 156e2b1b9c0Schristos * Set 'value' to the current value under the iterator 157f2e20987Schristos * 158f2e20987Schristos * Requires: 159f2e20987Schristos *\li 'it' is non NULL. 160f2e20987Schristos *\li 'valuep' is non NULL and '*valuep' is NULL. 161e2b1b9c0Schristos */ 162e2b1b9c0Schristos void 163e2b1b9c0Schristos isc_ht_iter_current(isc_ht_iter_t *it, void **valuep); 164e2b1b9c0Schristos 165e2b1b9c0Schristos /*% 166e2b1b9c0Schristos * Set 'key' and 'keysize to the current key and keysize for the value 167e2b1b9c0Schristos * under the iterator 168f2e20987Schristos * 169f2e20987Schristos * Requires: 170f2e20987Schristos *\li 'it' is non NULL. 171f2e20987Schristos *\li 'key' is non NULL and '*key' is NULL. 172f2e20987Schristos *\li 'keysize' is non NULL. 173e2b1b9c0Schristos */ 174e2b1b9c0Schristos void 175e2b1b9c0Schristos isc_ht_iter_currentkey(isc_ht_iter_t *it, unsigned char **key, size_t *keysize); 176e2b1b9c0Schristos 177e2b1b9c0Schristos /*% 178e2b1b9c0Schristos * Returns the number of items in the hashtable. 179e2b1b9c0Schristos * 180e2b1b9c0Schristos * Requires: 181e2b1b9c0Schristos *\li 'ht' is a valid hashtable 182e2b1b9c0Schristos */ 183e2b1b9c0Schristos unsigned int 184e2b1b9c0Schristos isc_ht_count(isc_ht_t *ht); 1859742fdb4Schristos #endif /* ifndef ISC_HT_H */ 186