Övervakning av C API

Tillagd i version 3.13.

Ett tillägg kan behöva interagera med händelseövervakningssystemet. Prenumeration på händelser och registrering av callbacks kan göras via Python API som exponeras i sys.monitoring.

Generering av exekveringshändelser

Funktionerna nedan gör det möjligt för en tilläggsfunktion att utlösa övervakningshändelser när den emulerar exekveringen av Python-kod. Var och en av dessa funktioner accepterar en PyMonitoringState -struktur som innehåller kortfattad information om händelsernas aktiveringsstatus, samt händelseargumenten, som inkluderar en PyObject* som representerar kodobjektet, instruktionsförskjutningen och ibland ytterligare händelsespecifika argument (se sys.monitoring för detaljer om signaturerna för de olika händelseåteranropen). Argumentet codelike bör vara en instans av types.CodeType eller av en typ som emulerar den.

VM inaktiverar spårning när en händelse utlöses, så det finns inget behov av användarkod för att göra det.

Övervakningsfunktioner ska inte anropas med ett undantag inställt, förutom de som listas nedan som arbetar med det aktuella undantaget.

type PyMonitoringState

Representation av tillståndet för en händelsetyp. Den allokeras av användaren medan dess innehåll underhålls av API-funktionerna för övervakning som beskrivs nedan.

Alla funktioner nedan returnerar 0 vid framgång och -1 (med en undantagsinställning) vid fel.

Se sys.monitoring för beskrivningar av händelserna.

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

Starta en PY_START -händelse.

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

Starta en PY_RESUME -händelse.

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

Starta en PY_RETURN -händelse.

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

Starta en PY_YIELD -händelse.

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

Starta en CALL -händelse.

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

Starta en LINE -händelse.

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

Starta en JUMP -händelse.

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

Startar en händelse av typen BRANCH_LEFT.

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

Startar en händelse av typen BRANCH_RIGHT.

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

Utlösa en C_RETURN -händelse.

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

Startar en PY_THROW händelse med det aktuella undantaget (som returneras av PyErr_GetRaisedException()).

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

Startar en RAISE -händelse med det aktuella undantaget (som returneras av PyErr_GetRaisedException()).

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

Startar en C_RAISE -händelse med det aktuella undantaget (som returneras av PyErr_GetRaisedException()).

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

Startar en RERAISE -händelse med det aktuella undantaget (som returneras av PyErr_GetRaisedException()).

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

Startar en EXCEPTION_HANDLED -händelse med det aktuella undantaget (som returneras av PyErr_GetRaisedException()).

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

Startar en PY_UNWIND -händelse med det aktuella undantaget (som returneras av PyErr_GetRaisedException()).

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

Utlöser en STOP_ITERATION-händelse. Om value är en instans av StopIteration, så används den. Annars skapas en ny StopIteration-instans med value som argument.

Hantering av övervakningstillståndet

Övervakningstillstånd kan hanteras med hjälp av övervakningsscope. Ett scope motsvarar vanligtvis en pythonfunktion.

int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)

Ange ett övervakat scope. event_types är en array med händelse-ID:n för händelser som kan avfyras från scopet. ID:t för en händelse av typen PY_START är till exempel värdet PY_MONITORING_EVENT_PY_START, som är numeriskt lika med bas-2-logaritmen för sys.monitoring.events.PY_START. state_array är en array med en övervakningstillståndspost för varje händelse i event_types, den allokeras av användaren men fylls på av PyMonitoring_EnterScope() med information om händelsens aktiveringstillstånd. Storleken på event_types (och därmed också på state_array) anges i length.

Argumentet version är en pekare till ett värde som bör allokeras av användaren tillsammans med state_array och initialiseras till 0, och sedan endast sättas av PyMonitoring_EnterScope() själv. Det gör det möjligt för denna funktion att avgöra om händelsetillstånd har ändrats sedan föregående anrop och att snabbt återvända om så inte är fallet.

De scope som avses här är lexikala scope: en funktion, klass eller metod. PyMonitoring_EnterScope() bör anropas varje gång det lexikala scopet skrivs in. Scopes kan skrivas in på nytt, med samma state_array och version, i situationer som när man emulerar en rekursiv Python-funktion. När en kodliknande exekvering pausas, t.ex. vid emulering av en generator, måste scopet lämnas och återinmatas.

Makron för event_types är:

Makro	Händelse
PY_MONITORING_EVENT_BRANCH_LEFT	BRANCH_LEFT
PY_MONITORING_EVENT_BRANCH_RIGHT	BRANCH_RIGHT
PY_MONITORING_EVENT_CALL	CALL
PY_MONITORING_EVENT_C_RAISE	C_RAISE
PY_MONITORING_EVENT_C_RETURN	C_RETURN
PY_MONITORING_EVENT_EXCEPTION_HANDLED	EXCEPTION_HANDLED
PY_MONITORING_EVENT_INSTRUCTION	INSTRUCTION
PY_MONITORING_EVENT_JUMP	JUMP
PY_MONITORING_EVENT_LINE	LINE
PY_MONITORING_EVENT_PY_RESUME	PY_RESUME
PY_MONITORING_EVENT_PY_RETURN	PY_RETURN
PY_MONITORING_EVENT_PY_START	PY_START
PY_MONITORING_EVENT_PY_THROW	PY_THROW
PY_MONITORING_EVENT_PY_UNWIND	PY_UNWIND
PY_MONITORING_EVENT_PY_YIELD	PY_YIELD
PY_MONITORING_EVENT_RAISE	RAISE
PY_MONITORING_EVENT_RERAISE	RERAISE
PY_MONITORING_EVENT_STOP_ITERATION	STOP_ITERATION

int PyMonitoring_ExitScope(void)

Avsluta det senaste området som angavs med PyMonitoring_EnterScope().

int PY_MONITORING_IS_INSTRUMENTED_EVENT(uint8_t ev)

Returnerar true om händelsen som motsvarar händelse-ID:t ev är en lokal händelse.

Tillagd i version 3.13.

Föråldrad sedan version 3.14: Denna funktion är soft deprecated.