Fred Drake | 1e9abf0 | 2002-05-30 16:41:14 +0000 | [diff] [blame] | 1 | /* The idea of this file is that you bundle it with your extension, |
Michael W. Hudson | e4df27f | 2002-05-30 16:22:29 +0000 | [diff] [blame] | 2 | #include it, program to Python 2.3's memory API and have your |
| 3 | extension build with any version of Python from 1.5.2 through to |
Fred Drake | 1e9abf0 | 2002-05-30 16:41:14 +0000 | [diff] [blame] | 4 | 2.3 (and hopefully beyond). */ |
Michael W. Hudson | e4df27f | 2002-05-30 16:22:29 +0000 | [diff] [blame] | 5 | |
| 6 | #ifndef Py_PYMEMCOMPAT_H |
| 7 | #define Py_PYMEMCOMPAT_H |
| 8 | |
| 9 | #include "Python.h" |
| 10 | |
| 11 | /* There are three "families" of memory API: the "raw memory", "object |
| 12 | memory" and "object" families. (This is ignoring the matter of the |
| 13 | cycle collector, about which more is said below). |
| 14 | |
| 15 | Raw Memory: |
| 16 | |
| 17 | PyMem_Malloc, PyMem_Realloc, PyMem_Free |
| 18 | |
| 19 | Object Memory: |
| 20 | |
| 21 | PyObject_Malloc, PyObject_Realloc, PyObject_Free |
| 22 | |
| 23 | Object: |
| 24 | |
| 25 | PyObject_New, PyObject_NewVar, PyObject_Del |
| 26 | |
| 27 | The raw memory and object memory allocators both mimic the |
| 28 | malloc/realloc/free interface from ANSI C, but the object memory |
| 29 | allocator can (and, since 2.3, does by default) use a different |
| 30 | allocation strategy biased towards lots of lots of "small" |
| 31 | allocations. |
| 32 | |
| 33 | The object family is used for allocating Python objects, and the |
| 34 | initializers take care of some basic initialization (setting the |
| 35 | refcount to 1 and filling out the ob_type field) as well as having |
| 36 | a somewhat different interface. |
| 37 | |
| 38 | Do not mix the families! E.g. do not allocate memory with |
| 39 | PyMem_Malloc and free it with PyObject_Free. You may get away with |
| 40 | it quite a lot of the time, but there *are* scenarios where this |
| 41 | will break. You Have Been Warned. |
| 42 | |
| 43 | Also, in many versions of Python there are an insane amount of |
| 44 | memory interfaces to choose from. Use the ones described above. */ |
| 45 | |
| 46 | #if PY_VERSION_HEX < 0x01060000 |
| 47 | /* raw memory interface already present */ |
| 48 | |
| 49 | /* there is no object memory interface in 1.5.2 */ |
| 50 | #define PyObject_Malloc PyMem_Malloc |
| 51 | #define PyObject_Realloc PyMem_Realloc |
| 52 | #define PyObject_Free PyMem_Free |
| 53 | |
| 54 | /* the object interface is there, but the names have changed */ |
| 55 | #define PyObject_New PyObject_NEW |
| 56 | #define PyObject_NewVar PyObject_NEW_VAR |
| 57 | #define PyObject_Del PyMem_Free |
| 58 | #endif |
| 59 | |
| 60 | /* If your object is a container you probably want to support the |
| 61 | cycle collector, which was new in Python 2.0. |
| 62 | |
| 63 | Unfortunately, the interface to the collector that was present in |
| 64 | Python 2.0 and 2.1 proved to be tricky to use, and so changed in |
| 65 | 2.2 -- in a way that can't easily be papered over with macros. |
| 66 | |
| 67 | This file contains macros that let you program to the 2.2 GC API. |
| 68 | Your module will compile against any Python since version 1.5.2, |
| 69 | but the type will only participate in the GC in versions 2.2 and |
| 70 | up. Some work is still necessary on your part to only fill out the |
| 71 | tp_traverse and tp_clear fields when they exist and set tp_flags |
| 72 | appropriately. |
| 73 | |
| 74 | It is possible to support both the 2.0 and 2.2 GC APIs, but it's |
| 75 | not pretty and this comment block is too narrow to contain a |
| 76 | desciption of what's required... */ |
| 77 | |
| 78 | #if PY_VERSION_HEX < 0x020200B1 |
| 79 | #define PyObject_GC_New PyObject_New |
| 80 | #define PyObject_GC_NewVar PyObject_NewVar |
| 81 | #define PyObject_GC_Del PyObject_Del |
| 82 | #define PyObject_GC_Track(op) |
| 83 | #define PyObject_GC_UnTrack(op) |
| 84 | #endif |
| 85 | |
| 86 | #endif /* !Py_PYMEMCOMPAT_H */ |