GH-122548: Implement branch taken and not taken events for sys.monitoring (GH-122564)

4 files changed, 47 insertions, 10 deletions

diff --git a/Doc/c-api/monitoring.rst b/Doc/c-api/monitoring.rst
index 51d866c..bda6cd2 100644
--- a/Doc/c-api/monitoring.rst
+++ b/Doc/c-api/monitoring.rst
@@ -75,9 +75,14 @@ See :mod:`sys.monitoring` for descriptions of the events.
    Fire a ``JUMP`` event.
 
 
-.. c:function:: int PyMonitoring_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
+.. c:function:: int PyMonitoring_FireBranchLeftEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
 
-   Fire a ``BRANCH`` event.
+   Fire a ``BRANCH_LEFT`` event.
+
+
+.. c:function:: int PyMonitoring_FireBranchRightEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
+
+   Fire a ``BRANCH_RIGHT`` event.
 
 
 .. c:function:: int PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)
@@ -168,7 +173,8 @@ would typically correspond to a python function.
    ================================================== =====================================
    Macro                                              Event
    ================================================== =====================================
-   .. c:macro:: PY_MONITORING_EVENT_BRANCH            :monitoring-event:`BRANCH`
+   .. c:macro:: PY_MONITORING_EVENT_BRANCH_LEFT       :monitoring-event:`BRANCH_LEFT`
+   .. c:macro:: PY_MONITORING_EVENT_BRANCH_RIGHT      :monitoring-event:`BRANCH_RIGHT`
    .. c:macro:: PY_MONITORING_EVENT_CALL              :monitoring-event:`CALL`
    .. c:macro:: PY_MONITORING_EVENT_C_RAISE           :monitoring-event:`C_RAISE`
    .. c:macro:: PY_MONITORING_EVENT_C_RETURN          :monitoring-event:`C_RETURN`
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`::
 
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 9f6d98b..45cc1b5 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -1971,7 +1971,7 @@ New Features
   * :c:func:`PyMonitoring_FireCallEvent`
   * :c:func:`PyMonitoring_FireLineEvent`
   * :c:func:`PyMonitoring_FireJumpEvent`
-  * :c:func:`PyMonitoring_FireBranchEvent`
+  * ``PyMonitoring_FireBranchEvent``
   * :c:func:`PyMonitoring_FireCReturnEvent`
   * :c:func:`PyMonitoring_FirePyThrowEvent`
   * :c:func:`PyMonitoring_FireRaiseEvent`
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index 2e43dce..97a37a8 100644
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -603,6 +603,11 @@ sys
   which only exists in specialized builds of Python, may now return objects
   from other interpreters than the one it's called in.
 
+sys.monitoring
+--------------
+
+Two new events are added: :monitoring-event:`BRANCH_LEFT` and
+:monitoring-event:`BRANCH_RIGHT`. The ``BRANCH`` event is deprecated.
 
 tkinter
 -------
@@ -1144,6 +1149,11 @@ New features
   a :exc:`UnicodeError` object.
   (Contributed by Bénédikt Tran in :gh:`127691`.)
 
+* Add :c:func:`PyMonitoring_FireBranchLeftEvent` and
+  :c:func:`PyMonitoring_FireBranchRightEvent` for generating
+  :monitoring-event:`BRANCH_LEFT` and :monitoring-event:`BRANCH_RIGHT`
+  events, respectively.
+
 
 Porting to Python 3.14
 ----------------------
@@ -1177,6 +1187,10 @@ Deprecated
 
 .. include:: ../deprecations/c-api-pending-removal-in-future.rst
 
+* The ``PyMonitoring_FireBranchEvent`` function is deprecated and should
+  be replaced with calls to :c:func:`PyMonitoring_FireBranchLeftEvent`
+  and :c:func:`PyMonitoring_FireBranchRightEvent`.
+
 Removed
 -------