Mercurial > cpython-lru_cache-weakref

annotate Include/pyarena.h @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 1d055ebd8322
children 62b61abd02b8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
36065
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1 /* An arena-like memory interface for the compiler.
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
2 */
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
3
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
4 #ifndef Py_PYARENA_H
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
5 #define Py_PYARENA_H
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
6
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
7 #ifdef __cplusplus
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
8 extern "C" {
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
9 #endif
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
10
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
11 typedef struct _arena PyArena;
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
12
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
13 /* PyArena_New() and PyArena_Free() create a new arena and free it,
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
14 respectively. Once an arena has been created, it can be used
36811
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
15 to allocate memory via PyArena_Malloc(). Pointers to PyObject can
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
16 also be registered with the arena via PyArena_AddPyObject(), and the
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
17 arena will ensure that the PyObjects stay alive at least until
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
18 PyArena_Free() is called. When an arena is freed, all the memory it
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
19 allocated is freed, the arena releases internal references to registered
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
20 PyObject*, and none of its pointers are valid.
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
21 XXX (tim) What does "none of its pointers are valid" mean? Does it
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
22 XXX mean that pointers previously obtained via PyArena_Malloc() are
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
23 XXX no longer valid? (That's clearly true, but not sure that's what
aba73b46803c Beefed up description of what this does; new XXX.
Tim Peters <tim.peters@gmail.com>
parents: 36810
diff changeset
24 XXX the text is trying to say.)
36065
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
25
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
26 PyArena_New() returns an arena pointer. On error, it
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
27 returns a negative number and sets an exception.
36810
ef8779d455ec New XXX pointing out errors in the description of
Tim Peters <tim.peters@gmail.com>
parents: 36808
diff changeset
28 XXX (tim): Not true. On error, PyArena_New() actually returns NULL,
ef8779d455ec New XXX pointing out errors in the description of
Tim Peters <tim.peters@gmail.com>
parents: 36808
diff changeset
29 XXX and looks like it may or may not set an exception (e.g., if the
ef8779d455ec New XXX pointing out errors in the description of
Tim Peters <tim.peters@gmail.com>
parents: 36808
diff changeset
30 XXX internal PyList_New(0) returns NULL, PyArena_New() passes that on
ef8779d455ec New XXX pointing out errors in the description of
Tim Peters <tim.peters@gmail.com>
parents: 36808
diff changeset
31 XXX and an exception is set; OTOH, if the internal
ef8779d455ec New XXX pointing out errors in the description of
Tim Peters <tim.peters@gmail.com>
parents: 36808
diff changeset
32 XXX block_new(DEFAULT_BLOCK_SIZE) returns NULL, that's passed on but
ef8779d455ec New XXX pointing out errors in the description of
Tim Peters <tim.peters@gmail.com>
parents: 36808
diff changeset
33 XXX an exception is not set in that case).
36065
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
34 */
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
35 PyAPI_FUNC(PyArena *) PyArena_New(void);
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
36 PyAPI_FUNC(void) PyArena_Free(PyArena *);
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
37
36812
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
38 /* Mostly like malloc(), return the address of a block of memory spanning
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
39 * `size` bytes, or return NULL (without setting an exception) if enough
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
40 * new memory can't be obtained. Unlike malloc(0), PyArena_Malloc() with
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
41 * size=0 does not guarantee to return a unique pointer (the pointer
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
42 * returned may equal one or more other pointers obtained from
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
43 * PyArena_Malloc()).
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
44 * Note that pointers obtained via PyArena_Malloc() must never be passed to
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
45 * the system free() or realloc(), or to any of Python's similar memory-
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
46 * management functions. PyArena_Malloc()-obtained pointers remain valid
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
47 * until PyArena_Free(ar) is called, at which point all pointers obtained
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
48 * from the arena `ar` become invalid simultaneously.
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
49 */
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
50 PyAPI_FUNC(void *) PyArena_Malloc(PyArena *, size_t size);
36065
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
51
36812
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
52 /* This routine isn't a proper arena allocation routine. It takes
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
53 * a PyObject* and records it so that it can be DECREFed when the
1d055ebd8322 Added words about what PyArena_Malloc() does.
Tim Peters <tim.peters@gmail.com>
parents: 36811
diff changeset
54 * arena is freed.
36808
b1a3c2238f97 Trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 36716
diff changeset
55 */
36065
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
56 PyAPI_FUNC(int) PyArena_AddPyObject(PyArena *, PyObject *);
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
57
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
58 #ifdef __cplusplus
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
59 }
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
60 #endif
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
61
ea083efdc96c Merge from ast-arena. This reduces the code in Python/ast.c by ~300 lines,
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
62 #endif /* !Py_PYARENA_H */