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-2016, 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 *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 void *repalloc(void *pointer, Size size);
81 extern void pfree(void *pointer);
82
83 /*
84 * The result of palloc() is always word-aligned, so we can skip testing
85 * alignment of the pointer when deciding which MemSet variant to use.
86 * Note that this variant does not offer any advantage, and should not be
87 * used, unless its "sz" argument is a compile-time constant; therefore, the
88 * issue that it evaluates the argument multiple times isn't a problem in
89 * practice.
90 */
91 #define palloc0fast(sz) \
92 ( MemSetTest(0, sz) ? \
93 MemoryContextAllocZeroAligned(CurrentMemoryContext, sz) : \
94 MemoryContextAllocZero(CurrentMemoryContext, sz) )
95
96 /* Higher-limit allocators. */
97 extern void *MemoryContextAllocHuge(MemoryContext context, Size size);
98 extern void *repalloc_huge(void *pointer, Size size);
99
100 /*
101 * Although this header file is nominally backend-only, certain frontend
102 * programs like pg_controldata include it via postgres.h. For some compilers
103 * it's necessary to hide the inline definition of MemoryContextSwitchTo in
104 * this scenario; hence the #ifndef FRONTEND.
105 */
106
107 #ifndef FRONTEND
108 static inline MemoryContext
MemoryContextSwitchTo(MemoryContext context)109 MemoryContextSwitchTo(MemoryContext context)
110 {
111 MemoryContext old = CurrentMemoryContext;
112
113 CurrentMemoryContext = context;
114 return old;
115 }
116 #endif /* FRONTEND */
117
118 /* Registration of memory context reset/delete callbacks */
119 extern void MemoryContextRegisterResetCallback(MemoryContext context,
120 MemoryContextCallback *cb);
121
122 /*
123 * These are like standard strdup() except the copied string is
124 * allocated in a context, not with malloc().
125 */
126 extern char *MemoryContextStrdup(MemoryContext context, const char *string);
127 extern char *pstrdup(const char *in);
128 extern char *pnstrdup(const char *in, Size len);
129
130 /* sprintf into a palloc'd buffer --- these are in psprintf.c */
131 extern char *psprintf(const char *fmt,...) pg_attribute_printf(1, 2);
132 extern size_t pvsnprintf(char *buf, size_t len, const char *fmt, va_list args) pg_attribute_printf(3, 0);
133
134 #endif /* PALLOC_H */
135