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

# 스레드 워커 및 SQL 쿼리

> vsql::preview::thread_worker 기능은 서버가 구동하는 백그라운드 스레드를 실행하고, vsql::preview::sql_query 기능은 백그라운드 스레드에서 SQL 문을 실행합니다.

이 페이지의 기능은 미리보기 단계입니다. API는 안정적이지 않으며, 이 기능을 선언하는 확장 프로그램은 설치 시 `vsql_allow_preview_extensions = ON`이 필요합니다. 미리보기 계층을 활성화하고 기능을 등록하는 방법은 [미리보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities)을 참조하세요.

## 스레드 워커

thread\_worker 기능(`vsql::preview::thread_worker`)은 확장 프로그램이 서버가 제어하는 백그라운드 스레드를 실행할 수 있게 해줍니다. 스레드는 서버가 확장 프로그램 로드 시 등록하는 제어 시스템 변수를 통해 시작 및 중지되며, 서버는 주기적 타이머, 파일 디스크립터 준비, 또는 활성/비활성 이벤트에 반응하여 확장 프로그램의 작업 함수를 호출합니다.

기능 이름 `VEF_PREVIEW_THREAD_WORKER_NAME`은 `"vsql::preview::thread_worker"`입니다.

### 기능 선언

헤더를 포함하고, 파일 범위에서 작업 함수로 인스턴스화된 `ThreadWorkerCapability`을 선언하고, `.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))
```

작업 함수는 비유형 템플릿 인수(`ThreadWorkerCapability<&my_work>`)로 제공되므로, 다음 서명을 가진 함수여야 합니다. 첫 번째 생성자 인수는 스레드 이름 접미사이며, 선택적 두 번째 인수는 제어 시스템 변수 이름을 오버라이드합니다.

### 작업 함수 서명

```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`은 서버가 함수를 호출한 이유를 나타냅니다. `thread`는 이 워커에 대한 서버 소유 핸들입니다(초기 `VEF_WAKEUP_ENABLE` 호출 시 NULL — 아래 참조). `arg`는 디스크립터에 등록된 불투명(opaque) 포인터이며, 변경 없이 전달됩니다.

### 웨이크업 라이프사이클

서버는 다음 네 가지 이유 중 하나로 작업 함수를 호출합니다:

| 이유 | 의미 |
| - | - |
| `VEF_WAKEUP_ENABLE` | 워커가 방금 활성화되었습니다(제어 시스템 변수가 ON으로 전환됨). 반환 값은 초기 `poll_fd` 및 `sleep_ms`를 설정합니다. |
| `VEF_WAKEUP_PERIODIC` | 주기적 타이머가 발동되었습니다(`sleep_ms` 경과). |
| `VEF_WAKEUP_POLL_FD` | 감시 중인 파일 디스크립터가 읽을 수 있게 되었습니다. |
| `VEF_WAKEUP_DISABLE` | 워커 비활성화(제어 시스템 변수 OFF) 또는 서버 종료. 반환 값은 무시됩니다. |

`reason`이 `VEF_WAKEUP_ENABLE`인 경우 `thread` 매개변수는 NULL입니다. 이 시점에는 스레드 핸들이 아직 존재하지 않기 때문입니다. 다른 세 가지 이유에 대해서는 `thread`가 NULL이 아닙니다.

### 웨이크업 반환 값

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

작업 함수는 `vef_next_wakeup_t`를 반환하여 다음 웨이크업 구성 설정을 업데이트합니다. 각 필드의 0 값은 "현재 설정 유지"를 의미합니다 — 변경하지 않으려면 구조체를 기본값으로 초기화하여 반환(`return {};`)하세요.

새로운 poll 파일 디스크립터를 설정하려면 해당 값을 반환합니다(0보다 커야 함). 기존 poll 파일 디스크립터를 제거하려면 `poll_fd`에 `-1`을 반환합니다.

`reason`이 `VEF_WAKEUP_DISABLE`인 경우 반환 값은 무시됩니다.

### 스레드 이름 및 제어 변수

디스크립터의 두 필드가 이름을 제어합니다:

* `suffix` — 스레드 이름 접미사. 서버는 확장 프로그램 이름을 접두사로 추가하여 `my_ext/monitor`와 같은 스레드 이름을 생성합니다.
* `var_name` — 선택적. NULL이 아닌 경우 서버는 이 정확한 이름을 제어 시스템 변수로 등록합니다. NULL인 경우 서버는 기본 패턴 `{suffix}_enabled`을 사용합니다.

제어 변수는 서버가 등록한 시스템 변수이므로, 확장 프로그램 이름을 구성 접두사로 사용합니다. 접미사가 `monitor`인 확장 프로그램 `my_ext`의 경우, 변수는 `my_ext.monitor_enabled`입니다.

