reclaimable 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. checksums.yaml +7 -0
  2. data/.claude/launch.json +11 -0
  3. data/.gitignore +11 -0
  4. data/.gitlab-ci.yml +16 -0
  5. data/AGENTS.md +88 -0
  6. data/CLAUDE.md +1 -0
  7. data/Gemfile +3 -0
  8. data/LICENSE +674 -0
  9. data/README.md +160 -0
  10. data/Rakefile +28 -0
  11. data/ai-skill/reclaimable/SKILL.md +94 -0
  12. data/benchmark/README.md +59 -0
  13. data/benchmark/experiments/lstat_scanner.rb +11 -0
  14. data/benchmark/experiments/ractor_scanner.rb +92 -0
  15. data/benchmark/experiments/verify_bulk_list.rb +34 -0
  16. data/benchmark/lib/fixture.rb +104 -0
  17. data/benchmark/lib/results.rb +62 -0
  18. data/benchmark/reports/00-baseline.md +75 -0
  19. data/benchmark/reports/01-jit.md +70 -0
  20. data/benchmark/reports/02-ractor.md +58 -0
  21. data/benchmark/reports/03-getattrlistbulk.md +84 -0
  22. data/benchmark/reports/04-others.md +52 -0
  23. data/benchmark/reports/05-outside-root.md +56 -0
  24. data/benchmark/reports/06-round2-discussion.md +374 -0
  25. data/benchmark/reports/06-round2.md +194 -0
  26. data/benchmark/reports/README.md +46 -0
  27. data/benchmark/results/baseline.yml +126 -0
  28. data/benchmark/results/bulk-list.yml +126 -0
  29. data/benchmark/results/final-yjit.yml +126 -0
  30. data/benchmark/results/final.yml +126 -0
  31. data/benchmark/results/ractor-exp.yml +38 -0
  32. data/benchmark/results/round2-after.yml +126 -0
  33. data/benchmark/results/round2-before.yml +126 -0
  34. data/benchmark/results/src-baseline.yml +32 -0
  35. data/benchmark/results/src-bulk-list.yml +32 -0
  36. data/benchmark/results/src-pair-none1.yml +38 -0
  37. data/benchmark/results/src-pair-none2.yml +38 -0
  38. data/benchmark/results/src-pair-yjit1.yml +38 -0
  39. data/benchmark/results/src-pair-yjit2.yml +38 -0
  40. data/benchmark/results/src-ractor-exp.yml +32 -0
  41. data/benchmark/results/src-round2-after1.yml +52 -0
  42. data/benchmark/results/src-round2-after2.yml +52 -0
  43. data/benchmark/results/src-round2-before1.yml +52 -0
  44. data/benchmark/results/src-round2-before2.yml +52 -0
  45. data/benchmark/results/yjit.yml +126 -0
  46. data/benchmark/results/zjit.yml +126 -0
  47. data/benchmark/run.rb +149 -0
  48. data/bin/reclaimable +10 -0
  49. data/doc/performance.md +179 -0
  50. data/lib/reclaimable/ai_skill.rb +138 -0
  51. data/lib/reclaimable/bulk_list.rb +91 -0
  52. data/lib/reclaimable/cache_dump.rb +125 -0
  53. data/lib/reclaimable/cli.rb +168 -0
  54. data/lib/reclaimable/cloud_files.rb +33 -0
  55. data/lib/reclaimable/config.rb +100 -0
  56. data/lib/reclaimable/i18n.rb +24 -0
  57. data/lib/reclaimable/locations.rb +89 -0
  58. data/lib/reclaimable/output.rb +154 -0
  59. data/lib/reclaimable/paths.rb +36 -0
  60. data/lib/reclaimable/report.rb +504 -0
  61. data/lib/reclaimable/ruby_abi.rb +69 -0
  62. data/lib/reclaimable/scan_cache.rb +97 -0
  63. data/lib/reclaimable/scanner.rb +440 -0
  64. data/lib/reclaimable/util.rb +34 -0
  65. data/lib/reclaimable.rb +42 -0
  66. data/locale/ja/LC_MESSAGES/reclaimable.mo +0 -0
  67. data/man/reclaimable.1.ronn +302 -0
  68. data/man/reclaimable.en.1 +234 -0
  69. data/man/reclaimable.ja.1 +452 -0
  70. data/po/ja/reclaimable-docs.po +668 -0
  71. data/po/ja/reclaimable.po +510 -0
  72. data/rakelib/benchmark.rake +22 -0
  73. data/rakelib/docs/japanese.rb +132 -0
  74. data/rakelib/docs/man_page.rb +73 -0
  75. data/rakelib/docs/site.rb +187 -0
  76. data/rakelib/docs/sources.rb +94 -0
  77. data/rakelib/docs/translation.rb +157 -0
  78. data/rakelib/docs.rake +62 -0
  79. data/rakelib/gettext.rake +30 -0
  80. data/rakelib/i18n.rake +199 -0
  81. data/reclaimable.gemspec +56 -0
  82. data/site/index.md +142 -0
  83. data/site/layout.html.erb +60 -0
  84. data/site/style.css +82 -0
  85. metadata +231 -0
