blob: 71fc8b58d8404effc249721f95af5a2105601f3a [file] [log] [blame]
Peter Schneider-Kamp25f68942000-07-31 22:19:30 +00001
2/* Lowest-level memory allocation interface */
3
4#ifndef Py_PYMEM_H
5#define Py_PYMEM_H
6
7#include "pyport.h"
8
9#ifdef __cplusplus
10extern "C" {
11#endif
12
13/*
14 * Core memory allocator
15 * =====================
16 */
17
18/* To make sure the interpreter is user-malloc friendly, all memory
19 APIs are implemented on top of this one.
20
21 The PyCore_* macros can be defined to make the interpreter use a
22 custom allocator. Note that they are for internal use only. Both
23 the core and extension modules should use the PyMem_* API.
24
25 See the comment block at the end of this file for two scenarios
26 showing how to use this to use a different allocator. */
27
28#ifndef PyCore_MALLOC_FUNC
29#undef PyCore_REALLOC_FUNC
30#undef PyCore_FREE_FUNC
31#define PyCore_MALLOC_FUNC malloc
32#define PyCore_REALLOC_FUNC realloc
33#define PyCore_FREE_FUNC free
34#endif
35
36#ifndef PyCore_MALLOC_PROTO
37#undef PyCore_REALLOC_PROTO
38#undef PyCore_FREE_PROTO
39#define PyCore_MALLOC_PROTO (size_t)
40#define PyCore_REALLOC_PROTO (void *, size_t)
41#define PyCore_FREE_PROTO (void *)
42#endif
43
44#ifdef NEED_TO_DECLARE_MALLOC_AND_FRIEND
45extern void *PyCore_MALLOC_FUNC PyCore_MALLOC_PROTO;
46extern void *PyCore_REALLOC_FUNC PyCore_REALLOC_PROTO;
47extern void PyCore_FREE_FUNC PyCore_FREE_PROTO;
48#endif
49
50#ifndef PyCore_MALLOC
51#undef PyCore_REALLOC
52#undef PyCore_FREE
53#define PyCore_MALLOC(n) PyCore_MALLOC_FUNC(n)
54#define PyCore_REALLOC(p, n) PyCore_REALLOC_FUNC((p), (n))
55#define PyCore_FREE(p) PyCore_FREE_FUNC(p)
56#endif
57
58/* BEWARE:
59
60 Each interface exports both functions and macros. Extension modules
61 should normally use the functions for ensuring binary compatibility
62 of the user's code across Python versions. Subsequently, if the
63 Python runtime switches to its own malloc (different from standard
64 malloc), no recompilation is required for the extensions.
65
66 The macro versions trade compatibility for speed. They can be used
67 whenever there is a performance problem, but their use implies
68 recompilation of the code for each new Python release. The Python
69 core uses the macros because it *is* compiled on every upgrade.
70 This might not be the case with 3rd party extensions in a custom
71 setup (for example, a customer does not always have access to the
72 source of 3rd party deliverables). You have been warned! */
73
74/*
75 * Raw memory interface
76 * ====================
77 */
78
79/* Functions */
80
81/* Function wrappers around PyCore_MALLOC and friends; useful if you
82 need to be sure that you are using the same memory allocator as
83 Python. Note that the wrappers make sure that allocating 0 bytes
84 returns a non-NULL pointer, even if the underlying malloc
85 doesn't. Returned pointers must be checked for NULL explicitly.
86 No action is performed on failure. */
87extern DL_IMPORT(void *) PyMem_Malloc(size_t);
88extern DL_IMPORT(void *) PyMem_Realloc(void *, size_t);
89extern DL_IMPORT(void) PyMem_Free(void *);
90
91/* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are
92 no longer supported. They used to call PyErr_NoMemory() on failure. */
93
94/* Macros */
95#define PyMem_MALLOC(n) PyCore_MALLOC(n)
96#define PyMem_REALLOC(p, n) PyCore_REALLOC((void *)(p), (n))
97#define PyMem_FREE(p) PyCore_FREE((void *)(p))
98
99/*
100 * Type-oriented memory interface
101 * ==============================
102 */
103
104/* Functions */
105#define PyMem_New(type, n) \
106 ( (type *) PyMem_Malloc((n) * sizeof(type)) )
107#define PyMem_Resize(p, type, n) \
Vladimir Marangozovdcb45c32000-08-13 11:59:08 +0000108 ( (p) = (type *) PyMem_Realloc((p), (n) * sizeof(type)) )
Peter Schneider-Kamp25f68942000-07-31 22:19:30 +0000109#define PyMem_Del(p) PyMem_Free(p)
110
111/* Macros */
112#define PyMem_NEW(type, n) \
113 ( (type *) PyMem_MALLOC(_PyMem_EXTRA + (n) * sizeof(type)) )
114#define PyMem_RESIZE(p, type, n) \
115 if ((p) == NULL) \
116 (p) = (type *)(PyMem_MALLOC( \
117 _PyMem_EXTRA + (n) * sizeof(type))); \
118 else \
119 (p) = (type *)(PyMem_REALLOC((p), \
120 _PyMem_EXTRA + (n) * sizeof(type)))
121#define PyMem_DEL(p) PyMem_FREE(p)
122
123/* PyMem_XDEL is deprecated. To avoid the call when p is NULL,
124 it is recommended to write the test explicitly in the code.
125 Note that according to ANSI C, free(NULL) has no effect. */
126
127#ifdef __cplusplus
128}
129#endif
130
131/* SCENARIOS
132
133 Here are two scenarios by Vladimir Marangozov (the author of the
134 memory allocation redesign).
135
136 1) Scenario A
137
138 Suppose you want to use a debugging malloc library that collects info on
139 where the malloc calls originate from. Assume the interface is:
140
141 d_malloc(size_t n, char* src_file, unsigned long src_line) c.s.
142
143 In this case, you would define (for example in config.h) :
144
145 #define PyCore_MALLOC_FUNC d_malloc
146 ...
147 #define PyCore_MALLOC_PROTO (size_t, char *, unsigned long)
148 ...
149 #define NEED_TO_DECLARE_MALLOC_AND_FRIEND
150
151 #define PyCore_MALLOC(n) PyCore_MALLOC_FUNC((n), __FILE__, __LINE__)
152 ...
153
154 2) Scenario B
155
156 Suppose you want to use malloc hooks (defined & initialized in a 3rd party
157 malloc library) instead of malloc functions. In this case, you would
158 define:
159
160 #define PyCore_MALLOC_FUNC (*malloc_hook)
161 ...
162 #define NEED_TO_DECLARE_MALLOC_AND_FRIEND
163
164 and ignore the previous definitions about PyCore_MALLOC_FUNC, etc.
165
166
167*/
168
169
170#endif /* !Py_PYMEM_H */