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-2008, PostgreSQL Global Development Group
  11  * Portions Copyright (c) 1994, Regents of the University of California
  12  *
  13  * $PostgreSQL$
  14  *
  15  *-------------------------------------------------------------------------
  16  */
  17 #ifndef MEMUTILS_H
  18 #define MEMUTILS_H
  19
  20 #include "nodes/memnodes.h"
  21
  22
  23 /*
  24  * MaxAllocSize
  25  *              Quasi-arbitrary limit on size of allocations.
  26  *
  27  * Note:
  28  *              There is no guarantee that allocations smaller than MaxAllocSize
  29  *              will succeed.  Allocation requests larger than MaxAllocSize will
  30  *              be summarily denied.
  31  *
  32  * XXX This is deliberately chosen to correspond to the limiting size
  33  * of varlena objects under TOAST.      See VARATT_MASK_SIZE in postgres.h.
  34  *
  35  * XXX Also, various places in aset.c assume they can compute twice an
  36  * allocation's size without overflow, so beware of raising this.
  37  */
  38 #define MaxAllocSize    ((Size) 0x3fffffff)             /* 1 gigabyte - 1 */
  39
  40 #define AllocSizeIsValid(size)  ((Size) (size) <= MaxAllocSize)
  41
  42 /*
  43  * All chunks allocated by any memory context manager are required to be
  44  * preceded by a StandardChunkHeader at a spacing of STANDARDCHUNKHEADERSIZE.
  45  * A currently-allocated chunk must contain a backpointer to its owning
  46  * context as well as the allocated size of the chunk.  The backpointer is
  47  * used by pfree() and repalloc() to find the context to call.  The allocated
  48  * size is not absolutely essential, but it's expected to be needed by any
  49  * reasonable implementation.
  50  */
  51 typedef struct StandardChunkHeader
  52 {
  53         MemoryContext context;          /* owning context */
  54         Size            size;                   /* size of data space allocated in chunk */
  55 #ifdef MEMORY_CONTEXT_CHECKING
  56         /* when debugging memory usage, also store actual requested size */
  57         Size            requested_size;
  58 #endif
  59 } StandardChunkHeader;
  60
  61 #define STANDARDCHUNKHEADERSIZE  MAXALIGN(sizeof(StandardChunkHeader))
  62
  63
  64 /*
  65  * Standard top-level memory contexts.
  66  *
  67  * Only TopMemoryContext and ErrorContext are initialized by
  68  * MemoryContextInit() itself.
  69  */
  70 extern PGDLLIMPORT MemoryContext TopMemoryContext;
  71 extern PGDLLIMPORT MemoryContext ErrorContext;
  72 extern PGDLLIMPORT MemoryContext PostmasterContext;
  73 extern PGDLLIMPORT MemoryContext CacheMemoryContext;
  74 extern PGDLLIMPORT MemoryContext MessageContext;
  75 extern PGDLLIMPORT MemoryContext TopTransactionContext;
  76 extern PGDLLIMPORT MemoryContext CurTransactionContext;
  77
  78 /* This is a transient link to the active portal's memory context: */
  79 extern PGDLLIMPORT MemoryContext PortalContext;
  80
  81
  82 /*
  83  * Memory-context-type-independent functions in mcxt.c
  84  */
  85 extern void MemoryContextInit(void);
  86 extern void MemoryContextReset(MemoryContext context);
  87 extern void MemoryContextDelete(MemoryContext context);
  88 extern void MemoryContextResetChildren(MemoryContext context);
  89 extern void MemoryContextDeleteChildren(MemoryContext context);
  90 extern void MemoryContextResetAndDeleteChildren(MemoryContext context);
  91 extern Size GetMemoryChunkSpace(void *pointer);
  92 extern MemoryContext GetMemoryChunkContext(void *pointer);
  93 extern bool MemoryContextIsEmpty(MemoryContext context);
  94 extern void MemoryContextStats(MemoryContext context);
  95
  96 #ifdef MEMORY_CONTEXT_CHECKING
  97 extern void MemoryContextCheck(MemoryContext context);
  98 #endif
  99 extern bool MemoryContextContains(MemoryContext context, void *pointer);
 100
 101 /*
 102  * This routine handles the context-type-independent part of memory
 103  * context creation.  It's intended to be called from context-type-
 104  * specific creation routines, and noplace else.
 105  */
 106 extern MemoryContext MemoryContextCreate(NodeTag tag, Size size,
 107                                         MemoryContextMethods *methods,
 108                                         MemoryContext parent,
 109                                         const char *name);
 110
 111
 112 /*
 113  * Memory-context-type-specific functions
 114  */
 115
 116 /* aset.c */
 117 extern MemoryContext AllocSetContextCreate(MemoryContext parent,
 118                                           const char *name,
 119                                           Size minContextSize,
 120                                           Size initBlockSize,
 121                                           Size maxBlockSize);
 122
 123 /*
 124  * Recommended default alloc parameters, suitable for "ordinary" contexts
 125  * that might hold quite a lot of data.
 126  */
 127 #define ALLOCSET_DEFAULT_MINSIZE   0
 128 #define ALLOCSET_DEFAULT_INITSIZE  (8 * 1024)
 129 #define ALLOCSET_DEFAULT_MAXSIZE   (8 * 1024 * 1024)
 130
 131 /*
 132  * Recommended alloc parameters for "small" contexts that are not expected
 133  * to contain much data (for example, a context to contain a query plan).
 134  */
 135 #define ALLOCSET_SMALL_MINSIZE   0
 136 #define ALLOCSET_SMALL_INITSIZE  (1 * 1024)
 137 #define ALLOCSET_SMALL_MAXSIZE   (8 * 1024)
 138
 139 #endif   /* MEMUTILS_H */