active: true
derived: false
groups:
- HERD
header: |
  Thundering Herd対策構成
level: 2.13
links:
- REQ013: tKylQ3MlgP5WxneklHbCBHWMZ7lGffbNKhTuZG9o0Mw=
normative: true
ref: ''
reviewed: 5r18tv59qCBMC4TqQ_KXhz37BL3eTS_r2yWcQfG7SeA=
text: |
  ## コンポーネント構成

  ```mermaid
  graph TD
    A[core.Spot] -->|管理要求| B[CacheManager]
    B -->|In-flight追跡| C[_inflight Dict]
    C -->|同期待機| D[threading.Event]
    C -->|非同期待機| E[asyncio.Future]
  ```

  ## コンポーネント責務

  コンポーネント責務インターフェースCacheManagerキャッシュキーごとの実行状態管理と実行のシリアライズ`get_or_create_inflight()`\_inflight実行中のタスクを保持し、後続リクエストをイベントで待機させる`ExecutionState`core.Spot待機結果の受け取りとエラーの伝播`cached_run()`

  ## データフロー

  ```mermaid
  sequenceDiagram
    participant T1 as Thread 1 (First)
    participant T2 as Thread 2 (Second)
    participant CM as CacheManager
    participant Fn as Target Function

    T1->>CM: get_or_create(key)
    Note over CM: 新規作成 (Executor)
    T2->>CM: get_or_create(key)
    Note over CM: 既存あり (Waiter)

    T1->>Fn: execute()
    Fn-->>T1: result
    T1->>CM: set_result(key, result)
    Note over CM: Eventをセット
    CM-->>T2: notify result
    T1-->>T1: return result
    T2-->>T2: return result
  ```

  ## 技術選定

  技術領域選定理由待機機構Event / FutureOS/ランタイムレベルの待機を使用し、CPU負荷（ビジーループ）を回避スコープキャッシュキー単位異なる関数の実行は妨げず、同一入力のみを直列化安全策タイムアウト & リトライ実行者がハングした場合に、待機側がデッドロックしないよう保護

  ## 非機能要件方針

  -   **一貫性**: 実行者が成功すれば全員に結果を、失敗すれば全員に同じ例外を伝播

  -   **効率性**: メモリリークを防ぐため、結果配布後に `_inflight` エントリを即座に削除

  -   **信頼性**: 強参照 (`StrongReference`) で実行中のタスクを保持し、GCによる消失を防止
