Pular para o conteúdo principal
As capabilities desta página estão em Preview: suas APIs não são estáveis, e uma extensão que declara uma delas requer vsql_allow_preview_extensions = ON para instalar. Consulte Capabilities Preview para saber como habilitar o nível Preview e registrar uma capability.

Variáveis de Status

A capability status_var (vsql::status_var) permite que uma extensão exponha contadores long long e double como variáveis de status do MySQL. A extensão é dona do armazenamento e escreve nele; o servidor lê através dos pointers cada vez que a variável de status é consultada. Construa a capability com vsql::preview_status_var::make_capability(), passando uma lista entre chaves de descritores de make_int(name, value_ptr) ou make_double(name, value_ptr). O template deduz a contagem a partir da lista entre chaves, então nenhum tamanho explícito é necessário.

Exemplo Completo

make_int requer um long long *; make_double requer um double *. Esses são os únicos dois tipos compatíveis.

Acessando a partir do SQL

Após INSTALL EXTENSION my_ext, a variável fica visível com o nome da extensão como prefixo:
Incrementos concorrentes de múltiplas threads de consulta usando um ++ não-atômico podem ocasionalmente ser perdidos; isso é aceitável para contadores aproximados de chamadas expostos via SHOW STATUS.

Variáveis de Sistema

A capability sys_var (vsql::sys_var) permite que uma extensão registre variáveis de sistema do MySQL respaldadas por armazenamento de propriedade da extensão. Há suporte para quatro tipos: BOOL (bool *), INT (long long *), STR (char **) e ENUM (unsigned long *, que armazena um índice com base zero em uma lista fixa e ordenada de nomes). Os descritores INT também carregam limites min_val e max_val; todos os descritores carregam um valor padrão e um comentário. Construa a capability com vsql::preview_sys_var::make_capability() e as funções de fábrica correspondentes make_bool, make_int, make_str e make_enum. O objeto de capability também expõe get() e set() para acesso programático a partir do código da extensão. Ambos retornam false em caso de sucesso. Para reagir a mudanças de valor, encadeie .on_change<&fn>() em um descritor. O callback recebe um sv::SysVarChange com var_name() e acessadores tipados (as_int(), as_str() e as_enum()). O servidor chama esse callback enquanto mantém o seu lock global de variáveis de sistema. Ler ou escrever outra variável desta extensão através do seu pointer de armazenamento é seguro ali, e as outras sessões veem o novo valor imediatamente, porque o servidor lê essas variáveis sob o mesmo lock.
Chamar o get() ou o set() da capability, executar SQL ou esperar por uma thread que faça uma dessas coisas causa deadlock nesse lock. Mantenha o callback curto e não bloqueante, entregue a uma thread de trabalho o trabalho que precisa de SQL, ou libere o LOCK_global_system_variables em volta da parte bloqueante e retome-o antes de retornar, como o event_scheduler_update() faz em sql/sys_vars.cc.
O objeto de capability deve ter duração de armazenamento estática. O MySQL escreve diretamente nos pointers de armazenamento quando o usuário define uma variável. Uma variável enum é definida pelo nome (SET GLOBAL my_ext.mode = 'sync') ou pelo índice com base zero do nome; em ambos os casos o servidor valida o valor contra names antes de aceitá-lo, rejeitando um nome não reconhecido ou um índice fora do intervalo em vez de armazená-lo:
Essa validação é o que a distingue de um make_str de formato livre: o espaço de valores é fechado e imposto no momento do SET. Uma sobrecarga de conveniência deduz name_count a partir de um array static const char *const NAMES[] = {...}, então o argumento de contagem pode ser omitido.

Exemplo Completo

Acessando a partir do SQL

Após INSTALL EXTENSION my_ext, as variáveis ficam acessíveis usando o nome da extensão como prefixo de componente:

Lendo e Escrevendo a partir do Código da Extensão

