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 |
Serhiy Storchaka | 25fc088 | 2019-10-30 12:03:20 +0200 | [diff] [blame] | 63 | ``NULL``. This function always succeeds. |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 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 |
Serhiy Storchaka | 25fc088 | 2019-10-30 12:03:20 +0200 | [diff] [blame] | 68 | ``NULL``. This function always succeeds. |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 69 | |
| 70 | .. c:function:: int PyContextToken_CheckExact(PyObject *o) |
| 71 | |
| 72 | Return true if *o* is of type :c:data:`PyContextToken_Type`. |
Serhiy Storchaka | 25fc088 | 2019-10-30 12:03:20 +0200 | [diff] [blame] | 73 | *o* must not be ``NULL``. This function always succeeds. |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 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 | |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 104 | |
| 105 | Context variable functions: |
| 106 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 107 | .. c:function:: PyObject *PyContextVar_New(const char *name, PyObject *def) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 108 | |
| 109 | Create a new ``ContextVar`` object. The *name* parameter is used |
scoder | 4c49be7 | 2021-04-28 16:03:19 +0200 | [diff] [blame] | 110 | for introspection and debug purposes. The *def* parameter specifies |
| 111 | a default value for the context variable, or ``NULL`` for no default. |
| 112 | If an error has occurred, this function returns ``NULL``. |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 113 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 114 | .. c:function:: int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 115 | |
| 116 | Get the value of a context variable. Returns ``-1`` if an error has |
| 117 | occurred during lookup, and ``0`` if no error occurred, whether or not |
| 118 | a value was found. |
| 119 | |
| 120 | If the context variable was found, *value* will be a pointer to it. |
| 121 | If the context variable was *not* found, *value* will point to: |
| 122 | |
| 123 | - *default_value*, if not ``NULL``; |
| 124 | - the default value of *var*, if not ``NULL``; |
| 125 | - ``NULL`` |
| 126 | |
scoder | 4c49be7 | 2021-04-28 16:03:19 +0200 | [diff] [blame] | 127 | Except for ``NULL``, the function returns a new reference. |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 128 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 129 | .. c:function:: PyObject *PyContextVar_Set(PyObject *var, PyObject *value) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 130 | |
scoder | 4c49be7 | 2021-04-28 16:03:19 +0200 | [diff] [blame] | 131 | Set the value of *var* to *value* in the current context. Returns |
| 132 | a new token object for this change, or ``NULL`` if an error has occurred. |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 133 | |
Yury Selivanov | 2ec872b | 2018-09-21 15:33:56 -0400 | [diff] [blame] | 134 | .. c:function:: int PyContextVar_Reset(PyObject *var, PyObject *token) |
Elvis Pranskevichus | b2f5f59 | 2018-05-22 13:31:56 -0400 | [diff] [blame] | 135 | |
| 136 | Reset the state of the *var* context variable to that it was in before |
| 137 | :c:func:`PyContextVar_Set` that returned the *token* was called. |
| 138 | This function returns ``0`` on success and ``-1`` on error. |