PostgreSQL Source Code  git master
memutils.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * memutils.h
4  * This file contains declarations for memory allocation utility
5  * functions. These are functions that are not quite widely used
6  * enough to justify going in utils/palloc.h, but are still part
7  * of the API of the memory management subsystem.
8  *
9  *
10  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
11  * Portions Copyright (c) 1994, Regents of the University of California
12  *
13  * src/include/utils/memutils.h
14  *
15  *-------------------------------------------------------------------------
16  */
17 #ifndef MEMUTILS_H
18 #define MEMUTILS_H
19 
20 #include "nodes/memnodes.h"
21 
22 
23 /*
24  * MaxAllocSize, MaxAllocHugeSize
25  * Quasi-arbitrary limits on size of allocations.
26  *
27  * Note:
28  * There is no guarantee that smaller allocations will succeed, but
29  * larger requests will be summarily denied.
30  *
31  * palloc() enforces MaxAllocSize, chosen to correspond to the limiting size
32  * of varlena objects under TOAST. See VARSIZE_4B() and related macros in
33  * postgres.h. Many datatypes assume that any allocatable size can be
34  * represented in a varlena header. This limit also permits a caller to use
35  * an "int" variable for an index into or length of an allocation. Callers
36  * careful to avoid these hazards can access the higher limit with
37  * MemoryContextAllocHuge(). Both limits permit code to assume that it may
38  * compute twice an allocation's size without overflow.
39  */
40 #define MaxAllocSize ((Size) 0x3fffffff) /* 1 gigabyte - 1 */
41 
42 #define AllocSizeIsValid(size) ((Size) (size) <= MaxAllocSize)
43 
44 /* Must be less than SIZE_MAX */
45 #define MaxAllocHugeSize (SIZE_MAX / 2)
46 
47 #define InvalidAllocSize SIZE_MAX
48 
49 #define AllocHugeSizeIsValid(size) ((Size) (size) <= MaxAllocHugeSize)
50 
51 
52 /*
53  * Standard top-level memory contexts.
54  *
55  * Only TopMemoryContext and ErrorContext are initialized by
56  * MemoryContextInit() itself.
57  */
65 
66 /* This is a transient link to the active portal's memory context: */
68 
69 /* Backwards compatibility macro */
70 #define MemoryContextResetAndDeleteChildren(ctx) MemoryContextReset(ctx)
71 
72 
73 /*
74  * Memory-context-type-independent functions in mcxt.c
75  */
76 extern void MemoryContextInit(void);
77 extern void MemoryContextReset(MemoryContext context);
78 extern void MemoryContextDelete(MemoryContext context);
79 extern void MemoryContextResetOnly(MemoryContext context);
80 extern void MemoryContextResetChildren(MemoryContext context);
81 extern void MemoryContextDeleteChildren(MemoryContext context);
82 extern void MemoryContextSetIdentifier(MemoryContext context, const char *id);
83 extern void MemoryContextSetParent(MemoryContext context,
84  MemoryContext new_parent);
85 extern MemoryContext GetMemoryChunkContext(void *pointer);
86 extern Size GetMemoryChunkSpace(void *pointer);
88 extern bool MemoryContextIsEmpty(MemoryContext context);
89 extern Size MemoryContextMemAllocated(MemoryContext context, bool recurse);
90 extern void MemoryContextStats(MemoryContext context);
91 extern void MemoryContextStatsDetail(MemoryContext context, int max_children,
92  bool print_to_stderr);
94  bool allow);
95 
96 #ifdef MEMORY_CONTEXT_CHECKING
97 extern void MemoryContextCheck(MemoryContext context);
98 #endif
99 
100 /* Handy macro for copying and assigning context ID ... but note double eval */
101 #define MemoryContextCopyAndSetIdentifier(cxt, id) \
102  MemoryContextSetIdentifier(cxt, MemoryContextStrdup(cxt, id))
103 
104 extern void HandleLogMemoryContextInterrupt(void);
105 extern void ProcessLogMemoryContextInterrupt(void);
106 
107 /*
108  * Memory-context-type-specific functions
109  */
110 
111 /* aset.c */
113  const char *name,
114  Size minContextSize,
115  Size initBlockSize,
116  Size maxBlockSize);
117 
118 /*
119  * This wrapper macro exists to check for non-constant strings used as context
120  * names; that's no longer supported. (Use MemoryContextSetIdentifier if you
121  * want to provide a variable identifier.)
122  */
123 #ifdef HAVE__BUILTIN_CONSTANT_P
124 #define AllocSetContextCreate(parent, name, ...) \
125  (StaticAssertExpr(__builtin_constant_p(name), \
126  "memory context names must be constant strings"), \
127  AllocSetContextCreateInternal(parent, name, __VA_ARGS__))
128 #else
129 #define AllocSetContextCreate \
130  AllocSetContextCreateInternal
131 #endif
132 
133 /* slab.c */
135  const char *name,
136  Size blockSize,
137  Size chunkSize);
138 
139 /* generation.c */
141  const char *name,
142  Size minContextSize,
143  Size initBlockSize,
144  Size maxBlockSize);
145 
146 /*
147  * Recommended default alloc parameters, suitable for "ordinary" contexts
148  * that might hold quite a lot of data.
149  */
150 #define ALLOCSET_DEFAULT_MINSIZE 0
151 #define ALLOCSET_DEFAULT_INITSIZE (8 * 1024)
152 #define ALLOCSET_DEFAULT_MAXSIZE (8 * 1024 * 1024)
153 #define ALLOCSET_DEFAULT_SIZES \
154  ALLOCSET_DEFAULT_MINSIZE, ALLOCSET_DEFAULT_INITSIZE, ALLOCSET_DEFAULT_MAXSIZE
155 
156 /*
157  * Recommended alloc parameters for "small" contexts that are never expected
158  * to contain much data (for example, a context to contain a query plan).
159  */
160 #define ALLOCSET_SMALL_MINSIZE 0
161 #define ALLOCSET_SMALL_INITSIZE (1 * 1024)
162 #define ALLOCSET_SMALL_MAXSIZE (8 * 1024)
163 #define ALLOCSET_SMALL_SIZES \
164  ALLOCSET_SMALL_MINSIZE, ALLOCSET_SMALL_INITSIZE, ALLOCSET_SMALL_MAXSIZE
165 
166 /*
167  * Recommended alloc parameters for contexts that should start out small,
168  * but might sometimes grow big.
169  */
170 #define ALLOCSET_START_SMALL_SIZES \
171  ALLOCSET_SMALL_MINSIZE, ALLOCSET_SMALL_INITSIZE, ALLOCSET_DEFAULT_MAXSIZE
172 
173 
174 /*
175  * Threshold above which a request in an AllocSet context is certain to be
176  * allocated separately (and thereby have constant allocation overhead).
177  * Few callers should be interested in this, but tuplesort/tuplestore need
178  * to know it.
179  */
180 #define ALLOCSET_SEPARATE_THRESHOLD 8192
181 
182 #define SLAB_DEFAULT_BLOCK_SIZE (8 * 1024)
183 #define SLAB_LARGE_BLOCK_SIZE (8 * 1024 * 1024)
184 
185 #endif /* MEMUTILS_H */
#define PGDLLIMPORT
Definition: c.h:1252
size_t Size
Definition: c.h:541
const char * name
Definition: encode.c:561
PGDLLIMPORT MemoryContext CurTransactionContext
Definition: mcxt.c:136
bool MemoryContextIsEmpty(MemoryContext context)
Definition: mcxt.c:625
void MemoryContextReset(MemoryContext context)
Definition: mcxt.c:303
PGDLLIMPORT MemoryContext MessageContext
Definition: mcxt.c:134
PGDLLIMPORT MemoryContext TopMemoryContext
Definition: mcxt.c:130
PGDLLIMPORT MemoryContext TopTransactionContext
Definition: mcxt.c:135
void HandleLogMemoryContextInterrupt(void)
Definition: mcxt.c:1155
void MemoryContextSetParent(MemoryContext context, MemoryContext new_parent)
Definition: mcxt.c:519
void MemoryContextStatsDetail(MemoryContext context, int max_children, bool print_to_stderr)
Definition: mcxt.c:687
Size GetMemoryChunkSpace(void *pointer)
Definition: mcxt.c:603
void MemoryContextDeleteChildren(MemoryContext context)
Definition: mcxt.c:421
MemoryContext GetMemoryChunkContext(void *pointer)
Definition: mcxt.c:589
PGDLLIMPORT MemoryContext PostmasterContext
Definition: mcxt.c:132
Size MemoryContextMemAllocated(MemoryContext context, bool recurse)
Definition: mcxt.c:644
void MemoryContextStats(MemoryContext context)
Definition: mcxt.c:672
MemoryContext SlabContextCreate(MemoryContext parent, const char *name, Size blockSize, Size chunkSize)
Definition: slab.c:141
void MemoryContextInit(void)
Definition: mcxt.c:259
PGDLLIMPORT MemoryContext CacheMemoryContext
Definition: mcxt.c:133
MemoryContext MemoryContextGetParent(MemoryContext context)
Definition: mcxt.c:613
void ProcessLogMemoryContextInterrupt(void)
Definition: mcxt.c:1172
PGDLLIMPORT MemoryContext PortalContext
Definition: mcxt.c:139
MemoryContext GenerationContextCreate(MemoryContext parent, const char *name, Size minContextSize, Size initBlockSize, Size maxBlockSize)
Definition: generation.c:158
void MemoryContextDelete(MemoryContext context)
Definition: mcxt.c:376
void MemoryContextAllowInCriticalSection(MemoryContext context, bool allow)
Definition: mcxt.c:576
void MemoryContextResetChildren(MemoryContext context)
Definition: mcxt.c:353
void MemoryContextSetIdentifier(MemoryContext context, const char *id)
Definition: mcxt.c:494
void MemoryContextResetOnly(MemoryContext context)
Definition: mcxt.c:322
PGDLLIMPORT MemoryContext ErrorContext
Definition: mcxt.c:131
MemoryContext AllocSetContextCreateInternal(MemoryContext parent, const char *name, Size minContextSize, Size initBlockSize, Size maxBlockSize)
Definition: aset.c:349