PostgreSQL Source Code  git master
memutils_memorychunk.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * memutils_memorychunk.h
4  * Here we define a struct named MemoryChunk which implementations of
5  * MemoryContexts may use as a header for chunks of memory they allocate.
6  *
7  * MemoryChunk provides a lightweight header that a MemoryContext can use to
8  * store a reference back to the block which the given chunk is allocated on
9  * and also an additional 30-bits to store another value such as the size of
10  * the allocated chunk.
11  *
12  * Although MemoryChunks are used by each of our MemoryContexts, future
13  * implementations may choose to implement their own method for storing chunk
14  * headers. The only requirement is that the header ends with an 8-byte value
15  * which the least significant 3-bits of are set to the MemoryContextMethodID
16  * of the given context.
17  *
18  * By default, a MemoryChunk is 8 bytes in size, however, when
19  * MEMORY_CONTEXT_CHECKING is defined the header becomes 16 bytes in size due
20  * to the additional requested_size field. The MemoryContext may use this
21  * field for whatever they wish, but it is intended to be used for additional
22  * checks which are only done in MEMORY_CONTEXT_CHECKING builds.
23  *
24  * The MemoryChunk contains a uint64 field named 'hdrmask'. This field is
25  * used to encode 4 separate pieces of information. Starting with the least
26  * significant bits of 'hdrmask', the bit space is reserved as follows:
27  *
28  * 1. 3-bits to indicate the MemoryContextMethodID as defined by
29  * MEMORY_CONTEXT_METHODID_MASK
30  * 2. 1-bit to denote an "external" chunk (see below)
31  * 3. 30-bits reserved for the MemoryContext to use for anything it
32  * requires. Most MemoryContext likely want to store the size of the
33  * chunk here.
34  * 4. 30-bits for the number of bytes that must be subtracted from the chunk
35  * to obtain the address of the block that the chunk is stored on.
36  *
37  * In some cases, for example when memory allocations become large, it's
38  * possible fields 3 and 4 above are not large enough to store the values
39  * required for the chunk. In this case, the MemoryContext can choose to mark
40  * the chunk as "external" by calling the MemoryChunkSetHdrMaskExternal()
41  * function. When this is done, fields 3 and 4 are unavailable for use by the
42  * MemoryContext and it's up to the MemoryContext itself to devise its own
43  * method for getting the reference to the block.
44  *
45  * Interface:
46  *
47  * MemoryChunkSetHdrMask:
48  * Used to set up a non-external MemoryChunk.
49  *
50  * MemoryChunkSetHdrMaskExternal:
51  * Used to set up an externally managed MemoryChunk.
52  *
53  * MemoryChunkIsExternal:
54  * Determine if the given MemoryChunk is externally managed, i.e.
55  * MemoryChunkSetHdrMaskExternal() was called on the chunk.
56  *
57  * MemoryChunkGetValue:
58  * For non-external chunks, return the stored 30-bit value as it was set
59  * in the call to MemoryChunkSetHdrMask().
60  *
61  * MemoryChunkGetBlock:
62  * For non-external chunks, return a pointer to the block as it was set
63  * in the call to MemoryChunkSetHdrMask().
64  *
65  * Also exports:
66  * MEMORYCHUNK_MAX_VALUE
67  * MEMORYCHUNK_MAX_BLOCKOFFSET
68  * PointerGetMemoryChunk
69  * MemoryChunkGetPointer
70  *
71  * Portions Copyright (c) 2022-2023, PostgreSQL Global Development Group
72  * Portions Copyright (c) 1994, Regents of the University of California
73  *
74  * src/include/utils/memutils_memorychunk.h
75  *
76  *-------------------------------------------------------------------------
77  */
78 
79 #ifndef MEMUTILS_MEMORYCHUNK_H
80 #define MEMUTILS_MEMORYCHUNK_H
81 
83 
84  /*
85  * The maximum allowed value that MemoryContexts can store in the value
86  * field. Must be 1 less than a power of 2.
87  */
88 #define MEMORYCHUNK_MAX_VALUE UINT64CONST(0x3FFFFFFF)
89 
90 /*
91  * The maximum distance in bytes that a MemoryChunk can be offset from the
92  * block that is storing the chunk. Must be 1 less than a power of 2.
93  */
94 #define MEMORYCHUNK_MAX_BLOCKOFFSET UINT64CONST(0x3FFFFFFF)
95 
96 /* define the least significant base-0 bit of each portion of the hdrmask */
97 #define MEMORYCHUNK_EXTERNAL_BASEBIT MEMORY_CONTEXT_METHODID_BITS
98 #define MEMORYCHUNK_VALUE_BASEBIT (MEMORYCHUNK_EXTERNAL_BASEBIT + 1)
99 #define MEMORYCHUNK_BLOCKOFFSET_BASEBIT (MEMORYCHUNK_VALUE_BASEBIT + 30)
100 
101 /*
102  * A magic number for storing in the free bits of an external chunk. This
103  * must mask out the bits used for storing the MemoryContextMethodID and the
104  * external bit.
105  */
106 #define MEMORYCHUNK_MAGIC (UINT64CONST(0xB1A8DB858EB6EFBA) >> \
107  MEMORYCHUNK_VALUE_BASEBIT << \
108  MEMORYCHUNK_VALUE_BASEBIT)
109 
110 typedef struct MemoryChunk
111 {
112 #ifdef MEMORY_CONTEXT_CHECKING
113  Size requested_size;
114 #endif
115 
116  /* bitfield for storing details about the chunk */
117  uint64 hdrmask; /* must be last */
119 
120 /* Get the MemoryChunk from the pointer */
121 #define PointerGetMemoryChunk(p) \
122  ((MemoryChunk *) ((char *) (p) - sizeof(MemoryChunk)))
123 /* Get the pointer from the MemoryChunk */
124 #define MemoryChunkGetPointer(c) \
125  ((void *) ((char *) (c) + sizeof(MemoryChunk)))
126 
127 /* private macros for making the inline functions below more simple */
128 #define HdrMaskIsExternal(hdrmask) \
129  ((hdrmask) & (((uint64) 1) << MEMORYCHUNK_EXTERNAL_BASEBIT))
130 #define HdrMaskGetValue(hdrmask) \
131  (((hdrmask) >> MEMORYCHUNK_VALUE_BASEBIT) & MEMORYCHUNK_MAX_VALUE)
132 
133 /*
134  * We should have used up all the bits here, so the compiler is likely to
135  * optimize out the & MEMORYCHUNK_MAX_BLOCKOFFSET.
136  */
137 #define HdrMaskBlockOffset(hdrmask) \
138  (((hdrmask) >> MEMORYCHUNK_BLOCKOFFSET_BASEBIT) & MEMORYCHUNK_MAX_BLOCKOFFSET)
139 
140 /* For external chunks only, check the magic number matches */
141 #define HdrMaskCheckMagic(hdrmask) \
142  (MEMORYCHUNK_MAGIC == \
143  ((hdrmask) >> MEMORYCHUNK_VALUE_BASEBIT << MEMORYCHUNK_VALUE_BASEBIT))
144 /*
145  * MemoryChunkSetHdrMask
146  * Store the given 'block', 'chunk_size' and 'methodid' in the given
147  * MemoryChunk.
148  *
149  * The number of bytes between 'block' and 'chunk' must be <=
150  * MEMORYCHUNK_MAX_BLOCKOFFSET.
151  * 'value' must be <= MEMORYCHUNK_MAX_VALUE.
152  */
153 static inline void
154 MemoryChunkSetHdrMask(MemoryChunk *chunk, void *block,
155  Size value, MemoryContextMethodID methodid)
156 {
157  Size blockoffset = (char *) chunk - (char *) block;
158 
159  Assert((char *) chunk >= (char *) block);
160  Assert(blockoffset <= MEMORYCHUNK_MAX_BLOCKOFFSET);
162  Assert((int) methodid <= MEMORY_CONTEXT_METHODID_MASK);
163 
164  chunk->hdrmask = (((uint64) blockoffset) << MEMORYCHUNK_BLOCKOFFSET_BASEBIT) |
165  (((uint64) value) << MEMORYCHUNK_VALUE_BASEBIT) |
166  methodid;
167 }
168 
169 /*
170  * MemoryChunkSetHdrMaskExternal
171  * Set 'chunk' as an externally managed chunk. Here we only record the
172  * MemoryContextMethodID and set the external chunk bit.
173  */
174 static inline void
176  MemoryContextMethodID methodid)
177 {
178  Assert((int) methodid <= MEMORY_CONTEXT_METHODID_MASK);
179 
180  chunk->hdrmask = MEMORYCHUNK_MAGIC | (((uint64) 1) << MEMORYCHUNK_EXTERNAL_BASEBIT) |
181  methodid;
182 }
183 
184 /*
185  * MemoryChunkIsExternal
186  * Return true if 'chunk' is marked as external.
187  */
188 static inline bool
190 {
191  /*
192  * External chunks should always store MEMORYCHUNK_MAGIC in the upper
193  * portion of the hdrmask, check that nothing has stomped on that.
194  */
195  Assert(!HdrMaskIsExternal(chunk->hdrmask) ||
196  HdrMaskCheckMagic(chunk->hdrmask));
197 
198  return HdrMaskIsExternal(chunk->hdrmask);
199 }
200 
201 /*
202  * MemoryChunkGetValue
203  * For non-external chunks, returns the value field as it was set in
204  * MemoryChunkSetHdrMask.
205  */
206 static inline Size
208 {
209  Assert(!HdrMaskIsExternal(chunk->hdrmask));
210 
211  return HdrMaskGetValue(chunk->hdrmask);
212 }
213 
214 /*
215  * MemoryChunkGetBlock
216  * For non-external chunks, returns the pointer to the block as was set
217  * in MemoryChunkSetHdrMask.
218  */
219 static inline void *
221 {
222  Assert(!HdrMaskIsExternal(chunk->hdrmask));
223 
224  return (void *) ((char *) chunk - HdrMaskBlockOffset(chunk->hdrmask));
225 }
226 
227 /* cleanup all internal definitions */
228 #undef MEMORYCHUNK_EXTERNAL_BASEBIT
229 #undef MEMORYCHUNK_VALUE_BASEBIT
230 #undef MEMORYCHUNK_BLOCKOFFSET_BASEBIT
231 #undef MEMORYCHUNK_MAGIC
232 #undef HdrMaskIsExternal
233 #undef HdrMaskGetValue
234 #undef HdrMaskBlockOffset
235 #undef HdrMaskCheckMagic
236 
237 #endif /* MEMUTILS_MEMORYCHUNK_H */
size_t Size
Definition: c.h:589
static struct @147 value
Assert(fmt[strlen(fmt) - 1] !='\n')
#define MEMORY_CONTEXT_METHODID_MASK
MemoryContextMethodID
#define MEMORYCHUNK_MAX_BLOCKOFFSET
#define MEMORYCHUNK_MAX_VALUE
static Size MemoryChunkGetValue(MemoryChunk *chunk)
#define MEMORYCHUNK_VALUE_BASEBIT
#define MEMORYCHUNK_EXTERNAL_BASEBIT
#define HdrMaskBlockOffset(hdrmask)
static bool MemoryChunkIsExternal(MemoryChunk *chunk)
static void MemoryChunkSetHdrMaskExternal(MemoryChunk *chunk, MemoryContextMethodID methodid)
#define HdrMaskCheckMagic(hdrmask)
#define HdrMaskIsExternal(hdrmask)
struct MemoryChunk MemoryChunk
#define MEMORYCHUNK_BLOCKOFFSET_BASEBIT
static void * MemoryChunkGetBlock(MemoryChunk *chunk)
static void MemoryChunkSetHdrMask(MemoryChunk *chunk, void *block, Size value, MemoryContextMethodID methodid)
#define MEMORYCHUNK_MAGIC
#define HdrMaskGetValue(hdrmask)