include/python3.12/pymem.h

0001 /* The PyMem_ family:  low-level memory allocation interfaces.
0002    See objimpl.h for the PyObject_ memory family.
0003 */
0004
0005 #ifndef Py_PYMEM_H
0006 #define Py_PYMEM_H
0007
0008 #include "pyport.h"
0009
0010 #ifdef __cplusplus
0011 extern "C" {
0012 #endif
0013
0014 /* BEWARE:
0015
0016    Each interface exports both functions and macros.  Extension modules should
0017    use the functions, to ensure binary compatibility across Python versions.
0018    Because the Python implementation is free to change internal details, and
0019    the macros may (or may not) expose details for speed, if you do use the
0020    macros you must recompile your extensions with each Python release.
0021
0022    Never mix calls to PyMem_ with calls to the platform malloc/realloc/
0023    calloc/free.  For example, on Windows different DLLs may end up using
0024    different heaps, and if you use PyMem_Malloc you'll get the memory from the
0025    heap used by the Python DLL; it could be a disaster if you free()'ed that
0026    directly in your own extension.  Using PyMem_Free instead ensures Python
0027    can return the memory to the proper heap.  As another example, in
0028    a debug build (Py_DEBUG macro), Python wraps all calls to all PyMem_ and
0029    PyObject_ memory functions in special debugging wrappers that add additional
0030    debugging info to dynamic memory blocks.  The system routines have no idea
0031    what to do with that stuff, and the Python wrappers have no idea what to do
0032    with raw blocks obtained directly by the system routines then.
0033
0034    The GIL must be held when using these APIs.
0035 */
0036
0037 /*
0038  * Raw memory interface
0039  * ====================
0040  */
0041
0042 /* Functions
0043
0044    Functions supplying platform-independent semantics for malloc/realloc/
0045    free.  These functions make sure that allocating 0 bytes returns a distinct
0046    non-NULL pointer (whenever possible -- if we're flat out of memory, NULL
0047    may be returned), even if the platform malloc and realloc don't.
0048    Returned pointers must be checked for NULL explicitly.  No action is
0049    performed on failure (no exception is set, no warning is printed, etc).
0050 */
0051
0052 PyAPI_FUNC(void *) PyMem_Malloc(size_t size);
0053 PyAPI_FUNC(void *) PyMem_Calloc(size_t nelem, size_t elsize);
0054 PyAPI_FUNC(void *) PyMem_Realloc(void *ptr, size_t new_size);
0055 PyAPI_FUNC(void) PyMem_Free(void *ptr);
0056
0057 /*
0058  * Type-oriented memory interface
0059  * ==============================
0060  *
0061  * Allocate memory for n objects of the given type.  Returns a new pointer
0062  * or NULL if the request was too large or memory allocation failed.  Use
0063  * these macros rather than doing the multiplication yourself so that proper
0064  * overflow checking is always done.
0065  */
0066
0067 #define PyMem_New(type, n) \
0068   ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :      \
0069         ( (type *) PyMem_Malloc((n) * sizeof(type)) ) )
0070
0071 /*
0072  * The value of (p) is always clobbered by this macro regardless of success.
0073  * The caller MUST check if (p) is NULL afterwards and deal with the memory
0074  * error if so.  This means the original value of (p) MUST be saved for the
0075  * caller's memory error handler to not lose track of it.
0076  */
0077 #define PyMem_Resize(p, type, n) \
0078   ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL :        \
0079         (type *) PyMem_Realloc((p), (n) * sizeof(type)) )
0080
0081
0082 // Deprecated aliases only kept for backward compatibility.
0083 // PyMem_Del and PyMem_DEL are defined with no parameter to be able to use
0084 // them as function pointers (ex: dealloc = PyMem_Del).
0085 #define PyMem_MALLOC(n)           PyMem_Malloc((n))
0086 #define PyMem_NEW(type, n)        PyMem_New(type, (n))
0087 #define PyMem_REALLOC(p, n)       PyMem_Realloc((p), (n))
0088 #define PyMem_RESIZE(p, type, n)  PyMem_Resize((p), type, (n))
0089 #define PyMem_FREE(p)             PyMem_Free((p))
0090 #define PyMem_Del(p)              PyMem_Free((p))
0091 #define PyMem_DEL(p)              PyMem_Free((p))
0092
0093
0094 #ifndef Py_LIMITED_API
0095 #  define Py_CPYTHON_PYMEM_H
0096 #  include "cpython/pymem.h"
0097 #  undef Py_CPYTHON_PYMEM_H
0098 #endif
0099
0100 #ifdef __cplusplus
0101 }
0102 #endif
0103
0104 #endif /* !Py_PYMEM_H */