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ósINSTALL EXTENSION my_ext, a variável fica visível com o nome da extensão
como prefixo:
++
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.
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:
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ósINSTALL 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), chameSYS_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 comvsql::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áveisSTRele é o único caminho: não há um caminho rápido sem lock para strings, porque um slotSTRcontém um pointer para um buffer alocado separadamente, que umSET SESSIONouUNINSTALLconcorrente pode liberar.SESSION_VARS.int_var(name)retorna umIntVarque se resolve de forma preguiçosa no seu primeiroread()e armazena o resultado em cache, de modo que pode ser declarado no escopo do arquivo/estático antes que a capability tenha carregado. Cadaread()seguinte é uma carga por offset por thread sem lock — sem busca por nome, sem lock global — o equivalente doTHDVAR(thd, var)de um plugin. Esse caminho rápido é apenas paraINT.
Acessando a partir do SQL
ApósINSTALL 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.:
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.