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-2024, 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 
70 /*
71  * Memory-context-type-independent functions in mcxt.c
72  */
73 extern void MemoryContextInit(void);
74 extern void MemoryContextReset(MemoryContext context);
75 extern void MemoryContextDelete(MemoryContext context);
76 extern void MemoryContextResetOnly(MemoryContext context);
77 extern void MemoryContextResetChildren(MemoryContext context);
78 extern void MemoryContextDeleteChildren(MemoryContext context);
79 extern void MemoryContextSetIdentifier(MemoryContext context, const char *id);
80 extern void MemoryContextSetParent(MemoryContext context,
81  MemoryContext new_parent);
82 extern MemoryContext GetMemoryChunkContext(void *pointer);
83 extern Size GetMemoryChunkSpace(void *pointer);
85 extern bool MemoryContextIsEmpty(MemoryContext context);
86 extern Size MemoryContextMemAllocated(MemoryContext context, bool recurse);
87 extern void MemoryContextMemConsumed(MemoryContext context,
88  MemoryContextCounters *consumed);
89 extern void MemoryContextStats(MemoryContext context);
90 extern void MemoryContextStatsDetail(MemoryContext context, int max_children,
91  bool print_to_stderr);
93  bool allow);
94 
95 #ifdef MEMORY_CONTEXT_CHECKING
96 extern void MemoryContextCheck(MemoryContext context);
97 #endif
98 
99 /* Handy macro for copying and assigning context ID ... but note double eval */
100 #define MemoryContextCopyAndSetIdentifier(cxt, id) \
101  MemoryContextSetIdentifier(cxt, MemoryContextStrdup(cxt, id))
102 
103 extern void HandleLogMemoryContextInterrupt(void);
104 extern void ProcessLogMemoryContextInterrupt(void);
105 
106 /*
107  * Memory-context-type-specific functions
108  */
109 
110 /* aset.c */
112  const char *name,
113  Size minContextSize,
114  Size initBlockSize,
115  Size maxBlockSize);
116 
117 /*
118  * This wrapper macro exists to check for non-constant strings used as context
119  * names; that's no longer supported. (Use MemoryContextSetIdentifier if you
120  * want to provide a variable identifier.)
121  */
122 #ifdef HAVE__BUILTIN_CONSTANT_P
123 #define AllocSetContextCreate(parent, name, ...) \
124  (StaticAssertExpr(__builtin_constant_p(name), \
125  "memory context names must be constant strings"), \
126  AllocSetContextCreateInternal(parent, name, __VA_ARGS__))
127 #else
128 #define AllocSetContextCreate \
129  AllocSetContextCreateInternal
130 #endif
131 
132 /* slab.c */
134  const char *name,
135  Size blockSize,
136  Size chunkSize);
137 
138 /* generation.c */
140  const char *name,
141  Size minContextSize,
142  Size initBlockSize,
143  Size maxBlockSize);
144 
145 /*
146  * Recommended default alloc parameters, suitable for "ordinary" contexts
147  * that might hold quite a lot of data.
148  */
149 #define ALLOCSET_DEFAULT_MINSIZE 0
150 #define ALLOCSET_DEFAULT_INITSIZE (8 * 1024)
151 #define ALLOCSET_DEFAULT_MAXSIZE (8 * 1024 * 1024)
152 #define ALLOCSET_DEFAULT_SIZES \
153  ALLOCSET_DEFAULT_MINSIZE, ALLOCSET_DEFAULT_INITSIZE, ALLOCSET_DEFAULT_MAXSIZE
154 
155 /*
156  * Recommended alloc parameters for "small" contexts that are never expected
157  * to contain much data (for example, a context to contain a query plan).
158  */
159 #define ALLOCSET_SMALL_MINSIZE 0
160 #define ALLOCSET_SMALL_INITSIZE (1 * 1024)
161 #define ALLOCSET_SMALL_MAXSIZE (8 * 1024)
162 #define ALLOCSET_SMALL_SIZES \
163  ALLOCSET_SMALL_MINSIZE, ALLOCSET_SMALL_INITSIZE, ALLOCSET_SMALL_MAXSIZE
164 
165 /*
166  * Recommended alloc parameters for contexts that should start out small,
167  * but might sometimes grow big.
168  */
169 #define ALLOCSET_START_SMALL_SIZES \
170  ALLOCSET_SMALL_MINSIZE, ALLOCSET_SMALL_INITSIZE, ALLOCSET_DEFAULT_MAXSIZE
171 
172 
173 /*
174  * Threshold above which a request in an AllocSet context is certain to be
175  * allocated separately (and thereby have constant allocation overhead).
176  * Few callers should be interested in this, but tuplesort/tuplestore need
177  * to know it.
178  */
179 #define ALLOCSET_SEPARATE_THRESHOLD 8192
180 
181 #define SLAB_DEFAULT_BLOCK_SIZE (8 * 1024)
182 #define SLAB_LARGE_BLOCK_SIZE (8 * 1024 * 1024)
183 
184 #endif /* MEMUTILS_H */
#define PGDLLIMPORT
Definition: c.h:1305
size_t Size
Definition: c.h:594
PGDLLIMPORT MemoryContext CurTransactionContext
Definition: mcxt.c:147
bool MemoryContextIsEmpty(MemoryContext context)
Definition: mcxt.c:652
void MemoryContextMemConsumed(MemoryContext context, MemoryContextCounters *consumed)
Definition: mcxt.c:695
void MemoryContextReset(MemoryContext context)
Definition: mcxt.c:330
PGDLLIMPORT MemoryContext MessageContext
Definition: mcxt.c:145
PGDLLIMPORT MemoryContext TopMemoryContext
Definition: mcxt.c:141
PGDLLIMPORT MemoryContext TopTransactionContext
Definition: mcxt.c:146
void HandleLogMemoryContextInterrupt(void)
Definition: mcxt.c:1157
void MemoryContextSetParent(MemoryContext context, MemoryContext new_parent)
Definition: mcxt.c:546
void MemoryContextStatsDetail(MemoryContext context, int max_children, bool print_to_stderr)
Definition: mcxt.c:727
Size GetMemoryChunkSpace(void *pointer)
Definition: mcxt.c:630
void MemoryContextDeleteChildren(MemoryContext context)
Definition: mcxt.c:448
MemoryContext GetMemoryChunkContext(void *pointer)
Definition: mcxt.c:616
PGDLLIMPORT MemoryContext PostmasterContext
Definition: mcxt.c:143
Size MemoryContextMemAllocated(MemoryContext context, bool recurse)
Definition: mcxt.c:671
void MemoryContextStats(MemoryContext context)
Definition: mcxt.c:712
MemoryContext SlabContextCreate(MemoryContext parent, const char *name, Size blockSize, Size chunkSize)
Definition: slab.c:322
void MemoryContextInit(void)
Definition: mcxt.c:286
PGDLLIMPORT MemoryContext CacheMemoryContext
Definition: mcxt.c:144
MemoryContext MemoryContextGetParent(MemoryContext context)
Definition: mcxt.c:640
void ProcessLogMemoryContextInterrupt(void)
Definition: mcxt.c:1174
PGDLLIMPORT MemoryContext PortalContext
Definition: mcxt.c:150
MemoryContext GenerationContextCreate(MemoryContext parent, const char *name, Size minContextSize, Size initBlockSize, Size maxBlockSize)
Definition: generation.c:157
void MemoryContextDelete(MemoryContext context)
Definition: mcxt.c:403
void MemoryContextAllowInCriticalSection(MemoryContext context, bool allow)
Definition: mcxt.c:603
void MemoryContextResetChildren(MemoryContext context)
Definition: mcxt.c:380
void MemoryContextSetIdentifier(MemoryContext context, const char *id)
Definition: mcxt.c:521
void MemoryContextResetOnly(MemoryContext context)
Definition: mcxt.c:349
PGDLLIMPORT MemoryContext ErrorContext
Definition: mcxt.c:142
MemoryContext AllocSetContextCreateInternal(MemoryContext parent, const char *name, Size minContextSize, Size initBlockSize, Size maxBlockSize)
Definition: aset.c:347
const char * name