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

gh-75459: Doc: C API: Improve object life cycle documentation#125962

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
encukou merged 29 commits intopython:mainfromrhansen:docs
May 20, 2025
Merged
Show file tree
Hide file tree
Changes from1 commit
Commits
Show all changes
29 commits
Select commitHold shift + click to select a range
bc32398
gh-75459: Doc: C API: Improve object life cycle documentation
rhansenOct 19, 2024
361eaca
gh-75459: Doc: Tell sphinx to run graphviz
rhansenOct 25, 2024
b27bcca
add blurb
rhansenOct 25, 2024
b42b58d
Revert "gh-75459: Doc: Tell sphinx to run graphviz"
rhansenOct 25, 2024
7e571ae
delete "ref count == 0" node, link directly to `tp_dealloc`
rhansenOct 26, 2024
97dc30c
Merge branch 'main' into docs
rhansenNov 7, 2024
85e535a
significant rewrite to address review comments
rhansenNov 7, 2024
ef979e6
fix warnings
rhansenNov 7, 2024
f3863c4
tweak cyclic isolate definition
rhansenNov 7, 2024
6a114f9
apply css to the svg to support dark theme
rhansenNov 8, 2024
182c977
increase font size
rhansenNov 8, 2024
7cd0cb5
attempt to make the svg accessible
rhansenNov 8, 2024
e34e224
wrap at 79 chars
rhansenNov 8, 2024
16a29ab
address review feedback, and other tweaks
rhansenNov 9, 2024
018a3c4
be more precise about the finalized mark
rhansenNov 21, 2024
442b7f2
add pdf support, improve epub support
rhansenNov 21, 2024
5ed484a
address feedback, and other improvements
rhansenNov 27, 2024
b7774ae
Merge in the main branch
encukouMar 11, 2025
bb1a94f
Remove redundant notes added in GH-129850
encukouMar 11, 2025
fd38fd4
Merge branch 'main' into docs
ZeroIntensityMay 5, 2025
3573c79
Apply suggestions from code review
ZeroIntensityMay 5, 2025
2633594
Update Doc/c-api/lifecycle.rst
ZeroIntensityMay 5, 2025
c57574a
Mention tp_alloc()
ZeroIntensityMay 5, 2025
878fd27
Avoid using 'do not'
ZeroIntensityMay 5, 2025
1b96fad
Mention PyObject_CallFinalizerFromDealloc()
ZeroIntensityMay 5, 2025
e8c6852
Add some clarifications about tp_finalize()
ZeroIntensityMay 5, 2025
3408919
Say that tp_dealloc() must free.
ZeroIntensityMay 5, 2025
b6023a3
Fix doctest.
ZeroIntensityMay 5, 2025
da3593c
Apply suggestions from code review
ZeroIntensityMay 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
PrevPrevious commit
NextNext commit
address review feedback, and other tweaks
  • Loading branch information
@rhansen
rhansen committedNov 20, 2024
commit16a29ab853d76e664ad98c8137727df93f24fdaa
41 changes: 28 additions & 13 deletionsDoc/c-api/allocation.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -22,16 +22,19 @@ Allocating Objects on the Heap
.. warning::

This function does not guarantee that the memory will be completely
zeroed before it is initialized. Fields that are not initialized by this
function will have indeterminate values, which might include sensitive
data from previously destroyed objects (e.g., secret keys).
zeroed before it is initialized.


.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)

This does everything :c:func:`PyObject_Init` does, and also initializes the
length information for a variable-size object.

.. warning::

This function does not guarantee that the memory will be completely
zeroed before it is initialized.


.. c:macro:: PyObject_New(TYPE, typeobj)

Expand All@@ -43,9 +46,9 @@ Allocating Objects on the Heap
allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize`
field of the type object.

For a type's :c:member:`~PyTypeObject.tp_alloc` slot,
:c:func:`PyType_GenericAlloc` isgenerallypreferred over a custom function
thatsimply calls this macro.
When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
:c:func:`PyType_GenericAlloc` is preferred over a custom function that
simply calls this macro.

This macro does not call :c:member:`~PyTypeObject.tp_alloc`,
:c:member:`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or
Expand All@@ -55,15 +58,13 @@ Allocating Objects on the Heap
set in :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New`
instead.

Memory allocated by this function must be freed with
:c:func:`PyObject_Free`.
Memory allocated by this function must be freed with :c:func:`PyObject_Free`
(usually called via the object's:c:member:`~PyTypeObject.tp_free` slot).

.. warning::

The returned memory is not guaranteed to have been completely zeroed
before it was initialized. Fields that were not initialized by this
function will have indeterminate values, which might include sensitive
data from previously destroyed objects (e.g., secret keys).
before it was initialized.

.. warning::

Expand DownExpand Up@@ -93,8 +94,22 @@ Allocating Objects on the Heap
in :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_NewVar`
instead.

Memory allocated by this function must be freed with
:c:func:`PyObject_Free`.
Memory allocated by this function must be freed with :c:func:`PyObject_Free`
(usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).

.. warning::

The returned memory is not guaranteed to have been completely zeroed
before it was initialized.

.. warning::

This macro does not construct a fully initialized object of the given
type; it merely allocates memory and prepares it for further
initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
fully initialized object, call *typeobj* instead. For example::

PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);


.. c:function:: void PyObject_Del(void *op)
Expand Down
9 changes: 6 additions & 3 deletionsDoc/c-api/gcsupport.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -58,15 +58,17 @@ rules:
:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.

