From b2f5f59ae15564b991f3ca4850e6ad28d9faacbc Mon Sep 17 00:00:00 2001 From: Elvis Pranskevichus Date: Tue, 22 May 2018 13:31:56 -0400 Subject: bpo-33592: Document the C API in PEP 567 (contextvars) (GH-7033) --- Doc/c-api/concrete.rst | 2 +- Doc/c-api/contextvars.rst | 125 ++++++++++++++++++++++++++++++++++++++++++++++ Doc/whatsnew/3.7.rst | 6 ++- 3 files changed, 131 insertions(+), 2 deletions(-) create mode 100644 Doc/c-api/contextvars.rst diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index 47dab81..9558a4a 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -113,5 +113,5 @@ Other Objects capsule.rst gen.rst coro.rst + contextvars.rst datetime.rst - diff --git a/Doc/c-api/contextvars.rst b/Doc/c-api/contextvars.rst new file mode 100644 index 0000000..4c33ba4 --- /dev/null +++ b/Doc/c-api/contextvars.rst @@ -0,0 +1,125 @@ +.. highlightlang:: c + +.. _contextvarsobjects: + +Context Variables Objects +------------------------- + +.. versionadded:: 3.7 + +This section details the public C API for the :mod:`contextvars` module. + +.. c:type:: PyContext + + The C structure used to represent a :class:`contextvars.Context` + object. + +.. c:type:: PyContextVar + + The C structure used to represent a :class:`contextvars.ContextVar` + object. + +.. c:type:: PyContextToken + + The C structure used to represent a :class:`contextvars.Token` object. + +.. c:var:: PyTypeObject PyContext_Type + + The type object representing the *context* type. + +.. c:var:: PyTypeObject PyContextVar_Type + + The type object representing the *context variable* type. + +.. c:var:: PyTypeObject PyContextToken_Type + + The type object representing the *context variable token* type. + + +Type-check macros: + +.. c:function:: int PyContext_CheckExact(PyObject *o) + + Return true if *o* is of type :c:data:`PyContext_Type`. *o* must not be + *NULL*. This function always succeeds. + +.. c:function:: int PyContextVar_CheckExact(PyObject *o) + + Return true if *o* is of type :c:data:`PyContextVar_Type`. *o* must not be + *NULL*. This function always succeeds. + +.. c:function:: int PyContextToken_CheckExact(PyObject *o) + + Return true if *o* is of type :c:data:`PyContextToken_Type`. + *o* must not be *NULL*. This function always succeeds. + + +Context object management functions: + +.. c:function:: PyContext *PyContext_New(void) + + Create a new empty context object. Returns ``NULL`` if an error + has occurred. + +.. c:function:: PyContext *PyContext_Copy(PyContext *ctx) + + Create a shallow copy of the passed *ctx* context object. + Returns ``NULL`` if an error has occurred. + +.. c:function:: PyContext *PyContext_CopyCurrent(void) + + Create a shallow copy of the current thread context. + Returns ``NULL`` if an error has occurred. + +.. c:function:: int PyContext_Enter(PyContext *ctx) + + Set *ctx* as the current context for the current thread. + Returns ``0`` on success, and ``-1`` on error. + +.. c:function:: int PyContext_Exit(PyContext *ctx) + + Deactivate the *ctx* context and restore the previous context as the + current context for the current thread. Returns ``0`` on success, + and ``-1`` on error. + +.. c:function:: int PyContext_ClearFreeList() + + Clear the context variable free list. Return the total number of + freed items. This function always succeeds. + + +Context variable functions: + +.. c:function:: PyContextVar *PyContextVar_New(const char *name, PyObject *def) + + Create a new ``ContextVar`` object. The *name* parameter is used + for introspection and debug purposes. The *def* parameter may optionally + specify the default value for the context variable. If an error has + occurred, this function returns ``NULL``. + +.. c:function:: int PyContextVar_Get(PyContextVar *var, PyObject *default_value, PyObject **value) + + Get the value of a context variable. Returns ``-1`` if an error has + occurred during lookup, and ``0`` if no error occurred, whether or not + a value was found. + + If the context variable was found, *value* will be a pointer to it. + If the context variable was *not* found, *value* will point to: + + - *default_value*, if not ``NULL``; + - the default value of *var*, if not ``NULL``; + - ``NULL`` + + If the value was found, the function will create a new reference to it. + +.. c:function:: PyContextToken *PyContextVar_Set(PyContextVar *var, PyObject *value) + + Set the value of *var* to *value* in the current context. Returns a + pointer to a :c:type:`PyContextToken` object, or ``NULL`` if an error + has occurred. + +.. c:function:: int PyContextVar_Reset(PyContextVar *var, PyContextToken *token) + + Reset the state of the *var* context variable to that it was in before + :c:func:`PyContextVar_Set` that returned the *token* was called. + This function returns ``0`` on success and ``-1`` on error. diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 8324be8..ac69719 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -515,7 +515,8 @@ New Modules contextvars ----------- -The new :mod:`contextvars` module and a set of new C APIs introduce +The new :mod:`contextvars` module and a set of +:ref:`new C APIs ` introduce support for *context variables*. Context variables are conceptually similar to thread-local variables. Unlike TLS, context variables support asynchronous code correctly. @@ -1543,6 +1544,9 @@ A new API for thread-local storage has been implemented. See :ref:`thread-specific-storage-api` for a complete reference. (Contributed by Masayuki Yamamoto in :issue:`25658`.) +The new :ref:`context variables ` functionality +exposes a number of :ref:`new C APIs `. + The new :c:func:`PyImport_GetModule` function returns the previously imported module with the given name. (Contributed by Eric Snow in :issue:`28411`.) -- cgit v0.12