Ereignisse

Während ein Code-Objekt ausgeführt wird, treten verschiedene Ereignisse auf, die für Tools von Interesse sein könnten. Durch die Aktivierung von Ereignissen und die Registrierung von Callback-Funktionen können Tools auf diese Ereignisse nach Belieben reagieren. Ereignisse können global oder für einzelne Code-Objekte festgelegt werden.

Für 3.12 unterstützt CPython die folgenden Ereignisse

• PY_START: Beginn einer Python-Funktion (tritt unmittelbar nach dem Aufruf auf, der Frame des Aufgerufenen befindet sich auf dem Stack)
• PY_RESUME: Wiederaufnahme einer Python-Funktion (für Generator- und Coroutine-Funktionen), außer bei throw()-Aufrufen.
• PY_THROW: Eine Python-Funktion wird durch einen throw()-Aufruf wieder aufgenommen.
• PY_RETURN: Rückgabe aus einer Python-Funktion (tritt unmittelbar vor der Rückgabe auf, der Frame des Aufgerufenen befindet sich auf dem Stack).
• PY_YIELD: Yield aus einer Python-Funktion (tritt unmittelbar vor dem Yield auf, der Frame des Aufgerufenen befindet sich auf dem Stack).
• PY_UNWIND: Verlassen einer Python-Funktion während der Exception-Unwinding.
• CALL: Ein Aufruf im Python-Code (Ereignis tritt vor dem Aufruf auf).
• C_RETURN: Rückkehr von einem beliebigen aufrufbaren Objekt, außer Python-Funktionen (Ereignis tritt nach der Rückkehr auf).
• C_RAISE: Exception, die von einem beliebigen aufrufbaren Objekt außer Python-Funktionen ausgelöst wird (Ereignis tritt nach dem Verlassen auf).
• RAISE: Eine Exception wird ausgelöst, außer denen, die ein STOP_ITERATION-Ereignis verursachen.
• EXCEPTION_HANDLED: Eine Exception wird behandelt.
• LINE: Eine Anweisung steht kurz vor der Ausführung, die eine andere Zeilennummer als die vorhergehende Anweisung hat.
• INSTRUCTION – Eine VM-Anweisung steht kurz vor der Ausführung.
• JUMP – Ein unbedingter Sprung im Kontrollflussgraphen wird gemacht.
• BRANCH – Ein bedingter Sprung wird genommen (oder nicht).
• STOP_ITERATION – Eine künstliche StopIteration wird ausgelöst; siehe das STOP_ITERATION-Ereignis.

Zukünftig können weitere Ereignisse hinzugefügt werden.

Alle Ereignisse werden Attribute des events-Namensraums in sys.monitoring sein. Alle Ereignisse werden durch eine Potenz von zwei als Ganzzahl dargestellt, sodass sie mit dem |-Operator kombiniert werden können.

Ereignisse sind in drei Gruppen unterteilt

Tool-Identifikatoren

Die VM kann bis zu 6 Tools gleichzeitig unterstützen. Vor der Registrierung oder Aktivierung von Ereignissen sollte ein Tool einen Bezeichner wählen. Bezeichner sind Ganzzahlen im Bereich von 0 bis 5.

sys.monitoring.use_tool_id(id, name:str) -> None
sys.monitoring.free_tool_id(id) -> None
sys.monitoring.get_tool(id) ->  str | None

sys.monitoring.use_tool_id löst einen ValueError aus, wenn id in Gebrauch ist. sys.monitoring.get_tool gibt den Namen des Tools zurück, wenn id in Gebrauch ist, andernfalls gibt es None zurück.

Alle IDs werden von der VM in Bezug auf Ereignisse gleich behandelt, aber die folgenden IDs sind vordefiniert, um die Zusammenarbeit von Tools zu erleichtern

sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5

Es besteht keine Verpflichtung, eine ID festzulegen, noch hindert etwas ein Tool daran, eine ID zu verwenden, auch wenn sie bereits verwendet wird. Tools wird jedoch empfohlen, eine eindeutige ID zu verwenden und andere Tools zu respektieren.

