1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
.. highlight:: c
.. _contextvarsobjects:
Context Variables Objects
-------------------------
.. _contextvarsobjects_pointertype_change:
.. versionadded:: 3.7
.. versionchanged:: 3.7.1
.. note::
In Python 3.7.1 the signatures of all context variables
C APIs were **changed** to use :c:type:`PyObject` pointers instead
of :c:type:`PyContext`, :c:type:`PyContextVar`, and
:c:type:`PyContextToken`, e.g.::
// in 3.7.0:
PyContext *PyContext_New(void);
// in 3.7.1+:
PyObject *PyContext_New(void);
See :issue:`34762` for more details.
This section details the public C API for the :mod:`contextvars` module.
.. c:type:: PyContext
The C structure used to represent a :class:`contextvars.Context`
object.
.. c:type:: PyContextVar
The C structure used to represent a :class:`contextvars.ContextVar`
object.
.. c:type:: PyContextToken
The C structure used to represent a :class:`contextvars.Token` object.
.. c:var:: PyTypeObject PyContext_Type
The type object representing the *context* type.
.. c:var:: PyTypeObject PyContextVar_Type
The type object representing the *context variable* type.
.. c:var:: PyTypeObject PyContextToken_Type
The type object representing the *context variable token* type.
Type-check macros:
.. c:function:: int PyContext_CheckExact(PyObject *o)
Return true if *o* is of type :c:data:`PyContext_Type`. *o* must not be
``NULL``. This function always succeeds.
.. c:function:: int PyContextVar_CheckExact(PyObject *o)
Return true if *o* is of type :c:data:`PyContextVar_Type`. *o* must not be
``NULL``. This function always succeeds.
.. c:function:: int PyContextToken_CheckExact(PyObject *o)
Return true if *o* is of type :c:data:`PyContextToken_Type`.
*o* must not be ``NULL``. This function always succeeds.
Context object management functions:
.. c:function:: PyObject *PyContext_New(void)
Create a new empty context object. Returns ``NULL`` if an error
has occurred.
.. c:function:: PyObject *PyContext_Copy(PyObject *ctx)
Create a shallow copy of the passed *ctx* context object.
Returns ``NULL`` if an error has occurred.
.. c:function:: PyObject *PyContext_CopyCurrent(void)
Create a shallow copy of the current thread context.
Returns ``NULL`` if an error has occurred.
.. c:function:: int PyContext_Enter(PyObject *ctx)
Set *ctx* as the current context for the current thread.
Returns ``0`` on success, and ``-1`` on error.
.. c:function:: int PyContext_Exit(PyObject *ctx)
Deactivate the *ctx* context and restore the previous context as the
current context for the current thread. Returns ``0`` on success,
and ``-1`` on error.
.. c:function:: int PyContext_AddWatcher(PyContext_WatchCallback callback)
Register *callback* as a context object watcher for the current interpreter.
Return an ID which may be passed to :c:func:`PyContext_ClearWatcher`.
In case of error (e.g. no more watcher IDs available),
return ``-1`` and set an exception.
.. versionadded:: 3.14
.. c:function:: int PyContext_ClearWatcher(int watcher_id)
Clear watcher identified by *watcher_id* previously returned from
:c:func:`PyContext_AddWatcher` for the current interpreter.
Return ``0`` on success, or ``-1`` and set an exception on error
(e.g. if the given *watcher_id* was never registered.)
.. versionadded:: 3.14
.. c:type:: PyContextEvent
Enumeration of possible context object watcher events:
- ``Py_CONTEXT_EVENT_ENTER``: A context has been entered, causing the
:term:`current context` to switch to it. The object passed to the watch
callback is the now-current :class:`contextvars.Context` object. Each
enter event will eventually have a corresponding exit event for the same
context object after any subsequently entered contexts have themselves been
exited.
- ``Py_CONTEXT_EVENT_EXIT``: A context is about to be exited, which will
cause the :term:`current context` to switch back to what it was before the
context was entered. The object passed to the watch callback is the
still-current :class:`contextvars.Context` object.
.. versionadded:: 3.14
.. c:type:: int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)
Context object watcher callback function. The object passed to the callback
is event-specific; see :c:type:`PyContextEvent` for details.
If the callback returns with an exception set, it must return ``-1``; this
exception will be printed as an unraisable exception using
:c:func:`PyErr_FormatUnraisable`. Otherwise it should return ``0``.
There may already be a pending exception set on entry to the callback. In
this case, the callback should return ``0`` with the same exception still
set. This means the callback may not call any other API that can set an
exception unless it saves and clears the exception state first, and restores
it before returning.
.. versionadded:: 3.14
Context variable functions:
.. c:function:: PyObject *PyContextVar_New(const char *name, PyObject *def)
Create a new ``ContextVar`` object. The *name* parameter is used
for introspection and debug purposes. The *def* parameter specifies
a default value for the context variable, or ``NULL`` for no default.
If an error has occurred, this function returns ``NULL``.
.. c:function:: int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)
Get the value of a context variable. Returns ``-1`` if an error has
occurred during lookup, and ``0`` if no error occurred, whether or not
a value was found.
If the context variable was found, *value* will be a pointer to it.
If the context variable was *not* found, *value* will point to:
- *default_value*, if not ``NULL``;
- the default value of *var*, if not ``NULL``;
- ``NULL``
Except for ``NULL``, the function returns a new reference.
.. c:function:: PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
Set the value of *var* to *value* in the current context. Returns
a new token object for this change, or ``NULL`` if an error has occurred.
.. c:function:: int PyContextVar_Reset(PyObject *var, PyObject *token)
Reset the state of the *var* context variable to that it was in before
:c:func:`PyContextVar_Set` that returned the *token* was called.
This function returns ``0`` on success and ``-1`` on error.
|
