active: true
derived: false
groups:
- DB
header: |
  SQLiteTaskDB 実装
level: 2.7
links:
- SPEC007: 0HwpNXmcPue82WV2rmVdY4OyJk_Ez9kXoWX3t6UN6ts=  # pragma: allowlist secret
normative: true
ref: ''
references:
- path: src/beautyspot/db.py
  type: file
reviewed: d-YowDMPy1gSBNFSfYM7ty-bPaF_TVh9iflIJAskWI0=  # pragma: allowlist secret
text: |
  ## 実装概要

  `SQLiteTaskDB` クラスが中核。Writer Thread + Reader Threads パターンで実装。
  単一の `_writer_thread`（デーモン）が `_write_queue` から書き込みタスクを取り出して直列処理し、読み取りは `threading.local()` のスレッドローカル接続で並行実行する。
  WAL モードにより読み取りと書き込みの並行性を確保している。

  ## タイムアウトの実装
  - `_enqueue_write` 内で `task.event.wait(timeout=0.5)` をループさせ、`self.timeout` を超えた場合にフェイルファスト処理を行う。
  - **PENDING**: `task.try_cancel()` でキュー内キャンセル。
  - **RUNNING**: `self._writer_conn.interrupt()` を呼び出して実行中の SQLite クエリを強制終了させ、呼び出し元に `TimeoutError` を返す。
  - interrupt 後、ライタースレッド側の例外処理を待つための猶予時間を設け、可用性と整合性を両立させている。
