initial commit

docs/memory-pressure.md

@@ -0,0 +1,44 @@
+# メモリ圧迫への対応
+
+原設計02「キャッシュと資源管理」と06「先読みの自動抑制」を実装する。
+描画キャッシュの設定値とは別に、OSが報告する利用可能な物理メモリを監視する。
+Linuxでは `/proc/meminfo` の `MemTotal` / `MemAvailable`、Windowsでは
+`GlobalMemoryStatusEx` の物理メモリ値を用いる。1秒間隔で読み、圧迫状態の変化を
+Controllerへ通知する。パーサーワーカーにはこの監視を追加しない。
+
+## 閾値と遷移
+
+閾値は実装時に決めた暫定値であり、原設計08の性能予算を変更しない。
+
+- 空きが総物理メモリの10%未満、かつ1 GiB未満になったら先読みを止める。
+- 同条件が続くと、5サンプルごとに不可視キャッシュ回収、解像度抑制、文書処理停止へ進む。
+- 空きが3%未満、かつ256 MiB未満の場合は、毎サンプル1段階ずつ進む。処置の順を飛ばさない。
+- 空きが15%以上、または1.5 GiB以上の状態が5サンプル続いたら通常状態へ戻す。
+- 取得失敗、不正な数値、欠損、重複、オーバーフローは状態を維持し、連続判定をリセットする。
+  不明な値を空きゼロや回復として扱わない。
+
+監視はOSの物理メモリ報告に基づく。cgroup固有の割当量、GPUメモリ、仮想アドレス空間の
+残量をこのサンプルから推測しない。これらを含む全種類の割当失敗を予知する保証ではない。
+既存のworker資源上限、renderer監視、キャッシュ予算と併用する。
+
+## 文書処理
+
+PDFの先読み停止は設定値を書き換えず、既存の描画世代を失効させる。
+不可視キャッシュは位置が変わった後も回収し、表示中の画像を優先する。
+解像度抑制では論理倍率とページ・注釈座標を変えず、描画時の画素密度を原則半分にする。
+workerが受け付ける最小倍率・DPRを下回らないよう制限する。読書位置を維持し、通知する。
+低解像度画像が揃った後に旧画像を回収する。回復時は通常の解像度で再描画する。
+
+HTML/ZIP/EPUBのWebEngine内部キャッシュや描画解像度を外部から操作したとは扱わない。
+これらは圧迫継続の通知と、最終段階での資源提供・renderer・展開処理の停止を適用する。
+最終段階では読込中の新文書を取り消し、現在の文書の処理を止め、PDF画像も回収する。
+状態は `Recovering` とし、原本へ書き込まない。圧迫中の新規openを拒否する。
+メモリが回復しても停止した文書は自動で再読込せず、利用者が明示的に開き直す。
+
+## 検証方法
+
+メモリを実際に枯渇させず、同じ監視・Controller・Canvas経路へ有限のサンプルを注入する。
+状態遷移、閾値境界、破損サンプル、ヒステリシス、先読み・キャッシュ・解像度・座標の保持、
+取消、原本ハッシュ、停止後の明示的再openを試験する。Linuxの実サンプル取得も別に確認する。
+この方法をOS全体のOOM耐性試験やWindows実行の証拠とはしない。結果は
+[検証記録](VALIDATION.md)へ記録する。