diff options
| author | Mark Shannon <mark@hotpy.org> | 2024-12-19 16:59:51 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-12-19 16:59:51 (GMT) |
| commit | d2f1d917e8b3d2dd8f35495c7632a32688883332 (patch) | |
| tree | 334558f483e0f41d80924973d16b68354bf95b82 /Doc/library | |
| parent | 7b811d0562a0bf7433165785f1549ac199610f8b (diff) | |
| download | cpython-d2f1d917e8b3d2dd8f35495c7632a32688883332.zip cpython-d2f1d917e8b3d2dd8f35495c7632a32688883332.tar.gz cpython-d2f1d917e8b3d2dd8f35495c7632a32688883332.tar.bz2 | |
GH-122548: Implement branch taken and not taken events for sys.monitoring (GH-122564)
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/sys.monitoring.rst | 29 |
1 files changed, 23 insertions, 6 deletions
diff --git a/Doc/library/sys.monitoring.rst b/Doc/library/sys.monitoring.rst index f7140af..cfdcdf2 100644 --- a/Doc/library/sys.monitoring.rst +++ b/Doc/library/sys.monitoring.rst @@ -79,9 +79,17 @@ Events The following events are supported: -.. monitoring-event:: BRANCH +.. monitoring-event:: BRANCH_LEFT - A conditional branch is taken (or not). + A conditional branch goes left. + + It is up to the tool to determine how to present "left" and "right" branches. + There is no guarantee which branch is "left" and which is "right", except + that it will be consistent for the duration of the program. + +.. monitoring-event:: BRANCH_RIGHT + + A conditional branch goes right. .. monitoring-event:: CALL @@ -180,9 +188,20 @@ The local events are: * :monitoring-event:`LINE` * :monitoring-event:`INSTRUCTION` * :monitoring-event:`JUMP` -* :monitoring-event:`BRANCH` +* :monitoring-event:`BRANCH_LEFT` +* :monitoring-event:`BRANCH_RIGHT` * :monitoring-event:`STOP_ITERATION` +Deprecated event +'''''''''''''''' + +* ``BRANCH`` + +The ``BRANCH`` event is deprecated in 3.14. +Using :monitoring-event:`BRANCH_LEFT` and :monitoring-event:`BRANCH_RIGHT` +events will give much better performance as they can be disabled +independently. + Ancillary events '''''''''''''''' @@ -357,13 +376,11 @@ Different events will provide the callback function with different arguments, as func(code: CodeType, line_number: int) -> DISABLE | Any -* :monitoring-event:`BRANCH` and :monitoring-event:`JUMP`:: +* :monitoring-event:`BRANCH_LEFT`, :monitoring-event:`BRANCH_RIGHT` and :monitoring-event:`JUMP`:: func(code: CodeType, instruction_offset: int, destination_offset: int) -> DISABLE | Any Note that the *destination_offset* is where the code will next execute. - For an untaken branch this will be the offset of the instruction following - the branch. * :monitoring-event:`INSTRUCTION`:: |