active: true
derived: false
groups:
- BGIO
header: |
  バックグラウンドIO構成
level: 2.6
links:
- REQ006: 3PN_I3D9BWCwGe4h19vSOVkDSeWNY3sM_fbWg0rwOfk=
normative: true
ref: ''
reviewed: _Gax81WV-nwHbXx_ZeV8pNxwoFBJzW6iKi9yJOzkciE=
text: |
  ## コンポーネント構成

  ```mermaid
  graph TD
    A[core.Spot] -->|非同期タスク投入| B[_BackgroundLoop]
    B -->|Daemon Thread| C[asyncio.AbstractEventLoop]
    C -->|I/O| D[TaskDB / BlobStorage]
    A -->|ライフサイクル制御| E[atexit / ContextManager]
  ```

  ## コンポーネント責務

  | コンポーネント | 責務 | インターフェース |
  |---|---|---|
  | _BackgroundLoop | デーモンスレッドでのイベントループ管理とタスク投入 | `submit()`, `run_forever()` |
  | core.Spot | 非同期保存のトリガーとエラーハンドリング | `_save_metadata_async()` |
  | ContextManager | 処理終了時のタスク完了待機（Flush） | `__exit__`, `flush()` |

  ## データフロー

  ```mermaid
  sequenceDiagram
    participant Main as メインスレッド
    participant BGLoop as _BackgroundLoop
    participant Store as ストレージ

    Main->>BGLoop: submit(save_coro)
    Note over Main: 関数は即座に結果を返す (save_sync=False)
    BGLoop->>Store: 書き込み実行 (I/O)
    alt 成功
        Store-->>BGLoop: OK
    else 失敗
        BGLoop->>Main: on_background_error(error)
    end
  ```

  ## 技術選定

  | 技術領域 | 選定 | 理由 |
  |---|---|---|
  | 並行処理 | asyncio in Thread | GILを解放しつつ、多数のI/Oタスクを効率的に多重化 |
  | スレッド種類 | Daemon Thread | アプリケーション終了時にプロセスをブロックしない |
  | 終了制御 | atexit / drain | 強制終了時も、可能な限り保留中の書き込みを完了させる |

  ## 非機能要件方針

  -   **透過性**: 保存失敗時もユーザーコードの例外にはせず、コールバック経由で通知

  -   **一貫性**: `flush()` により、クリティカルな処理の直後での保存完了を保証

  -   **安全性**: シャットダウンシーケンス中に新規タスクを受け付けない排他制御を導入

  ## 設計根拠

  同期処理に影響を与えずに非同期での保存を完了させるため。専用のバックグラウンドループ（デーモンスレッド）を用意し、メインスレッドのブロックを回避しつつ、アプリケーション終了時には確実にキューを消化する（atexit）仕組みを採用した。
