PostgreSQL Source Code  git master
palloc.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * palloc.h
4  * POSTGRES memory allocator definitions.
5  *
6  * This file contains the basic memory allocation interface that is
7  * needed by almost every backend module. It is included directly by
8  * postgres.h, so the definitions here are automatically available
9  * everywhere. Keep it lean!
10  *
11  * Memory allocation occurs within "contexts". Every chunk obtained from
12  * palloc()/MemoryContextAlloc() is allocated within a specific context.
13  * The entire contents of a context can be freed easily and quickly by
14  * resetting or deleting the context --- this is both faster and less
15  * prone to memory-leakage bugs than releasing chunks individually.
16  * We organize contexts into context trees to allow fine-grain control
17  * over chunk lifetime while preserving the certainty that we will free
18  * everything that should be freed. See utils/mmgr/README for more info.
19  *
20  *
21  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
22  * Portions Copyright (c) 1994, Regents of the University of California
23  *
24  * src/include/utils/palloc.h
25  *
26  *-------------------------------------------------------------------------
27  */
28 #ifndef PALLOC_H
29 #define PALLOC_H
30 
31 /*
32  * Type MemoryContextData is declared in nodes/memnodes.h. Most users
33  * of memory allocation should just treat it as an abstract type, so we
34  * do not provide the struct contents here.
35  */
37 
38 /*
39  * A memory context can have callback functions registered on it. Any such
40  * function will be called once just before the context is next reset or
41  * deleted. The MemoryContextCallback struct describing such a callback
42  * typically would be allocated within the context itself, thereby avoiding
43  * any need to manage it explicitly (the reset/delete action will free it).
44  */
45 typedef void (*MemoryContextCallbackFunction) (void *arg);
46 
47 typedef struct MemoryContextCallback
48 {
49  MemoryContextCallbackFunction func; /* function to call */
50  void *arg; /* argument to pass it */
51  struct MemoryContextCallback *next; /* next in list of callbacks */
53 
54 /*
55  * CurrentMemoryContext is the default allocation context for palloc().
56  * Avoid accessing it directly! Instead, use MemoryContextSwitchTo()
57  * to change the setting.
58  */
60 
61 /*
62  * Flags for MemoryContextAllocExtended.
63  */
64 #define MCXT_ALLOC_HUGE 0x01 /* allow huge allocation (> 1 GB) */
65 #define MCXT_ALLOC_NO_OOM 0x02 /* no failure if out-of-memory */
66 #define MCXT_ALLOC_ZERO 0x04 /* zero allocated memory */
67 
68 /*
69  * Fundamental memory-allocation operations (more are in utils/memutils.h)
70  */
71 extern void *MemoryContextAlloc(MemoryContext context, Size size);
72 extern void *MemoryContextAllocZero(MemoryContext context, Size size);
73 extern void *MemoryContextAllocZeroAligned(MemoryContext context, Size size);
74 extern void *MemoryContextAllocExtended(MemoryContext context,
75  Size size, int flags);
76 
77 extern void *palloc(Size size);
78 extern void *palloc0(Size size);
79 extern void *palloc_extended(Size size, int flags);
80 extern pg_nodiscard void *repalloc(void *pointer, Size size);
81 extern pg_nodiscard void *repalloc_extended(void *pointer,
82  Size size, int flags);
83 extern pg_nodiscard void *repalloc0(void *pointer, Size oldsize, Size size);
84 extern void pfree(void *pointer);
85 
86 /*
87  * Variants with easier notation and more type safety
88  */
89 
90 /*
91  * Allocate space for one object of type "type"
92  */
93 #define palloc_object(type) ((type *) palloc(sizeof(type)))
94 #define palloc0_object(type) ((type *) palloc0(sizeof(type)))
95 
96 /*
97  * Allocate space for "count" objects of type "type"
98  */
99 #define palloc_array(type, count) ((type *) palloc(sizeof(type) * (count)))
100 #define palloc0_array(type, count) ((type *) palloc0(sizeof(type) * (count)))
101 
102 /*
103  * Change size of allocation pointed to by "pointer" to have space for "count"
104  * objects of type "type"
105  */
106 #define repalloc_array(pointer, type, count) ((type *) repalloc(pointer, sizeof(type) * (count)))
107 #define repalloc0_array(pointer, type, oldcount, count) ((type *) repalloc0(pointer, sizeof(type) * (oldcount), sizeof(type) * (count)))
108 
109 /*
110  * The result of palloc() is always word-aligned, so we can skip testing
111  * alignment of the pointer when deciding which MemSet variant to use.
112  * Note that this variant does not offer any advantage, and should not be
113  * used, unless its "sz" argument is a compile-time constant; therefore, the
114  * issue that it evaluates the argument multiple times isn't a problem in
115  * practice.
116  */
117 #define palloc0fast(sz) \
118  ( MemSetTest(0, sz) ? \
119  MemoryContextAllocZeroAligned(CurrentMemoryContext, sz) : \
120  MemoryContextAllocZero(CurrentMemoryContext, sz) )
121 
122 /* Higher-limit allocators. */
123 extern void *MemoryContextAllocHuge(MemoryContext context, Size size);
124 extern pg_nodiscard void *repalloc_huge(void *pointer, Size size);
125 
126 /*
127  * Although this header file is nominally backend-only, certain frontend
128  * programs like pg_controldata include it via postgres.h. For some compilers
129  * it's necessary to hide the inline definition of MemoryContextSwitchTo in
130  * this scenario; hence the #ifndef FRONTEND.
131  */
132 
133 #ifndef FRONTEND
134 static inline MemoryContext
136 {
138 
139  CurrentMemoryContext = context;
140  return old;
141 }
142 #endif /* FRONTEND */
143 
144 /* Registration of memory context reset/delete callbacks */
147 
148 /*
149  * These are like standard strdup() except the copied string is
150  * allocated in a context, not with malloc().
151  */
152 extern char *MemoryContextStrdup(MemoryContext context, const char *string);
153 extern char *pstrdup(const char *in);
154 extern char *pnstrdup(const char *in, Size len);
155 
156 extern char *pchomp(const char *in);
157 
158 /* sprintf into a palloc'd buffer --- these are in psprintf.c */
159 extern char *psprintf(const char *fmt,...) pg_attribute_printf(1, 2);
160 extern size_t pvsnprintf(char *buf, size_t len, const char *fmt, va_list args) pg_attribute_printf(3, 0);
161 
162 #endif /* PALLOC_H */
#define PGDLLIMPORT
Definition: c.h:1252
#define pg_nodiscard
Definition: c.h:132
#define pg_attribute_printf(f, a)
Definition: c.h:175
size_t Size
Definition: c.h:541
static void const char * fmt
char * pnstrdup(const char *in, Size len)
Definition: mcxt.c:1494
pg_nodiscard void * repalloc0(void *pointer, Size oldsize, Size size)
Definition: mcxt.c:1404
struct MemoryContextCallback MemoryContextCallback
char * pchomp(const char *in)
Definition: mcxt.c:1511
void MemoryContextRegisterResetCallback(MemoryContext context, MemoryContextCallback *cb)
Definition: mcxt.c:450
static MemoryContext MemoryContextSwitchTo(MemoryContext context)
Definition: palloc.h:135
char * pstrdup(const char *in)
Definition: mcxt.c:1483
void pfree(void *pointer)
Definition: mcxt.c:1306
pg_nodiscard void * repalloc_huge(void *pointer, Size size)
Definition: mcxt.c:1459
void(* MemoryContextCallbackFunction)(void *arg)
Definition: palloc.h:45
void * palloc0(Size size)
Definition: mcxt.c:1230
void * MemoryContextAllocZero(MemoryContext context, Size size)
Definition: mcxt.c:1037
struct MemoryContextData * MemoryContext
Definition: palloc.h:36
void * MemoryContextAllocExtended(MemoryContext context, Size size, int flags)
Definition: mcxt.c:1110
void * palloc_extended(Size size, int flags)
Definition: mcxt.c:1263
void * MemoryContextAlloc(MemoryContext context, Size size)
Definition: mcxt.c:994
void * MemoryContextAllocZeroAligned(MemoryContext context, Size size)
Definition: mcxt.c:1075
char size_t pvsnprintf(char *buf, size_t len, const char *fmt, va_list args) pg_attribute_printf(3
char * MemoryContextStrdup(MemoryContext context, const char *string)
Definition: mcxt.c:1470
char * psprintf(const char *fmt,...) pg_attribute_printf(1
void * MemoryContextAllocHuge(MemoryContext context, Size size)
Definition: mcxt.c:1425
pg_nodiscard void * repalloc_extended(void *pointer, Size size, int flags)
Definition: mcxt.c:1360
pg_nodiscard void * repalloc(void *pointer, Size size)
Definition: mcxt.c:1321
void * palloc(Size size)
Definition: mcxt.c:1199
PGDLLIMPORT MemoryContext CurrentMemoryContext
Definition: mcxt.c:124
void * arg
const void size_t len
static char * buf
Definition: pg_test_fsync.c:67
struct MemoryContextCallback * next
Definition: palloc.h:51
MemoryContextCallbackFunction func
Definition: palloc.h:49