関数の実行前、キャッシュヒット時、キャッシュミス時にカスタムコールバック（フック）を実行できること。スレッドセーフなフック実装を提供すること。

コンポーネント構成

graph TD
  A[core.Spot] -->|イベント通知| B[HookBase]
  C[ThreadSafeHookBase]　--> B
  B -->|コンテキスト| D[Context Objects]
  E[PreExecuteContext] --> D
  F[CacheHitContext] --> D
  G[CacheMissContext] --> D

コンポーネント責務

データフロー

sequenceDiagram
  participant Spot as core.Spot
  participant Hook as HookBase
  participant Fn as Target Function

  Spot->>Hook: pre_execute(ctx)
  alt キャッシュヒット
      Spot->>Hook: on_cache_hit(ctx)
  else キャッシュミス
      Spot->>Fn: execute()
      Fn-->>Spot: result
      Spot->>Hook: on_cache_miss(ctx)
  end

技術選定

非機能要件方針

• 透過性: フックの実行失敗（例外）は主処理の結果に影響を与えない

• 柔軟性: 関数ごとに異なるフックリストを hooks=[...] で指定可能

• パフォーマンス: フック未登録時のオーバーヘッドを最小化するガード条件を実装

インターフェース

class HookBase:
    def pre_execute(self, ctx: PreExecuteContext) -> None: ...
    def on_cache_hit(self, ctx: CacheHitContext) -> None: ...
    def on_cache_miss(self, ctx: CacheMissContext) -> None: ...

振る舞い

1. フック呼出: キャッシュエンジンの各ステート（実行前、ヒット、ミス）で登録されたフックを順番に実行する
2. スレッド安全化: ThreadSafeHookBase を継承した場合、メタクラスが自動的に各メソッドを with self._lock: で包む

パラメータ詳細 (Context)

エラーハンドリング

• フック内例外: フックの実行中に発生した例外はキャッチされ、エラーログとして出力されるが、主処理（関数の実行結果）は中断されない。

エッジケース

• フックの順序: hooks=[h1, h2] と指定した場合、h1 -> h2 の順で実行される。

目的

Hook システムはキャッシュライフサイクルへのユーザー拡張ポイント（ロギング、メトリクス収集、監査等）であり、フック内の不具合がメインの関数実行に影響を与えないことが最重要の契約である。また ThreadSafeHookBase の自動ロック機構の正確性を保証する。

検証観点

• ライフサイクル呼び出し順: キャッシュミス時に pre_execute → 関数実行 → on_cache_miss の順でフックが呼ばれること。キャッシュヒット時に pre_execute → on_cache_hit の順で呼ばれること
• コンテキスト情報: 各フックに渡されるコンテキスト（PreExecuteContext, CacheHitContext, CacheMissContext）が正しい情報（func_name, args, result 等）を含むこと
• 例外隔離: フック内で例外が発生しても、関数の実行結果には影響せず、ERROR ログにのみ記録されること
• 状態保持: フックインスタンスが呼び出し間で状態（カウンタ等）を保持できること
• ThreadSafeHookBase: __init_subclass__ によりユーザー定義メソッドが自動的に RLock でラップされ、複数スレッドからの同時呼び出しで競合状態が発生しないこと

実装概要

タスク実行ライフサイクルに介入するインターフェース HookBase と、 そのスレッドセーフ版 ThreadSafeHookBase の実装。 pre_execute, on_cache_hit, on_cache_miss の各コールバックが提供される。 ThreadSafeHookBase は __init_subclass__ を利用し、サブクラスで定義された フックメソッドを自動的にロックでラップする。

設計判断

init_subclass による透過的ロッキング

ユーザーが手動でロックを書く手間を省くため、メタクラス的なアプローチを採用。 クラス定義時にフックメソッドを抽出し、_wrap_with_lock デコレータで包むことで、 ユーザーコードを汚さずに完全な排他制御を実現している。

RLock（再入可能ロック）の使用

当初の Lock から RLock に変更された。 サブクラスが super().pre_execute(...) のように親のメソッドを呼び出した際、 同一スレッドが再度ロックを取得しようとしてデッドロックする問題を防ぐため。

実装メモ

• _wrap_with_lock は functools.wraps を使い、元のメタデータを保持する
• ThreadSafeHookBase は __getattr__ をオーバーライドし、 super().__init__() の呼び出し忘れに対して親切なエラーメッセージを返す

クラスベース・フックシステムと並列実行サポート

Context and Problem Statement / コンテキスト

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

Decision Drivers / 要求

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

Considered Options / 検討

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

Decision Outcome / 決定

Chosen option: Option 2.

1. クラスベースのフックインターフェース (HookBase)

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

2. 並列実行のための自動ロック機構 (ThreadSafeHookBase)

サブクラスでオーバーライドされたメソッドを自動でロックラッパーで包む仕組みを導入します。これにより、ユーザーは明示的なロック制御なしでスレッドセーフな集計が可能になります。

3. 型安全なコンテキストオブジェクトの分離

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

4. ゼロオーバーヘッドの原則

フックが登録されていない場合は、コンテキストオブジェクトの生成を完全にスキップします。

Consequences / 決定

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