[3.13] GH-109975: Copyedit 3.13 What's New: C API (GH-124313) by AA-Turner · Pull Request #124334 · python/cpython
@@ -1,6 +1,6 @@
.. highlight:: c
.. _monitoring: .. _c-api-monitoring:
Monitoring C API ================Expand Down
Expand Up
@@ -133,32 +133,60 @@ Managing the Monitoring State
Monitoring states can be managed with the help of monitoring scopes. A scope
would typically correspond to a python function.
.. :c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length) .. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
Enter a monitored scope. ``event_types`` is an array of the event IDs for events that may be fired from the scope. For example, the ID of a ``PY_START`` event is the value ``PY_MONITORING_EVENT_PY_START``, which is numerically equal to the base-2 logarithm of ``sys.monitoring.events.PY_START``. ``state_array`` is an array with a monitoring state entry for each event in ``event_types``, it is allocated by the user but populated by ``PyMonitoring_EnterScope`` with information about the activation state of :c:func:`!PyMonitoring_EnterScope` with information about the activation state of the event. The size of ``event_types`` (and hence also of ``state_array``) is given in ``length``.
The ``version`` argument is a pointer to a value which should be allocated by the user together with ``state_array`` and initialized to 0, and then set only by ``PyMonitoring_EnterScope`` itelf. It allows this and then set only by :c:func:`!PyMonitoring_EnterScope` itelf. It allows this function to determine whether event states have changed since the previous call, and to return quickly if they have not.
The scopes referred to here are lexical scopes: a function, class or method. ``PyMonitoring_EnterScope`` should be called whenever the lexical scope is :c:func:`!PyMonitoring_EnterScope` should be called whenever the lexical scope is entered. Scopes can be reentered, reusing the same *state_array* and *version*, in situations like when emulating a recursive Python function. When a code-like's execution is paused, such as when emulating a generator, the scope needs to be exited and re-entered.
.. :c:function:: int PyMonitoring_ExitScope(void)
Exit the last scope that was entered with ``PyMonitoring_EnterScope``. The macros for *event_types* are:
.. c:namespace:: NULL
.. The table is here to make the docs searchable, and to allow automatic links to the identifiers.
================================================== ===================================== Macro Event ================================================== ===================================== .. c:macro:: PY_MONITORING_EVENT_BRANCH :monitoring-event:`BRANCH` .. 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` .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED` .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION :monitoring-event:`INSTRUCTION` .. c:macro:: PY_MONITORING_EVENT_JUMP :monitoring-event:`JUMP` .. c:macro:: PY_MONITORING_EVENT_LINE :monitoring-event:`LINE` .. c:macro:: PY_MONITORING_EVENT_PY_RESUME :monitoring-event:`PY_RESUME` .. c:macro:: PY_MONITORING_EVENT_PY_RETURN :monitoring-event:`PY_RETURN` .. c:macro:: PY_MONITORING_EVENT_PY_START :monitoring-event:`PY_START` .. c:macro:: PY_MONITORING_EVENT_PY_THROW :monitoring-event:`PY_THROW` .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND :monitoring-event:`PY_UNWIND` .. c:macro:: PY_MONITORING_EVENT_PY_YIELD :monitoring-event:`PY_YIELD` .. c:macro:: PY_MONITORING_EVENT_RAISE :monitoring-event:`RAISE` .. c:macro:: PY_MONITORING_EVENT_RERAISE :monitoring-event:`RERAISE` .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION :monitoring-event:`STOP_ITERATION` ================================================== =====================================
.. c:function:: int PyMonitoring_ExitScope(void)
Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`.
.. _monitoring: .. _c-api-monitoring:
Monitoring C API ================
.. :c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length) .. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
Enter a monitored scope. ``event_types`` is an array of the event IDs for events that may be fired from the scope. For example, the ID of a ``PY_START`` event is the value ``PY_MONITORING_EVENT_PY_START``, which is numerically equal to the base-2 logarithm of ``sys.monitoring.events.PY_START``. ``state_array`` is an array with a monitoring state entry for each event in ``event_types``, it is allocated by the user but populated by ``PyMonitoring_EnterScope`` with information about the activation state of :c:func:`!PyMonitoring_EnterScope` with information about the activation state of the event. The size of ``event_types`` (and hence also of ``state_array``) is given in ``length``.
The ``version`` argument is a pointer to a value which should be allocated by the user together with ``state_array`` and initialized to 0, and then set only by ``PyMonitoring_EnterScope`` itelf. It allows this and then set only by :c:func:`!PyMonitoring_EnterScope` itelf. It allows this function to determine whether event states have changed since the previous call, and to return quickly if they have not.
The scopes referred to here are lexical scopes: a function, class or method. ``PyMonitoring_EnterScope`` should be called whenever the lexical scope is :c:func:`!PyMonitoring_EnterScope` should be called whenever the lexical scope is entered. Scopes can be reentered, reusing the same *state_array* and *version*, in situations like when emulating a recursive Python function. When a code-like's execution is paused, such as when emulating a generator, the scope needs to be exited and re-entered.
.. :c:function:: int PyMonitoring_ExitScope(void)
Exit the last scope that was entered with ``PyMonitoring_EnterScope``. The macros for *event_types* are:
.. c:namespace:: NULL
.. The table is here to make the docs searchable, and to allow automatic links to the identifiers.
================================================== ===================================== Macro Event ================================================== ===================================== .. c:macro:: PY_MONITORING_EVENT_BRANCH :monitoring-event:`BRANCH` .. 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` .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED` .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION :monitoring-event:`INSTRUCTION` .. c:macro:: PY_MONITORING_EVENT_JUMP :monitoring-event:`JUMP` .. c:macro:: PY_MONITORING_EVENT_LINE :monitoring-event:`LINE` .. c:macro:: PY_MONITORING_EVENT_PY_RESUME :monitoring-event:`PY_RESUME` .. c:macro:: PY_MONITORING_EVENT_PY_RETURN :monitoring-event:`PY_RETURN` .. c:macro:: PY_MONITORING_EVENT_PY_START :monitoring-event:`PY_START` .. c:macro:: PY_MONITORING_EVENT_PY_THROW :monitoring-event:`PY_THROW` .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND :monitoring-event:`PY_UNWIND` .. c:macro:: PY_MONITORING_EVENT_PY_YIELD :monitoring-event:`PY_YIELD` .. c:macro:: PY_MONITORING_EVENT_RAISE :monitoring-event:`RAISE` .. c:macro:: PY_MONITORING_EVENT_RERAISE :monitoring-event:`RERAISE` .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION :monitoring-event:`STOP_ITERATION` ================================================== =====================================
.. c:function:: int PyMonitoring_ExitScope(void)
Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`.