src/include/utils/memutils.h

   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-2022, 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 /* Must be less than SIZE_MAX */
  45 #define MaxAllocHugeSize        (SIZE_MAX / 2)
  46
  47 #define InvalidAllocSize        SIZE_MAX
  48
  49 #define AllocHugeSizeIsValid(size)      ((Size) (size) <= MaxAllocHugeSize)
  50
  51
  52 /*
  53  * Standard top-level memory contexts.
  54  *
  55  * Only TopMemoryContext and ErrorContext are initialized by
  56  * MemoryContextInit() itself.
  57  */
  58 extern PGDLLIMPORT MemoryContext TopMemoryContext;
  59 extern PGDLLIMPORT MemoryContext ErrorContext;
  60 extern PGDLLIMPORT MemoryContext PostmasterContext;
  61 extern PGDLLIMPORT MemoryContext CacheMemoryContext;
  62 extern PGDLLIMPORT MemoryContext MessageContext;
  63 extern PGDLLIMPORT MemoryContext TopTransactionContext;
  64 extern PGDLLIMPORT MemoryContext CurTransactionContext;
  65
  66 /* This is a transient link to the active portal's memory context: */
  67 extern PGDLLIMPORT MemoryContext PortalContext;
  68
  69 /* Backwards compatibility macro */
  70 #define MemoryContextResetAndDeleteChildren(ctx) MemoryContextReset(ctx)
  71
  72
  73 /*
  74  * Memory-context-type-independent functions in mcxt.c
  75  */
  76 extern void MemoryContextInit(void);
  77 extern void MemoryContextReset(MemoryContext context);
  78 extern void MemoryContextDelete(MemoryContext context);
  79 extern void MemoryContextResetOnly(MemoryContext context);
  80 extern void MemoryContextResetChildren(MemoryContext context);
  81 extern void MemoryContextDeleteChildren(MemoryContext context);
  82 extern void MemoryContextSetIdentifier(MemoryContext context, const char *id);
  83 extern void MemoryContextSetParent(MemoryContext context,
  84                                                                    MemoryContext new_parent);
  85 extern MemoryContext GetMemoryChunkContext(void *pointer);
  86 extern Size GetMemoryChunkSpace(void *pointer);
  87 extern MemoryContext MemoryContextGetParent(MemoryContext context);
  88 extern bool MemoryContextIsEmpty(MemoryContext context);
  89 extern Size MemoryContextMemAllocated(MemoryContext context, bool recurse);
  90 extern void MemoryContextStats(MemoryContext context);
  91 extern void MemoryContextStatsDetail(MemoryContext context, int max_children,
  92                                                                          bool print_to_stderr);
  93 extern void MemoryContextAllowInCriticalSection(MemoryContext context,
  94                                                                                                 bool allow);
  95
  96 #ifdef MEMORY_CONTEXT_CHECKING
  97 extern void MemoryContextCheck(MemoryContext context);
  98 #endif
  99
 100 /* Handy macro for copying and assigning context ID ... but note double eval */
 101 #define MemoryContextCopyAndSetIdentifier(cxt, id) \
 102         MemoryContextSetIdentifier(cxt, MemoryContextStrdup(cxt, id))
 103
 104 extern void HandleLogMemoryContextInterrupt(void);
 105 extern void ProcessLogMemoryContextInterrupt(void);
 106
 107 /*
 108  * Memory-context-type-specific functions
 109  */
 110
 111 /* aset.c */
 112 extern MemoryContext AllocSetContextCreateInternal(MemoryContext parent,
 113                                                                                                    const char *name,
 114                                                                                                    Size minContextSize,
 115                                                                                                    Size initBlockSize,
 116                                                                                                    Size maxBlockSize);
 117
 118 /*
 119  * This wrapper macro exists to check for non-constant strings used as context
 120  * names; that's no longer supported.  (Use MemoryContextSetIdentifier if you
 121  * want to provide a variable identifier.)
 122  */
 123 #ifdef HAVE__BUILTIN_CONSTANT_P
 124 #define AllocSetContextCreate(parent, name, ...) \
 125         (StaticAssertExpr(__builtin_constant_p(name), \
 126                                           "memory context names must be constant strings"), \
 127          AllocSetContextCreateInternal(parent, name, __VA_ARGS__))
 128 #else
 129 #define AllocSetContextCreate \
 130         AllocSetContextCreateInternal
 131 #endif
 132
 133 /* slab.c */
 134 extern MemoryContext SlabContextCreate(MemoryContext parent,
 135                                                                            const char *name,
 136                                                                            Size blockSize,
 137                                                                            Size chunkSize);
 138
 139 /* generation.c */
 140 extern MemoryContext GenerationContextCreate(MemoryContext parent,
 141                                                                                          const char *name,
 142                                                                                          Size minContextSize,
 143                                                                                          Size initBlockSize,
 144                                                                                          Size maxBlockSize);
 145
 146 /*
 147  * Recommended default alloc parameters, suitable for "ordinary" contexts
 148  * that might hold quite a lot of data.
 149  */
 150 #define ALLOCSET_DEFAULT_MINSIZE   0
 151 #define ALLOCSET_DEFAULT_INITSIZE  (8 * 1024)
 152 #define ALLOCSET_DEFAULT_MAXSIZE   (8 * 1024 * 1024)
 153 #define ALLOCSET_DEFAULT_SIZES \
 154         ALLOCSET_DEFAULT_MINSIZE, ALLOCSET_DEFAULT_INITSIZE, ALLOCSET_DEFAULT_MAXSIZE
 155
 156 /*
 157  * Recommended alloc parameters for "small" contexts that are never expected
 158  * to contain much data (for example, a context to contain a query plan).
 159  */
 160 #define ALLOCSET_SMALL_MINSIZE   0
 161 #define ALLOCSET_SMALL_INITSIZE  (1 * 1024)
 162 #define ALLOCSET_SMALL_MAXSIZE   (8 * 1024)
 163 #define ALLOCSET_SMALL_SIZES \
 164         ALLOCSET_SMALL_MINSIZE, ALLOCSET_SMALL_INITSIZE, ALLOCSET_SMALL_MAXSIZE
 165
 166 /*
 167  * Recommended alloc parameters for contexts that should start out small,
 168  * but might sometimes grow big.
 169  */
 170 #define ALLOCSET_START_SMALL_SIZES \
 171         ALLOCSET_SMALL_MINSIZE, ALLOCSET_SMALL_INITSIZE, ALLOCSET_DEFAULT_MAXSIZE
 172
 173
 174 /*
 175  * Threshold above which a request in an AllocSet context is certain to be
 176  * allocated separately (and thereby have constant allocation overhead).
 177  * Few callers should be interested in this, but tuplesort/tuplestore need
 178  * to know it.
 179  */
 180 #define ALLOCSET_SEPARATE_THRESHOLD  8192
 181
 182 #define SLAB_DEFAULT_BLOCK_SIZE         (8 * 1024)
 183 #define SLAB_LARGE_BLOCK_SIZE           (8 * 1024 * 1024)
 184
 185 #endif                                                  /* MEMUTILS_H */