@@ -0,0 +1,75 @@
1
+ # 00. ベースラインと、時間のかかっている場所
2
+
3
+ 2026-11-16 計測。施策を入れる前の状態(コミット c7602d2 の `lib/`)。
4
+
5
+ ## 計測の条件
6
+
7
+ - 機械: Apple Silicon(高性能コア 4 + 高効率コア 4)、macOS(Darwin 27.2)、APFS
8
+ - Ruby: 4.0.9(+PRISM)、JIT なし
9
+ - スレッド数: 8(`-j` の既定)
10
+ - 測り方: [README](../README.md) を参照。各シナリオを繰り返し、`real` の最小値で比べる
11
+ - 対象は 2 つ
12
+ - **フィクスチャー**: 作り物のツリー(30,088 フォルダー、216,846 ファイル)。全部が OS のファイルキャッシュに乗るので、
13
+ ディスクの待ちが無く、プログラムとシステムコールの CPU 時間だけが出る
14
+ - **`~/src`**: 実際のフォルダー(624,894 フォルダー、実占有 287GB)。繰り返しは 2 回
15
+
16
+ ## 結果
17
+
18
+ フィクスチャー([results/baseline.yml](../results/baseline.yml))。時間は秒。
19
+
20
+ | シナリオ | real | user | sys |
21
+ | --- | ---: | ---: | ---: |
22
+ | scan (no cache) | 2.372 | 1.060 | 3.938 |
23
+ | scan (cached) | 0.246 | 0.162 | 0.151 |
24
+ | cache save | 0.072 | 0.070 | 0.001 |
25
+ | cache load | 0.033 | 0.032 | 0.000 |
26
+ | cache dump (json) | 0.106 | 0.104 | 0.002 |
27
+ | startup (--help) | 0.143 | 0.105 | 0.035 |
28
+
29
+ `~/src`([results/src-baseline.yml](../results/src-baseline.yml))。
30
+
31
+ | シナリオ | real | user | sys |
32
+ | --- | ---: | ---: | ---: |
33
+ | scan (no cache) | 43.02 | 19.24 | 95.08 |
34
+ | scan (cached) | 7.96 | 4.07 | 11.92 |
35
+
36
+ ## 分かったこと
37
+
38
+ ### 時間の大半は走査で、その大半はカーネルの中(lstat)
39
+
40
+ キャッシュ無しの走査では、CPU 時間の 8 割が `sys`(システムコールの中)。Ruby のコードが動いている `user` は 2 割しかない。
41
+ ファイル 1 つにつき `lstat` を 1 回呼んでいるのが効いている。
42
+ Ruby の側をいくら速くしても(JIT など)、縮められるのは残りの 2 割まで。
43
+ システムコールの回数を減らすのが、いちばん効く([03](03-getattrlistbulk.md))。
44
+
45
+ ### スレッドは、待ち時間のある実際のフォルダーでは効くが、CPU だけの仕事では効かない
46
+
47
+ スレッド数を変えて測った(`BENCH_JOBS`)。
48
+
49
+ | スレッド数 | フィクスチャー no cache | フィクスチャー cached | `~/src` no cache | `~/src` cached |
50
+ | ---: | ---: | ---: | ---: | ---: |
51
+ | 1 | 2.171 | 0.153 | 110.2 | 36.8 |
52
+ | 2 | 1.803 | 0.238 | | |
53
+ | 4 | 2.245 | 0.244 | | |
54
+ | 8 | 2.372 | 0.246 | 43.0 | 8.0 |
55
+
56
+ - `~/src` では 8 スレッドで 2.6〜4.6 倍速い。1 スレッドのときは `real` 110 秒に対して CPU 時間が 61 秒しかなく、
57
+ 残りは待ち(60 万フォルダーぶんのメタデータは OS のキャッシュに収まりきらず、読み直しが起きる)。
58
+ 待っている間にほかのスレッドが進めるので、スレッドが効く。
59
+ - フィクスチャーでは 1 スレッドがいちばん速い。待ちが無いので、スレッドを増やしても GVL の取り合いと、
60
+ カーネルの中でのロックの取り合い(`sys` の合計が 1.6 秒 → 3.9 秒に増える)で遅くなるだけ。
61
+
62
+ 実際の使い方は `~/src` の側に近いので、スレッドでの並列化はそのままでよい。
63
+ フィクスチャーは「CPU 時間がどれだけ減ったか」を見るのに使い、採否は `~/src` の値と合わせて決める。
64
+
65
+ ### キャッシュの読み書きと起動は、走査に比べれば小さい
66
+
67
+ `~/src` のキャッシュ(60 万フォルダー、16MB)で、読み込み 1.8 秒、書き込み 2.3 秒。
68
+ 走査(キャッシュありで 8 秒)に比べれば小さいが、無視できるほどでもない([04](04-others.md))。
69
+ 起動(0.14 秒)は、走査する実行では誤差。
70
+
71
+ ## このベンチマークで測れないもの
72
+
73
+ - **再起動直後など、OS のファイルキャッシュが空の状態**。ディスクの読み込み待ちが大半になり、スレッドの効き方も変わる。
74
+ キャッシュを空にするには管理者権限(`sudo purge`)が要るので、ベンチマークには入れていない。
75
+ - **レポートの各節**(`brew`・`docker` などの外部コマンド)。外部の状態で時間が変わるので外した。
@@ -0,0 +1,70 @@
1
+ # 01. JIT(YJIT・ZJIT)
2
+
3
+ **結論: YJIT を採用した**(走査を始める前に有効にする)。効果は走査で 6〜15%。**ZJIT は効果が無いので使わない。**
4
+ 実装は `CLI#enable_jit`([lib/reclaimable/cli.rb](../../lib/reclaimable/cli.rb))。
5
+
6
+ ## 試したこと
7
+
8
+ Ruby 4.0.9 には YJIT と ZJIT の両方が入っている。ベンチマークを `--yjit`・`--zjit` を付けて測った。
9
+
10
+ ```sh
11
+ JIT=yjit bundle exec rake "benchmark[yjit]"
12
+ JIT=zjit bundle exec rake "benchmark[zjit]"
13
+ ```
14
+
15
+ ## 結果
16
+
17
+ ### 施策を入れる前の状態で(フィクスチャー)
18
+
19
+ 時間は秒(`real` の最小値)。括弧の中は JIT なしに対する比。
20
+
21
+ | シナリオ | JIT なし | YJIT | ZJIT |
22
+ | --- | ---: | ---: | ---: |
23
+ | scan (no cache) | 2.372 | 2.274 (x0.96) | 2.385 (x1.01) |
24
+ | scan (cached) | 0.246 | 0.197 (x0.80) | 0.240 (x0.98) |
25
+ | cache save | 0.072 | 0.069 (x0.96) | 0.070 (x0.97) |
26
+ | cache load | 0.033 | 0.030 (x0.91) | 0.030 (x0.91) |
27
+ | cache dump (json) | 0.106 | 0.092 (x0.87) | 0.100 (x0.94) |
28
+ | startup (--help) | 0.143 | 0.147 (x1.03) | 0.150 (x1.05) |
29
+
30
+ 結果のファイル: [baseline.yml](../results/baseline.yml)、[yjit.yml](../results/yjit.yml)、[zjit.yml](../results/zjit.yml)
31
+
32
+ - YJIT は、Ruby のコードが動いている時間(`user`)の割合が大きいシナリオほど効く。キャッシュありの走査で 20%。
33
+ - キャッシュ無しの走査は、時間の 8 割がカーネルの中([00](00-baseline.md))なので、4% しか縮まない。
34
+ - ZJIT は、どのシナリオでも JIT なしとほぼ同じ。4.0 の時点ではまだ YJIT ほど速くならない。
35
+ - 起動は、どちらの JIT でも 4〜7 ミリ秒遅くなる。
36
+
37
+ ### getattrlistbulk を入れた後の状態で
38
+
39
+ [03](03-getattrlistbulk.md) を入れるとシステムコールが減り、Ruby のコードの割合が上がるので、YJIT の効きが少し良くなる。
40
+
41
+ | | JIT なし | YJIT |
42
+ | --- | ---: | ---: |
43
+ | フィクスチャー no cache | 1.130 | 0.984 (x0.87) |
44
+ | フィクスチャー cached | 0.209 | 0.181 (x0.87) |
45
+ | `~/src` no cache(1 回目) | 27.00 | 24.68 (x0.91) |
46
+ | `~/src` cached(1 回目) | 8.62 | 8.23 (x0.95) |
47
+ | `~/src` no cache(2 回目) | 26.92 | 25.13 (x0.93) |
48
+ | `~/src` cached(2 回目) | 8.72 | 8.00 (x0.92) |
49
+
50
+ 結果のファイル: [final.yml](../results/final.yml)、[final-yjit.yml](../results/final-yjit.yml)、
51
+ `src-pair-none1`・`src-pair-yjit1`・`src-pair-none2`・`src-pair-yjit2`(`~/src`。JIT なしと YJIT を交互に 2 回ずつ)
52
+
53
+ `~/src` は計測ごとのばらつきが大きい(同じ条件でも、測った時間帯によって 1〜2 割違う)ので、
54
+ JIT なしと YJIT を交互に測った。2 回とも YJIT のほうが速く、差は 5〜9%。
55
+ `user` の最小値は、キャッシュ無しで 15.2 秒 → 12.7 秒、キャッシュありで 4.8 秒 → 4.2 秒に減っている。
56
+
57
+ ## 入れ方
58
+
59
+ `ruby --yjit` で起動する代わりに、走査を始める直前に `RubyVM::YJIT.enable` を呼ぶ。
60
+
61
+ - 走査をしない実行(`--help`・`--dump-cache`・`--ai-skill` など)は、JIT のぶん起動が遅くなるだけなので、有効にしない。
62
+ - 有効にするのは、レポートを作るときと、`--freeze` でフォルダーを測るとき。
63
+ - YJIT 無しでビルドされた Ruby(`RubyVM::YJIT` が無い)では、何もしない。結果は変わらず、遅くなるだけ。
64
+ - 利用者が `--yjit` や `RUBY_YJIT_ENABLE=1` ですでに有効にしているときは、そのまま。
65
+
66
+ ## 気をつける点
67
+
68
+ - YJIT は生成したコードのぶんメモリーを使う(既定で上限 128MB を確保するが、実際に使うのは生成したぶんだけ)。
69
+ 走査で持つデータ(100 万フォルダーで数百 MB)に比べれば小さい。
70
+ - ZJIT は開発が進んでいるので、Ruby の版が上がったら測り直す価値がある(`JIT=zjit` で測れる)。
@@ -0,0 +1,58 @@
1
+ # 02. Ractor
2
+
3
+ **結論: 採用しない。** 試作は [experiments/ractor_scanner.rb](../experiments/ractor_scanner.rb) に残してある。
4
+
5
+ ## 試したこと
6
+
7
+ スレッドの代わりに Ractor でサブツリーを並列にたどる走査を試作した。
8
+ スレッドは GVL のために Ruby のコードを同時に 1 つしか実行できないが、Ractor どうしは並列に実行できる。
9
+
10
+ - 親(メインの Ractor)が深さ 3 まで自分でたどり、その下のサブツリーをタスクとして集める
11
+ - ワーカーの Ractor(8 つ)が、手が空くたびに親からタスクを 1 つ受け取り(`Ractor::Port`)、サブツリーを最後までたどる
12
+ - ワーカーは終わるときに、集計結果を `Ractor#value` で親に渡す
13
+ - 前回の走査結果(キャッシュ)は、Ractor の間で共有できるよう全体を凍結する(`Ractor.make_shareable`)
14
+
15
+ ```sh
16
+ BENCH_REQUIRE=benchmark/experiments/ractor_scanner.rb BENCH_SCANNER=Reclaimable::RactorScanner \
17
+ bundle exec rake "benchmark[ractor]"
18
+ ```
19
+
20
+ ## 結果
21
+
22
+ 時間は秒(`real` の最小値)。括弧の中はベースライン(スレッド + lstat)に対する比。
23
+
24
+ | | ベースライン | Ractor | (参考)スレッド + getattrlistbulk |
25
+ | --- | ---: | ---: | ---: |
26
+ | フィクスチャー no cache | 2.372 | 1.188 (x0.50) | 1.028 (x0.43) |
27
+ | フィクスチャー cached | 0.246 | **0.067 (x0.27)** | 0.242 (x0.98) |
28
+ | `~/src` no cache | 43.02 | 31.68 (x0.74) | 22.27 (x0.52) |
29
+ | `~/src` cached | 7.96 | 8.46 (x1.06) | 7.10 (x0.89) |
30
+
31
+ 結果のファイル: [ractor-exp.yml](../results/ractor-exp.yml)、[src-ractor-exp.yml](../results/src-ractor-exp.yml)
32
+
33
+ - CPU だけの仕事(フィクスチャー)では、はっきり速い。とくにキャッシュありの走査は 3.7 倍。
34
+ スレッドでは GVL の取り合いで並列にならなかった部分が、並列に動いている。
35
+ - 実際のフォルダー(`~/src`)では、キャッシュ無しで 26% 速いだけで、ふだん使うキャッシュありの走査は速くならない。
36
+ ここでは待ち時間が大半で、スレッドでも待ちの間は並列に進めているため、GVL が無くなる利点が出にくい。
37
+
38
+ ## 採用しない理由
39
+
40
+ 1. **getattrlistbulk と併用できない。** getattrlistbulk を呼ぶのに使う Fiddle は、メイン以外の Ractor から呼べない
41
+ (`Ractor::UnsafeError: ractor unsafe method called from not main ractor`)。どちらかを選ぶことになり、
42
+ 実際のフォルダーでは getattrlistbulk([03](03-getattrlistbulk.md))のほうがどのシナリオでも速い。
43
+ 自前の C 拡張を書けば併用できるが、「実行時の依存は gettext だけ、ほかは標準添付ライブラリー」という方針に反する。
44
+ 2. **ハードリンクの重複を除けない。** 「同じ inode は最初の 1 回だけ数える」ための記録(`@seen_inodes`)を
45
+ Ractor の間で共有できない。試作では Ractor ごとに除いたので、`~/src` の合計が 174MB 多く出た
46
+ (287,391,289,344 → 287,565,713,408 バイト)。正しくするには、ハードリンクの一覧を親に集めてから
47
+ フォルダーごとの合計を引き直す仕組みが要る。
48
+ 3. **仕事の配り直しができない。** 今の走査は、手の空いたスレッドがいれば、たどっている途中の子フォルダーを渡す
49
+ (ファイルの多いサブツリーが 1 つあっても、全体がそれを待たずに済む)。Ractor の間では途中の状態を共有できないので、
50
+ 同じことをするには作りを大きく変える必要がある。
51
+ 4. **Ractor はまだ実験的。** Ruby 4.0 でも使うたびに警告が出る(`Ractor API is experimental`)。
52
+ API も 4.0 で変わったばかり(`Ractor::Port`、`Ractor#value`)。
53
+
54
+ ## 今後、見直す価値があるとき
55
+
56
+ - Fiddle が Ractor の中で使えるようになったとき。getattrlistbulk と併用できれば、フィクスチャーの
57
+ キャッシュありの走査で見えた 3.7 倍が、OS のキャッシュに収まる大きさのフォルダーでは実際に得られる見込みがある。
58
+ - 走査の対象が小さく(数万フォルダー)、全部が OS のキャッシュに乗る使い方が主になったとき。
@@ -0,0 +1,84 @@
1
+ # 03. フォルダーの直下をまとめて読む(getattrlistbulk)
2
+
3
+ **結論: 採用した。** キャッシュ無しの走査が、およそ半分の時間になる。
4
+ 実装は [lib/reclaimable/bulk_list.rb](../../lib/reclaimable/bulk_list.rb) と `Scanner#read_dir`。
5
+
6
+ ## 何を変えたか
7
+
8
+ [ベースライン](00-baseline.md)で見たとおり、キャッシュ無しの走査の時間は大半が `lstat` で、
9
+ ファイル 1 つにつきシステムコールを 1 回呼んでいた。
10
+
11
+ | | 変更前 | 変更後 |
12
+ | --- | --- | --- |
13
+ | 名前の一覧 | `Dir.children` | `getattrlistbulk` が名前と属性を一緒に返す |
14
+ | ファイルの種類・大きさ・リンク数 | 名前ごとに `File.lstat` | (同上) |
15
+ | システムコールの回数 | フォルダーごとに「ファイルの数 + 数回」 | フォルダーごとに数回 |
16
+
17
+ `getattrlistbulk(2)` は、フォルダーの直下の全部の名前と、求めた属性をまとめて返す macOS のシステムコール。
18
+ 求める属性は、名前・種類(`ATTR_CMN_OBJTYPE`)・リンク数・実占有(`ATTR_FILE_ALLOCSIZE`)・見かけの大きさ
19
+ (`ATTR_FILE_DATALENGTH`)。`setiopolicy_np` と同じく Fiddle で呼ぶので、依存は増えない。
20
+
21
+ 変えたのは「キャッシュに無いフォルダーの直下を読む」ところだけ。次のものは前のまま。
22
+
23
+ - 子フォルダーへ降りる前の `lstat`(更新時刻と、別ボリュームかどうかを確かめる)
24
+ - 大きいファイルとハードリンクの、毎回の `lstat`
25
+ - キャッシュの形式(前に作ったキャッシュをそのまま使える)
26
+
27
+ ## 結果
28
+
29
+ 時間は秒(`real` の最小値)。括弧の中はベースラインに対する比。
30
+
31
+ | | ベースライン | 変更後 |
32
+ | --- | ---: | ---: |
33
+ | フィクスチャー no cache | 2.372 | **1.028 (x0.43)** |
34
+ | フィクスチャー cached | 0.246 | 0.242 (x0.98) |
35
+ | `~/src` no cache | 43.02 | **22.27 (x0.52)** |
36
+ | `~/src` cached | 7.96 | 7.10 (x0.89) |
37
+
38
+ 結果のファイル: [bulk-list.yml](../results/bulk-list.yml)、[src-bulk-list.yml](../results/src-bulk-list.yml)
39
+
40
+ - キャッシュ無しの走査(初回、`--fresh`、キャッシュが 7 日より古いとき)が半分になる。
41
+ `~/src` では CPU 時間も `sys` 95 秒 → 49 秒、`user` 19 秒 → 12 秒に減った。
42
+ - キャッシュありの走査は、キャッシュに無い(前回から変わった)フォルダーだけが速くなる。
43
+ ベンチマークでは全部のフォルダーがキャッシュにあるので、ほぼ変わらない(`~/src` の 0.89 は計測のばらつきの範囲)。
44
+
45
+ ## 結果が変わっていないことの確認
46
+
47
+ - フィクスチャーの合計は、変更の前後で同じ(887,324,672 バイト)。
48
+ - 実際のフォルダーでは、両方の読み方で走査して、フォルダーごとの記録(小さいファイルの合計・子フォルダー名・
49
+ 大きいファイル名)を突き合わせた([experiments/verify_bulk_list.rb](../experiments/verify_bulk_list.rb))。
50
+ `~/Library`(88,085 フォルダー、117GB。圧縮されたファイル・ソケット・シンボリックリンク・クラウド上のファイルを含む)で、
51
+ 走査の合間に中身が変わった 2 フォルダーを除き、全部一致した。合計のバイト数も一致した。
52
+
53
+ ```sh
54
+ bundle exec ruby benchmark/experiments/verify_bulk_list.rb ~/Library
55
+ ```
56
+
57
+ ## 使えないときの扱い
58
+
59
+ - Fiddle が無い、macOS でない(関数が無い): `BulkList.available?` が false になり、前と同じく `lstat` で読む。
60
+ - ファイルシステムが対応していない(`ENOTSUP`・`EINVAL`): そのフォルダーを `lstat` で読み直す。
61
+ - 属性をもらえなかったファイル: そのファイルだけ `lstat` で調べる。
62
+ - 読めない(`EACCES`・`EPERM`)、クラウド上にしか無い(`EDEADLK`): 前と同じ扱い。
63
+
64
+ 前の読み方と比べたいときは、[experiments/lstat_scanner.rb](../experiments/lstat_scanner.rb) に差し替えて測る。
65
+
66
+ ## 気をつける点
67
+
68
+ - ファイル名は、ファイルシステムにある並びのバイト列をそのまま使う。Ruby の `Dir.children` は HFS+ のボリュームでは
69
+ 名前を NFC に直すが、こちらは直さない。APFS では `Dir.children` も直さないので同じ結果になる。
70
+ 起点(`-d`)が HFS+ のボリュームのときだけ、前に作ったキャッシュの名前と食い違って、1 度だけ読み直しになりうる。
71
+
72
+ ## 見送ったもの
73
+
74
+ - **子フォルダーの `lstat` も、親をまとめ読みして置き換える。** キャッシュありの走査で残っているシステムコールは、
75
+ ほぼこの `lstat` だけ(フォルダー 1 つにつき 1 回)。`~/src` のキャッシュを使って、1 スレッドで試した。
76
+
77
+ | 読み方 | real |
78
+ | --- | ---: |
79
+ | 子フォルダーごとに `lstat`(今のまま) | 25.0 秒 |
80
+ | 子フォルダーのある親を全部まとめ読み | 39.7 秒 |
81
+ | 子フォルダーが 3 つ以上の親だけまとめ読み | 22.5 秒(残りの `lstat` は含まない) |
82
+
83
+ まとめ読みはファイルも全部読むことになり、子フォルダーが 1 つか 2 つの親(全体の 8 割)では損をする。
84
+ 3 つ以上に絞っても差は小さいので、入れなかった。
@@ -0,0 +1,52 @@
1
+ # 04. そのほかの施策
2
+
3
+ ## 採用: キャッシュの書き込みで、圧縮の速さを優先する
4
+
5
+ **結論: 採用した。** キャッシュの書き込みが 3〜4 割速くなる。実装は `ScanCache#save`
6
+ ([lib/reclaimable/scan_cache.rb](../../lib/reclaimable/scan_cache.rb))。
7
+
8
+ キャッシュは Marshal したものを gzip で圧縮して書いている。`~/src` のキャッシュ(60 万フォルダー)で内訳を測ると、
9
+ 書き込みの時間の半分以上が圧縮だった。
10
+
11
+ | | 時間 | ファイルの大きさ |
12
+ | --- | ---: | ---: |
13
+ | Marshal だけ(圧縮なし) | 1.05 秒 | 110.0MB |
14
+ | Marshal + gzip(既定の圧縮率。変更前) | 2.33 秒 | 16.2MB |
15
+ | Marshal + gzip(`Zlib::BEST_SPEED`。変更後) | 1.51 秒 | 18.8MB |
16
+
17
+ ファイルは 16% 大きくなるが、書き込みは 35% 速くなる。フィクスチャーでは 0.072 秒 → 0.041 秒(x0.57)。
18
+ 読む側は圧縮率によらず読めるので、前に作ったキャッシュもそのまま使え、形式の版(`FORMAT_VERSION`)も変えていない。
19
+
20
+ 読み込み(`~/src` で 1.8 秒)は、gzip の展開が 0.1 秒、残りが `Marshal.load` で、圧縮を変えても縮まない。
21
+
22
+ ## 見送り: スレッド数を増やす
23
+
24
+ `~/src` の走査は待ち時間が大半([00](00-baseline.md))なので、スレッドを既定の 8 より増やせば速くなるかを試した
25
+ (getattrlistbulk を入れた後の状態、`BENCH_JOBS`)。
26
+
27
+ | スレッド数 | no cache | cached |
28
+ | ---: | ---: | ---: |
29
+ | 8(既定) | 22.27 | 7.10 |
30
+ | 16 | 24.03 | 8.78 |
31
+ | 32 | 28.76 | 8.78 |
32
+
33
+ 増やすと遅くなる。`sys` の合計も増えており(キャッシュ無しで 49 秒 → 65 秒)、カーネルの中での取り合いが増えるだけだった。
34
+ 既定の「CPU の数(最大 8)」のままにする。
35
+
36
+ ## 見送り: 子フォルダーの `lstat` をまとめ読みに替える
37
+
38
+ [03](03-getattrlistbulk.md) の「見送ったもの」を参照。キャッシュありの走査では損になる場合のほうが多い。
39
+
40
+ ## 今後の候補(今回は手を付けていない)
41
+
42
+ 追記: このうち外部コマンドとキャッシュの読み込みは、二巡目([06](06-round2.md))で手を付けた。
43
+
44
+ - **外部コマンドの時間。** `-d` で起点を絞って 2 回目以降に動かすと、全体 21 秒のうち 17 秒ほどが
45
+ `brew cleanup -n`・`docker`・`tmutil` などの外部コマンド([05](05-outside-root.md))。
46
+ 互いに独立しているので、並行して動かせば縮む見込みがある。
47
+ - **キャッシュありの走査で残る `lstat`。** フォルダー 1 つにつき 1 回、更新時刻を確かめるために呼んでいる。
48
+ `~/src` ではこれが時間のほぼ全部(8 秒)。減らすには「どのフォルダーが変わったか」を走査せずに知る仕組み
49
+ (FSEvents など)が要り、作りが大きく変わる。
50
+ - **キャッシュの読み込み。** 100 万フォルダーで数秒。走査と並行して読む、起点の下の一部だけ読む、などの余地はあるが、
51
+ 走査に比べて小さいので後回し。
52
+ - **Ractor。** Fiddle が Ractor の中で使えるようになったら見直す([02](02-ractor.md))。
@@ -0,0 +1,56 @@
1
+ # 05. 起点の外の場所を、まとめて測ってキャッシュする
2
+
3
+ **結論: 採用した。** `-d` で起点を絞ったとき、2 回目以降の実行が 31 秒 → 21 秒になる。
4
+ 実装は `Report#measure_outside`([lib/reclaimable/report.rb](../../lib/reclaimable/report.rb))。
5
+
6
+ ## 何が遅かったか
7
+
8
+ `-d` で起点を絞ると、既知のキャッシュ置き場(`~/Library/Caches`・`~/.cache` など)、コンテナのデータ置き場、
9
+ gem 置き場は起点の外になる。これらは起点の走査では測れないので、`Report#measure` がその場で 1 つずつ走査していた。
10
+
11
+ - **キャッシュを使わない。** 起点の走査と違って、毎回全部を読み直していた。
12
+ - **同じ場所を何度も走査する。** 測る場所どうしが入れ子になっている(`~/.cache` と `~/.cache/huggingface`、
13
+ gem 置き場とその `doc`)と、中の場所を重ねて走査していた。gem の `doc` は 2 つの節から測るので、さらにもう 1 回。
14
+
15
+ ホーム全体を起点にする普通の使い方では、どれも起点の走査で測れているので、この問題は起きない。
16
+
17
+ ## 何を変えたか
18
+
19
+ - 起点の外で測る場所のうち、いちばん外側のものだけを走査する。中の場所のサイズは、その走査で一緒に記録する
20
+ (起点の走査の `watched` と同じ仕組み)。同じ場所を 2 度は走査しない。
21
+ - 走査結果を、起点と同じ形でキャッシュする(場所ごとに 1 ファイル)。次回は、変わっていないフォルダーの読み直しを省く。
22
+ `--fresh` と 7 日の期限も、起点のキャッシュと同じ扱い。
23
+ - 外側の走査がたどり着かなかった場所(シンボリックリンクの先など)は、前と同じく、そこだけ走査する。
24
+
25
+ ## 結果
26
+
27
+ フィクスチャーを起点にして、コマンド全体の時間を測った(レポートの最後の `Took N s`)。
28
+ 起点の外で測る場所は、この機械では 62 か所。
29
+
30
+ ```sh
31
+ LC_ALL=C ruby -Ilib bin/reclaimable -d tmp/benchmark/fixture --no-save
32
+ ```
33
+
34
+ | | 変更前 | 変更後 |
35
+ | --- | ---: | ---: |
36
+ | 1 回目(キャッシュ無し) | 31 秒 | 33 秒 |
37
+ | 2 回目 | 31 秒 | **21 秒** |
38
+ | 3 回目 | 31 秒 | **21 秒** |
39
+
40
+ - 2 回目以降は 10 秒縮む。起点の外の走査にかかる時間は、ログの時刻で見て 4 秒ほどになった。
41
+ 残りの 17 秒ほどは外部コマンド(`brew cleanup -n`・`docker`・`tmutil` など)で、走査とは別。
42
+ - 1 回目は 2 秒遅くなる。キャッシュを書くぶんが、入れ子の重複を省いたぶんを上回った。
43
+
44
+ ## 結果が変わっていないことの確認
45
+
46
+ 変更前と変更後のコードで続けて動かし、起点の外の場所が出る節(再生成できる場所・gem・コンテナ)の出力を比べて、
47
+ 1 回目(キャッシュ無し)・2 回目(キャッシュあり)とも一致した。
48
+
49
+ ## 気をつける点
50
+
51
+ - キャッシュのファイルが、起点の外で測る場所の数だけ増える(この機械で 62 個、合わせて 13MB)。
52
+ 置き場所は起点のキャッシュと同じ(`~/Library/Caches/reclaimable`)。
53
+ - ハードリンクは、1 回の走査の中で最初の 1 回だけ数える。前は場所ごとに別々に走査していたので、入れ子の場所の両方から
54
+ 同じファイルにハードリンクがあると、それぞれで数えていた。今は外側の走査で 1 回だけ数える(起点の中の場所と同じ扱い)。
55
+ - このシナリオはベンチマーク(`rake benchmark`)には入っていない。外部コマンドと、機械ごとに違うホームの中身に
56
+ 時間が左右されるため。確かめるときは上のコマンドを 2 回動かす。