diff options
Diffstat (limited to 'devdocs/python~3.12/c-api%2Fcontextvars.html')
| -rw-r--r-- | devdocs/python~3.12/c-api%2Fcontextvars.html | 66 |
1 files changed, 66 insertions, 0 deletions
diff --git a/devdocs/python~3.12/c-api%2Fcontextvars.html b/devdocs/python~3.12/c-api%2Fcontextvars.html new file mode 100644 index 00000000..200b2e9f --- /dev/null +++ b/devdocs/python~3.12/c-api%2Fcontextvars.html @@ -0,0 +1,66 @@ + <span id="contextvarsobjects"></span><h1>Context Variables Objects</h1> <div class="versionchanged" id="contextvarsobjects-pointertype-change"> <p><span class="versionmodified changed">Changed in version 3.7.1: </span></p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>In Python 3.7.1 the signatures of all context variables C APIs were <strong>changed</strong> to use <a class="reference internal" href="structures#c.PyObject" title="PyObject"><code>PyObject</code></a> pointers instead of <a class="reference internal" href="#c.PyContext" title="PyContext"><code>PyContext</code></a>, <a class="reference internal" href="#c.PyContextVar" title="PyContextVar"><code>PyContextVar</code></a>, and <a class="reference internal" href="#c.PyContextToken" title="PyContextToken"><code>PyContextToken</code></a>, e.g.:</p> <pre data-language="c">// in 3.7.0: +PyContext *PyContext_New(void); + +// in 3.7.1+: +PyObject *PyContext_New(void); +</pre> <p>See <a class="reference external" href="https://bugs.python.org/issue?@action=redirect&bpo=34762">bpo-34762</a> for more details.</p> </div> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> <p>This section details the public C API for the <a class="reference internal" href="../library/contextvars#module-contextvars" title="contextvars: Context Variables"><code>contextvars</code></a> module.</p> <dl class="c type"> <dt class="sig sig-object c" id="c.PyContext"> +<code>type PyContext</code> </dt> <dd> +<p>The C structure used to represent a <a class="reference internal" href="../library/contextvars#contextvars.Context" title="contextvars.Context"><code>contextvars.Context</code></a> object.</p> </dd> +</dl> <dl class="c type"> <dt class="sig sig-object c" id="c.PyContextVar"> +<code>type PyContextVar</code> </dt> <dd> +<p>The C structure used to represent a <a class="reference internal" href="../library/contextvars#contextvars.ContextVar" title="contextvars.ContextVar"><code>contextvars.ContextVar</code></a> object.</p> </dd> +</dl> <dl class="c type"> <dt class="sig sig-object c" id="c.PyContextToken"> +<code>type PyContextToken</code> </dt> <dd> +<p>The C structure used to represent a <a class="reference internal" href="../library/contextvars#contextvars.Token" title="contextvars.Token"><code>contextvars.Token</code></a> object.</p> </dd> +</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyContext_Type"> +<code>PyTypeObject PyContext_Type</code> </dt> <dd> +<p>The type object representing the <em>context</em> type.</p> </dd> +</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyContextVar_Type"> +<code>PyTypeObject PyContextVar_Type</code> </dt> <dd> +<p>The type object representing the <em>context variable</em> type.</p> </dd> +</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyContextToken_Type"> +<code>PyTypeObject PyContextToken_Type</code> </dt> <dd> +<p>The type object representing the <em>context variable token</em> type.</p> </dd> +</dl> <p>Type-check macros:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_CheckExact"> +<code>int PyContext_CheckExact(PyObject *o)</code> </dt> <dd> +<p>Return true if <em>o</em> is of type <a class="reference internal" href="#c.PyContext_Type" title="PyContext_Type"><code>PyContext_Type</code></a>. <em>o</em> must not be <code>NULL</code>. This function always succeeds.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_CheckExact"> +<code>int PyContextVar_CheckExact(PyObject *o)</code> </dt> <dd> +<p>Return true if <em>o</em> is of type <a class="reference internal" href="#c.PyContextVar_Type" title="PyContextVar_Type"><code>PyContextVar_Type</code></a>. <em>o</em> must not be <code>NULL</code>. This function always succeeds.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextToken_CheckExact"> +<code>int PyContextToken_CheckExact(PyObject *o)</code> </dt> <dd> +<p>Return true if <em>o</em> is of type <a class="reference internal" href="#c.PyContextToken_Type" title="PyContextToken_Type"><code>PyContextToken_Type</code></a>. <em>o</em> must not be <code>NULL</code>. This function always succeeds.</p> </dd> +</dl> <p>Context object management functions:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_New"> +<code>PyObject *PyContext_New(void)</code> </dt> <dd> +<em class="refcount">Return value: New reference.</em><p>Create a new empty context object. Returns <code>NULL</code> if an error has occurred.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_Copy"> +<code>PyObject *PyContext_Copy(PyObject *ctx)</code> </dt> <dd> +<em class="refcount">Return value: New reference.</em><p>Create a shallow copy of the passed <em>ctx</em> context object. Returns <code>NULL</code> if an error has occurred.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_CopyCurrent"> +<code>PyObject *PyContext_CopyCurrent(void)</code> </dt> <dd> +<em class="refcount">Return value: New reference.</em><p>Create a shallow copy of the current thread context. Returns <code>NULL</code> if an error has occurred.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_Enter"> +<code>int PyContext_Enter(PyObject *ctx)</code> </dt> <dd> +<p>Set <em>ctx</em> as the current context for the current thread. Returns <code>0</code> on success, and <code>-1</code> on error.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_Exit"> +<code>int PyContext_Exit(PyObject *ctx)</code> </dt> <dd> +<p>Deactivate the <em>ctx</em> context and restore the previous context as the current context for the current thread. Returns <code>0</code> on success, and <code>-1</code> on error.</p> </dd> +</dl> <p>Context variable functions:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_New"> +<code>PyObject *PyContextVar_New(const char *name, PyObject *def)</code> </dt> <dd> +<em class="refcount">Return value: New reference.</em><p>Create a new <code>ContextVar</code> object. The <em>name</em> parameter is used for introspection and debug purposes. The <em>def</em> parameter specifies a default value for the context variable, or <code>NULL</code> for no default. If an error has occurred, this function returns <code>NULL</code>.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_Get"> +<code>int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)</code> </dt> <dd> +<p>Get the value of a context variable. Returns <code>-1</code> if an error has occurred during lookup, and <code>0</code> if no error occurred, whether or not a value was found.</p> <p>If the context variable was found, <em>value</em> will be a pointer to it. If the context variable was <em>not</em> found, <em>value</em> will point to:</p> <ul class="simple"> <li> +<em>default_value</em>, if not <code>NULL</code>;</li> <li>the default value of <em>var</em>, if not <code>NULL</code>;</li> <li><code>NULL</code></li> </ul> <p>Except for <code>NULL</code>, the function returns a new reference.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_Set"> +<code>PyObject *PyContextVar_Set(PyObject *var, PyObject *value)</code> </dt> <dd> +<em class="refcount">Return value: New reference.</em><p>Set the value of <em>var</em> to <em>value</em> in the current context. Returns a new token object for this change, or <code>NULL</code> if an error has occurred.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_Reset"> +<code>int PyContextVar_Reset(PyObject *var, PyObject *token)</code> </dt> <dd> +<p>Reset the state of the <em>var</em> context variable to that it was in before <a class="reference internal" href="#c.PyContextVar_Set" title="PyContextVar_Set"><code>PyContextVar_Set()</code></a> that returned the <em>token</em> was called. This function returns <code>0</code> on success and <code>-1</code> on error.</p> </dd> +</dl> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/c-api/contextvars.html" class="_attribution-link">https://docs.python.org/3.12/c-api/contextvars.html</a> + </p> +</div> |