• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* The PyMem_ family:  low-level memory allocation interfaces.
2    See objimpl.h for the PyObject_ memory family.
3 */
4 
5 #ifndef Py_PYMEM_H
6 #define Py_PYMEM_H
7 
8 #include "pyport.h"
9 
10 #ifdef __cplusplus
11 extern "C" {
12 #endif
13 
14 /* BEWARE:
15 
16    Each interface exports both functions and macros.  Extension modules should
17    use the functions, to ensure binary compatibility across Python versions.
18    Because the Python implementation is free to change internal details, and
19    the macros may (or may not) expose details for speed, if you do use the
20    macros you must recompile your extensions with each Python release.
21 
22    Never mix calls to PyMem_ with calls to the platform malloc/realloc/
23    calloc/free.  For example, on Windows different DLLs may end up using
24    different heaps, and if you use PyMem_Malloc you'll get the memory from the
25    heap used by the Python DLL; it could be a disaster if you free()'ed that
26    directly in your own extension.  Using PyMem_Free instead ensures Python
27    can return the memory to the proper heap.  As another example, in
28    PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_
29    memory functions in special debugging wrappers that add additional
30    debugging info to dynamic memory blocks.  The system routines have no idea
31    what to do with that stuff, and the Python wrappers have no idea what to do
32    with raw blocks obtained directly by the system routines then.
33 
34    The GIL must be held when using these APIs.
35 */
36 
37 /*
38  * Raw memory interface
39  * ====================
40  */
41 
42 /* Functions
43 
44    Functions supplying platform-independent semantics for malloc/realloc/
45    free.  These functions make sure that allocating 0 bytes returns a distinct
46    non-NULL pointer (whenever possible -- if we're flat out of memory, NULL
47    may be returned), even if the platform malloc and realloc don't.
48    Returned pointers must be checked for NULL explicitly.  No action is
49    performed on failure (no exception is set, no warning is printed, etc).
50 */
51 
52 PyAPI_FUNC(void *) PyMem_Malloc(size_t);
53 PyAPI_FUNC(void *) PyMem_Realloc(void *, size_t);
54 PyAPI_FUNC(void) PyMem_Free(void *);
55 
56 /* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are
57    no longer supported. They used to call PyErr_NoMemory() on failure. */
58 
59 /* Macros. */
60 #ifdef PYMALLOC_DEBUG
61 /* Redirect all memory operations to Python's debugging allocator. */
62 #define PyMem_MALLOC		_PyMem_DebugMalloc
63 #define PyMem_REALLOC		_PyMem_DebugRealloc
64 #define PyMem_FREE		_PyMem_DebugFree
65 
66 #else	/* ! PYMALLOC_DEBUG */
67 
68 /* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL
69    for malloc(0), which would be treated as an error. Some platforms
70    would return a pointer with no memory behind it, which would break
71    pymalloc. To solve these problems, allocate an extra byte. */
72 /* Returns NULL to indicate error if a negative size or size larger than
73    Py_ssize_t can represent is supplied.  Helps prevents security holes. */
74 #define PyMem_MALLOC(n)		((size_t)(n) > (size_t)PY_SSIZE_T_MAX ? NULL \
75 				: malloc((n) ? (n) : 1))
76 #define PyMem_REALLOC(p, n)	((size_t)(n) > (size_t)PY_SSIZE_T_MAX  ? NULL \
77 				: realloc((p), (n) ? (n) : 1))
78 #define PyMem_FREE		free
79 
80 #endif	/* PYMALLOC_DEBUG */
81 
82 /*
83  * Type-oriented memory interface
84  * ==============================
85  *
86  * Allocate memory for n objects of the given type.  Returns a new pointer
87  * or NULL if the request was too large or memory allocation failed.  Use
88  * these macros rather than doing the multiplication yourself so that proper
89  * overflow checking is always done.
90  */
91 
92 #define PyMem_New(type, n) \
93   ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :	\
94 	( (type *) PyMem_Malloc((n) * sizeof(type)) ) )
95 #define PyMem_NEW(type, n) \
96   ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :	\
97 	( (type *) PyMem_MALLOC((n) * sizeof(type)) ) )
98 
99 /*
100  * The value of (p) is always clobbered by this macro regardless of success.
101  * The caller MUST check if (p) is NULL afterwards and deal with the memory
102  * error if so.  This means the original value of (p) MUST be saved for the
103  * caller's memory error handler to not lose track of it.
104  */
105 #define PyMem_Resize(p, type, n) \
106   ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :	\
107 	(type *) PyMem_Realloc((p), (n) * sizeof(type)) )
108 #define PyMem_RESIZE(p, type, n) \
109   ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :	\
110 	(type *) PyMem_REALLOC((p), (n) * sizeof(type)) )
111 
112 /* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used
113  * anymore.  They're just confusing aliases for PyMem_{Free,FREE} now.
114  */
115 #define PyMem_Del		PyMem_Free
116 #define PyMem_DEL		PyMem_FREE
117 
118 #ifdef __cplusplus
119 }
120 #endif
121 
122 #endif /* !Py_PYMEM_H */
123