| 1 | /* The idea of this file is that you bundle it with your extension,
|
|---|
| 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
|
|---|
| 4 | 2.3 (and hopefully beyond). */
|
|---|
| 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 "small" allocations.
|
|---|
| 31 |
|
|---|
| 32 | The object family is used for allocating Python objects, and the
|
|---|
| 33 | initializers take care of some basic initialization (setting the
|
|---|
| 34 | refcount to 1 and filling out the ob_type field) as well as having
|
|---|
| 35 | a somewhat different interface.
|
|---|
| 36 |
|
|---|
| 37 | Do not mix the families! E.g. do not allocate memory with
|
|---|
| 38 | PyMem_Malloc and free it with PyObject_Free. You may get away with
|
|---|
| 39 | it quite a lot of the time, but there *are* scenarios where this
|
|---|
| 40 | will break. You Have Been Warned.
|
|---|
| 41 |
|
|---|
| 42 | Also, in many versions of Python there are an insane amount of
|
|---|
| 43 | memory interfaces to choose from. Use the ones described above. */
|
|---|
| 44 |
|
|---|
| 45 | #if PY_VERSION_HEX < 0x01060000
|
|---|
| 46 | /* raw memory interface already present */
|
|---|
| 47 |
|
|---|
| 48 | /* there is no object memory interface in 1.5.2 */
|
|---|
| 49 | #define PyObject_Malloc PyMem_Malloc
|
|---|
| 50 | #define PyObject_Realloc PyMem_Realloc
|
|---|
| 51 | #define PyObject_Free PyMem_Free
|
|---|
| 52 |
|
|---|
| 53 | /* the object interface is there, but the names have changed */
|
|---|
| 54 | #define PyObject_New PyObject_NEW
|
|---|
| 55 | #define PyObject_NewVar PyObject_NEW_VAR
|
|---|
| 56 | #define PyObject_Del PyMem_Free
|
|---|
| 57 | #endif
|
|---|
| 58 |
|
|---|
| 59 | /* If your object is a container you probably want to support the
|
|---|
| 60 | cycle collector, which was new in Python 2.0.
|
|---|
| 61 |
|
|---|
| 62 | Unfortunately, the interface to the collector that was present in
|
|---|
| 63 | Python 2.0 and 2.1 proved to be tricky to use, and so changed in
|
|---|
| 64 | 2.2 -- in a way that can't easily be papered over with macros.
|
|---|
| 65 |
|
|---|
| 66 | This file contains macros that let you program to the 2.2 GC API.
|
|---|
| 67 | Your module will compile against any Python since version 1.5.2,
|
|---|
| 68 | but the type will only participate in the GC in versions 2.2 and
|
|---|
| 69 | up. Some work is still necessary on your part to only fill out the
|
|---|
| 70 | tp_traverse and tp_clear fields when they exist and set tp_flags
|
|---|
| 71 | appropriately.
|
|---|
| 72 |
|
|---|
| 73 | It is possible to support both the 2.0 and 2.2 GC APIs, but it's
|
|---|
| 74 | not pretty and this comment block is too narrow to contain a
|
|---|
| 75 | description of what's required... */
|
|---|
| 76 |
|
|---|
| 77 | #if PY_VERSION_HEX < 0x020200B1
|
|---|
| 78 | #define PyObject_GC_New PyObject_New
|
|---|
| 79 | #define PyObject_GC_NewVar PyObject_NewVar
|
|---|
| 80 | #define PyObject_GC_Del PyObject_Del
|
|---|
| 81 | #define PyObject_GC_Track(op)
|
|---|
| 82 | #define PyObject_GC_UnTrack(op)
|
|---|
| 83 | #endif
|
|---|
| 84 |
|
|---|
| 85 | #endif /* !Py_PYMEMCOMPAT_H */
|
|---|
