active: true
derived: false
gherkin: |
  Feature: save_sync and flush operations
    Scenario: Managing background save tasks
      Given a background save operation in progress
      When flush is called or the Spot context exits
      Then it waits until all pending in-flight tasks are completed or a timeout occurs
groups:
- BGIO
header: |
  save_sync / flush / drain
level: 2.15
links:
- ARCH006: NQNGQUULw16h1cxj2M5I4pgAr3bNlRze6AMKu_rdo0s=
normative: true
ref: ''
reviewed: 0s5kYMU5QTPuIbKAE6o1iWjJlsTG1-UXdDJ0Ib3GkbY=
text: |
  ## インターフェース

  ```python
  def flush(timeout: float | None = None) -> bool: ...

  @spot.mark(save_sync=False)
  def my_func(): ...
  ```

  ## 振る舞い

  ### 同期保存 (`save_sync=True`)
  - 関数終了後、DBおよびBlobへの保存が完了するまで呼び出し元をブロックする。

  ### 非同期保存 (`save_sync=False`)
  - 保存処理を `BackgroundLoop` に委譲し、即座に関数の戻り値を返す。

  ### フラッシュ (`flush`)
  - `_inflight` タスク（保存中）のリストを確認し、それら全てが完了するまで、またはタイムアウトまで待機する。

  ## パラメータ詳細

  | パラメータ | デフォルト | 説明 |
  |---|---|---|
  | `timeout` | `None` | `flush` の最大待機時間（秒）。`None` は無限待機 |
  | `on_background_error` | `logger.error` | 非同期保存失敗時のエラーハンドラ |

  ## エラーハンドリング

  - **タイムアウト**: `flush` がタイムアウトした場合、`False` を返し、一部のデータが未保存である可能性を通知する。

  ## エッジケース

  - **コンテキスト終了**: `with spot:` 終了時に自動的に `flush` が呼ばれ、プロセス終了前のデータ保存を確実にする。

  ## 設計判断

  スクリプトの終了時や、確実にキャッシュを永続化してから次の処理に進みたいケース（バッチ処理等）において、バックグラウンドの非同期保存タスクの完了を待機し、データロストを防ぐ制御手段を提供するため。
