vsql_allow_preview_extensions = ON para instalar. Consulte Capabilities Preview para saber como habilitar o nível Preview e registrar uma capability.
Thread de Trabalho
A capability thread worker (vsql::preview::thread_worker) permite que uma
extensão execute uma thread em segundo plano conduzida pelo servidor. A thread é
iniciada e parada através de uma variável de sistema de controle que o servidor
registra no carregamento da extensão; o servidor invoca a função de trabalho da
extensão em um temporizador periódico, na prontidão de um descritor de arquivo,
ou em resposta a eventos de habilitação/desabilitação.
O nome da capability VEF_PREVIEW_THREAD_WORKER_NAME é
"vsql::preview::thread_worker".
Declarando a Capability
Inclua o cabeçalho, declare umThreadWorkerCapability instanciado sobre a sua
função de trabalho no escopo do arquivo e passe-o para .with():
ThreadWorkerCapability<&my_work>), portanto deve ser uma função com a
assinatura mostrada abaixo. O primeiro argumento do construtor é o sufixo do nome
da thread; o segundo argumento, opcional, sobrescreve o nome da variável de
sistema de controle.
Assinatura da Função de Trabalho
reason indica por que o servidor chamou a função. thread é o handle de
propriedade do servidor para este worker (NULL na chamada inicial de
VEF_WAKEUP_ENABLE — veja abaixo). arg é o pointer opaco registrado no
descritor; ele é repassado inalterado.
Ciclo de Vida do Wakeup
O servidor chama a função de trabalho com um de quatro motivos:
O parâmetro
thread é NULL quando o motivo é VEF_WAKEUP_ENABLE, porque o
handle da thread ainda não existe nesse ponto. Para os outros três motivos,
thread é não-nulo.
Valor de Retorno do Wakeup
vef_next_wakeup_t para atualizar a configuração
do próximo wakeup. Um valor zero em qualquer um dos campos significa “manter a
configuração atual” — retorne uma struct inicializada por valor (return {};)
para deixar ambos inalterados.
Para definir um novo descritor de arquivo de poll, retorne seu valor (deve ser
maior que zero). Para limpar um descritor de arquivo de poll existente, retorne
-1 em poll_fd.
O valor de retorno é ignorado quando o motivo é VEF_WAKEUP_DISABLE.
Nome da Thread e Variável de Controle
Dois campos no descritor controlam a nomenclatura:suffix— o sufixo do nome da thread. O servidor antepõe o nome da extensão, produzindo nomes de thread comomy_ext/monitor.var_name— opcional. Quando não-nulo, o servidor registra exatamente este nome como a variável de sistema de controle. Quando nulo, o servidor usa o padrão{suffix}_enabled.
my_ext com o sufixo monitor, a variável é my_ext.monitor_enabled.
Defini-la como ON inicia o worker: o servidor chama a função de trabalho com
VEF_WAKEUP_ENABLE e então cria a thread, de modo que a instrução só retorna
depois que essa primeira chamada termina. Defini-la como ON de novo enquanto o
worker já está em execução não faz nada. Defini-la como OFF retorna depois que
a thread termina. O servidor libera o seu lock global de variáveis de sistema em volta das duas operações, então a função de trabalho pode ler variáveis de sistema, mas uma consulta que ela executa durante VEF_WAKEUP_DISABLE não retorna nenhuma linha.
Exemplo Completo
Uma extensão mínima com um único worker periódico que incrementa um contador de heartbeat a cada tique do temporizador.vsql_allow_preview_extensions = ON), o servidor
registra uma variável de sistema heartbeat_enabled sob o nome da extensão. Para
uma extensão chamada my_ext, habilite o worker com:
Consulta SQL
A capability sql_query (vsql::preview::sql_query) permite que uma extensão
execute instruções SQL a partir de uma thread em segundo plano. As consultas são
executadas dentro do servidor através da vtable da capability — as extensões não
são vinculadas a nenhuma biblioteca cliente do MySQL.
O nome da capability VEF_PREVIEW_SQL_QUERY_NAME é
"vsql::preview::sql_query".
Declarando a Capability
Inclua o cabeçalho, declare umSqlQueryCapability no escopo do arquivo e
passe-o para .with(). Ele é tipicamente registrado junto de um
ThreadWorkerCapability, já que as sessões são abertas a partir do callback do
worker:
g_sql.open(handle) retorna uma Session. Verifique-a com operator bool antes
de usá-la; uma Session inválida indica que a vtable da capability não foi
vinculada ou que o servidor não conseguiu alocar uma sessão. A Session é
move-only e se fecha na destruição.
Executando Consultas
UmaSession produz uma SqlQuery via session.sql(sv). A consulta pode ser
executada em dois modos:
execute()— executa a instrução e armazena em buffer todo o conjunto de resultados em umResult. Itere as linhas chamandonext()no ritmo do chamador.for_each(fn)— executa a instrução e invocafnuma vez por linha à medida que as linhas são produzidas, sem armazenar em buffer. OResultretornado carrega apenas diagnósticos (nenhuma linha).
Result. Um Result não-nulo não significa que a instrução
teve sucesso — chame has_error() para descobrir.
Em buffer (execute):
column_str() retorna um string_view que é válido apenas até a próxima chamada
de next() ou até que o Result seja destruído. Copie-o se um tempo de vida
mais longo for necessário. Um string_view com data() == nullptr indica SQL
NULL.
Em streaming (for_each):
Row passada para o callback é válida apenas durante a chamada — não armazene
referências a ela entre as linhas. O Result retornado por for_each não contém
linhas em buffer; next() nele não produzirá dados. Use-o apenas para
has_error(), error(), warning_count() e warning(i).
Diagnósticos
Tantoexecute() quanto for_each() expõem diagnósticos através do Result
retornado. Um diagnóstico é um Diag:
Result expõe:
error() retorna um Diag construído por padrão (errno_ == 0) quando a
instrução teve sucesso. warning(i) retorna um Diag construído por padrão
quando i >= warning_count().
Os views sqlstate e message apontam para armazenamento de propriedade do
Result e se tornam inválidos quando o Result é destruído — copie-os se eles
precisarem sobreviver a ele.