active: true
derived: false
groups:
- BGIO
header: |
  ガベージコレクション時のバックグラウンドループシャットダウン戦略
level: 1.46
links:
- ARCH006: NQNGQUULw16h1cxj2M5I4pgAr3bNlRze6AMKu_rdo0s=
- REQ006: 3PN_I3D9BWCwGe4h19vSOVkDSeWNY3sM_fbWg0rwOfk=
normative: true
ref: ''
reviewed: CIarSgn9_1r7-SEajNRQSdEXD0UPKTKg0P3A47xtQMs=
status: proposed
text: |
  # ガベージコレクション時のバックグラウンドループシャットダウン戦略

  ## コンテキストと課題

  `beautyspot` はキャッシュの永続化をバックグラウンドスレッドにオフロードしています。コンテキストマネージャを使用した場合は安全にタスクがドレインされますが、インスタンスをグローバルに生成して使い捨てた場合など、ガベージコレクション (GC) によってインスタンスが破棄される際の振る舞いが課題となっていました。GC のタイミングで未完了の I/O タスクを待機すべきか、それとも破棄すべきかを決定する必要があります。

  ## 判断基準

  * **Responsiveness**: GC は任意のタイミングで発生するため、メインスレッドを予期せずフリーズさせないこと。
  * **Predictability**: リソース管理の責務を明確にし、マジックに頼りすぎない予測可能なライフサイクルを提供すること。
  * **Observability**: 適切でない管理によってデータが破棄された場合に、開発者がそれを検知できるようにすること。

  ## 検討した選択肢

  * **Option 1**: GC 時にもタスクの完了を待機する。メインスレッドがフリーズするリスクがある。
  * **Option 2**: 未完了タスクを即座に破棄（キャンセル）し、警告を発行する。メインスレッドの安定性を最優先する。

  ## 決定事項

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

  ガベージコレクション (`weakref.finalize`) によるインスタンス破棄時には、**未完了のタスクを待機せず、即座に破棄する（Fail-fast & Non-blocking）** ことを決定しました。

  同時に、タスクが破棄された場合は `logger.warning` および `ResourceWarning` を発行し、ユーザーに対してコンテキストマネージャや明示的な `shutdown()` の使用を強く促します。

  ## 影響・結果

  * **ポジティブ**:
      * `beautyspot` が原因でアプリケーションの GC やシャットダウンがハングアップしないことが保証される。
      * ライフサイクル管理の重要性をユーザーに明示的に伝えることができる。
  * **ネガティブ**:
      * 不適切な使い方をした場合、キャッシュが永続化されない（データロスト）事象が発生する。
  * **Mitigation**:
      * ドキュメントにてコンテキストマネージャの利用をベストプラクティスとして周知し、安全な管理方法を強調する。
