PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
dsa.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * dsa.h
4  * Dynamic shared memory areas.
5  *
6  * Portions Copyright (c) 1996-2017, PostgreSQL Global Development Group
7  * Portions Copyright (c) 1994, Regents of the University of California
8  *
9  * IDENTIFICATION
10  * src/include/utils/dsa.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 #ifndef DSA_H
15 #define DSA_H
16 
17 #include "postgres.h"
18 
19 #include "port/atomics.h"
20 #include "storage/dsm.h"
21 
22 /* The opaque type used for an area. */
23 struct dsa_area;
24 typedef struct dsa_area dsa_area;
25 
26 /*
27  * If this system only uses a 32-bit value for Size, then use the 32-bit
28  * implementation of DSA. This limits the amount of DSA that can be created
29  * to something significantly less than the entire 4GB address space because
30  * the DSA pointer must encode both a segment identifier and an offset, but
31  * that shouldn't be a significant limitation in practice.
32  *
33  * If this system doesn't support atomic operations on 64-bit values, then
34  * we fall back to 32-bit dsa_pointer for lack of other options.
35  *
36  * For testing purposes, USE_SMALL_DSA_POINTER can be defined to force the use
37  * of 32-bit dsa_pointer even on systems capable of supporting a 64-bit
38  * dsa_pointer.
39  */
40 #if SIZEOF_SIZE_T == 4 || !defined(PG_HAVE_ATOMIC_U64_SUPPORT) || \
41  defined(USE_SMALL_DSA_POINTER)
42 #define SIZEOF_DSA_POINTER 4
43 #else
44 #define SIZEOF_DSA_POINTER 8
45 #endif
46 
47 /*
48  * The type of 'relative pointers' to memory allocated by a dynamic shared
49  * area. dsa_pointer values can be shared with other processes, but must be
50  * converted to backend-local pointers before they can be dereferenced. See
51  * dsa_get_address. Also, an atomic version and appropriately sized atomic
52  * operations.
53  */
54 #if SIZEOF_DSA_POINTER == 4
57 #define dsa_pointer_atomic_init pg_atomic_init_u32
58 #define dsa_pointer_atomic_read pg_atomic_read_u32
59 #define dsa_pointer_atomic_write pg_atomic_write_u32
60 #define dsa_pointer_atomic_fetch_add pg_atomic_fetch_add_u32
61 #define dsa_pointer_atomic_compare_exchange pg_atomic_compare_exchange_u32
62 #define DSA_POINTER_FORMAT "%08x"
63 #else
64 typedef uint64 dsa_pointer;
65 typedef pg_atomic_uint64 dsa_pointer_atomic;
66 #define dsa_pointer_atomic_init pg_atomic_init_u64
67 #define dsa_pointer_atomic_read pg_atomic_read_u64
68 #define dsa_pointer_atomic_write pg_atomic_write_u64
69 #define dsa_pointer_atomic_fetch_add pg_atomic_fetch_add_u64
70 #define dsa_pointer_atomic_compare_exchange pg_atomic_compare_exchange_u64
71 #define DSA_POINTER_FORMAT "%016" INT64_MODIFIER "x"
72 #endif
73 
74 /* Flags for dsa_allocate_extended. */
75 #define DSA_ALLOC_HUGE 0x01 /* allow huge allocation (> 1 GB) */
76 #define DSA_ALLOC_NO_OOM 0x02 /* no failure if out-of-memory */
77 #define DSA_ALLOC_ZERO 0x04 /* zero allocated memory */
78 
79 /* A sentinel value for dsa_pointer used to indicate failure to allocate. */
80 #define InvalidDsaPointer ((dsa_pointer) 0)
81 
82 /* Check if a dsa_pointer value is valid. */
83 #define DsaPointerIsValid(x) ((x) != InvalidDsaPointer)
84 
85 /* Allocate uninitialized memory with error on out-of-memory. */
86 #define dsa_allocate(area, size) \
87  dsa_allocate_extended(area, size, 0)
88 
89 /* Allocate zero-initialized memory with error on out-of-memory. */
90 #define dsa_allocate0(area, size) \
91  dsa_allocate_extended(area, size, DSA_ALLOC_ZERO)
92 
93 /*
94  * The type used for dsa_area handles. dsa_handle values can be shared with
95  * other processes, so that they can attach to them. This provides a way to
96  * share allocated storage with other processes.
97  *
98  * The handle for a dsa_area is currently implemented as the dsm_handle
99  * for the first DSM segment backing this dynamic storage area, but client
100  * code shouldn't assume that is true.
101  */
103 
104 extern void dsa_startup(void);
105 
106 extern dsa_area *dsa_create(int tranche_id);
107 extern dsa_area *dsa_create_in_place(void *place, Size size,
108  int tranche_id, dsm_segment *segment);
109 extern dsa_area *dsa_attach(dsa_handle handle);
110 extern dsa_area *dsa_attach_in_place(void *place, dsm_segment *segment);
111 extern void dsa_release_in_place(void *place);
113 extern void dsa_on_shmem_exit_release_in_place(int, Datum);
114 extern void dsa_pin_mapping(dsa_area *area);
115 extern void dsa_detach(dsa_area *area);
116 extern void dsa_pin(dsa_area *area);
117 extern void dsa_unpin(dsa_area *area);
118 extern void dsa_set_size_limit(dsa_area *area, Size limit);
119 extern Size dsa_minimum_size(void);
120 extern dsa_handle dsa_get_handle(dsa_area *area);
121 extern dsa_pointer dsa_allocate_extended(dsa_area *area, Size size, int flags);
122 extern void dsa_free(dsa_area *area, dsa_pointer dp);
123 extern void *dsa_get_address(dsa_area *area, dsa_pointer dp);
124 extern void dsa_trim(dsa_area *area);
125 extern void dsa_dump(dsa_area *area);
126 
127 #endif /* DSA_H */
void dsa_startup(void)
void dsa_set_size_limit(dsa_area *area, Size limit)
Definition: dsa.c:1000
void dsa_on_dsm_detach_release_in_place(dsm_segment *, Datum)
Definition: dsa.c:571
Size dsa_minimum_size(void)
Definition: dsa.c:1160
dsa_area * dsa_create(int tranche_id)
Definition: dsa.c:419
uint32 dsm_handle
Definition: dsm_impl.h:55
void dsa_pin(dsa_area *area)
Definition: dsa.c:957
void dsa_trim(dsa_area *area)
Definition: dsa.c:1012
dsa_area * dsa_attach(dsa_handle handle)
Definition: dsa.c:505
void dsa_release_in_place(void *place)
Definition: dsa.c:600
dsm_handle dsa_handle
Definition: dsa.h:102
void dsa_free(dsa_area *area, dsa_pointer dp)
Definition: dsa.c:812
void dsa_dump(dsa_area *area)
Definition: dsa.c:1057
void dsa_on_shmem_exit_release_in_place(int, Datum)
Definition: dsa.c:585
unsigned int uint32
Definition: c.h:265
uint32 dsa_pointer
Definition: dsa.h:55
uintptr_t Datum
Definition: postgres.h:374
dsa_area * dsa_create_in_place(void *place, Size size, int tranche_id, dsm_segment *segment)
Definition: dsa.c:468
void dsa_unpin(dsa_area *area)
Definition: dsa.c:976
size_t Size
Definition: c.h:352
dsa_handle dsa_get_handle(dsa_area *area)
Definition: dsa.c:493
Definition: dsa.c:354
pg_atomic_uint32 dsa_pointer_atomic
Definition: dsa.h:56
dsa_pointer dsa_allocate_extended(dsa_area *area, Size size, int flags)
Definition: dsa.c:664
void dsa_detach(dsa_area *area)
Definition: dsa.c:1875
void dsa_pin_mapping(dsa_area *area)
Definition: dsa.c:630
void * dsa_get_address(dsa_area *area, dsa_pointer dp)
Definition: dsa.c:924
dsa_area * dsa_attach_in_place(void *place, dsm_segment *segment)
Definition: dsa.c:540