active: true
derived: false
groups:
- HOOK
header: |
  クラスベース・フックシステムと並列実行サポート
level: 1.34
links:
- ARCH009: QB3oa3wODbrEiWMPJXf1o-YHfM7CoQRgkyg-ERzIA6U=
- REQ009: Pz2A0pug8oCFm4G1UmkLY_oBU2CrulUJDQCx4D6WXyk=
normative: true
ref: ''
reviewed: ILCA9JjXImLZUkcfPq2whYd-twkv5QABvdj_bvqR9Us=
status: accepted
text: |
  # クラスベース・フックシステムと並列実行サポート

  ## コンテキストと課題

  `beautyspot` のコアロジックを汚染することなく、ユーザーが「トークン計算」や「レイテンシ計測」などのカスタムメトリクスを収集できる仕組みが必要です。また、並列実行環境においても、競合状態を避けつつ安全に状態を共有・更新できることが求められます。

  ## 判断基準

  * **Extensibility**: コアコードを修正することなく、実行の各フェーズにユーザー定義の処理を差し込めること。
  * **Thread Safety**: マルチスレッド環境下でも、ユーザーが複雑なロック制御を意識することなく安全に状態を集計できること。
  * **Type Safety & DX**: 実行フェーズ（実行前、ヒット時、ミス時）ごとに利用可能なデータを明確にし、IDE での型補完を最大限に活用できること。

  ## 検討した選択肢

  * **Option 1**: 単純な関数ベースのコールバック。状態保持が難しく、スレッドセーフティの確保がユーザー任せになる。
  * **Option 2**: クラスベースのインターフェース (`HookBase`) と、フェーズ別に分離された専用コンテキストオブジェクトの導入。

  ## 決定事項

  採用した選択肢: **Option 2**.

  ### 1. クラスベースのフックインターフェース (`HookBase`)
  状態（開始時間や累計カウンタ）を保持しやすいよう、クラスベースのインターフェースを採用します。

  ### 2. 並列実行のための自動ロック機構 (`ThreadSafeHookBase`)
  サブクラスでオーバーライドされたメソッドを自動でロックラッパーで包む仕組みを導入します。これにより、ユーザーは明示的なロック制御なしでスレッドセーフな集計が可能になります。

  ### 3. 型安全なコンテキストオブジェクトの分離
  実行フェーズごとに最適化された **3つの専用コンテキストクラス** を提供します。
  * **`PreExecuteContext`**: 関数実行前。
  * **`CacheHitContext`**: キャッシュ取得成功時。
  * **`CacheMissContext`**: 関数実行完了時。

  ### 4. ゼロオーバーヘッドの原則
  フックが登録されていない場合は、コンテキストオブジェクトの生成を完全にスキップします。

  ## 影響・結果

  * **ポジティブ**:
      * **優れた DX**: 専用コンテキストにより、IDE でのプロパティ補完が正確に機能し、開発時のミスを防げる。
      * **並列処理の安全保障**: 複雑なマルチスレッドプログラミングの知識がなくても安全な拡張が可能になる。
  * **ネガティブ**:
      * **実装の複雑性**: ライブラリ内部で複数のコンテキストクラスを管理する必要がある。
      * **ボイラープレート**: ユーザーはクラスを継承して実装する手間があるが、型安全性のメリットが上回る。
