Age Owner Branch data TLA 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-2024, 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 : : extern pg_nodiscard void *repalloc(void *pointer, Size size);
83 : : extern pg_nodiscard void *repalloc_extended(void *pointer,
84 : : Size size, int flags);
85 : : extern pg_nodiscard void *repalloc0(void *pointer, Size oldsize, Size size);
86 : : extern 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. */
112 : : extern void *MemoryContextAllocHuge(MemoryContext context, Size size);
113 : : extern 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
123 : : static inline MemoryContext
6995 tgl@sss.pgh.pa.us 124 :CBC 429399665 : MemoryContextSwitchTo(MemoryContext context)
125 : : {
126 : 429399665 : MemoryContext old = CurrentMemoryContext;
127 : :
128 : 429399665 : CurrentMemoryContext = context;
129 : 429399665 : return old;
130 : : }
131 : : #endif /* FRONTEND */
132 : :
133 : : /* Registration of memory context reset/delete callbacks */
134 : : extern void MemoryContextRegisterResetCallback(MemoryContext context,
135 : : MemoryContextCallback *cb);
136 : :
137 : : /*
138 : : * These are like standard strdup() except the copied string is
139 : : * allocated in a context, not with malloc().
140 : : */
141 : : extern char *MemoryContextStrdup(MemoryContext context, const char *string);
142 : : extern char *pstrdup(const char *in);
143 : : extern char *pnstrdup(const char *in, Size len);
144 : :
145 : : extern char *pchomp(const char *in);
146 : :
147 : : /* sprintf into a palloc'd buffer --- these are in psprintf.c */
148 : : extern char *psprintf(const char *fmt,...) pg_attribute_printf(1, 2);
149 : : extern size_t pvsnprintf(char *buf, size_t len, const char *fmt, va_list args) pg_attribute_printf(3, 0);
150 : :
151 : : #endif /* PALLOC_H */
|
