Stéphane Wirtel | cbb6484 | 2019-05-17 11:55:34 +0200 | [diff] [blame] | 1 | .. highlight:: c |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 2 | |
| 3 | .. _contextvarsobjects: |
| 4 | |
| 5 | Context Variables Objects |
| 6 | ------------------------- |
| 7 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 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 | |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 27 | .. versionadded:: 3.7 |
| 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 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 78 | .. c:function:: PyObject *PyContext_New(void) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 79 | |
| 80 | Create a new empty context object. Returns ``NULL`` if an error |
| 81 | has occurred. |
| 82 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 83 | .. c:function:: PyObject *PyContext_Copy(PyObject *ctx) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 84 | |
| 85 | Create a shallow copy of the passed *ctx* context object. |
| 86 | Returns ``NULL`` if an error has occurred. |
| 87 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 88 | .. c:function:: PyObject *PyContext_CopyCurrent(void) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 89 | |
| 90 | Create a shallow copy of the current thread context. |
| 91 | Returns ``NULL`` if an error has occurred. |
| 92 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 93 | .. c:function:: int PyContext_Enter(PyObject *ctx) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 94 | |
| 95 | Set *ctx* as the current context for the current thread. |
| 96 | Returns ``0`` on success, and ``-1`` on error. |
| 97 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 98 | .. c:function:: int PyContext_Exit(PyObject *ctx) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 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 | |
| 110 | Context variable functions: |
| 111 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 112 | .. c:function:: PyObject *PyContextVar_New(const char *name, PyObject *def) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 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 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 119 | .. c:function:: int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 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 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 134 | .. c:function:: PyObject *PyContextVar_Set(PyObject *var, PyObject *value) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 135 | |
| 136 | Set the value of *var* to *value* in the current context. Returns a |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 137 | pointer to a :c:type:`PyObject` object, or ``NULL`` if an error |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 138 | has occurred. |
| 139 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 140 | .. c:function:: int PyContextVar_Reset(PyObject *var, PyObject *token) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 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. |