Green shading in the line number column means the source is part of the translation unit, red means it is conditionally excluded. Highlighted line numbers link to the translation unit page. Highlighted macros link to the macro page.
1: /* An arena-like memory interface for the compiler. 2: */ 3: 4: #ifndef Py_LIMITED_API 5: #ifndef Py_PYARENA_H 6: #define Py_PYARENA_H 7: 8: #ifdef __cplusplus 9: extern "C" { 10: #endif 11: 12: typedef struct _arena PyArena; 13: 14: /* PyArena_New() and PyArena_Free() create a new arena and free it, 15: respectively. Once an arena has been created, it can be used 16: to allocate memory via PyArena_Malloc(). Pointers to PyObject can 17: also be registered with the arena via PyArena_AddPyObject(), and the 18: arena will ensure that the PyObjects stay alive at least until 19: PyArena_Free() is called. When an arena is freed, all the memory it 20: allocated is freed, the arena releases internal references to registered 21: PyObject*, and none of its pointers are valid. 22: XXX (tim) What does "none of its pointers are valid" mean? Does it 23: XXX mean that pointers previously obtained via PyArena_Malloc() are 24: XXX no longer valid? (That's clearly true, but not sure that's what 25: XXX the text is trying to say.) 26: 27: PyArena_New() returns an arena pointer. On error, it 28: returns a negative number and sets an exception. 29: XXX (tim): Not true. On error, PyArena_New() actually returns NULL, 30: XXX and looks like it may or may not set an exception (e.g., if the 31: XXX internal PyList_New(0) returns NULL, PyArena_New() passes that on 32: XXX and an exception is set; OTOH, if the internal 33: XXX block_new(DEFAULT_BLOCK_SIZE) returns NULL, that's passed on but 34: XXX an exception is not set in that case). 35: */ 36: PyAPI_FUNC(PyArena *) PyArena_New(void); 37: PyAPI_FUNC(void) PyArena_Free(PyArena *); 38: 39: /* Mostly like malloc(), return the address of a block of memory spanning 40: * `size` bytes, or return NULL (without setting an exception) if enough 41: * new memory can't be obtained. Unlike malloc(0), PyArena_Malloc() with 42: * size=0 does not guarantee to return a unique pointer (the pointer 43: * returned may equal one or more other pointers obtained from 44: * PyArena_Malloc()). 45: * Note that pointers obtained via PyArena_Malloc() must never be passed to 46: * the system free() or realloc(), or to any of Python's similar memory- 47: * management functions. PyArena_Malloc()-obtained pointers remain valid 48: * until PyArena_Free(ar) is called, at which point all pointers obtained 49: * from the arena `ar` become invalid simultaneously. 50: */ 51: PyAPI_FUNC(void *) PyArena_Malloc(PyArena *, size_t size); 52: 53: /* This routine isn't a proper arena allocation routine. It takes 54: * a PyObject* and records it so that it can be DECREFed when the 55: * arena is freed. 56: */ 57: PyAPI_FUNC(int) PyArena_AddPyObject(PyArena *, PyObject *); 58: 59: #ifdef __cplusplus 60: } 61: #endif 62: 63: #endif /* !Py_PYARENA_H */ 64: #endif /* Py_LIMITED_API */ 65: