Chris@87: /* The PyMem_ family:  low-level memory allocation interfaces.
Chris@87:    See objimpl.h for the PyObject_ memory family.
Chris@87: */
Chris@87: 
Chris@87: #ifndef Py_PYMEM_H
Chris@87: #define Py_PYMEM_H
Chris@87: 
Chris@87: #include "pyport.h"
Chris@87: 
Chris@87: #ifdef __cplusplus
Chris@87: extern "C" {
Chris@87: #endif
Chris@87: 
Chris@87: /* BEWARE:
Chris@87: 
Chris@87:    Each interface exports both functions and macros.  Extension modules should
Chris@87:    use the functions, to ensure binary compatibility across Python versions.
Chris@87:    Because the Python implementation is free to change internal details, and
Chris@87:    the macros may (or may not) expose details for speed, if you do use the
Chris@87:    macros you must recompile your extensions with each Python release.
Chris@87: 
Chris@87:    Never mix calls to PyMem_ with calls to the platform malloc/realloc/
Chris@87:    calloc/free.  For example, on Windows different DLLs may end up using
Chris@87:    different heaps, and if you use PyMem_Malloc you'll get the memory from the
Chris@87:    heap used by the Python DLL; it could be a disaster if you free()'ed that
Chris@87:    directly in your own extension.  Using PyMem_Free instead ensures Python
Chris@87:    can return the memory to the proper heap.  As another example, in
Chris@87:    PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_
Chris@87:    memory functions in special debugging wrappers that add additional
Chris@87:    debugging info to dynamic memory blocks.  The system routines have no idea
Chris@87:    what to do with that stuff, and the Python wrappers have no idea what to do
Chris@87:    with raw blocks obtained directly by the system routines then.
Chris@87: 
Chris@87:    The GIL must be held when using these APIs.
Chris@87: */
Chris@87: 
Chris@87: /*
Chris@87:  * Raw memory interface
Chris@87:  * ====================
Chris@87:  */
Chris@87: 
Chris@87: /* Functions
Chris@87: 
Chris@87:    Functions supplying platform-independent semantics for malloc/realloc/
Chris@87:    free.  These functions make sure that allocating 0 bytes returns a distinct
Chris@87:    non-NULL pointer (whenever possible -- if we're flat out of memory, NULL
Chris@87:    may be returned), even if the platform malloc and realloc don't.
Chris@87:    Returned pointers must be checked for NULL explicitly.  No action is
Chris@87:    performed on failure (no exception is set, no warning is printed, etc).
Chris@87: */
Chris@87: 
Chris@87: PyAPI_FUNC(void *) PyMem_Malloc(size_t);
Chris@87: PyAPI_FUNC(void *) PyMem_Realloc(void *, size_t);
Chris@87: PyAPI_FUNC(void) PyMem_Free(void *);
Chris@87: 
Chris@87: /* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are
Chris@87:    no longer supported. They used to call PyErr_NoMemory() on failure. */
Chris@87: 
Chris@87: /* Macros. */
Chris@87: #ifdef PYMALLOC_DEBUG
Chris@87: /* Redirect all memory operations to Python's debugging allocator. */
Chris@87: #define PyMem_MALLOC		_PyMem_DebugMalloc
Chris@87: #define PyMem_REALLOC		_PyMem_DebugRealloc
Chris@87: #define PyMem_FREE		_PyMem_DebugFree
Chris@87: 
Chris@87: #else	/* ! PYMALLOC_DEBUG */
Chris@87: 
Chris@87: /* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL
Chris@87:    for malloc(0), which would be treated as an error. Some platforms
Chris@87:    would return a pointer with no memory behind it, which would break
Chris@87:    pymalloc. To solve these problems, allocate an extra byte. */
Chris@87: /* Returns NULL to indicate error if a negative size or size larger than
Chris@87:    Py_ssize_t can represent is supplied.  Helps prevents security holes. */
Chris@87: #define PyMem_MALLOC(n)		((size_t)(n) > (size_t)PY_SSIZE_T_MAX ? NULL \
Chris@87: 				: malloc((n) ? (n) : 1))
Chris@87: #define PyMem_REALLOC(p, n)	((size_t)(n) > (size_t)PY_SSIZE_T_MAX  ? NULL \
Chris@87: 				: realloc((p), (n) ? (n) : 1))
Chris@87: #define PyMem_FREE		free
Chris@87: 
Chris@87: #endif	/* PYMALLOC_DEBUG */
Chris@87: 
Chris@87: /*
Chris@87:  * Type-oriented memory interface
Chris@87:  * ==============================
Chris@87:  *
Chris@87:  * Allocate memory for n objects of the given type.  Returns a new pointer
Chris@87:  * or NULL if the request was too large or memory allocation failed.  Use
Chris@87:  * these macros rather than doing the multiplication yourself so that proper
Chris@87:  * overflow checking is always done.
Chris@87:  */
Chris@87: 
Chris@87: #define PyMem_New(type, n) \
Chris@87:   ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :	\
Chris@87: 	( (type *) PyMem_Malloc((n) * sizeof(type)) ) )
Chris@87: #define PyMem_NEW(type, n) \
Chris@87:   ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :	\
Chris@87: 	( (type *) PyMem_MALLOC((n) * sizeof(type)) ) )
Chris@87: 
Chris@87: /*
Chris@87:  * The value of (p) is always clobbered by this macro regardless of success.
Chris@87:  * The caller MUST check if (p) is NULL afterwards and deal with the memory
Chris@87:  * error if so.  This means the original value of (p) MUST be saved for the
Chris@87:  * caller's memory error handler to not lose track of it.
Chris@87:  */
Chris@87: #define PyMem_Resize(p, type, n) \
Chris@87:   ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :	\
Chris@87: 	(type *) PyMem_Realloc((p), (n) * sizeof(type)) )
Chris@87: #define PyMem_RESIZE(p, type, n) \
Chris@87:   ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :	\
Chris@87: 	(type *) PyMem_REALLOC((p), (n) * sizeof(type)) )
Chris@87: 
Chris@87: /* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used
Chris@87:  * anymore.  They're just confusing aliases for PyMem_{Free,FREE} now.
Chris@87:  */
Chris@87: #define PyMem_Del		PyMem_Free
Chris@87: #define PyMem_DEL		PyMem_FREE
Chris@87: 
Chris@87: #ifdef __cplusplus
Chris@87: }
Chris@87: #endif
Chris@87: 
Chris@87: #endif /* !Py_PYMEM_H */