Line data Source code
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-2026, 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 : */
36 : typedef struct MemoryContextData *MemoryContext;
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 */
52 : } MemoryContextCallback;
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 : */
59 : extern PGDLLIMPORT MemoryContext CurrentMemoryContext;
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 *MemoryContextAllocExtended(MemoryContext context,
74 : Size size, int flags);
75 : extern void *MemoryContextAllocAligned(MemoryContext context,
76 : Size size, Size alignto, int flags);
77 :
78 : extern void *palloc(Size size);
79 : extern void *palloc0(Size size);
80 : extern void *palloc_extended(Size size, int flags);
81 : extern void *palloc_aligned(Size size, Size alignto, int flags);
82 : pg_nodiscard extern void *repalloc(void *pointer, Size size);
83 : pg_nodiscard extern void *repalloc_extended(void *pointer,
84 : Size size, int flags);
85 : pg_nodiscard extern void *repalloc0(void *pointer, Size oldsize, Size size);
86 : extern void pfree(void *pointer);
87 :
88 : /*
89 : * Support for safe calculation of memory request sizes
90 : */
91 : extern Size add_size(Size s1, Size s2);
92 : extern Size mul_size(Size s1, Size s2);
93 : extern void *palloc_mul(Size s1, Size s2);
94 : extern void *palloc0_mul(Size s1, Size s2);
95 : extern void *palloc_mul_extended(Size s1, Size s2, int flags);
96 : pg_nodiscard extern void *repalloc_mul(void *p, Size s1, Size s2);
97 : pg_nodiscard extern void *repalloc_mul_extended(void *p, Size s1, Size s2,
98 : int flags);
99 :
100 : /*
101 : * Variants with easier notation and more type safety
102 : */
103 :
104 : /*
105 : * Allocate space for one object of type "type"
106 : */
107 : #define palloc_object(type) ((type *) palloc(sizeof(type)))
108 : #define palloc0_object(type) ((type *) palloc0(sizeof(type)))
109 :
110 : /*
111 : * Allocate space for "count" objects of type "type"
112 : */
113 : #define palloc_array(type, count) ((type *) palloc_mul(sizeof(type), count))
114 : #define palloc0_array(type, count) ((type *) palloc0_mul(sizeof(type), count))
115 : #define palloc_array_extended(type, count, flags) ((type *) palloc_mul_extended(sizeof(type), count, flags))
116 :
117 : /*
118 : * Change size of allocation pointed to by "pointer" to have space for "count"
119 : * objects of type "type"
120 : */
121 : #define repalloc_array(pointer, type, count) ((type *) repalloc_mul(pointer, sizeof(type), count))
122 : #define repalloc0_array(pointer, type, oldcount, count) ((type *) repalloc0(pointer, mul_size(sizeof(type), oldcount), mul_size(sizeof(type), count)))
123 : #define repalloc_array_extended(pointer, type, count, flags) ((type *) repalloc_mul_extended(pointer, sizeof(type), count, flags))
124 :
125 : /* Higher-limit allocators. */
126 : extern void *MemoryContextAllocHuge(MemoryContext context, Size size);
127 : pg_nodiscard extern void *repalloc_huge(void *pointer, Size size);
128 :
129 : /*
130 : * Although this header file is nominally backend-only, certain frontend
131 : * programs like pg_controldata include it via postgres.h. For some compilers
132 : * it's necessary to hide the inline definition of MemoryContextSwitchTo in
133 : * this scenario; hence the #ifndef FRONTEND.
134 : */
135 :
136 : #ifndef FRONTEND
137 : static inline MemoryContext
138 666187643 : MemoryContextSwitchTo(MemoryContext context)
139 : {
140 666187643 : MemoryContext old = CurrentMemoryContext;
141 :
142 666187643 : CurrentMemoryContext = context;
143 666187643 : return old;
144 : }
145 : #endif /* FRONTEND */
146 :
147 : /* Registration of memory context reset/delete callbacks */
148 : extern void MemoryContextRegisterResetCallback(MemoryContext context,
149 : MemoryContextCallback *cb);
150 : extern void MemoryContextUnregisterResetCallback(MemoryContext context,
151 : MemoryContextCallback *cb);
152 :
153 : /*
154 : * These are like standard strdup() except the copied string is
155 : * allocated in a context, not with malloc().
156 : */
157 : extern char *MemoryContextStrdup(MemoryContext context, const char *string);
158 : extern char *pstrdup(const char *in);
159 : extern char *pnstrdup(const char *in, Size len);
160 :
161 : extern char *pchomp(const char *in);
162 :
163 : /* sprintf into a palloc'd buffer --- these are in psprintf.c */
164 : extern char *psprintf(const char *fmt, ...) pg_attribute_printf(1, 2);
165 : extern size_t pvsnprintf(char *buf, size_t len, const char *fmt, va_list args) pg_attribute_printf(3, 0);
166 :
167 : #endif /* PALLOC_H */
|
