1 /* An arena-like memory interface for the compiler.

     2  */

     3 

     4 #ifndef Py_PYARENA_H

     5 #define Py_PYARENA_H

     6 

     7 #ifdef __cplusplus

     8 extern "C" {

     9 #endif

    10 

    11   typedef struct _arena PyArena;

    12 

    13   /* PyArena_New() and PyArena_Free() create a new arena and free it,

    14      respectively.  Once an arena has been created, it can be used

    15      to allocate memory via PyArena_Malloc().  Pointers to PyObject can

    16      also be registered with the arena via PyArena_AddPyObject(), and the

    17      arena will ensure that the PyObjects stay alive at least until

    18      PyArena_Free() is called.  When an arena is freed, all the memory it

    19      allocated is freed, the arena releases internal references to registered

    20      PyObject*, and none of its pointers are valid.

    21      XXX (tim) What does "none of its pointers are valid" mean?  Does it

    22      XXX mean that pointers previously obtained via PyArena_Malloc() are

    23      XXX no longer valid?  (That's clearly true, but not sure that's what

    24      XXX the text is trying to say.)

    25 

    26      PyArena_New() returns an arena pointer.  On error, it

    27      returns a negative number and sets an exception.

    28      XXX (tim):  Not true.  On error, PyArena_New() actually returns NULL,

    29      XXX and looks like it may or may not set an exception (e.g., if the

    30      XXX internal PyList_New(0) returns NULL, PyArena_New() passes that on

    31      XXX and an exception is set; OTOH, if the internal

    32      XXX block_new(DEFAULT_BLOCK_SIZE) returns NULL, that's passed on but

    33      XXX an exception is not set in that case).

    34   */

    35   PyAPI_FUNC(PyArena *) PyArena_New(void);

    36   PyAPI_FUNC(void) PyArena_Free(PyArena *);

    37 

    38   /* Mostly like malloc(), return the address of a block of memory spanning

    39    * `size` bytes, or return NULL (without setting an exception) if enough

    40    * new memory can't be obtained.  Unlike malloc(0), PyArena_Malloc() with

    41    * size=0 does not guarantee to return a unique pointer (the pointer

    42    * returned may equal one or more other pointers obtained from

    43    * PyArena_Malloc()).

    44    * Note that pointers obtained via PyArena_Malloc() must never be passed to

    45    * the system free() or realloc(), or to any of Python's similar memory-

    46    * management functions.  PyArena_Malloc()-obtained pointers remain valid

    47    * until PyArena_Free(ar) is called, at which point all pointers obtained

    48    * from the arena `ar` become invalid simultaneously.

    49    */

    50   PyAPI_FUNC(void *) PyArena_Malloc(PyArena *, size_t size);

    51 

    52   /* This routine isn't a proper arena allocation routine.  It takes

    53    * a PyObject* and records it so that it can be DECREFed when the

    54    * arena is freed.

    55    */

    56   PyAPI_FUNC(int) PyArena_AddPyObject(PyArena *, PyObject *);

    57 

    58 #ifdef __cplusplus

    59 }

    60 #endif

    61 

    62 #endif /* !Py_PYARENA_H */