active: true
derived: false
groups:
- BGIO
header: |
  save_sync / flush / drain テスト
level: 2.15
links:
- SPEC015: B228w_2s4cAN_TaP9dS_3m02jiuVCQOVg5PIkKmkDgs=
normative: true
ref: ''
references:
- path: tests/integration/core/test_exit_drain.py
  type: file
reviewed: -BCwmAvAywrytzQo7vVfVN6XYRcDJojShNtGrzbkeK4=
text: |
  ## 目的

  `save_sync` パラメータと `flush` / `drain` メカニズムは、キャッシュ保存のレイテンシとデータ安全性のトレードオフをユーザーが制御する手段である。`save_sync=False` 使用時にデータが失われないことと、コンテキストマネージャによる確実なフラッシュを保証する。

  ## 検証観点

  - **save_sync=True（デフォルト）**: キャッシュ保存が呼び出しスレッドで同期的に完了し、関数リターン時点でデータが永続化されていること
  - **save_sync=False**: キャッシュ保存がバックグラウンドに委譲され、関数がレイテンシなしでリターンすること。保存が最終的に完了すること
  - **flush()**: `spot.flush(timeout)` 呼び出しで全ペンディング保存が完了するまで待機すること。タイムアウト時の挙動が明確であること
  - **コンテキスト exit での drain**: `with spot:` ブロック終了時に未完了の保存が自動的に drain されること
  - **コンテキストマネージャの再利用**: 同一 spot インスタンスが複数の `with` ブロックで再利用でき、各ブロック終了時に適切に drain されること
  - **バックグラウンド保存失敗**: 非同期保存が例外を送出した場合に `on_background_error` コールバックが呼ばれ、メインスレッドには影響しないこと