이를 `ON`으로 설정하면 워커가 시작됩니다: 서버가 `VEF_WAKEUP_ENABLE`로 작업 함수를 호출한 다음 스레드를 생성하므로, 그 첫 호출이 끝날 때까지 문이 반환되지 않습니다. 워커가 이미 실행 중일 때 다시 `ON`으로 설정하면 아무 일도 일어나지 않습니다. `OFF`로 설정하면 스레드가 종료된 후에 반환됩니다. 서버는 두 경우 모두에서 전역 시스템 변수 잠금을 해제하므로 작업 함수는 시스템 변수를 읽을 수 있지만, `VEF_WAKEUP_DISABLE` 중에 실행한 쿼리는 행을 하나도 반환하지 않습니다.

### 완전한 예제

주기적 워커가 하나 있는 최소 확장 프로그램으로, 각 타이머 틱마다 심장 박동 카운터를 증가시킵니다.

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

이 확장 프로그램을 설치한 후(`vsql_allow_preview_extensions = ON`), 서버는 확장 프로그램 이름 아래에 `heartbeat_enabled` 시스템 변수를 등록합니다. `my_ext`라는 이름의 확장 프로그램의 경우, 워커를 활성화하려면:

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

## SQL 쿼리

sql\_query 기능(`vsql::preview::sql_query`)은 확장 프로그램이 백그라운드 스레드에서 SQL 문을 실행할 수 있게 해줍니다. 쿼리는 확장 프로그램이 MySQL 클라이언트 라이브러리에 링크하지 않고 기능 vtable을 통해 서버 내부에서 실행됩니다.

기능 이름 `VEF_PREVIEW_SQL_QUERY_NAME`은 `"vsql::preview::sql_query"`입니다.

> [!WARNING]
>
> SQL 세션은 스레드 워커 콜백에서 해당 콜백의 `vef_thread_handle_t *`를 사용하여 열어야 합니다. `open()`은 VDF 또는 임의의 확장 프로그램 생성 스레드에서 유효하지 않습니다 — 워커 세션 컨텍스트가 필요합니다.

### 기능 선언

헤더를 포함하고, 파일 범위에서 `SqlQueryCapability`을 선언한 후 `.with()`에 전달합니다. 세션은 워커 콜백에서 열리므로, 일반적으로 `ThreadWorkerCapability`과 함께 등록됩니다:

```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)`은 `Session`을 반환합니다. 사용 전에 `operator bool`로 확인하세요. 유효하지 않은 `Session`은 기능 vtable이 바인딩되지 않았거나 서버가 세션을 할당하지 못했음을 나타냅니다. `Session`은 이동 전용이며 소멸 시 자동으로 닫힙니다.

### 쿼리 실행

`Session`은 `session.sql(sv)`를 통해 `SqlQuery`를 생성합니다. 쿼리는 두 가지 모드로 실행할 수 있습니다:

* `execute()` — 문을 실행하고 전체 결과 세트를 `Result`에 버퍼링합니다. 호출자의 속도에 맞춰 `next()`를 호출하여 행을 반복합니다.
* `for_each(fn)` — 문을 실행하고 행이 생성될 때마다 `fn`을 한 번 호출합니다(버퍼링 없음). 반환된 `Result`는 진단 정보만 포함합니다(행 없음).

둘 다 `Result`를 반환합니다. `Result`가 null이 아닌 경우 문이 성공했다는 의미가 아닙니다 — `has_error()`를 호출하여 확인하세요.

버퍼링(`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()`은 `next()` 호출 또는 `Result` 소멸 전까지 유효한 `string_view`를 반환합니다. 더 긴 수명이 필요한 경우 복사하세요. `data() == nullptr`인 `string_view`는 SQL NULL을 나타냅니다.

스트리밍(`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
}
```

콜백에 전달된 `Row`는 호출 기간 동안만 유효합니다 — 행 간에 참조를 저장하지 마세요. `for_each`가 반환한 `Result`는 버퍼링된 행을 보유하지 않습니다. `next()`는 데이터를 생성하지 않습니다. `has_error()`, `error()`, `warning_count()`, `warning(i)`에만 사용하세요.

### 진단

`execute()` 및 `for_each()`는 반환된 `Result`를 통해 진단을 표시합니다. 진단은 하나의 `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
};
```

| 필드 | 의미 |
| - | - |
| `errno_` | MySQL 오류 번호. 오류가 없을 때 반환되는 기본 생성된 `Diag`에서는 `0`입니다. |
| `severity` | `VEF_SQL_DIAG_NOTE`, `VEF_SQL_DIAG_WARNING`, 또는 `VEF_SQL_DIAG_ERROR`. |
| `sqlstate` | 5자리 SQLSTATE. |
| `message` | 서버가 제공한 진단 메시지; 비어 있을 수 있습니다. |

`Result`는 다음과 같이 노출합니다:

```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()`는 문이 성공했을 때 기본 생성된 `Diag`(`errno_ == 0`)을 반환합니다. `warning(i)`는 `i >= warning_count()`일 때 기본 생성된 `Diag`를 반환합니다.

`sqlstate` 및 `message` 뷰는 `Result`가 소유하는 저장소를 가리키며 `Result`가 소멸될 때 무효화됩니다 — 이들이 `Result`보다 오래 유지되어야 할 경우 복사하세요.

### 완전한 예제

각 틱마다 버퍼링 쿼리와 스트리밍 쿼리를 실행하고, 두 쿼리에서 진단을 로깅하는 워커:

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