PostgreSQL Source Code  git master
dshash.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * dshash.h
4  * Concurrent hash tables backed by dynamic shared memory areas.
5  *
6  * Portions Copyright (c) 1996-2022, 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. */
20 struct dshash_table;
21 typedef struct dshash_table dshash_table;
22 
23 /* A handle for a dshash_table which can be shared with other processes. */
25 
26 /* The type for hash values. */
28 
29 /* A function type for comparing keys. */
30 typedef 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. */
34 typedef 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  */
49 typedef 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 */
57 
58 /* Forward declaration of private types for use only by dshash.c. */
59 struct dshash_table_item;
61 
62 /*
63  * Sequential scan state. The detail is exposed to let users know the storage
64  * size but it should be considered as an opaque type by callers.
65  */
66 typedef struct dshash_seq_status
67 {
68  dshash_table *hash_table; /* dshash table working on */
69  int curbucket; /* bucket number we are at */
70  int nbuckets; /* total number of buckets in the dshash */
71  dshash_table_item *curitem; /* item we are currently at */
72  dsa_pointer pnextitem; /* dsa-pointer to the next item */
73  int curpartition; /* partition number we are at */
74  bool exclusive; /* locking mode */
76 
77 /* Creating, sharing and destroying from hash tables. */
78 extern dshash_table *dshash_create(dsa_area *area,
79  const dshash_parameters *params,
80  void *arg);
81 extern dshash_table *dshash_attach(dsa_area *area,
82  const dshash_parameters *params,
83  dshash_table_handle handle,
84  void *arg);
85 extern void dshash_detach(dshash_table *hash_table);
87 extern void dshash_destroy(dshash_table *hash_table);
88 
89 /* Finding, creating, deleting entries. */
90 extern void *dshash_find(dshash_table *hash_table,
91  const void *key, bool exclusive);
92 extern void *dshash_find_or_insert(dshash_table *hash_table,
93  const void *key, bool *found);
94 extern bool dshash_delete_key(dshash_table *hash_table, const void *key);
95 extern void dshash_delete_entry(dshash_table *hash_table, void *entry);
96 extern void dshash_release_lock(dshash_table *hash_table, void *entry);
97 
98 /* seq scan support */
99 extern void dshash_seq_init(dshash_seq_status *status, dshash_table *hash_table,
100  bool exclusive);
104 
105 /* Convenience hash and compare functions wrapping memcmp and tag_hash. */
106 extern int dshash_memcmp(const void *a, const void *b, size_t size, void *arg);
107 extern dshash_hash dshash_memhash(const void *v, size_t size, void *arg);
108 
109 /* Debugging support. */
110 extern void dshash_dump(dshash_table *hash_table);
111 
112 #endif /* DSHASH_H */
unsigned int uint32
Definition: c.h:452
uint64 dsa_pointer
Definition: dsa.h:62
bool dshash_delete_key(dshash_table *hash_table, const void *key)
Definition: dshash.c:510
void dshash_delete_entry(dshash_table *hash_table, void *entry)
Definition: dshash.c:548
void dshash_destroy(dshash_table *hash_table)
Definition: dshash.c:326
void dshash_release_lock(dshash_table *hash_table, void *entry)
Definition: dshash.c:569
void dshash_detach(dshash_table *hash_table)
Definition: dshash.c:310
void dshash_seq_init(dshash_seq_status *status, dshash_table *hash_table, bool exclusive)
Definition: dshash.c:612
void * dshash_find(dshash_table *hash_table, const void *key, bool exclusive)
Definition: dshash.c:393
dsa_pointer dshash_table_handle
Definition: dshash.h:24
dshash_table_handle dshash_get_hash_table_handle(dshash_table *hash_table)
Definition: dshash.c:370
void dshash_dump(dshash_table *hash_table)
Definition: dshash.c:759
int(* dshash_compare_function)(const void *a, const void *b, size_t size, void *arg)
Definition: dshash.h:30
struct dshash_parameters dshash_parameters
void dshash_seq_term(dshash_seq_status *status)
Definition: dshash.c:723
uint32 dshash_hash
Definition: dshash.h:27
struct dshash_seq_status dshash_seq_status
dshash_hash dshash_memhash(const void *v, size_t size, void *arg)
Definition: dshash.c:598
dshash_hash(* dshash_hash_function)(const void *v, size_t size, void *arg)
Definition: dshash.h:34
void * dshash_find_or_insert(dshash_table *hash_table, const void *key, bool *found)
Definition: dshash.c:438
dshash_table * dshash_attach(dsa_area *area, const dshash_parameters *params, dshash_table_handle handle, void *arg)
Definition: dshash.c:271
int dshash_memcmp(const void *a, const void *b, size_t size, void *arg)
Definition: dshash.c:589
dshash_table * dshash_create(dsa_area *area, const dshash_parameters *params, void *arg)
Definition: dshash.c:204
void * dshash_seq_next(dshash_seq_status *status)
Definition: dshash.c:631
void dshash_delete_current(dshash_seq_status *status)
Definition: dshash.c:736
int b
Definition: isn.c:70
int a
Definition: isn.c:69
void * arg
static void static void status(const char *fmt,...) pg_attribute_printf(1
Definition: pg_regress.c:229
Definition: dsa.c:355
dshash_hash_function hash_function
Definition: dshash.h:54
size_t key_size
Definition: dshash.h:51
dshash_compare_function compare_function
Definition: dshash.h:53
size_t entry_size
Definition: dshash.h:52
bool exclusive
Definition: dshash.h:74
dshash_table_item * curitem
Definition: dshash.h:71
dsa_pointer pnextitem
Definition: dshash.h:72
int curpartition
Definition: dshash.h:73
dshash_table * hash_table
Definition: dshash.h:68