src/include/lib/dshash.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * dshash.h
   4  *        Concurrent hash tables backed by dynamic shared memory areas.
   5  *
   6  * Portions Copyright (c) 1996-2021, 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. */
  24 typedef dsa_pointer dshash_table_handle;
  25
  26 /* The type for hash values. */
  27 typedef uint32 dshash_hash;
  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 */
  56 } dshash_parameters;
  57
  58 /* Forward declaration of private types for use only by dshash.c. */
  59 struct dshash_table_item;
  60 typedef struct dshash_table_item dshash_table_item;
  61
  62 /* Creating, sharing and destroying from hash tables. */
  63 extern dshash_table *dshash_create(dsa_area *area,
  64                                                                    const dshash_parameters *params,
  65                                                                    void *arg);
  66 extern dshash_table *dshash_attach(dsa_area *area,
  67                                                                    const dshash_parameters *params,
  68                                                                    dshash_table_handle handle,
  69                                                                    void *arg);
  70 extern void dshash_detach(dshash_table *hash_table);
  71 extern dshash_table_handle dshash_get_hash_table_handle(dshash_table *hash_table);
  72 extern void dshash_destroy(dshash_table *hash_table);
  73
  74 /* Finding, creating, deleting entries. */
  75 extern void *dshash_find(dshash_table *hash_table,
  76                                                  const void *key, bool exclusive);
  77 extern void *dshash_find_or_insert(dshash_table *hash_table,
  78                                                                    const void *key, bool *found);
  79 extern bool dshash_delete_key(dshash_table *hash_table, const void *key);
  80 extern void dshash_delete_entry(dshash_table *hash_table, void *entry);
  81 extern void dshash_release_lock(dshash_table *hash_table, void *entry);
  82
  83 /* Convenience hash and compare functions wrapping memcmp and tag_hash. */
  84 extern int      dshash_memcmp(const void *a, const void *b, size_t size, void *arg);
  85 extern dshash_hash dshash_memhash(const void *v, size_t size, void *arg);
  86
  87 /* Debugging support. */
  88 extern void dshash_dump(dshash_table *hash_table);
  89
  90 #endif                                                  /* DSHASH_H */