Skip to content

gh-119786: move frames documentation to InternalDocs and add details #121009

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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
iritkatriel merged 4 commits into from
Jun 26, 2024
+38 −55
Merged

gh-119786: move frames documentation to InternalDocs and add details #121009

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ba933ea
gh-119786: move frames documentation to InternalDocs and add details
iritkatriel Jun 25, 2024
30797fe
Merge remote-tracking branch 'upstream/main' into frames-doc
iritkatriel Jun 25, 2024
56c223d
review comments
iritkatriel Jun 26, 2024
26fd907
remove linkage section
iritkatriel Jun 26, 2024
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
Prev Previous commit
remove linkage section
  • Loading branch information
@iritkatriel
iritkatriel committed Jun 26, 2024
commit 26fd9074e49d15b0989a9ea58362ee028939e46f
21 changes: 10 additions & 11 deletions InternalDocs/frames.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

Each call to a Python function has an activation record, commonly known as a
"frame". It contains information about the function being executed, consisting
of four conceptual sections:
of three conceptual sections:

* Local variables (including arguments, cells and free variables)
* Evaluation stack and instruction pointer
* Specials: The per-frame object references needed by the VM: globals dict,
code object, etc.
* Linkage: Pointer to the previous activation record, stack depth, etc.
* Evaluation stack
* Specials: The per-frame object references needed by the VM, including
globals dict, code object, instruction pointer, stack depth, the
previous frame, etc.

The definition of the ``_PyInterpreterFrame`` struct is in
[Include/internal/pycore_frame.h](https://github.com/python/cpython/blob/main/Include/internal/pycore_frame.h).
Expand All @@ -27,22 +27,21 @@ objects, so are not allocated in the per-thread stack. See ``PyGenObject`` in

## Layout

The specials and linkage sections have a fixed size, so are grouped together.

Each activation record is laid out as:
* Specials and linkage
* Specials
* Locals
* Stack

This seems to provide the best performance without excessive complexity.
It needs the interpreter to hold two pointers, a frame pointer and a stack pointer.
The specials have a fixed size, so the offset of the locals is know. The
interpreter needs to hold two pointers, a frame pointer and a stack pointer.

#### Alternative layout

An alternative layout that was used for part of 3.11 alpha was:

* Locals
* Specials and linkage
* Specials
* Stack

This has the advantage that no copying is required when making a call,
Expand Down Expand Up @@ -76,7 +75,7 @@ section. The `frame_obj` field is initially `NULL`.
The `PyFrameObject` may outlive a stack-allocated `_PyInterpreterFrame`.
If it does then `_PyInterpreterFrame` is copied into the `PyFrameObject`,
except the evaluation stack which must be empty at this point.
The linkage section is updated to reflect the new location of the frame.
The previous frame link is updated to reflect the new location of the frame.

This mechanism provides the appearance of persistent, heap-allocated
frames for each activation, but with low runtime overhead.
Expand Down