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-2019, 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 */
28typedef struct shm_toc shm_toc;
29
30extern shm_toc *shm_toc_create(uint64 magic, void *address, Size nbytes);
31extern shm_toc *shm_toc_attach(uint64 magic, void *address);
32extern void *shm_toc_allocate(shm_toc *toc, Size nbytes);
33extern Size shm_toc_freespace(shm_toc *toc);
34extern void shm_toc_insert(shm_toc *toc, uint64 key, void *address);
35extern 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 */
43typedef 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
56extern Size shm_toc_estimate(shm_toc_estimator *e);
57
58#endif /* SHM_TOC_H */
59