PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
memutils.h
Go to the documentation of this file.
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 
105 #ifdef MEMORY_CONTEXT_CHECKING
106 extern void MemoryContextCheck(MemoryContext context);
107 #endif
108 extern bool MemoryContextContains(MemoryContext context, void *pointer);
109 
110 /*
111  * This routine handles the context-type-independent part of memory
112  * context creation. It's intended to be called from context-type-
113  * specific creation routines, and noplace else.
114  */
115 extern MemoryContext MemoryContextCreate(NodeTag tag, Size size,
116  MemoryContextMethods *methods,
117  MemoryContext parent,
118  const char *name);
119 
120 
121 /*
122  * Memory-context-type-specific functions
123  */
124 
125 /* aset.c */
126 extern MemoryContext AllocSetContextCreate(MemoryContext parent,
127  const char *name,
128  Size minContextSize,
129  Size initBlockSize,
130  Size maxBlockSize);
131 
132 /*
133  * Recommended default alloc parameters, suitable for "ordinary" contexts
134  * that might hold quite a lot of data.
135  */
136 #define ALLOCSET_DEFAULT_MINSIZE 0
137 #define ALLOCSET_DEFAULT_INITSIZE (8 * 1024)
138 #define ALLOCSET_DEFAULT_MAXSIZE (8 * 1024 * 1024)
139 
140 /*
141  * Recommended alloc parameters for "small" contexts that are not expected
142  * to contain much data (for example, a context to contain a query plan).
143  */
144 #define ALLOCSET_SMALL_MINSIZE 0
145 #define ALLOCSET_SMALL_INITSIZE (1 * 1024)
146 #define ALLOCSET_SMALL_MAXSIZE (8 * 1024)
147 
148 #endif /* MEMUTILS_H */