Objetos de variáveis ​​de contexto
**********************************

Adicionado na versão 3.7.

Alterado na versão 3.7.1:

Nota:

  No Python 3.7.1, as assinaturas de todas as APIs C de variáveis de
  contexto foram **alteradas** para usar ponteiros "PyObject" em vez
  de "PyContext", "PyContextVar" e "PyContextToken". Por exemplo:

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

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

  Veja bpo-34762 para mais detalhes.

Esta seção detalha a API C pública para o módulo "contextvars".

type PyContext

   A estrutura C usada para representar um objeto
   "contextvars.Context".

type PyContextVar

   A estrutura C usada para representar um objeto
   "contextvars.ContextVar".

type PyContextToken

   A estrutura C usada para representar um objeto "contextvars.Token"

PyTypeObject PyContext_Type

   O objeto de tipo que representa o tipo de *contexto*.

PyTypeObject PyContextVar_Type

   O objeto de tipo que representa o tipo de *variável de contexto*.

PyTypeObject PyContextToken_Type

   O objeto de tipo que representa o tipo de *token de variável de
   contexto*.

Macros de verificação de tipo:

int PyContext_CheckExact(PyObject *o)

   Retorna verdadeiro se *o* for do tipo "PyContext_Type". *o* não
   deve ser "NULL". Esta função sempre tem sucesso.

int PyContextVar_CheckExact(PyObject *o)

   Retorna verdadeiro se *o* for do tipo "PyContextVar_Type". *o* não
   deve ser "NULL". Esta função sempre tem sucesso.

int PyContextToken_CheckExact(PyObject *o)

   Retorna verdadeiro se *o* for do tipo "PyContextToken_Type". *o*
   não deve ser "NULL". Esta função sempre tem sucesso.

Funções de gerenciamento de objetos de contexto:

PyObject *PyContext_New(void)
    *Retorna valor: Nova referência.*

   Cria um novo objeto de contexto vazio. Retorna "NULL" se um erro
   ocorreu.

PyObject *PyContext_Copy(PyObject *ctx)
    *Retorna valor: Nova referência.*

   Cria uma cópia rasa do objeto de contexto *ctx* passado. Retorna
   "NULL" se um erro ocorreu.

PyObject *PyContext_CopyCurrent(void)
    *Retorna valor: Nova referência.*

   Cria uma cópia rasa do contexto da thread atual. Retorna "NULL" se
   um erro ocorreu.

int PyContext_Enter(PyObject *ctx)

   Defina *ctx* como o contexto atual para o thread atual. Retorna "0"
   em caso de sucesso e "-1" em caso de erro.

int PyContext_Exit(PyObject *ctx)

   Desativa  o contexto *ctx* e restaura o contexto anterior como o
   contexto atual para a thread atual. Retorna "0" em caso de sucesso
   e "-1" em caso de erro.

int PyContext_AddWatcher(PyContext_WatchCallback callback)

   Register *callback* as a context object watcher for the current
   interpreter. Return an ID which may be passed to
   "PyContext_ClearWatcher()". In case of error (e.g. no more watcher
   IDs available), return "-1" and set an exception.

   Adicionado na versão 3.14.

int PyContext_ClearWatcher(int watcher_id)

   Clear watcher identified by *watcher_id* previously returned from
   "PyContext_AddWatcher()" for the current interpreter. Return "0" on
   success, or "-1" and set an exception on error (e.g. if the given
   *watcher_id* was never registered.)

   Adicionado na versão 3.14.

type PyContextEvent

   Enumeration of possible context object watcher events:

   * "Py_CONTEXT_SWITCHED": The *current context* has switched to a
     different context.  The object passed to the watch callback is
     the now-current "contextvars.Context" object, or None if no
     context is current.

   Adicionado na versão 3.14.

typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)

   Context object watcher callback function.  The object passed to the
   callback is event-specific; see "PyContextEvent" for details.

   If the callback returns with an exception set, it must return "-1";
   this exception will be printed as an unraisable exception using
   "PyErr_FormatUnraisable()". Otherwise it should return "0".

   There may already be a pending exception set on entry to the
   callback. In this case, the callback should return "0" with the
   same exception still set. This means the callback may not call any
   other API that can set an exception unless it saves and clears the
   exception state first, and restores it before returning.

   Adicionado na versão 3.14.

Funções de variável de contexto:

PyObject *PyContextVar_New(const char *name, PyObject *def)
    *Retorna valor: Nova referência.*

   Cria um novo objeto "ContextVar". O parâmetro *name* é usado para
   fins de introspecção e depuração. O parâmetro *def* especifica um
   valor padrão para a variável de contexto, ou  "NULL" para nenhum
   padrão. Se ocorrer um erro, esta função retorna "NULL".

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

   Obtém o valor de uma variável de contexto. Retorna "-1" se um erro
   ocorreu durante a pesquisa, e "0" se nenhum erro ocorreu, se um
   valor foi encontrado ou não.

   Se a variável de contexto foi encontrada, *value* será um ponteiro
   para ela. Se a variável de contexto *não* foi encontrada, *value*
   apontará para:

   * *default_value*, se não for "NULL";

   * o valor padrão de *var*, se não for "NULL";

   * "NULL"

   Exceto para "NULL", a função retorna uma nova referência.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
    *Retorna valor: Nova referência.*

   Define o valor de *var* como *value* no contexto atual. Retorna um
   novo objeto token para esta alteração, ou "NULL" se um erro
   ocorreu.

int PyContextVar_Reset(PyObject *var, PyObject *token)

   Redefine o estado da variável de contexto *var* para o estado que
   anterior a "PyContextVar_Set()" que retornou o *token* foi chamado.
   Esta função retorna "0" em caso de sucesso e "-1" em caso de erro.
