ctdb/common/db_hash.h

   1 /*
   2    Using tdb as a hash table
   3
   4    Copyright (C) Amitay Isaacs  2015
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef __CTDB_DB_HASH_H__
  21 #define __CTDB_DB_HASH_H__
  22
  23 #include <talloc.h>
  24 #include <tdb.h>
  25
  26 /**
  27  * @file db_hash.h
  28  *
  29  * @brief Use tdb database as a hash table
  30  *
  31  * This uses in-memory tdb databases to create a fixed sized hash table.
  32  */
  33
  34 /**
  35  * @brief Hash type to indicate the hashing function to use.
  36  *
  37  * DB_HASH_SIMPLE uses default hashing function
  38  * DB_HASH_COMPLEX uses jenkins hashing function
  39  */
  40 enum db_hash_type {
  41         DB_HASH_SIMPLE,
  42         DB_HASH_COMPLEX,
  43 };
  44
  45 /**
  46  * @brief Parser callback function called when fetching a record
  47  *
  48  * This function is called when fetching a record. This function should
  49  * not modify key and data arguments.
  50  *
  51  * The function should return 0 on success and errno on error.
  52  */
  53 typedef int (*db_hash_record_parser_fn)(uint8_t *keybuf, size_t keylen,
  54                                         uint8_t *databuf, size_t datalen,
  55                                         void *private_data);
  56
  57 /**
  58  * @brief Abstract structure representing tdb hash table
  59  */
  60 struct db_hash_context;
  61
  62 /**
  63  * @brief Initialize tdb hash table
  64  *
  65  * This returns a new tdb hash table context which is a talloc context.  Freeing
  66  * this context will free all the memory associated with the hash table.
  67  *
  68  * @param[in] mem_ctx Talloc memory context
  69  * @param[in] name The name for the hash table
  70  * @param[in] hash_size The size of the hash table
  71  * @param[in] type The type of hashing function to use
  72  * @param[out] result The new db_hash_context structure
  73  * @return 0 on success, errno on failure
  74  */
  75 int db_hash_init(TALLOC_CTX *mem_ctx, const char *name, int hash_size,
  76                  enum db_hash_type type, struct db_hash_context **result);
  77
  78 /**
  79  * @brief Insert a record into the hash table
  80  *
  81  * The key and data can be any binary data.  Insert only if the record does not
  82  * exist.  If the record already exists, return error.
  83  *
  84  * @param[in] dh The tdb hash table context
  85  * @param[in] keybuf The key buffer
  86  * @param[in] keylen The key length
  87  * @param[in] databuf The data buffer
  88  * @param[in] datalen The data length
  89  * @return 0 on success, errno on failure
  90  */
  91 int db_hash_insert(struct db_hash_context *dh, uint8_t *keybuf, size_t keylen,
  92                    uint8_t *databuf, size_t datalen);
  93
  94 /**
  95  * @brief Add a record into the hash table
  96  *
  97  * The key and data can be any binary data.  If the record does not exist,
  98  * insert the record.  If the record already exists, replace the record.
  99  *
 100  * @param[in] dh The tdb hash table context
 101  * @param[in] keybuf The key buffer
 102  * @param[in] keylen The key length
 103  * @param[in] databuf The data buffer
 104  * @param[in] datalen The data length
 105  * @return 0 on success, errno on failure
 106  */
 107 int db_hash_add(struct db_hash_context *dh, uint8_t *keybuf, size_t keylen,
 108                 uint8_t *databuf, size_t datalen);
 109 /**
 110  * @brief Delete a record from the hash table
 111  *
 112  * @param[in] dh The tdb hash table context
 113  * @param[in] keybuf The key buffer
 114  * @param[in] keylen The key length
 115  * @return 0 on success, errno on failure
 116  */
 117 int db_hash_delete(struct db_hash_context *dh, uint8_t *keybuf, size_t keylen);
 118
 119 /**
 120  * @brief Fetch a record from the hash table
 121  *
 122  * The key and data can be any binary data.
 123  *
 124  * @param[in] dh The tdb hash table context
 125  * @param[in] keybuf The key buffer
 126  * @param[in] keylen The key length
 127  * @param[in] parser Function called when the matching record is found
 128  * @param[in] private_data Private data to parser function
 129  * @return 0 on success, errno on failure
 130  */
 131 int db_hash_fetch(struct db_hash_context *dh, uint8_t *keybuf, size_t keylen,
 132                   db_hash_record_parser_fn parser, void *private_data);
 133
 134 /**
 135  * @brief Check if a record exists in the hash table
 136  *
 137  * @param[in] dh The tdb hash table context
 138  * @param[in] keybuf The key buffer
 139  * @param[in] keylen The key length
 140  * @return 0 if the record exists, errno on failure
 141  */
 142 int db_hash_exists(struct db_hash_context *dh, uint8_t *keybuf, size_t keylen);
 143
 144 /**
 145  * @brief Traverse the database without modification
 146  *
 147  * The parser function should return non-zero value to stop traverse.
 148  *
 149  * @param[in] dh The tdb hash table context
 150  * @param[in] parser Function called for each record
 151  * @param[in] private_data Private data to parser function
 152  * @param[out] count Number of records traversed
 153  * @return 0 on success, errno on failure
 154  */
 155 int db_hash_traverse(struct db_hash_context *dh,
 156                      db_hash_record_parser_fn parser, void *private_data,
 157                      int *count);
 158
 159 /**
 160  * @brief Traverse the database for modifications
 161  *
 162  * The parser function should return non-zero value to stop traverse.
 163  *
 164  * @param[in] dh The tdb hash table context
 165  * @param[in] parser Function called for each record
 166  * @param[in] private_data Private data to parser function
 167  * @param[out] count Number of records traversed
 168  * @return 0 on success, errno on failure
 169  */
 170 int db_hash_traverse_update(struct db_hash_context *dh,
 171                             db_hash_record_parser_fn parser,
 172                             void *private_data, int *count);
 173
 174 #endif /* __CTDB_DB_HASH_H__ */