PostgreSQL Source Code git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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-2025, 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 */
45typedef void (*MemoryContextCallbackFunction) (void *arg);
46
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 */
71extern void *MemoryContextAlloc(MemoryContext context, Size size);
72extern void *MemoryContextAllocZero(MemoryContext context, Size size);
73extern void *MemoryContextAllocExtended(MemoryContext context,
74 Size size, int flags);
75extern void *MemoryContextAllocAligned(MemoryContext context,
76 Size size, Size alignto, int flags);
77
78extern void *palloc(Size size);
79extern void *palloc0(Size size);
80extern void *palloc_extended(Size size, int flags);
81extern void *palloc_aligned(Size size, Size alignto, int flags);
82extern pg_nodiscard void *repalloc(void *pointer, Size size);
83extern pg_nodiscard void *repalloc_extended(void *pointer,
84 Size size, int flags);
85extern pg_nodiscard void *repalloc0(void *pointer, Size oldsize, Size size);
86extern void pfree(void *pointer);
87
88/*
89 * Variants with easier notation and more type safety
90 */
91
92/*
93 * Allocate space for one object of type "type"
94 */
95#define palloc_object(type) ((type *) palloc(sizeof(type)))
96#define palloc0_object(type) ((type *) palloc0(sizeof(type)))
97
98/*
99 * Allocate space for "count" objects of type "type"
100 */
101#define palloc_array(type, count) ((type *) palloc(sizeof(type) * (count)))
102#define palloc0_array(type, count) ((type *) palloc0(sizeof(type) * (count)))
103
104/*
105 * Change size of allocation pointed to by "pointer" to have space for "count"
106 * objects of type "type"
107 */
108#define repalloc_array(pointer, type, count) ((type *) repalloc(pointer, sizeof(type) * (count)))
109#define repalloc0_array(pointer, type, oldcount, count) ((type *) repalloc0(pointer, sizeof(type) * (oldcount), sizeof(type) * (count)))
110
111/* Higher-limit allocators. */
112extern void *MemoryContextAllocHuge(MemoryContext context, Size size);
113extern pg_nodiscard void *repalloc_huge(void *pointer, Size size);
114
115/*
116 * Although this header file is nominally backend-only, certain frontend
117 * programs like pg_controldata include it via postgres.h. For some compilers
118 * it's necessary to hide the inline definition of MemoryContextSwitchTo in
119 * this scenario; hence the #ifndef FRONTEND.
120 */
121
122#ifndef FRONTEND
123static inline MemoryContext
125{
127
128 CurrentMemoryContext = context;
129 return old;
130}
131#endif /* FRONTEND */
132
133/* Registration of memory context reset/delete callbacks */
136
137/*
138 * These are like standard strdup() except the copied string is
139 * allocated in a context, not with malloc().
140 */
141extern char *MemoryContextStrdup(MemoryContext context, const char *string);
142extern char *pstrdup(const char *in);
143extern char *pnstrdup(const char *in, Size len);
144
145extern char *pchomp(const char *in);
146
147/* sprintf into a palloc'd buffer --- these are in psprintf.c */
148extern char *psprintf(const char *fmt,...) pg_attribute_printf(1, 2);
149extern size_t pvsnprintf(char *buf, size_t len, const char *fmt, va_list args) pg_attribute_printf(3, 0);
150
151#endif /* PALLOC_H */
#define PGDLLIMPORT
Definition: c.h:1274
#define pg_nodiscard
Definition: c.h:142
#define pg_attribute_printf(f, a)
Definition: c.h:210
size_t Size
Definition: c.h:559
static void const char * fmt
char * MemoryContextStrdup(MemoryContext context, const char *string)
Definition: mcxt.c:1683
void * MemoryContextAlloc(MemoryContext context, Size size)
Definition: mcxt.c:1181
struct MemoryContextCallback MemoryContextCallback
void * MemoryContextAllocZero(MemoryContext context, Size size)
Definition: mcxt.c:1215
char * pstrdup(const char *in)
Definition: mcxt.c:1696
void MemoryContextRegisterResetCallback(MemoryContext context, MemoryContextCallback *cb)
Definition: mcxt.c:568
char * psprintf(const char *fmt,...) pg_attribute_printf(1
static MemoryContext MemoryContextSwitchTo(MemoryContext context)
Definition: palloc.h:124
pg_nodiscard void * repalloc_huge(void *pointer, Size size)
Definition: mcxt.c:1672
void pfree(void *pointer)
Definition: mcxt.c:1521
void * palloc0(Size size)
Definition: mcxt.c:1347
void * MemoryContextAllocAligned(MemoryContext context, Size size, Size alignto, int flags)
Definition: mcxt.c:1409
void(* MemoryContextCallbackFunction)(void *arg)
Definition: palloc.h:45
char * pchomp(const char *in)
Definition: mcxt.c:1724
void * palloc(Size size)
Definition: mcxt.c:1317
struct MemoryContextData * MemoryContext
Definition: palloc.h:36
void * MemoryContextAllocExtended(MemoryContext context, Size size, int flags)
Definition: mcxt.c:1238
char * pnstrdup(const char *in, Size len)
Definition: mcxt.c:1707
void * palloc_extended(Size size, int flags)
Definition: mcxt.c:1368
pg_nodiscard void * repalloc_extended(void *pointer, Size size, int flags)
Definition: mcxt.c:1582
char size_t pvsnprintf(char *buf, size_t len, const char *fmt, va_list args) pg_attribute_printf(3
pg_nodiscard void * repalloc0(void *pointer, Size oldsize, Size size)
Definition: mcxt.c:1619
pg_nodiscard void * repalloc(void *pointer, Size size)
Definition: mcxt.c:1541
void * MemoryContextAllocHuge(MemoryContext context, Size size)
Definition: mcxt.c:1640
PGDLLIMPORT MemoryContext CurrentMemoryContext
Definition: mcxt.c:143
void * palloc_aligned(Size size, Size alignto, int flags)
Definition: mcxt.c:1511
void * arg
const void size_t len
static char * buf
Definition: pg_test_fsync.c:72
static pg_noinline void Size size
Definition: slab.c:607
struct MemoryContextCallback * next
Definition: palloc.h:51
MemoryContextCallbackFunction func
Definition: palloc.h:49