Context Variables Objects
*************************

Note: Changed in version 3.7.1: In Python 3.7.1 the signatures of
  all context variables C APIs were **changed** to use "PyObject"
  pointers instead of "PyContext", "PyContextVar", and
  "PyContextToken", e.g.:

     // in 3.7.0:
     PyContext *PyContext_New(void);

     // in 3.7.1+:
     PyObject *PyContext_New(void);

  See bpo-34762 for more details.

New in version 3.7.

This section details the public C API for the "contextvars" module.

PyContext

   The C structure used to represent a "contextvars.Context" object.

PyContextVar

   The C structure used to represent a "contextvars.ContextVar"
   object.

PyContextToken

   The C structure used to represent a "contextvars.Token" object.

PyTypeObject PyContext_Type

   The type object representing the *context* type.

PyTypeObject PyContextVar_Type

   The type object representing the *context variable* type.

PyTypeObject PyContextToken_Type

   The type object representing the *context variable token* type.

Type-check macros:

int PyContext_CheckExact(PyObject *o)

   Return true if *o* is of type "PyContext_Type". *o* must not be
   *NULL*.  This function always succeeds.

int PyContextVar_CheckExact(PyObject *o)

   Return true if *o* is of type "PyContextVar_Type". *o* must not be
   *NULL*.  This function always succeeds.

int PyContextToken_CheckExact(PyObject *o)

   Return true if *o* is of type "PyContextToken_Type". *o* must not
   be *NULL*.  This function always succeeds.

Context object management functions:

PyObject *PyContext_New(void)
    *Return value: New reference.*

   Create a new empty context object.  Returns "NULL" if an error has
   occurred.

PyObject *PyContext_Copy(PyObject *ctx)
    *Return value: New reference.*

   Create a shallow copy of the passed *ctx* context object. Returns
   "NULL" if an error has occurred.

PyObject *PyContext_CopyCurrent(void)
    *Return value: New reference.*

   Create a shallow copy of the current thread context. Returns "NULL"
   if an error has occurred.

int PyContext_Enter(PyObject *ctx)

   Set *ctx* as the current context for the current thread. Returns
   "0" on success, and "-1" on error.

int PyContext_Exit(PyObject *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.

int PyContext_ClearFreeList()

   Clear the context variable free list. Return the total number of
   freed items.  This function always succeeds.

Context variable functions:

PyObject *PyContextVar_New(const char *name, PyObject *def)
    *Return value: New reference.*

   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".

int PyContextVar_Get(PyObject *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.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
    *Return value: New reference.*

   Set the value of *var* to *value* in the current context.  Returns
   a pointer to a "PyObject" object, or "NULL" if an error has
   occurred.

int PyContextVar_Reset(PyObject *var, PyObject *token)

   Reset the state of the *var* context variable to that it was in
   before "PyContextVar_Set()" that returned the *token* was called.
   This function returns "0" on success and "-1" on error.
