Kontextvariablenobjekte

Hinzugefügt in Version 3.7.

Geändert in Version 3.7.1

Hinweis

In Python 3.7.1 wurden die Signaturen aller Kontextvariablen-C-APIs geändert, um PyObject-Zeiger anstelle von PyContext, PyContextVar und PyContextToken zu verwenden, z.B.

// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);

Weitere Details finden Sie unter bpo-34762.

Dieser Abschnitt beschreibt die öffentliche C-API für das Modul contextvars.

type PyContext

Die C-Struktur, die zur Darstellung eines contextvars.Context-Objekts verwendet wird.

type PyContextVar

Die C-Struktur, die zur Darstellung eines contextvars.ContextVar-Objekts verwendet wird.

type PyContextToken

Die C-Struktur, die zur Darstellung eines contextvars.Token-Objekts verwendet wird.

PyTypeObject PyContext_Type

Das Typobjekt, das den Kontext-Typ repräsentiert.

PyTypeObject PyContextVar_Type

Das Typobjekt, das den Kontextvariablen-Typ repräsentiert.

PyTypeObject PyContextToken_Type

Das Typobjekt, das den Kontextvariablen-Token-Typ repräsentiert.

Typüberprüfungs-Makros

int PyContext_CheckExact(PyObject *o)

Gibt `true` zurück, wenn o vom Typ PyContext_Type ist. o darf nicht NULL sein. Diese Funktion schlägt nie fehl.

int PyContextVar_CheckExact(PyObject *o)

Gibt `true` zurück, wenn o vom Typ PyContextVar_Type ist. o darf nicht NULL sein. Diese Funktion schlägt nie fehl.

int PyContextToken_CheckExact(PyObject *o)

Gibt `true` zurück, wenn o vom Typ PyContextToken_Type ist. o darf nicht NULL sein. Diese Funktion schlägt nie fehl.

Funktionen zur Verwaltung von Kontextobjekten

PyObject *PyContext_New(void)

Rückgabewert: Neue Referenz.

Erstellt ein neues, leeres Kontextobjekt. Gibt NULL zurück, wenn ein Fehler aufgetreten ist.

PyObject *PyContext_Copy(PyObject *ctx)

Rückgabewert: Neue Referenz.

Erstellt eine flache Kopie des übergebenen Kontextobjekts ctx. Gibt NULL zurück, wenn ein Fehler aufgetreten ist.

PyObject *PyContext_CopyCurrent(void)

Rückgabewert: Neue Referenz.

Erstellt eine flache Kopie des aktuellen Thread-Kontexts. Gibt NULL zurück, wenn ein Fehler aufgetreten ist.

int PyContext_Enter(PyObject *ctx)

Setzt ctx als aktuellen Kontext für den aktuellen Thread. Gibt 0 bei Erfolg und -1 bei einem Fehler zurück.

int PyContext_Exit(PyObject *ctx)

Deaktiviert den Kontext ctx und stellt den vorherigen Kontext als aktuellen Kontext für den aktuellen Thread wieder her. Gibt 0 bei Erfolg und -1 bei einem Fehler zurück.

int PyContext_AddWatcher(PyContext_WatchCallback callback)

Registriert callback als Beobachter für Kontextobjekte für den aktuellen Interpreter. Gibt eine ID zurück, die an PyContext_ClearWatcher() übergeben werden kann. Im Fehlerfall (z. B. keine verfügbaren Beobachter-IDs mehr) wird -1 zurückgegeben und eine Ausnahme gesetzt.

Hinzugefügt in Version 3.14.

int PyContext_ClearWatcher(int watcher_id)

Löscht den durch watcher_id identifizierten Beobachter, der zuvor von PyContext_AddWatcher() für den aktuellen Interpreter zurückgegeben wurde. Gibt 0 bei Erfolg oder -1 und setzt eine Ausnahme bei einem Fehler zurück (z. B. wenn die angegebene watcher_id nie registriert wurde).

Hinzugefügt in Version 3.14.

type PyContextEvent

Aufzählung möglicher Ereignisse für Beobachter von Kontextobjekten

• Py_CONTEXT_SWITCHED: Der aktuelle Kontext wurde zu einem anderen Kontext gewechselt. Das an die Beobachter-Callback-Funktion übergebene Objekt ist das nun aktuelle contextvars.Context-Objekt oder None, wenn kein Kontext aktuell ist.

Hinzugefügt in Version 3.14.

typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)

Callback-Funktion für Beobachter von Kontextobjekten. Das an die Callback-Funktion übergebene Objekt ist ereignisspezifisch; siehe PyContextEvent für Details.

Wenn die Callback-Funktion mit einer gesetzten Ausnahme zurückkehrt, muss sie -1 zurückgeben; diese Ausnahme wird als nicht abfangbare Ausnahme mit PyErr_FormatUnraisable() ausgegeben. Andernfalls sollte sie 0 zurückgeben.

Es kann bereits eine ausstehende Ausnahme beim Eintritt in den Callback gesetzt sein. In diesem Fall sollte der Callback 0 zurückgeben, wobei die Ausnahme weiterhin gesetzt ist. Das bedeutet, der Callback darf keine andere API aufrufen, die eine Ausnahme setzen kann, es sei denn, er speichert und löscht zuerst den Ausnahmezustand und stellt ihn vor der Rückgabe wieder her.

Hinzugefügt in Version 3.14.

Kontextvariablen-Funktionen

PyObject *PyContextVar_New(const char *name, PyObject *def)

Rückgabewert: Neue Referenz.

Erstellt ein neues ContextVar-Objekt. Der Parameter name wird für Introspektion und Debugging verwendet. Der Parameter def gibt einen Standardwert für die Kontextvariable an oder NULL, wenn kein Standardwert vorhanden ist. Wenn ein Fehler aufgetreten ist, gibt diese Funktion NULL zurück.

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

Ruft den Wert einer Kontextvariable ab. Gibt -1 zurück, wenn während der Suche ein Fehler aufgetreten ist, und 0, wenn kein Fehler aufgetreten ist, unabhängig davon, ob ein Wert gefunden wurde.

Wenn die Kontextvariable gefunden wurde, ist value ein Zeiger darauf. Wenn die Kontextvariable nicht gefunden wurde, zeigt value auf

• default_value, wenn nicht NULL;

• den Standardwert von var, wenn nicht NULL;

• NULL

Mit Ausnahme von NULL gibt die Funktion eine neue Referenz zurück.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)

Rückgabewert: Neue Referenz.

Setzt den Wert von var auf value im aktuellen Kontext. Gibt ein neues Token-Objekt für diese Änderung zurück oder NULL, wenn ein Fehler aufgetreten ist.

int PyContextVar_Reset(PyObject *var, PyObject *token)

Setzt den Zustand der Kontextvariable var auf den Zustand zurück, den sie vor dem Aufruf von PyContextVar_Set() hatte, der das token zurückgegeben hat. Diese Funktion gibt 0 bei Erfolg und -1 bei einem Fehler zurück.