1 /*------------------------------------------------------------------------- 2 * 3 * memutils.h 4 * This file contains declarations for memory allocation utility 5 * functions. These are functions that are not quite widely used 6 * enough to justify going in utils/palloc.h, but are still part 7 * of the API of the memory management subsystem. 8 * 9 * 10 * Portions Copyright (c) 1996-2016, PostgreSQL Global Development Group 11 * Portions Copyright (c) 1994, Regents of the University of California 12 * 13 * src/include/utils/memutils.h 14 * 15 *------------------------------------------------------------------------- 16 */ 17 #ifndef MEMUTILS_H 18 #define MEMUTILS_H 19 20 #include "nodes/memnodes.h" 21 22 23 /* 24 * MaxAllocSize, MaxAllocHugeSize 25 * Quasi-arbitrary limits on size of allocations. 26 * 27 * Note: 28 * There is no guarantee that smaller allocations will succeed, but 29 * larger requests will be summarily denied. 30 * 31 * palloc() enforces MaxAllocSize, chosen to correspond to the limiting size 32 * of varlena objects under TOAST. See VARSIZE_4B() and related macros in 33 * postgres.h. Many datatypes assume that any allocatable size can be 34 * represented in a varlena header. This limit also permits a caller to use 35 * an "int" variable for an index into or length of an allocation. Callers 36 * careful to avoid these hazards can access the higher limit with 37 * MemoryContextAllocHuge(). Both limits permit code to assume that it may 38 * compute twice an allocation's size without overflow. 39 */ 40 #define MaxAllocSize ((Size) 0x3fffffff) /* 1 gigabyte - 1 */ 41 42 #define AllocSizeIsValid(size) ((Size) (size) <= MaxAllocSize) 43 44 #define MaxAllocHugeSize (SIZE_MAX / 2) 45 46 #define AllocHugeSizeIsValid(size) ((Size) (size) <= MaxAllocHugeSize) 47 48 /* 49 * All chunks allocated by any memory context manager are required to be 50 * preceded by a StandardChunkHeader at a spacing of STANDARDCHUNKHEADERSIZE. 51 * A currently-allocated chunk must contain a backpointer to its owning 52 * context as well as the allocated size of the chunk. The backpointer is 53 * used by pfree() and repalloc() to find the context to call. The allocated 54 * size is not absolutely essential, but it's expected to be needed by any 55 * reasonable implementation. 56 */ 57 typedef struct StandardChunkHeader 58 { 59 MemoryContext context; /* owning context */ 60 Size size; /* size of data space allocated in chunk */ 61 #ifdef MEMORY_CONTEXT_CHECKING 62 /* when debugging memory usage, also store actual requested size */ 63 Size requested_size; 64 #endif 65 } StandardChunkHeader; 66 67 #define STANDARDCHUNKHEADERSIZE MAXALIGN(sizeof(StandardChunkHeader)) 68 69 70 /* 71 * Standard top-level memory contexts. 72 * 73 * Only TopMemoryContext and ErrorContext are initialized by 74 * MemoryContextInit() itself. 75 */ 76 extern PGDLLIMPORT MemoryContext TopMemoryContext; 77 extern PGDLLIMPORT MemoryContext ErrorContext; 78 extern PGDLLIMPORT MemoryContext PostmasterContext; 79 extern PGDLLIMPORT MemoryContext CacheMemoryContext; 80 extern PGDLLIMPORT MemoryContext MessageContext; 81 extern PGDLLIMPORT MemoryContext TopTransactionContext; 82 extern PGDLLIMPORT MemoryContext CurTransactionContext; 83 84 /* This is a transient link to the active portal's memory context: */ 85 extern PGDLLIMPORT MemoryContext PortalContext; 86 87 /* Backwards compatibility macro */ 88 #define MemoryContextResetAndDeleteChildren(ctx) MemoryContextReset(ctx) 89 90 91 /* 92 * Memory-context-type-independent functions in mcxt.c 93 */ 94 extern void MemoryContextInit(void); 95 extern void MemoryContextReset(MemoryContext context); 96 extern void MemoryContextDelete(MemoryContext context); 97 extern void MemoryContextResetOnly(MemoryContext context); 98 extern void MemoryContextResetChildren(MemoryContext context); 99 extern void MemoryContextDeleteChildren(MemoryContext context); 100 extern void MemoryContextSetParent(MemoryContext context, 101 MemoryContext new_parent); 102 extern Size GetMemoryChunkSpace(void *pointer); 103 extern MemoryContext GetMemoryChunkContext(void *pointer); 104 extern MemoryContext MemoryContextGetParent(MemoryContext context); 105 extern bool MemoryContextIsEmpty(MemoryContext context); 106 extern void MemoryContextStats(MemoryContext context); 107 extern void MemoryContextStatsDetail(MemoryContext context, int max_children); 108 extern void MemoryContextAllowInCriticalSection(MemoryContext context, 109 bool allow); 110 111 #ifdef MEMORY_CONTEXT_CHECKING 112 extern void MemoryContextCheck(MemoryContext context); 113 #endif 114 extern bool MemoryContextContains(MemoryContext context, void *pointer); 115 116 /* 117 * This routine handles the context-type-independent part of memory 118 * context creation. It's intended to be called from context-type- 119 * specific creation routines, and noplace else. 120 */ 121 extern MemoryContext MemoryContextCreate(NodeTag tag, Size size, 122 MemoryContextMethods *methods, 123 MemoryContext parent, 124 const char *name); 125 126 127 /* 128 * Memory-context-type-specific functions 129 */ 130 131 /* aset.c */ 132 extern MemoryContext AllocSetContextCreate(MemoryContext parent, 133 const char *name, 134 Size minContextSize, 135 Size initBlockSize, 136 Size maxBlockSize); 137 138 /* 139 * Recommended default alloc parameters, suitable for "ordinary" contexts 140 * that might hold quite a lot of data. 141 */ 142 #define ALLOCSET_DEFAULT_MINSIZE 0 143 #define ALLOCSET_DEFAULT_INITSIZE (8 * 1024) 144 #define ALLOCSET_DEFAULT_MAXSIZE (8 * 1024 * 1024) 145 #define ALLOCSET_DEFAULT_SIZES \ 146 ALLOCSET_DEFAULT_MINSIZE, ALLOCSET_DEFAULT_INITSIZE, ALLOCSET_DEFAULT_MAXSIZE 147 148 /* 149 * Recommended alloc parameters for "small" contexts that are never expected 150 * to contain much data (for example, a context to contain a query plan). 151 */ 152 #define ALLOCSET_SMALL_MINSIZE 0 153 #define ALLOCSET_SMALL_INITSIZE (1 * 1024) 154 #define ALLOCSET_SMALL_MAXSIZE (8 * 1024) 155 #define ALLOCSET_SMALL_SIZES \ 156 ALLOCSET_SMALL_MINSIZE, ALLOCSET_SMALL_INITSIZE, ALLOCSET_SMALL_MAXSIZE 157 158 /* 159 * Recommended alloc parameters for contexts that should start out small, 160 * but might sometimes grow big. 161 */ 162 #define ALLOCSET_START_SMALL_SIZES \ 163 ALLOCSET_SMALL_MINSIZE, ALLOCSET_SMALL_INITSIZE, ALLOCSET_DEFAULT_MAXSIZE 164 165 166 /* 167 * Threshold above which a request in an AllocSet context is certain to be 168 * allocated separately (and thereby have constant allocation overhead). 169 * Few callers should be interested in this, but tuplesort/tuplestore need 170 * to know it. 171 */ 172 #define ALLOCSET_SEPARATE_THRESHOLD 8192 173 174 #endif /* MEMUTILS_H */ 175