granicus.if.org Git - postgresql/blob - 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-2014, 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) -1 >> 1)        /* 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
  88 /*
  89  * Memory-context-type-independent functions in mcxt.c
  90  */
  91 extern void MemoryContextInit(void);
  92 extern void MemoryContextReset(MemoryContext context);
  93 extern void MemoryContextDelete(MemoryContext context);
  94 extern void MemoryContextResetChildren(MemoryContext context);
  95 extern void MemoryContextDeleteChildren(MemoryContext context);
  96 extern void MemoryContextResetAndDeleteChildren(MemoryContext context);
  97 extern void MemoryContextSetParent(MemoryContext context,
  98                                            MemoryContext new_parent);
  99 extern Size GetMemoryChunkSpace(void *pointer);
 100 extern MemoryContext GetMemoryChunkContext(void *pointer);
 101 extern MemoryContext MemoryContextGetParent(MemoryContext context);
 102 extern bool MemoryContextIsEmpty(MemoryContext context);
 103 extern void MemoryContextStats(MemoryContext context);
 104 extern void MemoryContextAllowInCriticalSection(MemoryContext context,
 105                                                                         bool allow);
 106
 107 #ifdef MEMORY_CONTEXT_CHECKING
 108 extern void MemoryContextCheck(MemoryContext context);
 109 #endif
 110 extern bool MemoryContextContains(MemoryContext context, void *pointer);
 111
 112 /*
 113  * This routine handles the context-type-independent part of memory
 114  * context creation.  It's intended to be called from context-type-
 115  * specific creation routines, and noplace else.
 116  */
 117 extern MemoryContext MemoryContextCreate(NodeTag tag, Size size,
 118                                         MemoryContextMethods *methods,
 119                                         MemoryContext parent,
 120                                         const char *name);
 121
 122
 123 /*
 124  * Memory-context-type-specific functions
 125  */
 126
 127 /* aset.c */
 128 extern MemoryContext AllocSetContextCreate(MemoryContext parent,
 129                                           const char *name,
 130                                           Size minContextSize,
 131                                           Size initBlockSize,
 132                                           Size maxBlockSize);
 133
 134 /*
 135  * Recommended default alloc parameters, suitable for "ordinary" contexts
 136  * that might hold quite a lot of data.
 137  */
 138 #define ALLOCSET_DEFAULT_MINSIZE   0
 139 #define ALLOCSET_DEFAULT_INITSIZE  (8 * 1024)
 140 #define ALLOCSET_DEFAULT_MAXSIZE   (8 * 1024 * 1024)
 141
 142 /*
 143  * Recommended alloc parameters for "small" contexts that are not expected
 144  * to contain much data (for example, a context to contain a query plan).
 145  */
 146 #define ALLOCSET_SMALL_MINSIZE   0
 147 #define ALLOCSET_SMALL_INITSIZE  (1 * 1024)
 148 #define ALLOCSET_SMALL_MAXSIZE   (8 * 1024)
 149
 150 #endif   /* MEMUTILS_H */