8000 [3.13] GH-109975: Copyedit 3.13 What's New: C API (GH-124313) (#124334) · python/cpython@86f30dd · GitHub
[go: up one dir, main page]
Skip to content

Commit 86f30dd

Browse files
AA-Turnerencukou
AA-Turner
and
encukou
authored
[3.13] GH-109975: Copyedit 3.13 What's New: C API (GH-124313) (#124334)
* [3.13] GH-109975: Copyedit 3.13 What's New: C API (GH-124313) (cherry picked from commit 9d0a752) * gh-118915: Add/fix docs entries for some new 3.13 C API (GH-124134) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>
1 parent af8e77e commit 86f30dd

File tree

5 files changed

+491
-355
lines changed

5 files changed

+491
-355
lines changed

‎Doc/c-api/monitoring.rst

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. highlight:: c
22

3-
.. _monitoring:
3+
.. _c-api-monitoring:
44

55
Monitoring C API
66
================
@@ -133,32 +133,60 @@ Managing the Monitoring State
133133
Monitoring states can be managed with the help of monitoring scopes. A scope
134134
would typically correspond to a python function.
135135
136-
.. :c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
136+
.. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
137137
138138
Enter a monitored scope. ``event_types`` is an array of the event IDs for
139139
events that may be fired from the scope. For example, the ID of a ``PY_START``
140140
event is the value ``PY_MONITORING_EVENT_PY_START``, which is numerically equal
141141
to the base-2 logarithm of ``sys.monitoring.events.PY_START``.
142142
``state_array`` is an array with a monitoring state entry for each event in
143143
``event_types``, it is allocated by the user but populated by
144-
``PyMonitoring_EnterScope`` with information about the activation state of
144+
:c:func:`!PyMonitoring_EnterScope` with information about the activation state of
145145
the event. The size of ``event_types`` (and hence also of ``state_array``)
146146
is given in ``length``.
147147
148148
The ``version`` argument is a pointer to a value which should be allocated
149149
by the user together with ``state_array`` and initialized to 0,
150-
and then set only by ``PyMonitoring_EnterScope`` itelf. It allows this
150+
and then set only by :c:func:`!PyMonitoring_EnterScope` itelf. It allows this
151151
function to determine whether event states have changed since the previous call,
152152
and to return quickly if they have not.
153153
154154
The scopes referred to here are lexical scopes: a function, class or method.
155-
``PyMonitoring_EnterScope`` should be called whenever the lexical scope is
155+
:c:func:`!PyMonitoring_EnterScope` should be called whenever the lexical scope is
156156
entered. Scopes can be reentered, reusing the same *state_array* and *version*,
157157
in situations like when emulating a recursive Python function. When a code-like's
158158
execution is paused, such as when emulating a generator, the scope needs to
159159
be exited and re-entered.
160160
161-
162-
.. :c:function:: int PyMonitoring_ExitScope(void)
163-
164-
Exit the last scope that was entered with ``PyMonitoring_EnterScope``.
161+
The macros for *event_types* are:
162+
163+
.. c:namespace:: NULL
164+
165+
.. The table is here to make the docs searchable, and to allow automatic
166+
links to the identifiers.
167+
168+
================================================== =====================================
169+
Macro Event
170+
================================================== =====================================
171+
.. c:macro:: PY_MONITORING_EVENT_BRANCH :monitoring-event:`BRANCH`
172+
.. c:macro:: PY_MONITORING_EVENT_CALL :monitoring-event:`CALL`
173+
.. c:macro:: PY_MONITORING_EVENT_C_RAISE :monitoring-event:`C_RAISE`
174+
.. c:macro:: PY_MONITORING_EVENT_C_RETURN :monitoring-event:`C_RETURN`
175+
.. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED`
176+
.. c:macro:: PY_MONITORING_EVENT_INSTRUCTION :monitoring-event:`INSTRUCTION`
177+
.. c:macro:: PY_MONITORING_EVENT_JUMP :monitoring-event:`JUMP`
178+
.. c:macro:: PY_MONITORING_EVENT_LINE :monitoring-event:`LINE`
179+
.. c:macro:: PY_MONITORING_EVENT_PY_RESUME :monitoring-event:`PY_RESUME`
180+
.. c:macro:: PY_MONITORING_EVENT_PY_RETURN :monitoring-event:`PY_RETURN`
181+
.. c:macro:: PY_MONITORING_EVENT_PY_START :monitoring-event:`PY_START`
182+
.. c:macro:: PY_MONITORING_EVENT_PY_THROW :monitoring-event:`PY_THROW`
183+
.. c:macro:: PY_MONITORING_EVENT_PY_UNWIND :monitoring-event:`PY_UNWIND`
184+
.. c:macro:: PY_MONITORING_EVENT_PY_YIELD :monitoring-event:`PY_YIELD`
185+
.. c:macro:: PY_MONITORING_EVENT_RAISE :monitoring-event:`RAISE`
186+
.. c:macro:: PY_MONITORING_EVENT_RERAISE :monitoring-event:`RERAISE`
187+
.. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION :monitoring-event:`STOP_ITERATION`
188+
================================================== =====================================
189+
190+
.. c:function:: int PyMonitoring_ExitScope(void)
191+
192+
Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`.

‎Doc/c-api/time.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
.. highlight:: c
22

3+
.. _c-api-time:
4+
35
PyTime C API
46
============
57

‎Doc/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,7 @@
141141
('c:type', 'size_t'),
142142
('c:type', 'ssize_t'),
143143
('c:type', 'time_t'),
144+
('c:type', 'uint8_t'),
144145
('c:type', 'uint64_t'),
145146
('c:type', 'uintmax_t'),
146147
('c:type', 'uintptr_t'),

‎Doc/library/sys.monitoring.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -258,7 +258,7 @@ Per code object events
258258
Events can also be controlled on a per code object basis. The functions
259259
defined below which accept a :class:`types.CodeType` should be prepared
260260
to accept a look-alike object from functions which are not defined
261-
in Python (see :ref:`monitoring`).
261+
in Python (see :ref:`c-api-monitoring`).
262262

263263
.. function:: get_local_events(tool_id: int, code: CodeType, /) -> int
264264

0 commit comments

Comments
 (0)
0