Monitoring C API
****************

Added in version 3.13.

An extension may need to interact with the event monitoring system.
Subscribing to events and registering callbacks can be done via the
Python API exposed in "sys.monitoring".


Generating Execution Events
***************************

The functions below make it possible for an extension to fire
monitoring events as it emulates the execution of Python code. Each of
these functions accepts a "PyMonitoringState" struct which contains
concise information about the activation state of events, as well as
the event arguments, which include a "PyObject*" representing the code
object, the instruction offset and sometimes additional, event-
specific arguments (see "sys.monitoring" for details about the
signatures of the different event callbacks). The "codelike" argument
should be an instance of "types.CodeType" or of a type that emulates
it.

The VM disables tracing when firing an event, so there is no need for
user code to do that.

Monitoring functions should not be called with an exception set,
except those listed below as working with the current exception.

type PyMonitoringState

   Representation of the state of an event type. It is allocated by
   the user while its contents are maintained by the monitoring API
   functions described below.

All of the functions below return 0 on success and -1 (with an
exception set) on error.

See "sys.monitoring" for descriptions of the events.

int PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

   Fire a "PY_START" event.

int PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

   Fire a "PY_RESUME" event.

int PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

   Fire a "PY_RETURN" event.

int PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

   Fire a "PY_YIELD" event.

int PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *callable, PyObject *arg0)

   Fire a "CALL" event.

int PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, int lineno)

   Fire a "LINE" event.

int PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

   Fire a "JUMP" event.

int PyMonitoring_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

   Fire a "BRANCH" event.

int PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

   Fire a "C_RETURN" event.

int PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

   Fire a "PY_THROW" event with the current exception (as returned by
   "PyErr_GetRaisedException()").

int PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

   Fire a "RAISE" event with the current exception (as returned by
   "PyErr_GetRaisedException()").

int PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

   Fire a "C_RAISE" event with the current exception (as returned by
   "PyErr_GetRaisedException()").

int PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

   Fire a "RERAISE" event with the current exception (as returned by
   "PyErr_GetRaisedException()").

int PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

   Fire an "EXCEPTION_HANDLED" event with the current exception (as
   returned by "PyErr_GetRaisedException()").

int PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

   Fire a "PY_UNWIND" event with the current exception (as returned by
   "PyErr_GetRaisedException()").

int PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value)

   Fire a "STOP_ITERATION" event. If "value" is an instance of
   "StopIteration", it is used. Otherwise, a new "StopIteration"
   instance is created with "value" as its argument.


Managing the Monitoring State
=============================

Monitoring states can be managed with the help of monitoring scopes. A
scope would typically correspond to a python function.
