src/include/storage/shm_toc.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * shm_toc.h
   4  *        shared memory segment table of contents
   5  *
   6  * This is intended to provide a simple way to divide a chunk of shared
   7  * memory (probably dynamic shared memory allocated via dsm_create) into
   8  * a number of regions and keep track of the addresses of those regions or
   9  * key data structures within those regions.  This is not intended to
  10  * scale to a large number of keys and will perform poorly if used that
  11  * way; if you need a large number of pointers, store them within some
  12  * other data structure within the segment and only put the pointer to
  13  * the data structure itself in the table of contents.
  14  *
  15  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
  16  * Portions Copyright (c) 1994, Regents of the University of California
  17  *
  18  * src/include/storage/shm_toc.h
  19  *
  20  *-------------------------------------------------------------------------
  21  */
  22 #ifndef SHM_TOC_H
  23 #define SHM_TOC_H
  24
  25 #include "storage/shmem.h"              /* for add_size() */
  26
  27 /* shm_toc is an opaque type known only within shm_toc.c */
  28 typedef struct shm_toc shm_toc;
  29
  30 extern shm_toc *shm_toc_create(uint64 magic, void *address, Size nbytes);
  31 extern shm_toc *shm_toc_attach(uint64 magic, void *address);
  32 extern void *shm_toc_allocate(shm_toc *toc, Size nbytes);
  33 extern Size shm_toc_freespace(shm_toc *toc);
  34 extern void shm_toc_insert(shm_toc *toc, uint64 key, void *address);
  35 extern void *shm_toc_lookup(shm_toc *toc, uint64 key, bool noError);
  36
  37 /*
  38  * Tools for estimating how large a chunk of shared memory will be needed
  39  * to store a TOC and its dependent objects.  Note: we don't really support
  40  * large numbers of keys, but it's convenient to declare number_of_keys
  41  * as a Size anyway.
  42  */
  43 typedef struct
  44 {
  45         Size            space_for_chunks;
  46         Size            number_of_keys;
  47 } shm_toc_estimator;
  48
  49 #define shm_toc_initialize_estimator(e) \
  50         ((e)->space_for_chunks = 0, (e)->number_of_keys = 0)
  51 #define shm_toc_estimate_chunk(e, sz) \
  52         ((e)->space_for_chunks = add_size((e)->space_for_chunks, BUFFERALIGN(sz)))
  53 #define shm_toc_estimate_keys(e, cnt) \
  54         ((e)->number_of_keys = add_size((e)->number_of_keys, cnt))
  55
  56 extern Size shm_toc_estimate(shm_toc_estimator *e);
  57
  58 #endif                                                  /* SHM_TOC_H */