메인 콘텐츠로 건너뛰기
이 페이지의 기능은 미리보기 단계입니다. API는 안정적이지 않으며, 이 기능을 선언하는 확장 프로그램은 설치 시 vsql_allow_preview_extensions = ON이 필요합니다. 미리보기 계층을 활성화하고 기능을 등록하는 방법은 미리보기 기능을 참조하세요.

스레드 워커

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

기능 선언

헤더를 포함하고, 파일 범위에서 작업 함수로 인스턴스화된 ThreadWorkerCapability을 선언하고, .with()에 전달합니다:
작업 함수는 비유형 템플릿 인수(ThreadWorkerCapability<&my_work>)로 제공되므로, 다음 서명을 가진 함수여야 합니다. 첫 번째 생성자 인수는 스레드 이름 접미사이며, 선택적 두 번째 인수는 제어 시스템 변수 이름을 오버라이드합니다.

작업 함수 서명

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

웨이크업 라이프사이클

서버는 다음 네 가지 이유 중 하나로 작업 함수를 호출합니다: reason이 VEF_WAKEUP_ENABLE인 경우 thread 매개변수는 NULL입니다. 이 시점에는 스레드 핸들이 아직 존재하지 않기 때문입니다. 다른 세 가지 이유에 대해서는 thread가 NULL이 아닙니다.

웨이크업 반환 값

작업 함수는 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 중에 실행한 쿼리는 행을 하나도 반환하지 않습니다.

완전한 예제

주기적 워커가 하나 있는 최소 확장 프로그램으로, 각 타이머 틱마다 심장 박동 카운터를 증가시킵니다.
이 확장 프로그램을 설치한 후(vsql_allow_preview_extensions = ON), 서버는 확장 프로그램 이름 아래에 heartbeat_enabled 시스템 변수를 등록합니다. my_ext라는 이름의 확장 프로그램의 경우, 워커를 활성화하려면:

SQL 쿼리

sql_query 기능(vsql::preview::sql_query)은 확장 프로그램이 백그라운드 스레드에서 SQL 문을 실행할 수 있게 해줍니다. 쿼리는 확장 프로그램이 MySQL 클라이언트 라이브러리에 링크하지 않고 기능 vtable을 통해 서버 내부에서 실행됩니다. 기능 이름 VEF_PREVIEW_SQL_QUERY_NAME은 "vsql::preview::sql_query"입니다.
SQL 세션은 스레드 워커 콜백에서 해당 콜백의 vef_thread_handle_t *를 사용하여 열어야 합니다. open()은 VDF 또는 임의의 확장 프로그램 생성 스레드에서 유효하지 않습니다 — 워커 세션 컨텍스트가 필요합니다.

기능 선언

헤더를 포함하고, 파일 범위에서 SqlQueryCapability을 선언한 후 .with()에 전달합니다. 세션은 워커 콜백에서 열리므로, 일반적으로 ThreadWorkerCapability과 함께 등록됩니다:
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):
column_str()은 next() 호출 또는 Result 소멸 전까지 유효한 string_view를 반환합니다. 더 긴 수명이 필요한 경우 복사하세요. data() == nullptr인 string_view는 SQL NULL을 나타냅니다. 스트리밍(for_each):
콜백에 전달된 Row는 호출 기간 동안만 유효합니다 — 행 간에 참조를 저장하지 마세요. for_each가 반환한 Result는 버퍼링된 행을 보유하지 않습니다. next()는 데이터를 생성하지 않습니다. has_error(), error(), warning_count(), warning(i)에만 사용하세요.

진단

execute() 및 for_each()는 반환된 Result를 통해 진단을 표시합니다. 진단은 하나의 Diag입니다:
Result는 다음과 같이 노출합니다:
error()는 문이 성공했을 때 기본 생성된 Diag(errno_ == 0)을 반환합니다. warning(i)는 i >= warning_count()일 때 기본 생성된 Diag를 반환합니다. sqlstate 및 message 뷰는 Result가 소유하는 저장소를 가리키며 Result가 소멸될 때 무효화됩니다 — 이들이 Result보다 오래 유지되어야 할 경우 복사하세요.

완전한 예제

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