1.. highlightlang:: c 2 3.. _contextvarsobjects: 4 5Context Variables Objects 6------------------------- 7 8.. _contextvarsobjects_pointertype_change: 9.. versionchanged:: 3.7.1 10 11 .. note:: 12 13 In Python 3.7.1 the signatures of all context variables 14 C APIs were **changed** to use :c:type:`PyObject` pointers instead 15 of :c:type:`PyContext`, :c:type:`PyContextVar`, and 16 :c:type:`PyContextToken`, e.g.:: 17 18 // in 3.7.0: 19 PyContext *PyContext_New(void); 20 21 // in 3.7.1+: 22 PyObject *PyContext_New(void); 23 24 See :issue:`34762` for more details. 25 26 27.. versionadded:: 3.7 28 29This 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 58Type-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 76Context 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_ClearFreeList() 105 106 Clear the context variable free list. Return the total number of 107 freed items. This function always succeeds. 108 109 110Context variable functions: 111 112.. c:function:: PyObject *PyContextVar_New(const char *name, PyObject *def) 113 114 Create a new ``ContextVar`` object. The *name* parameter is used 115 for introspection and debug purposes. The *def* parameter may optionally 116 specify the default value for the context variable. If an error has 117 occurred, this function returns ``NULL``. 118 119.. c:function:: int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value) 120 121 Get the value of a context variable. Returns ``-1`` if an error has 122 occurred during lookup, and ``0`` if no error occurred, whether or not 123 a value was found. 124 125 If the context variable was found, *value* will be a pointer to it. 126 If the context variable was *not* found, *value* will point to: 127 128 - *default_value*, if not ``NULL``; 129 - the default value of *var*, if not ``NULL``; 130 - ``NULL`` 131 132 If the value was found, the function will create a new reference to it. 133 134.. c:function:: PyObject *PyContextVar_Set(PyObject *var, PyObject *value) 135 136 Set the value of *var* to *value* in the current context. Returns a 137 pointer to a :c:type:`PyObject` object, or ``NULL`` if an error 138 has occurred. 139 140.. c:function:: int PyContextVar_Reset(PyObject *var, PyObject *token) 141 142 Reset the state of the *var* context variable to that it was in before 143 :c:func:`PyContextVar_Set` that returned the *token* was called. 144 This function returns ``0`` on success and ``-1`` on error. 145