Wenn beispielsweise ein Debugger angehängt wäre und DEBUGGER_ID verwendet würde, sollte er einen Fehler melden, anstatt einfach fortzufahren.

Die OPTIMIZER_ID ist für Tools wie Cinder oder PyTorch vorgesehen, die Python-Code optimieren möchten, aber entscheiden müssen, was sie in einer Weise optimieren, die von einem größeren Kontext abhängt.

Globale Ereignisse festlegen

Ereignisse können global gesteuert werden, indem die Menge der überwachten Ereignisse geändert wird

• sys.monitoring.get_events(tool_id:int) Gibt die int zurück, die alle aktiven Ereignisse darstellt.
• sys.monitoring.set_events(tool_id:int, event_set: int) Aktiviert alle Ereignisse, die in event_set festgelegt sind. Löst einen ValueError aus, wenn tool_id nicht in Gebrauch ist.

Standardmäßig sind keine Ereignisse aktiv.

Ereignisse pro Code-Objekt

Ereignisse können auch auf Code-Objekt-Basis gesteuert werden

• sys.monitoring.get_local_events(tool_id:int, code: CodeType)->int Gibt alle lokalen Ereignisse für code zurück
• sys.monitoring.set_local_events(tool_id:int, code: CodeType, event_set: int) Aktiviert alle lokalen Ereignisse für code, die in event_set festgelegt sind. Löst einen ValueError aus, wenn tool_id nicht in Gebrauch ist.

Lokale Ereignisse werden zu globalen Ereignissen hinzugefügt, maskieren sie aber nicht. Mit anderen Worten, alle globalen Ereignisse werden für ein Code-Objekt ausgelöst, unabhängig von den lokalen Ereignissen.

Callback-Funktionen registrieren

Um eine aufrufbare Funktion für Ereignisse zu registrieren, rufen Sie auf

sys.monitoring.register_callback(tool_id:int, event: int, func: Callable | None) -> Callable | None

Wenn ein anderer Callback für die gegebene tool_id und das gegebene event registriert war, wird dieser abgemeldet und zurückgegeben. Andernfalls gibt register_callback None zurück.

Funktionen können abgemeldet werden, indem sys.monitoring.register_callback(tool_id, event, None) aufgerufen wird.

Callback-Funktionen können jederzeit registriert und abgemeldet werden.

Die Registrierung oder Abmeldung einer Callback-Funktion löst ein sys.audit-Ereignis aus.

Ereignisse in Callback-Funktionen

Ereignisse werden in Callback-Funktionen und deren Aufgerufenen für das Tool, das den Callback registriert hat, suspendiert.

Das bedeutet, dass andere Tools Ereignisse in den Callback-Funktionen anderer Tools sehen werden. Dies könnte nützlich sein, um ein Profiling-Tool zu debuggen, würde aber irreführende Profile ergeben, da das Debugging-Tool im Profil erscheinen würde.

Reihenfolge der Ereignisse

Wenn eine Anweisung mehrere Ereignisse auslöst, treten diese in folgender Reihenfolge auf

• LINE
• INSTRUCTION
• Alle anderen Ereignisse (nur eines dieser Ereignisse kann pro Anweisung auftreten)

Jedes Ereignis wird in aufsteigender Reihenfolge der ID an die Tools geliefert.

Die Gruppe „call“-Ereignisse

Die meisten Ereignisse sind unabhängig; das Festlegen oder Deaktivieren eines Ereignisses hat keine Auswirkungen auf die anderen. Die Ereignisse CALL, C_RAISE und C_RETURN bilden jedoch eine Gruppe. Wenn eines dieser Ereignisse festgelegt oder deaktiviert wird, werden alle Ereignisse in der Gruppe ebenfalls betroffen. Das Deaktivieren eines CALL-Ereignisses deaktiviert nicht die übereinstimmenden C_RAISE- oder C_RETURN-Ereignisse, deaktiviert aber alle nachfolgenden Ereignisse.

Attribute des sys.monitoring-Namensraums

