greg/cpython
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Document that returning sys.monitoring.DISABLE in response to a global event raises ValueError (#140726)

Browse Source 
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
This commit is contained in:
Brett Cannon
2025-11-04 10:28:17 -08:00
committed by GitHub
parent 40096da95a
commit 8a7dbb7a68
1 changed files with 19 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
Doc/library/sys.monitoring.rst
View File

@@ -216,14 +216,17 @@ by another event:
The :monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events The :monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events
are controlled by the :monitoring-event:`CALL` event. are controlled by the :monitoring-event:`CALL` event.
:monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events will only be seen if the :monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events will only be
corresponding :monitoring-event:`CALL` event is being monitored. seen if the corresponding :monitoring-event:`CALL` event is being monitored.
.. _monitoring-event-global:
Other events Other events
'''''''''''' ''''''''''''
Other events are not necessarily tied to a specific location in the Other events are not necessarily tied to a specific location in the
program and cannot be individually disabled. program and cannot be individually disabled via :data:`DISABLE`.
The other events that can be monitored are: The other events that can be monitored are:
@@ -289,12 +292,13 @@ in Python (see :ref:`c-api-monitoring`).
.. function:: get_local_events(tool_id: int, code: CodeType, /) -> int .. function:: get_local_events(tool_id: int, code: CodeType, /) -> int
Returns all the local events for *code* Returns all the :ref:`local events <monitoring-event-local>` for *code*
.. function:: set_local_events(tool_id: int, code: CodeType, event_set: int, /) -> None .. function:: set_local_events(tool_id: int, code: CodeType, event_set: int, /) -> None
Activates all the local events for *code* which are set in *event_set*. Activates all the :ref:`local events <monitoring-event-local>` for *code*
Raises a :exc:`ValueError` if *tool_id* is not in use. which are set in *event_set*. Raises a :exc:`ValueError` if *tool_id* is not
in use.
Disabling events Disabling events
@@ -305,15 +309,21 @@ Disabling events
A special value that can be returned from a callback function to disable A special value that can be returned from a callback function to disable
events for the current code location. events for the current code location.
Local events can be disabled for a specific code location by returning :ref:`Local events <monitoring-event-local>` can be disabled for a specific code
:data:`sys.monitoring.DISABLE` from a callback function. This does not change location by returning :data:`sys.monitoring.DISABLE` from a callback function.
which events are set, or any other code locations for the same event. This does not change which events are set, or any other code locations for the
same event.
Disabling events for specific locations is very important for high Disabling events for specific locations is very important for high
performance monitoring. For example, a program can be run under a performance monitoring. For example, a program can be run under a
debugger with no overhead if the debugger disables all monitoring debugger with no overhead if the debugger disables all monitoring
except for a few breakpoints. except for a few breakpoints.
If :data:`DISABLE` is returned by a callback for a
:ref:`global event <monitoring-event-global>`, :exc:`ValueError` will be raised
by the interpreter in a non-specific location (that is, no traceback will be
provided).
.. function:: restart_events() -> None .. function:: restart_events() -> None
Enable all the events that were disabled by :data:`sys.monitoring.DISABLE` Enable all the events that were disabled by :data:`sys.monitoring.DISABLE`