Memory allocated by this function must be freed with
:c:func:`PyObject_GC_Del`.
:c:func:`PyObject_GC_Del` (usually called via the object's
:c:member:`~PyTypeObject.tp_free` slot).

.. c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)

Analogous to :c:macro:`PyObject_NewVar` but for container objects with the
:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.

Memory allocated by this function must be freed with
:c:func:`PyObject_GC_Del`.
:c:func:`PyObject_GC_Del` (usually called via the object's
:c:member:`~PyTypeObject.tp_free` slot).

.. c:function:: PyObject* PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)

Expand All@@ -80,7 +82,8 @@ rules:
not managed by Python.

Memory allocated by this function must be freed with
:c:func:`PyObject_GC_Del`.
:c:func:`PyObject_GC_Del` (usually called via the object's
:c:member:`~PyTypeObject.tp_free` slot).

.. warning::
The function is marked as unstable because the final mechanism
Expand Down
78 changes: 40 additions & 38 deletionsDoc/c-api/lifecycle.dot
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
digraph "Life Events" {
graph [
fontname="svg"
fontsize=12.0
id="life_events_graph"
layout="dot"
Expand All@@ -23,58 +22,61 @@ digraph "Life Events" {
"tp_alloc" [href="typeobj.html#c.PyTypeObject.tp_alloc" target="_top"]
}
"tp_init" [href="typeobj.html#c.PyTypeObject.tp_init" target="_top"]
{
rank="same"
"reachable" [fontname="Times-Italic" shape=box]
"tp_traverse" [
href="typeobj.html#c.PyTypeObject.tp_traverse"
target="_top"
]
}
"tp_finalize" [href="typeobj.html#c.PyTypeObject.tp_finalize" target="_top"]
"reachable" [fontname="Times-Italic" shape=box]
"tp_traverse" [
href="typeobj.html#c.PyTypeObject.tp_traverse"
target="_top"
]
"finalized" [
fontname="Times-Italic"
label=<marked as<br/>finalized?>
shape=diamond
]
"tp_finalize" [
href="typeobj.html#c.PyTypeObject.tp_finalize"
ordering="in"
target="_top"
]
"tp_clear" [href="typeobj.html#c.PyTypeObject.tp_clear" target="_top"]
"uncollectable" [
fontname="Times-Italic"
label=<uncollectable<br/>(leaked)>
shape=box
]
"tp_dealloc" [
href="typeobj.html#c.PyTypeObject.tp_dealloc"
ordering="in"
target="_top"
]
"tp_free" [href="typeobj.html#c.PyTypeObject.tp_free" target="_top"]

"start" -> "tp_new"
"tp_new" -> "tp_alloc" [label=< direct call >]
"tp_alloc" -> "tp_new" [label=< >]
"start" -> "tp_new" [label=< type call >]
"tp_new" -> "tp_alloc" [label=< direct call > arrowhead=empty]
"tp_new" -> "tp_init"
"tp_init" -> "reachable"
"reachable" -> "tp_traverse"
"tp_traverse" -> "reachable"
"reachable" -> "tp_clear" [
label=< was resurrected, <br/> then became <br/> unreachable >
"reachable" -> "tp_traverse" [
label=< periodic <br/> cyclic isolate <br/> detection >
]
"reachable" -> "tp_init"
"reachable" -> "tp_finalize" [dir="back" label=< resurrected >]
"reachable" -> "tp_finalize" [label=< became <br/> unreachable >]
"tp_finalize" -> "tp_clear" [label=< still <br/> unreachable >]
"tp_traverse" -> "reachable" [label=< not in a <br/> cyclic isolate >]
"tp_traverse" -> "finalized" [label=< cyclic <br/> isolate >]
"reachable" -> "finalized" [label=< no refs >]
"finalized" -> "tp_finalize" [label=< no >]
"finalized" -> "tp_clear" [label=< yes >]
"tp_finalize" -> "tp_clear" [label=< no refs or <br/> cyclic isolate >]
"tp_finalize" -> "tp_dealloc" [
arrowtail=empty
dir="back"
href="lifecycle.html#c.PyObject_CallFinalizerFromDealloc"
label=<
<table border="0" cellborder="0" cellpadding="0" cellspacing="0">
<tr>
<td rowspan="4"> </td>
<td align="left">recommended call to</td>
</tr>
<tr>
<td align="left"><font face="Courier">PyObject_Call</font></td>
</tr>
<tr>
<td align="left"><font face="Courier">FinalizerFrom</font></td>
</tr>
<tr><td align="left"><font face="Courier">Dealloc</font></td></tr>
</table>
>
style=dashed
label=< recommended<br/> call (see<br/> explanation)>
target="_top"
]
"tp_finalize" -> "tp_dealloc" [label=< still <br/> unreachable >]
"tp_clear" -> "tp_dealloc" [label=< >]
"reachable" -> "tp_dealloc" [label=< became <br/> unreachable >]
"tp_dealloc" -> "tp_free" [label=< direct call >]
"tp_finalize" -> "tp_dealloc" [label=< no refs >]
"tp_clear" -> "tp_dealloc" [label=< no refs >]
"tp_clear" -> "uncollectable" [label=< cyclic <br/> isolate >]
"uncollectable" -> "tp_dealloc" [style=invis]
"reachable" -> "tp_dealloc" [label=< no refs>]
"tp_dealloc" -> "tp_free" [label=< direct call > arrowhead=empty]
}
Loading
Loading
[8]ページ先頭
©2009-2025 Movatter.jp