[P7] instruction/ マイクロベンチの扱いを決める

[thawk105]

親イシュー: #28 / 旧 #36 をコンテキストごとに分割したうちの 1 つ。

概要

instruction/ は独自 Makefile ベースのマイクロベンチ・各種テスト群（fetch_add.cc, xoroshiro.cc, zipf_dist_test.cc, membench.cc など）。CMake ビルドに接続されておらず、新規参加者の混乱要因になっている。

重要（リポジトリオーナーより）: instruction/ は「特定の命令・操作のコストを測定・理解する」ために意図を持って作られたマイクロベンチ群。捨てるべきゴミではない。本イシューは「撤去ありき」ではなく (1) どこにあるべきか (2) トップレベル CMake に載せる価値があるか を決めるのがゴール。include/ 共通部品の正当性ユニットテストは別イシュー #92 のスコープであり、instruction/ は「正しさ」ではなく「コスト・性能」を測るもので性質が違う。

現状（2026-05-14）

• instruction/ は存在し、Makefile・include/・script/ と多数の .cc/.c を含む。
• トップレベル / cc/ の CMake から参照されていない（再確認済み: grep -rn instruction で CMake/GHA 共にヒット 0）。

調査結果（2026-05-15）

1. 中身の棚卸し

ファイル	何を測る/確かめるか	状態
fetch_add.cc	N スレッドが共有 std::atomic<uint64_t> に fetch_add し続けたときのスループット（atomic RMW のコンテンション特性）。include/atomic_wrapper.hh・cache_line_size.hh を使用	現役の意図、要補修
xoroshiro.cc	Xoroshiro128Plus 乱数 1 回あたりの clock 数（rdtscp 計測）。include/random.hh を使用	現役の意図、要補修
zipf_dist_test.cc	FastZipf の出力分布が skew どおりか（ヒストグラム出力）。include/zipf.hh・random.hh を使用	現役の意図、要補修
membench.cc	メモリ帯域・レイテンシのマイクロベンチ。seq/rnd × read/write の 4 ワークロードを bulk_size 別に測る。AlignedMemory・_mm_clwb 等。include/random.hh・cpu.hh・util.hh を使用	一番作り込まれている。現役の意図、要補修
rdtscBench.cc	rdtsc() と rdtscp() の 1 回あたり clock 数。include/tsc.hh を使用	現役の意図、ほぼそのまま動く
cache-test.cc	キャッシュ/コア間の挙動を見る実験。CPU 番号（1 と 28）をハードコードした 2 スレッド固定。include/common.hh 経由で int64byte.hh を使用	陳腐化（実験コード、ハードコード多数、ループ本体がコメントアウト）
pow_test.cc	std::pow(2, x) の引数別の実行時間	小物。現役の意図、ほぼそのまま動く
mcslock_with_timeout.c	timeout 付き MCS lock（Scott の論文実装）のリファレンス写経。main 無し・ビルド対象外（Makefile に登録されていない）。gethrtime/swap/compare_and_swap など未定義シンボル前提	陳腐化（コード片、ビルド不能）
include/common.hh	fetch_add.cc/cache-test.cc 用のグローバル変数定義ヘッダ	補助
script/*.sh, test_*.sh	各ベンチを thread 数を振って回し .dat に集計するドライバ。chris41/dbs11 という特定ホスト名・perf/numactl 前提	陳腐化（外部環境依存）
masstree_simple_test/unit-mt.cc	Masstree の put/get/insert スループット測定（コスト測定寄り）	陳腐化、要大補修
masstree_simple_test/unit-mt2.cc	Masstree に独自 record 型を載せる API 確認用の小さな実験	陳腐化、要大補修
masstree_simple_test/GNUmakefile, script/*.sh	上記のビルド/実行ドライバ	陳腐化
README.md	4 行の見出しのみ。実質ドキュメントなし	要刷新

2. 現状の独立性

• Makefile は g++ -march=native -std=c++17、親の ../common/Makefile を include し、../common/util.o をリンクする。chris41.omni.hpcc.jp / dbs11 という特定ホスト名で TBB のパスを切り替える分岐が残っている（外部環境前提）。
• 依存は include/ ヘッダ群と common/util.cc（isReady/waitForReady/sleepMs/chkClkSpan 等）。cc/ のプロトコル実装には依存していない。→ 本体ビルドからは完全に切り離された小物群で、CMake 統合のブロッカーは無い。
• masstree_simple_test/ のみ別格で、third_party/masstree（旧 ../../masstree）の config.h と静的ライブラリ、-lnuma を要求する。

3. include/ 共通部品との関係（重複ではなく「使用」）

instruction/ 版は本体コードの別実装ではなく、本体の include/ をそのまま使ってコストを測っている:

• xoroshiro.cc / zipf_dist_test.cc / membench.cc → include/random.hh・include/zipf.hh を直接 include
• fetch_add.cc → include/atomic_wrapper.hh・include/cache_line_size.hh を直接 include
• rdtscBench.cc → include/tsc.hh を直接 include

つまり #92（正当性ユニットテスト）が「include/ 部品が正しく動くか」を保証するのに対し、instruction/ は「その部品の操作がどれくらい速いか/どんなコスト特性か」を測る。両者は同じ部品を対象にするが目的が直交しており、統合せず別ターゲット群として共存させるのが自然。

ただし API が古く、現状のままではビルドが通らない:

• masstree_simple_test/*.cc は include/atomic_wrapper.hpp 等 .hpp を include。現リポは .hh（要修正）。
• cache-test.cc の worker は CPU 番号 1/28 をハードコード。
• Makefile のホスト名分岐（chris41/dbs11）は除去対象。
• 軽微な warning（旧スタイル catch(std::bad_alloc) 等）。Werror 環境では落ちる可能性。

4. git 履歴

• 初出: 2018-08-29（1bef76a add Instruction）。
• 最終更新: 2020-06-13（785d6ba format code.）。それ以降 約 6 年間ノータッチ。
• 直近のコミットは中身の変更ではなく一括フォーマット。実質 2018〜2019 に書かれたまま放置。
• → 「現役で回されている形跡」は無い。ただし測ろうとした対象（atomic RMW・乱数・zipf・rdtsc・メモリ帯域のコスト）は今でも有効な関心事であり、内容が陳腐化したわけではない。コードが bit-rot しているだけ。

5. 置き場所・CMake 統合方針の評価

検討した選択肢:

1. 全部そのままトップレベル CMake 化 — 却下。cache-test.cc・mcslock_with_timeout.c・各 script/・masstree_simple_test/ は陳腐化/ビルド不能で、補修コストに見合わない。CI を無条件に重くする。
2. オプトインで CMake 化 + リネーム移動 + ファイル単位の仕分け（推奨） — 後述。
3. legacy/ に丸ごと退避 — 却下。オーナーの「意図を持ったマイクロベンチ」という位置づけと矛盾する。少なくとも軽量な計測系（rdtscBench/pow_test/xoroshiro/fetch_add/zipf_dist_test/membench）は生かす価値がある。

CMake に載せる価値判断:

• ビルド時間: 対象は単一 .cc → 1 実行ファイルの小物が中心。ccbench_common と include/ に既にリンクできる。デフォルト OFF のオプトインにすれば CI 負荷はゼロ。開発者が atomic/乱数/メモリのコストを測りたいときだけ -DCCBENCH_BUILD_MICROBENCH=ON で有効化。
• 回す頻度: 日常ビルドでは不要。プロトコルのパラメータを疑うとき・新ハード評価時にたまに回す類。→ オプトインが最適。
• 名前: instruction/ は用途（命令・操作のコスト測定）を表していない。microbench/ にリネームすると意図が一目で分かる。

推奨

instruction/ を microbench/ にリネームし、ファイル単位で仕分けたうえで、-DCCBENCH_BUILD_MICROBENCH=ON（デフォルト OFF）のオプトインでトップレベル CMake に接続する。 ヘルパ ccbench_add_microbench(<name> SOURCES ...) を cmake/ に新設し、ccbench_common と include/ にリンクさせる。

ファイル単位の扱い:

対象	扱い	理由
rdtscBench.cc, pow_test.cc	microbench/ で CMake 化（補修ほぼ不要）	ほぼそのまま動く
xoroshiro.cc, fetch_add.cc, zipf_dist_test.cc, membench.cc	microbench/ で CMake 化（軽微補修: warning 潰し、ホスト依存除去）	測定対象が今も有効、include/ を直接使用
include/common.hh	microbench/include/ に維持（fetch_add が依存）	補助ヘッダ
cache-test.cc	microbench/legacy/ に隔離（CMake 非対象）	ハードコード・本体コメントアウトで計測になっていない。直す価値が出たら復活
mcslock_with_timeout.c	microbench/legacy/ に隔離（CMake 非対象）	main 無し・ビルド不能の写経コード片
masstree_simple_test/	microbench/legacy/ に隔離（CMake 非対象）	.hpp include 等で大補修が必要。別途やる気が出たら独立イシューで
script/*.sh, test_*.sh	削除 or legacy/ 隔離	chris41/dbs11 等の外部環境依存。CMake 化後は不要
README.md	刷新	各ベンチが何を測るか・-DCCBENCH_BUILD_MICROBENCH=ON の使い方を記載

やること

• instruction/ → microbench/ にリネーム移動する
• cmake/MicrobenchHelpers.cmake に ccbench_add_microbench(<name> SOURCES ...) を新設（ccbench_common + include/ にリンク、set_compile_options 適用）
• トップレベル CMakeLists.txt に option(CCBENCH_BUILD_MICROBENCH "build instruction-cost microbenchmarks" OFF) を追加し、ON のとき add_subdirectory(microbench)
• rdtscBench / pow_test / xoroshiro / fetch_add / zipf_dist_test / membench を CMake ターゲット化（軽微補修: warning 除去、-march=native とホスト名分岐の除去）
• cache-test.cc / mcslock_with_timeout.c / masstree_simple_test/ / 各 script/ を microbench/legacy/（CMake 非対象）へ隔離、または script/ 系は削除
• 旧 instruction/Makefile・common/Makefile の INST_SRCS* 行を撤去（CMake 化に伴い不要）
• microbench/README.md を刷新（各ベンチが測る対象・オプトインビルド手順）
• docs/ 側（build_ja.md / build_en.md あたり）に -DCCBENCH_BUILD_MICROBENCH=ON を 1 行追記
• 判断と理由を記録する（本セクション）

完了条件

• instruction/ が microbench/ にリネームされ、トップレベル CMake から -DCCBENCH_BUILD_MICROBENCH=ON で到達可能になっていること
• 生かすベンチ（rdtscBench/pow_test/xoroshiro/fetch_add/zipf_dist_test/membench）が CI と同じ GCC 13 でビルドできること
• 陳腐化したもの（cache-test/mcslock_with_timeout/masstree_simple_test/script）が legacy/ 隔離または削除で仕分けされていること
• デフォルトビルド（オプション OFF）の CI 時間が増えていないこと