Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitbc32398

Browse files
committed
gh-75459: Doc: C API: Improve object life cycle documentation
 * Add "cyclic isolate" to the glossary. * Add a new "Object Life Cycle" page. * Illustrate the order of life cycle functions. * Document `PyObject_CallFinalizer` and `PyObject_CallFinalizerFromDealloc`. * `PyObject_Init` does not call `tp_init`. * `PyObject_New`: * also initializes the memory * does not call `tp_alloc`, `tp_new`, or `tp_init` * should not be used for GC-enabled objects * memory must be freed by `PyObject_Free` * `PyObject_GC_New` memory must be freed by `PyObject_GC_Del`. * Warn that garbage collector functions can be called from any thread. * `tp_finalize` and `tp_clear`: * Only called when there's a cyclic isolate. * Only one object in the cyclic isolate is finalized/cleared at a time. * Clearly warn that they might not be called. * They can optionally be manually called from `tp_dealloc` (via `PyObject_CallFinalizerFromDealloc` in the case of `tp_finalize`). * `tp_finalize`: * Reference `object.__del__`. * The finalizer can resurrect the object. * Suggest `PyErr_GetRaisedException` and `PyErr_SetRaisedException` instead of the deprecated `PyErr_Fetch` and `PyErr_Restore` functions. * Add links to `PyErr_GetRaisedException` and `PyErr_SetRaisedException`. * Suggest using `PyErr_WriteUnraisable` if an exception is raised during finalization. * Rename the example function from `local_finalize` to `foo_finalize` for consistency with the `tp_dealloc` documentation and as a hint that the name isn't special. * Minor wording and sylistic tweaks. * Warn that `tp_finalize` can be called during shutdown.
1 parentebcc578 commitbc32398

8 files changed

+574
-44
lines changed

‎Doc/c-api/allocation.rst