• def use_tool_id(id)->None
• def free_tool_id(id)->None
• def get_events(tool_id: int)->int
• def set_events(tool_id: int, event_set: int)->None
• def get_local_events(tool_id: int, code: CodeType)->int
• def set_local_events(tool_id: int, code: CodeType, event_set: int)->None
• def register_callback(tool_id: int, event: int, func: Callable)->Optional[Callable]
• def restart_events()->None
• DISABLE: object
• MISSING: object

Zugriff auf „nur Debug“-Funktionen

Einige Funktionen der Standardbibliothek sind für normalen Code nicht zugänglich, aber für Debugger zugänglich. Zum Beispiel das Setzen lokaler Variablen oder die Zeilennummer.

Diese Funktionen werden für Callback-Funktionen verfügbar sein.

Performance

Wenn keine Ereignisse aktiv sind, sollte dieser PEP einen kleinen positiven Einfluss auf die Leistung haben. Experimente zeigen eine Beschleunigung von 1 bis 2 % durch die direkte Nichtunterstützung von sys.settrace().

Die Leistung von sys.settrace() wird ungefähr gleich bleiben. Die Leistung von sys.setprofile() sollte besser sein. Tools, die auf sys.settrace() und sys.setprofile() angewiesen sind, können jedoch mit der von diesem PEP bereitgestellten API erheblich beschleunigt werden.

Wenn eine kleine Menge von Ereignissen aktiv ist, z. B. für einen Debugger, dann wird der Overhead von Callbacks um Größenordnungen geringer sein als bei sys.settrace() und viel günstiger als die Verwendung von PEP 523.

Coverage-Tools können mit sehr geringen Kosten implementiert werden, indem DISABLE in allen Callbacks zurückgegeben wird.

Für stark instrumentierten Code, z. B. unter Verwendung von LINE, wird die Leistung besser sein als bei sys.settrace, aber nicht wesentlich, da die Leistung von der Zeit dominiert wird, die in Callbacks verbracht wird.

Für optimierende virtuelle Maschinen, wie zukünftige Versionen von CPython (und PyPy, falls sie diese API unterstützen möchten), können Änderungen am Satz aktiver Ereignisse mitten in einem lang laufenden Programm recht teuer sein und möglicherweise Hunderte von Millisekunden dauern, da sie Deoptimierungen auslösen. Sobald eine solche Deoptimierung stattgefunden hat, sollte sich die Leistung erholen, da die VM den instrumentierten Code neu optimieren kann.

Im Allgemeinen können diese Operationen als schnell betrachtet werden

• def get_events(tool_id: int)->int
• def get_local_events(tool_id: int, code: CodeType)->int
• def register_callback(tool_id: int, event: int, func: Callable)->Optional[Callable]
• def get_tool(tool_id) -> str | None

Diese Operationen sind langsamer, aber nicht besonders

• def set_local_events(tool_id: int, code: CodeType, event_set: int)->None

Und diese Operationen sollten als langsam angesehen werden

• def use_tool_id(id, name:str)->None
• def free_tool_id(id)->None
• def set_events(tool_id: int, event_set: int)->None
• def restart_events()->None

Wie langsam die langsamen Operationen sind, hängt davon ab, wann sie auftreten. Wenn sie früh im Programm ausgeführt werden, bevor Module geladen sind, sollten sie relativ kostengünstig sein.

Debugger

Coverage-Tools

Coverage-Tools müssen verfolgen, welche Teile des Kontrollflusses ausgeführt wurden. Dazu müssen sie sich für die PY_-Ereignisse sowie für JUMP und BRANCH registrieren.

Diese Informationen können dann nach Abschluss der Ausführung in einen zeilenbasierten Bericht umgewandelt werden.

Profiler

Einfache Profiler müssen Informationen über Aufrufe sammeln. Dazu sollten sich Profiler für die folgenden Ereignisse registrieren

• PY_START
• PY_RESUME
• PY_THROW
• PY_RETURN
• PY_YIELD
• PY_UNWIND
• CALL
• C_RAISE
• C_RETURN