# 23. Non-blocking Cache Persistence and Task Tracking

* Status: Accepted
* Date: 2026-02-17

## Context

大規模なデータのシリアライズや、S3 等のリモートストレージへの保存処理は、ユーザーのメインロジックの実行を妨げる（ブロッキング）要因となっていました。v2.0 では、「インフラとしてのキャッシュ処理がユーザーを待たせない」という設計思想を強化する必要があります。

## Decision

キャッシュの保存処理をバックグラウンドで実行（Fire-and-Forget）し、かつリソースの整合性を保つためのライフサイクル管理を導入します。

1. **`wait=False` モードの導入**: `@spot.mark` や `cached_run` に `wait` オプションを追加し、保存完了を待たずに結果を返すことを可能にします。
2. **タスク追跡メカニズム**: 実行中のバックグラウンドタスク（Future）を `_active_futures` セットで追跡します。
3. **Flush (非破壊的待機) の導入**: `with spot:` ブロックを抜ける際の挙動を、Executor の `shutdown` から、タスクの完了を待機する `wait` (Flush) に変更します。
4. **再利用性の確保**: コンテキストを抜けても Executor を生存させ、グローバルな `Spot` インスタンスを繰り返し再利用可能にします。

## Consequences

### Positive
* **レイテンシの改善**: 保存処理がバックグラウンド化され、ユーザーの体感速度が劇的に向上しました。
* **データ整合性の保証**: `with` ブロックやプロセス終了時に未完了タスクを必ず待機するため、データロストを防げます。
* **直感的な API**: グローバルに定義したオブジェクトを何度も `with` ブロックで安全に「フラッシュ」しながら使い回せます。

### Negative
* **例外ハンドリングの複雑化**: バックグラウンドで発生したエラーは即座に呼び出し元へ伝播しないため、ログによる通知 (`_save_result_safe`) に依存します。

