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    desciption 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 */