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 

    35 /*

    36  * Raw memory interface

    37  * ====================

    38  */

    39 

    40 /* Functions

    41 

    42    Functions supplying platform-independent semantics for malloc/realloc/

    43    free.  These functions make sure that allocating 0 bytes returns a distinct

    44    non-NULL pointer (whenever possible -- if we're flat out of memory, NULL

    45    may be returned), even if the platform malloc and realloc don't.

    46    Returned pointers must be checked for NULL explicitly.  No action is

    47    performed on failure (no exception is set, no warning is printed, etc).

    48 */

    49 

    50 PyAPI_FUNC(void *) PyMem_Malloc(size_t);

    51 PyAPI_FUNC(void *) PyMem_Realloc(void *, size_t);

    52 PyAPI_FUNC(void) PyMem_Free(void *);

    53 

    54 /* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are

    55    no longer supported. They used to call PyErr_NoMemory() on failure. */

    56 

    57 /* Macros. */

    58 #ifdef PYMALLOC_DEBUG

    59 /* Redirect all memory operations to Python's debugging allocator. */

    60 #define PyMem_MALLOC		PyObject_MALLOC

    61 #define PyMem_REALLOC		PyObject_REALLOC

    62 #define PyMem_FREE		PyObject_FREE

    63 

    64 #else	/* ! PYMALLOC_DEBUG */

    65 

    66 /* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL

    67    for malloc(0), which would be treated as an error. Some platforms

    68    would return a pointer with no memory behind it, which would break

    69    pymalloc. To solve these problems, allocate an extra byte. */

    70 #define PyMem_MALLOC(n)         malloc((n) ? (n) : 1)

    71 #define PyMem_REALLOC(p, n)     realloc((p), (n) ? (n) : 1)

    72 #define PyMem_FREE		free

    73 

    74 #endif	/* PYMALLOC_DEBUG */

    75 

    76 /*

    77  * Type-oriented memory interface

    78  * ==============================

    79  *

    80  * These are carried along for historical reasons.  There's rarely a good

    81  * reason to use them anymore (you can just as easily do the multiply and

    82  * cast yourself).

    83  */

    84 

    85 #define PyMem_New(type, n) \

    86   ( assert((n) <= PY_SIZE_MAX / sizeof(type)) , \

    87 	( (type *) PyMem_Malloc((n) * sizeof(type)) ) )

    88 #define PyMem_NEW(type, n) \

    89   ( assert((n) <= PY_SIZE_MAX / sizeof(type)) , \

    90 	( (type *) PyMem_MALLOC((n) * sizeof(type)) ) )

    91 

    92 #define PyMem_Resize(p, type, n) \

    93   ( assert((n) <= PY_SIZE_MAX / sizeof(type)) , \

    94 	( (p) = (type *) PyMem_Realloc((p), (n) * sizeof(type)) ) )

    95 #define PyMem_RESIZE(p, type, n) \

    96   ( assert((n) <= PY_SIZE_MAX / sizeof(type)) , \

    97 	( (p) = (type *) PyMem_REALLOC((p), (n) * sizeof(type)) ) )

    98 

    99 /* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used

   100  * anymore.  They're just confusing aliases for PyMem_{Free,FREE} now.

   101  */

   102 #define PyMem_Del		PyMem_Free

   103 #define PyMem_DEL		PyMem_FREE

   104 

   105 #ifdef __cplusplus

   106 }

   107 #endif

   108 

   109 #endif /* !Py_PYMEM_H */