Kontextvariabelobjekt

Tillagd i version 3.7.

Ändrad i version 3.7.1:

Anteckning

I Python 3.7.1 ändrades signaturerna för alla kontextvariabler C API:er till att använda PyObject pekare istället för PyContext, PyContextVar, och PyContextToken, t.ex:

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

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

Se bpo-34762 för mer information.

Detta avsnitt beskriver det publika C API:et för modulen contextvars.

type PyContext

Den C-struktur som används för att representera ett contextvars.Context-objekt.

type PyContextVar

Den C-struktur som används för att representera ett contextvars.ContextVar-objekt.

type PyContextToken

Den C-struktur som används för att representera ett contextvars.Token-objekt.

PyTypeObject PyContext_Type

Typobjektet som representerar kontext-typen.

PyTypeObject PyContextVar_Type

Typobjektet som representerar typen av kontextvariabel.

PyTypeObject PyContextToken_Type

Typobjektet som representerar kontextvariabelns token-typ.

Typkontrollera makron:

int PyContext_CheckExact(PyObject *o)

Returnerar true om o är av typen PyContext_Type. o får inte vara NULL. Denna funktion lyckas alltid.

int PyContextVar_CheckExact(PyObject *o)

Returnerar true om o är av typen PyContextVar_Type. o får inte vara NULL. Denna funktion lyckas alltid.

int PyContextToken_CheckExact(PyObject *o)

Returnerar true om o är av typen PyContextToken_Type. o får inte vara NULL. Denna funktion lyckas alltid.

Funktioner för hantering av kontextobjekt:

PyObject *PyContext_New(void)
Returnera värde: Ny referens.

Skapar ett nytt tomt kontextobjekt. Returnerar NULL om ett fel har inträffat.

PyObject *PyContext_Copy(PyObject *ctx)
Returnera värde: Ny referens.

Skapar en ytlig kopia av det passerade ctx kontextobjektet. Returnerar NULL om ett fel har inträffat.

PyObject *PyContext_CopyCurrent(void)
Returnera värde: Ny referens.

Skapar en ytlig kopia av den aktuella trådkontexten. Returnerar NULL om ett fel har inträffat.

int PyContext_Enter(PyObject *ctx)

Ställ in ctx som aktuell kontext för aktuell tråd. Returnerar 0 vid framgång och -1 vid fel.

int PyContext_Exit(PyObject *ctx)

Avaktiverar ctx-kontexten och återställer den föregående kontexten som aktuell kontext för den aktuella tråden. Returnerar 0 vid framgång och -1 vid fel.

int PyContext_AddWatcher(PyContext_WatchCallback callback)

Registrerar callback som en kontextobjekt-vaktare för den aktuella tolken. Returnerar ett ID som kan skickas till PyContext_ClearWatcher(). I händelse av fel (t.ex. inga fler ID:n tillgängliga), returnera -1 och sätt ett undantag.

Tillagd i version 3.14.

int PyContext_ClearWatcher(int watcher_id)

Rensa den observatör som identifieras av watcher_id och som tidigare returnerats från PyContext_AddWatcher() för den aktuella tolken. Returnerar 0 vid framgång, eller -1 och sätter ett undantag vid fel (t.ex. om det givna watcher_id aldrig registrerades)

Tillagd i version 3.14.

type PyContextEvent

Uppräkning av möjliga händelser för kontextobjektets bevakare:

  • Py_CONTEXT_SWITCHED: Den current context har bytt till en annan kontext. Objektet som skickas till watch callback är det nu aktuella contextvars.Context-objektet, eller None om inget sammanhang är aktuellt.

Tillagd i version 3.14.

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

Återkallelsefunktion för kontextobjektets bevakare. Objektet som skickas till återuppringningen är händelsespecifikt; se PyContextEvent för detaljer.

Om callbacken returneras med ett undantag inställt måste den returnera -1; detta undantag kommer att skrivas ut som ett undantag som inte kan bedömas med PyErr_FormatUnraisable(). Annars bör det returnera 0.

Det kan redan finnas ett väntande undantag inställt vid ingången till återuppringningen. I detta fall bör återuppringningen returnera 0 med samma undantag fortfarande inställt. Detta innebär att återuppringningen inte får anropa något annat API som kan ställa in ett undantag om det inte sparar och rensar undantagstillståndet först och återställer det innan det returneras.

Tillagd i version 3.14.

Funktioner för kontextvariabler:

PyObject *PyContextVar_New(const char *name, PyObject *def)
Returnera värde: Ny referens.

Skapa ett nytt objekt ContextVar. Parametern name används för introspektion och felsökning. Parametern def anger ett standardvärde för kontextvariabeln, eller NULL om inget standardvärde ska användas. Om ett fel har uppstått returnerar denna funktion NULL.

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

Hämtar värdet på en kontextvariabel. Returnerar -1 om ett fel har inträffat under sökningen, och 0 om inget fel har inträffat, oavsett om ett värde hittades eller inte.

Om kontextvariabeln hittades kommer value att vara en pekare till den. Om kontextvariabeln inte hittades kommer value att peka på:

  • default_value, om inte NULL;

  • standardvärdet för var, om det inte är NULL;

  • NULL

Med undantag för NULL returnerar funktionen en ny referens.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
Returnera värde: Ny referens.

Ställer in värdet på var till värde i det aktuella sammanhanget. Returnerar ett nytt token-objekt för denna ändring, eller NULL om ett fel har inträffat.

int PyContextVar_Reset(PyObject *var, PyObject *token)

Återställer tillståndet för kontextvariabeln var till det tillstånd den hade innan PyContextVar_Set() som returnerade token anropades. Denna funktion returnerar 0 vid framgång och -1 vid fel.