> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Thread de Trabalho e Consulta SQL

> A capability vsql::preview::thread_worker executa uma thread em segundo plano controlada pelo servidor, e a vsql::preview::sql_query executa instruções SQL a partir de uma thread em segundo plano.

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](https://villagesql.com/docs/pt-BR/extensions/build/preview-capabilities) 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()`:

```cpp theme={null}
#include <villagesql/preview/thread_worker.h>
#include <villagesql/vsql.h>

static vef_next_wakeup_t my_work(vef_wakeup_reason_t reason,
                                 struct vef_thread_handle_t *thread,
                                 void *arg) {
  // ...
  return {};
}

static vsql::preview_thread_worker::ThreadWorkerCapability<&my_work>
    g_worker{"suffix"};

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .with(g_worker))
```

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

```c theme={null}
typedef vef_next_wakeup_t (*vef_work_fn_t)(vef_wakeup_reason_t reason,
                                           struct vef_thread_handle_t *thread,
                                           void *arg);
```

`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:

| Motivo | Significado |
| - | - |
| `VEF_WAKEUP_ENABLE` | O worker acabou de ser habilitado (variável de sistema de controle foi alterada para ON). O valor de retorno define o `poll_fd` e o `sleep_ms` iniciais. |
| `VEF_WAKEUP_PERIODIC` | O temporizador periódico disparou (`sleep_ms` decorrido). |
| `VEF_WAKEUP_POLL_FD` | Um descritor de arquivo monitorado tornou-se pronto para leitura. |
| `VEF_WAKEUP_DISABLE` | Worker desabilitado (variável de sistema de controle em OFF) ou servidor desligando. O valor de retorno é ignorado. |

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

```c theme={null}
typedef struct {
  unsigned int sleep_ms;
  int poll_fd;
} vef_next_wakeup_t;
```

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.

```cpp theme={null}
#include <villagesql/preview/thread_worker.h>
#include <villagesql/vsql.h>

#include <atomic>

static std::atomic<unsigned long long> g_heartbeat{0};

static vef_next_wakeup_t heartbeat_work(vef_wakeup_reason_t reason,
                                        struct vef_thread_handle_t *thread,
                                        void *arg) {
  switch (reason) {
    case VEF_WAKEUP_ENABLE:
      return {1000, 0};  // tick every 1000 ms, no poll fd
    case VEF_WAKEUP_PERIODIC:
      g_heartbeat.fetch_add(1, std::memory_order_relaxed);
      return {};  // keep current sleep_ms and poll_fd
    case VEF_WAKEUP_POLL_FD:
      return {};  // not used in this example
    case VEF_WAKEUP_DISABLE:
      return {};  // ignored
  }
  return {};
}

static vsql::preview_thread_worker::ThreadWorkerCapability<&heartbeat_work>
    g_worker{"heartbeat"};

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .with(g_worker))
```

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:

```sql theme={null}
SET GLOBAL my_ext.heartbeat_enabled = ON;
```

## 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"`.

> [!WARNING]
>
> 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:

```cpp theme={null}
#include <villagesql/preview/sql_query.h>
#include <villagesql/preview/thread_worker.h>
#include <villagesql/vsql.h>

static vsql::preview_sql_query::SqlQueryCapability g_sql;

static vef_next_wakeup_t my_work(vef_wakeup_reason_t reason,
                                 struct vef_thread_handle_t *thread,
                                 void *arg) {
  auto session = g_sql.open(thread);
  if (!session) return {};
  // ...
  return {};
}

static vsql::preview_thread_worker::ThreadWorkerCapability<&my_work>
    g_worker{"sql_demo"};

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .with(g_worker)
        .with(g_sql))
```

`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`):

```cpp theme={null}
auto result = session.sql("SELECT id, name FROM t").execute();
if (result.has_error()) {
  // result.error().message holds the server error string.
  return {};
}
while (result.next()) {
  long long id          = result.column_int(0);
  std::string_view name = result.column_str(1);
  // ...
}
```

`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`):

```cpp theme={null}
auto status = session.sql("SELECT 1").for_each(
    [](const auto &row) {
      // row.column_int(0), row.column_str(1), etc.
    });
if (status.has_error()) {
  // status.error().message
}
```

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`:

```cpp theme={null}
struct Diag {
  uint32_t errno_;
  vef_sql_diag_severity_t severity;   // NOTE | WARNING | ERROR
  std::string_view sqlstate;          // 5-char SQLSTATE
  std::string_view message;           // may be empty
};
```

| Campo | Significado |
| - | - |
| `errno_` | Número do erro do MySQL. `0` em um `Diag` construído por padrão, retornado quando não há erro. |
| `severity` | `VEF_SQL_DIAG_NOTE`, `VEF_SQL_DIAG_WARNING` ou `VEF_SQL_DIAG_ERROR`. |
| `sqlstate` | SQLSTATE de 5 caracteres. |
| `message` | Mensagem de diagnóstico fornecida pelo servidor; pode estar vazia. |

`Result` expõe:

```cpp theme={null}
bool         Result::has_error() const;
Diag         Result::error() const;
unsigned int Result::warning_count() const;
Diag         Result::warning(unsigned int i) const;
```

`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:

```cpp theme={null}
#include <villagesql/preview/sql_query.h>
#include <villagesql/preview/thread_worker.h>
#include <villagesql/vsql.h>

static vsql::preview_sql_query::SqlQueryCapability g_sql;

static vef_next_wakeup_t sql_demo_work(vef_wakeup_reason_t reason,
                                       struct vef_thread_handle_t *thread,
                                       void *arg) {
  if (reason == VEF_WAKEUP_ENABLE) return {5000, 0};
  if (reason != VEF_WAKEUP_PERIODIC) return {};

  auto session = g_sql.open(thread);
  if (!session) return {};

  // Buffered: read a small result set.
  auto rs = session.sql("SELECT id, name FROM mydb.t LIMIT 10").execute();
  if (rs.has_error()) {
    auto e = rs.error();
    // Log e.errno_, e.sqlstate, e.message somewhere extension-owned.
  } else {
    while (rs.next()) {
      long long id          = rs.column_int(0);
      std::string_view name = rs.column_str(1);
      (void)id; (void)name;
    }
  }

  // Streaming: process rows without buffering.
  auto status = session.sql("SELECT v FROM mydb.t").for_each(
      [](const auto &row) {
        long long v = row.column_int(0);
        (void)v;
      });
  for (unsigned i = 0; i < status.warning_count(); ++i) {
    auto w = status.warning(i);
    (void)w;
  }
  return {};
}

static vsql::preview_thread_worker::ThreadWorkerCapability<&sql_demo_work>
    g_worker{"sql_demo"};

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .with(g_worker)
        .with(g_sql))
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.