Para variáveis INT e BOOL, leia o pointer de armazenamento global diretamente — o MySQL atualiza esses valores atomicamente. Para atualizar uma variável através do MySQL (de forma que travamento, validação de intervalo e persistência sejam tratados pelo servidor), chame SYS_VARS.set(extension_name, var_name, scope, value). Tanto set quanto get retornam false em caso de sucesso. Nenhum dos dois pode ser chamado a partir de um callback on_change: ambos causam deadlock no lock de variáveis de sistema.
set e get recebem o nome da extensão e o nome da variável como const char *. Uma variável INT é definida somente com um valor inteiro; set com um valor de string falha (retorna true) para uma variável INT. Defina as variáveis BOOL, STRING, DOUBLE e ENUM com um valor de string. O argumento scope controla a persistência:

Variáveis de Sessão

A capability session_var (vsql::session_var) permite que uma extensão registre variáveis de sistema por sessão (locais ao THD) — o equivalente funcional do MYSQL_THDVAR_* de um plugin. Ela é a irmã com escopo de sessão de vsql::sys_var: uma sys_var tem um único valor compartilhado por todas as conexões, enquanto uma session_var dá a cada conexão o seu próprio valor, definido com SET SESSION. O ponto de partida de uma nova sessão é o padrão do descritor, ou o valor armazenado por último com SET GLOBAL. O escopo de uma variável é fixado no registro — use esta capability para variáveis por sessão, e vsql::sys_var para as globais. Há suporte para apenas dois tipos: INT (long long) e STR (std::string). Não há variável de sessão BOOL ou DOUBLE, e não há mecanismo de callback on_change — diferente de vsql::sys_var, uma extensão observa o valor de uma variável de sessão apenas lendo-o de volta, e não sendo notificada quando ele muda.

Declarando a Capability

Construa a capability com vsql::preview_session_var::make_capability(), passando uma lista entre chaves de descritores de make_int(name, comment) ou make_str(name, comment), cada um configurado com os setters fluentes .default_(), .min() e .max() (min/max se aplicam apenas a INT):
make_int começa sem restrições (padrão 0, intervalo completo de long long); make_str começa com uma string vazia como padrão. O objeto de capability precisa de duração de armazenamento estática, como toda outra capability Preview desta página.

Lendo Valores de Sessão

Há dois caminhos de leitura, ambos resolvidos contra a thread da conexão chamadora — então ambos devem ser chamados na thread da conexão (uma VDF ou um callback em execução na conexão), nunca a partir de um thread worker em segundo plano:
  • SESSION_VARS.get_session_int(name, out) / get_session_str(name, out) — indexado pelo nome, resolve a variável novamente a cada chamada. Use-o para leituras ocasionais, e para variáveis STR ele é o único caminho: não há um caminho rápido sem lock para strings, porque um slot STR contém um pointer para um buffer alocado separadamente, que um SET SESSION ou UNINSTALL concorrente pode liberar.
  • SESSION_VARS.int_var(name) retorna um IntVar que se resolve de forma preguiçosa no seu primeiro read() e armazena o resultado em cache, de modo que pode ser declarado no escopo do arquivo/estático antes que a capability tenha carregado. Cada read() seguinte é uma carga por offset por thread sem lock — sem busca por nome, sem lock global — o equivalente do THDVAR(thd, var) de um plugin. Esse caminho rápido é apenas para INT.

Acessando a partir do SQL

Após INSTALL EXTENSION my_ext, cada variável recebe o nome da extensão como prefixo de componente e pode ser lida e definida tanto com @@session. quanto com @@global.:
Uma segunda conexão não é afetada pelo SET SESSION da primeira conexão, e vê o padrão compilado até definir o seu próprio valor; SET GLOBAL altera o padrão que as sessões novas ou redefinidas recebem, e não o valor já definido de qualquer sessão. As atribuições INT fora do intervalo são limitadas ao valor-limite e geram um aviso, e uma atribuição com o tipo errado é rejeitada, exatamente como em uma variável de sistema comum do MySQL:

Comportamento na Reinicialização

SET PERSIST e SET PERSIST_ONLY funcionam no valor global de uma variável de sessão como em qualquer variável de sistema do MySQL: o valor sobrevive a uma reinicialização do servidor, e cada nova sessão começa nele. Um valor de SET SESSION é estado por conexão e não sobrevive a uma reinicialização. Sem SET PERSIST, cada variável reaparece no seu padrão compilado depois de uma reinicialização com a extensão ainda instalada.