1/*
2 * rchash.h
3 *
4 * Copyright (C) 2018 Aerospike, Inc.
5 *
6 * Portions may be licensed to Aerospike, Inc. under one or more contributor
7 * license agreements.
8 *
9 * This program is free software: you can redistribute it and/or modify it under
10 * the terms of the GNU Affero General Public License as published by the Free
11 * Software Foundation, either version 3 of the License, or (at your option) any
12 * later version.
13 *
14 * This program is distributed in the hope that it will be useful, but WITHOUT
15 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16 * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
17 * details.
18 *
19 * You should have received a copy of the GNU Affero General Public License
20 * along with this program. If not, see http://www.gnu.org/licenses/
21 */
22
23#pragma once
24
25//==========================================================
26// Includes.
27//
28
29#include <stdint.h>
30
31#include "cf_mutex.h"
32
33
34//==========================================================
35// Typedefs & constants.
36//
37
38// Return codes.
39#define CF_RCHASH_ERR_FOUND -4
40#define CF_RCHASH_ERR_NOT_FOUND -3
41#define CF_RCHASH_ERR -1
42#define CF_RCHASH_OK 0
43#define CF_RCHASH_REDUCE_DELETE 1
44
45// Bit-values for 'flags' parameter.
46#define CF_RCHASH_BIG_LOCK 0x01 // thread-safe with single big lock
47#define CF_RCHASH_MANY_LOCK 0x02 // thread-safe with lock per bucket
48
49// User must provide the hash function at create time.
50typedef uint32_t (*cf_rchash_hash_fn)(const void *key, uint32_t key_size);
51
52// The "reduce" function called for every element. Returned value governs
53// behavior during reduce as follows:
54// - CF_RCHASH_OK - continue iterating
55// - CF_RCHASH_REDUCE_DELETE - delete the current element, continue iterating
56// - anything else (e.g. CF_RCHASH_ERR) - stop iterating and return reduce_fn's
57// returned value
58typedef int (*cf_rchash_reduce_fn)(const void *key, uint32_t key_size, void *object, void *udata);
59
60// User may provide an object "destructor" at create time. The destructor is
61// called - and the deleted element's object freed - from cf_rchash_delete(),
62// cf_rchash_delete_object(), or cf_rchash_reduce(), if the ref-count hits 0.
63// The destructor should not free the object itself - that is always done after
64// releasing the object if its ref-count hits 0. The destructor should only
65// clean up the object's "internals".
66typedef void (*cf_rchash_destructor_fn)(void *object);
67
68// Private data.
69typedef struct cf_rchash_s {
70 cf_rchash_hash_fn h_fn;
71 cf_rchash_destructor_fn d_fn;
72 uint32_t key_size; // if key_size == 0, use variable size functions
73 uint32_t n_buckets;
74 uint32_t flags;
75 uint32_t n_elements;
76 void *table;
77 cf_mutex *bucket_locks;
78 cf_mutex big_lock;
79} cf_rchash;
80
81
82//==========================================================
83// Public API - useful hash functions.
84//
85
86uint32_t cf_rchash_fn_u32(const void *key, uint32_t key_size);
87uint32_t cf_rchash_fn_fnv32(const void *key, uint32_t key_size);
88uint32_t cf_rchash_fn_zstr(const void *key, uint32_t key_size);
89
90
91//==========================================================
92// Public API.
93//
94
95cf_rchash *cf_rchash_create(cf_rchash_hash_fn h_fn, cf_rchash_destructor_fn d_fn, uint32_t key_size, uint32_t n_buckets, uint32_t flags);
96void cf_rchash_destroy(cf_rchash *h);
97uint32_t cf_rchash_get_size(const cf_rchash *h);
98
99void cf_rchash_put(cf_rchash *h, const void *key, uint32_t key_size, void *object);
100int cf_rchash_put_unique(cf_rchash *h, const void *key, uint32_t key_size, void *object);
101
102int cf_rchash_get(cf_rchash *h, const void *key, uint32_t key_size, void **object_r);
103
104int cf_rchash_delete(cf_rchash *h, const void *key, uint32_t key_size);
105int cf_rchash_delete_object(cf_rchash *h, const void *key, uint32_t key_size, void *object);
106
107int cf_rchash_reduce(cf_rchash *h, cf_rchash_reduce_fn reduce_fn, void *udata);
108