1/*-------------------------------------------------------------------------
2 *
3 * dshash.h
4 * Concurrent hash tables backed by dynamic shared memory areas.
5 *
6 * Portions Copyright (c) 1996-2019, PostgreSQL Global Development Group
7 * Portions Copyright (c) 1994, Regents of the University of California
8 *
9 * IDENTIFICATION
10 * src/include/lib/dshash.h
11 *
12 *-------------------------------------------------------------------------
13 */
14#ifndef DSHASH_H
15#define DSHASH_H
16
17#include "utils/dsa.h"
18
19/* The opaque type representing a hash table. */
20struct dshash_table;
21typedef struct dshash_table dshash_table;
22
23/* A handle for a dshash_table which can be shared with other processes. */
24typedef dsa_pointer dshash_table_handle;
25
26/* The type for hash values. */
27typedef uint32 dshash_hash;
28
29/* A function type for comparing keys. */
30typedef int (*dshash_compare_function) (const void *a, const void *b,
31 size_t size, void *arg);
32
33/* A function type for computing hash values for keys. */
34typedef dshash_hash (*dshash_hash_function) (const void *v, size_t size,
35 void *arg);
36
37/*
38 * The set of parameters needed to create or attach to a hash table. The
39 * members tranche_id and tranche_name do not need to be initialized when
40 * attaching to an existing hash table.
41 *
42 * Compare and hash functions must be supplied even when attaching, because we
43 * can't safely share function pointers between backends in general. Either
44 * the arg variants or the non-arg variants should be supplied; the other
45 * function pointers should be NULL. If the arg variants are supplied then the
46 * user data pointer supplied to the create and attach functions will be
47 * passed to the hash and compare functions.
48 */
49typedef struct dshash_parameters
50{
51 size_t key_size; /* Size of the key (initial bytes of entry) */
52 size_t entry_size; /* Total size of entry */
53 dshash_compare_function compare_function; /* Compare function */
54 dshash_hash_function hash_function; /* Hash function */
55 int tranche_id; /* The tranche ID to use for locks */
56} dshash_parameters;
57
58/* Forward declaration of private types for use only by dshash.c. */
59struct dshash_table_item;
60typedef struct dshash_table_item dshash_table_item;
61
62/* Creating, sharing and destroying from hash tables. */
63extern dshash_table *dshash_create(dsa_area *area,
64 const dshash_parameters *params,
65 void *arg);
66extern dshash_table *dshash_attach(dsa_area *area,
67 const dshash_parameters *params,
68 dshash_table_handle handle,
69 void *arg);
70extern void dshash_detach(dshash_table *hash_table);
71extern dshash_table_handle dshash_get_hash_table_handle(dshash_table *hash_table);
72extern void dshash_destroy(dshash_table *hash_table);
73
74/* Finding, creating, deleting entries. */
75extern void *dshash_find(dshash_table *hash_table,
76 const void *key, bool exclusive);
77extern void *dshash_find_or_insert(dshash_table *hash_table,
78 const void *key, bool *found);
79extern bool dshash_delete_key(dshash_table *hash_table, const void *key);
80extern void dshash_delete_entry(dshash_table *hash_table, void *entry);
81extern void dshash_release_lock(dshash_table *hash_table, void *entry);
82
83/* Convenience hash and compare functions wrapping memcmp and tag_hash. */
84extern int dshash_memcmp(const void *a, const void *b, size_t size, void *arg);
85extern dshash_hash dshash_memhash(const void *v, size_t size, void *arg);
86
87/* Debugging support. */
88extern void dshash_dump(dshash_table *hash_table);
89
90#endif /* DSHASH_H */
91