Lines changed: 36 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ Allocating Objects on the Heap
1818
reference. Returns the initialized object. If *type* indicates that the
1919
object participates in the cyclic garbage detector, it is added to the
2020
detector's set of observed objects. Other fields of the object are not
21-
affected.
21+
initialized. Specifically, this function does **not** call the object's
22+
:meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init` slot).
2223
2324
2425
.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
@@ -29,27 +30,44 @@ Allocating Objects on the Heap
2930
3031
..c:macro:: PyObject_New(TYPE, typeobj)
3132
32-
Allocate a new Python object using the C structure type *TYPE*
33-
and the Python type object *typeobj* (``PyTypeObject*``).
34-
Fields not defined by the Python object header are not initialized.
35-
The caller will own the only reference to the object
36-
(i.e. its reference count will be one).
37-
The size of the memory allocation is determined from the
38-
:c:member:`~PyTypeObject.tp_basicsize` field of the type object.
33+
Calls:c:func:`PyObject_Malloc` to allocate memory for a new Python object
34+
using the C structure type *TYPE* and the Python type object *typeobj*
35+
(``PyTypeObject*``), then initializes the memory like
36+
:c:func:`PyObject_Init`. The caller will own the only reference to the
37+
object (i.e. its reference count will be one). The size of the memory
38+
allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize`
39+
field of the type object.
40+
41+
This does not call :c:member:`~PyTypeObject.tp_alloc`,
42+
:c:member:`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or
43+
:c:member:`~PyTypeObject.tp_init` (:meth:`~object.__init__`).
44+
45+
This should not be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set
46+
in :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New`
47+
instead.
48+
49+
Memory allocated by this function must be freed with:c:func:`PyObject_Free`.
3950
4051
4152
..c:macro:: PyObject_NewVar(TYPE, typeobj, size)
4253
43-
Allocate a new Python object using the C structure type *TYPE* and the
44-
Python type object *typeobj* (``PyTypeObject*``).
45-
Fields not defined by the Python object header
46-
are not initialized. The allocated memory allows for the *TYPE* structure
47-
plus *size* (``Py_ssize_t``) fields of the size
48-
given by the :c:member:`~PyTypeObject.tp_itemsize` field of
49-
*typeobj*. This is useful for implementing objects like tuples, which are
50-
able to determine their size at construction time. Embedding the array of
51-
fields into the same allocation decreases the number of allocations,
52-
improving the memory management efficiency.
54+
Like:c:macro:`PyObject_New` except:
55+
56+
* It allocates enough memory for the *TYPE* structure plus *size*
57+
(``Py_ssize_t``) fields of the size given by the
58+
:c:member:`~PyTypeObject.tp_itemsize` field of *typeobj*.
59+
* The memory is initialized like :c:func:`PyObject_InitVar`.
60+
61+
This is useful for implementing objects like tuples, which are able to
62+
determine their size at construction time. Embedding the array of fields
63+
into the same allocation decreases the number of allocations, improving the
64+
memory management efficiency.
65+
66+
This should not be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set
67+
in :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_NewVar`
68+
instead.
69+
70+
Memory allocated by this function must be freed with:c:func:`PyObject_Free`.
5371
5472
5573
..c:function::voidPyObject_Del(void *op)

‎Doc/c-api/gcsupport.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,11 +57,17 @@ rules:
5757
Analogous to:c:macro:`PyObject_New` but for container objects with the
5858
:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
5959

60+
Memory allocated by this function must be freed with
61+
:c:func:`PyObject_GC_Del`.
62+
6063
..c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)
6164
6265
Analogous to:c:macro:`PyObject_NewVar` but for container objects with the
6366
:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
6467

68+
Memory allocated by this function must be freed with
69+
:c:func:`PyObject_GC_Del`.
70+
6571
..c:function:: PyObject*PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
6672
6773
Analogous to:c:macro:`PyObject_GC_New` but allocates *extra_size*
@@ -73,6 +79,9 @@ rules:
7379
The extra data will be deallocated with the object, but otherwise it is
7480
not managed by Python.
7581
82+
Memory allocated by this function must be freed with
83+
:c:func:`PyObject_GC_Del`.
84+
7685
.. warning::
7786
The function is marked as unstable because thefinal mechanism
7887
for reserving extra data after an instance is not yet decided.

‎Doc/c-api/lifecycle.dot

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
digraphG {
2+
graph [
3+
fontname="svg"
4+
fontsize=10.0
5+
layout="dot"
6+
ranksep=0.25
7+
]
8+
node [
9+
fontname="Courier"
10+
fontsize=10.0
11+
]
12+
edge [
13+
fontname="Times-Italic"
14+
fontsize=10.0
15+
]
16+
17+
"start" [fontname="Times-Italic"shape=plainlabel=< start >style=invis]
18+
"tp_alloc" [href="typeobj.html#c.PyTypeObject.tp_alloc" target="_top"]
19+
"tp_new" [href="typeobj.html#c.PyTypeObject.tp_new" target="_top"]
20+
"tp_init" [href="typeobj.html#c.PyTypeObject.tp_init" target="_top"]
21+
{
22+
rank="same"
23+
"alive" [
24+
fontname="Times-Italic"
25+
label=<alive, ref count &gt; 0>
26+
shape=box
27+
]
28+
"tp_traverse" [
29+
href="typeobj.html#c.PyTypeObject.tp_traverse"
30+
shape=octagon
31+
target="_top"
32+
]
33+
}
34+
"tp_finalize" [
35+
href="typeobj.html#c.PyTypeObject.tp_finalize"
36+
shape=octagon
37+
target="_top"
38+
]
39+
"tp_clear" [
40+
href="typeobj.html#c.PyTypeObject.tp_clear"
41+
shape=octagon
42+
target="_top"
43+
]
44+
"ref0" [
45+
fontname="Times-Italic"
46+
label=<ref count == 0>
47+
ordering="in"
48+
shape=box
49+
]
50+
"tp_dealloc" [href="typeobj.html#c.PyTypeObject.tp_dealloc" target="_top"]
51+
"tp_free" [href="typeobj.html#c.PyTypeObject.tp_free" target="_top"]
52+
53+
"start"->"tp_alloc"
54+
"tp_alloc"->"tp_new"
55+
"tp_new"->"tp_init"
56+
"tp_init"->"alive"
57+
"tp_traverse"->"alive"
58+
"alive"->"tp_traverse"
59+
"alive"->"tp_clear" [label=< cyclic <br/>isolate >]
60+
"alive"->"tp_finalize" [
61+
dir="back"
62+
label=< resurrected >
63+
]
64+
"alive"->"tp_finalize" [label=< cyclic <br/>isolate >]
65+
"tp_finalize"->"tp_clear"
66+
"tp_finalize"->"ref0"
67+
"tp_clear"->"ref0"
68+
"tp_clear"->"tp_dealloc" [
69+
dir="back"
70+
label=< optional<br/>direct call >
71+
]
72+
"alive"->"ref0"
73+
"ref0"->"tp_dealloc"
74+
"tp_finalize"->"tp_dealloc" [
75+
dir="back"
76+
href="lifecycle.html#c.PyObject_CallFinalizerFromDealloc"
77+
label=<
78+
<table border="0" cellborder="0" cellpadding="0" cellspacing="0">
79+
<tr>
80+
<td rowspan="4"> </td>
81+
<td align="left">optional call to</td>
82+
<td rowspan="4"> </td>
83+
</tr>
84+
<tr>
85+
<td align="left"><font face="Courier">PyObject_Call</font></td>
86+
</tr>
87+
<tr>
88+
<td align="left"><font face="Courier">FinalizerFrom</font></td>
89+
</tr>
90+
<tr><td align="left"><font face="Courier">Dealloc</font></td></tr>
91+
</table>
92+
>
93+
target="_top"
94+
]
95+
"tp_dealloc"->"tp_free" [label=< directly calls >]
96+
}

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp