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.

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 um ThreadWorkerCapability instanciado sobre a sua função de trabalho no escopo do arquivo e passe-o para .with():
A função de trabalho é fornecida como um argumento de template não-tipo (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

A função de trabalho retorna um 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 como my_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.
A variável de controle é uma variável de sistema registrada pelo servidor, então ela recebe o nome da extensão como prefixo de componente. Para a extensão 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.
Com essa extensão instalada (e 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".
Uma sessão SQL deve ser aberta a partir de um callback de thread worker usando o vef_thread_handle_t * daquele callback. open() não é válido a partir de VDFs ou de threads arbitrárias criadas pela extensão — ele requer o contexto de sessão do worker.

Declarando a Capability

Inclua o cabeçalho, declare um SqlQueryCapability 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

Uma Session 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 um Result. Itere as linhas chamando next() no ritmo do chamador.
  • for_each(fn) — executa a instrução e invoca fn uma vez por linha à medida que as linhas são produzidas, sem armazenar em buffer. O Result retornado carrega apenas diagnósticos (nenhuma linha).
Ambos retornam um 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):
A 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

Tanto execute() 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.

Exemplo Completo

Um worker que executa uma consulta em buffer e uma consulta em streaming a cada tique, registrando diagnósticos de ambas: