pymem.h 4.03 KB
Newer Older
Tim Peters's avatar
Tim Peters committed
1 2 3
/* The PyMem_ family:  low-level memory allocation interfaces.
   See objimpl.h for the PyObject_ memory family.
*/
4 5 6 7 8 9 10 11 12 13 14 15

#ifndef Py_PYMEM_H
#define Py_PYMEM_H

#include "pyport.h"

#ifdef __cplusplus
extern "C" {
#endif

/* BEWARE:

Tim Peters's avatar
Tim Peters committed
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
   Each interface exports both functions and macros.  Extension modules should
   use the functions, to ensure binary compatibility across Python versions.
   Because the Python implementation is free to change internal details, and
   the macros may (or may not) expose details for speed, if you do use the
   macros you must recompile your extensions with each Python release.

   Never mix calls to PyMem_ with calls to the platform malloc/realloc/
   calloc/free.  For example, on Windows different DLLs may end up using
   different heaps, and if you use PyMem_Malloc you'll get the memory from the
   heap used by the Python DLL; it could be a disaster if you free()'ed that
   directly in your own extension.  Using PyMem_Free instead ensures Python
   can return the memory to the proper heap.  As another example, in
   PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_
   memory functions in special debugging wrappers that add additional
   debugging info to dynamic memory blocks.  The system routines have no idea
   what to do with that stuff, and the Python wrappers have no idea what to do
   with raw blocks obtained directly by the system routines then.
*/
34 35 36 37 38 39

/*
 * Raw memory interface
 * ====================
 */

Tim Peters's avatar
Tim Peters committed
40
/* Functions
41

Tim Peters's avatar
Tim Peters committed
42 43
   Functions supplying platform-independent semantics for malloc/realloc/
   free.  These functions make sure that allocating 0 bytes returns a distinct
44 45 46
   non-NULL pointer (whenever possible -- if we're flat out of memory, NULL
   may be returned), even if the platform malloc and realloc don't.
   Returned pointers must be checked for NULL explicitly.  No action is
Tim Peters's avatar
Tim Peters committed
47 48
   performed on failure (no exception is set, no warning is printed, etc).
*/
49

50 51 52 53 54 55 56
extern DL_IMPORT(void *) PyMem_Malloc(size_t);
extern DL_IMPORT(void *) PyMem_Realloc(void *, size_t);
extern DL_IMPORT(void) PyMem_Free(void *);

/* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are
   no longer supported. They used to call PyErr_NoMemory() on failure. */

57
/* Macros. */
Tim Peters's avatar
Tim Peters committed
58 59 60 61 62 63 64
#ifdef PYMALLOC_DEBUG
/* Redirect all memory operations to Python's debugging allocator. */
#define PyMem_MALLOC		PyObject_MALLOC
#define PyMem_REALLOC		PyObject_REALLOC

#else	/* ! PYMALLOC_DEBUG */

65 66 67 68
#ifdef MALLOC_ZERO_RETURNS_NULL
#define PyMem_MALLOC(n)         malloc((n) ? (n) : 1)
#else
#define PyMem_MALLOC		malloc
69
#endif
Tim Peters's avatar
Tim Peters committed
70

71 72 73 74 75 76
/* Caution:  whether MALLOC_ZERO_RETURNS_NULL is #defined has nothing to
   do with whether platform realloc(non-NULL, 0) normally frees the memory
   or returns NULL.  Rather than introduce yet another config variation,
   just make a realloc to 0 bytes act as if to 1 instead. */
#define PyMem_REALLOC(p, n)     realloc((p), (n) ? (n) : 1)

Tim Peters's avatar
Tim Peters committed
77
#endif	/* PYMALLOC_DEBUG */
78

Tim Peters's avatar
Tim Peters committed
79 80 81 82 83
/* In order to avoid breaking old code mixing PyObject_{New, NEW} with
   PyMem_{Del, DEL} and PyMem_{Free, FREE}, the PyMem "release memory"
   functions have to be redirected to the object deallocator. */
#define PyMem_FREE           	PyObject_FREE

84 85 86
/*
 * Type-oriented memory interface
 * ==============================
87 88
 *
 * These are carried along for historical reasons.  There's rarely a good
Tim Peters's avatar
Tim Peters committed
89 90
 * reason to use them anymore (you can just as easily do the multiply and
 * cast yourself).
91 92 93 94 95
 */

#define PyMem_New(type, n) \
	( (type *) PyMem_Malloc((n) * sizeof(type)) )
#define PyMem_NEW(type, n) \
96
	( (type *) PyMem_MALLOC((n) * sizeof(type)) )
Tim Peters's avatar
Tim Peters committed
97 98 99

#define PyMem_Resize(p, type, n) \
	( (p) = (type *) PyMem_Realloc((p), (n) * sizeof(type)) )
100 101 102
#define PyMem_RESIZE(p, type, n) \
	( (p) = (type *) PyMem_REALLOC((p), (n) * sizeof(type)) )

Tim Peters's avatar
Tim Peters committed
103 104 105 106 107
/* In order to avoid breaking old code mixing PyObject_{New, NEW} with
   PyMem_{Del, DEL} and PyMem_{Free, FREE}, the PyMem "release memory"
   functions have to be redirected to the object deallocator. */
#define PyMem_Del		PyObject_Free
#define PyMem_DEL		PyObject_FREE
108

109 110 111 112 113
#ifdef __cplusplus
}
#endif

#endif /* !Py_PYMEM_H */