Debian Codegraph @

Doc/c-api/contextvars.rst

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