Thread: native_thread_id・thread_variables・each_caller_location を追加

[Watson1978]

概要

Ruby 4.0 に存在するのにリファレンスに項目が無い [c:Thread] のメソッド 3 個を追加しました。

• Thread#thread_variables — スレッドローカル変数名の一覧
• Thread#native_thread_id — ネイティブスレッドの ID
• Thread.each_caller_location — 実行スタックを配列を作らず順に渡す

登場バージョン

実機で確認しました。

2.7.8:  thread_variables のみ
3.0.7:  thread_variables のみ
3.1.6:  thread_variables, native_thread_id
3.4.10: thread_variables, native_thread_id, each_caller_location
4.0.6:  同上

• thread_variables … 3.0 以前から
• native_thread_id … 3.1 から
• each_caller_location … 3.4 から

既存の例の修正を含みます

thread_variables は独立した項目が無い一方、既に [m:Thread#thread_variable_set] の
例の中で p thr.thread_variables として使われていました。その出力が rdoc 由来で
[:dog, :cat] になっていましたが、実機は挿入順の [:cat, :dog] を返します
(2.7〜4.0 で確認)。

$ ruby -e 'thr = Thread.new { Thread.current.thread_variable_set(:cat, "meow"); Thread.current.thread_variable_set("dog", "woof") }; thr.join; p thr.thread_variables'
[:cat, :dog]

新設した項目と食い違わないよう、既存の例も [:cat, :dog] に直し、SEE に
thread_variables を足しています。

記述の根拠

• native_thread_id の返り値は OS 依存で、その他のプラットフォームでは
  [c:NotImplementedError]、ネイティブスレッドと未結合／切り離し済みなら nil に
  なる旨を記載しました。死んだスレッドで nil が返ることは実機で確認済みです。
• each_caller_location は [m:Kernel#caller_locations] と同じ引数 (start/length、
  range) を取れることを、CRuby の vm_backtrace.c (ec_backtrace_range) で確認して
  シグネチャに反映しました。

検証

• サンプルコードは対象の全バージョンで実行して出力を確認しました。
• rake check_blank_lines / check_indent_in_samplecode / check_single_space_indent
• bitclust update --markdowntree=manual/api を 3.0 / 3.1 / 3.3 / 3.4 / 4.0 で実行し、
  エラーが出ないこと、登録されるメソッドが 1 / 2 / 2 / 3 / 3 件と追加バージョン
  どおりになることを確認しました。

🤖 Generated with Claude Code

[znz]

レビューしました。thread_variables の順序修正・native_thread_id は正確でした。2 点、修正のご相談があります。

検証できた点(実機 3.0.7 / 3.1.7 / 3.3.12 / 3.4.10 / 4.0.6)

• thread_variables の順序: thread_variable_set(:cat,...) → set("dog",...) 後の thread_variables は全版で [:cat, :dog](挿入順) でした。旧記載の [:dog, :cat] を [:cat, :dog] に直す修正は正しいです。SEE の追加も適切です。
• native_thread_id(#@SInCE 3.1): 3.0 で未定義・3.1 以降で存在、Thread.current.native_thread_id.class == Integer(Linux は gettid)、Thread.new{} を join した後は nil、を確認。NEWS-3.1(Feature #17853)とも一致。返り値 Integer | nil も記載どおり。

相談1: each_caller_location の #@since 3.4 は版がずれています

実測すると、引数なし(ブロックのみ)の Thread.each_caller_location は Ruby 3.2 から存在します(NEWS-3.2 の Feature #16663)。3.4 で追加されたのは start / length / range の引数を取れるようになったことだけです(Feature #20335)。

3.1.7: each_caller_location なし
3.2.11 / 3.3.12: 無引数(ブロックのみ)は動く / 引数付きは ArgumentError
3.4.10: 無引数も引数付きも動く

現状はセクション全体を #@since 3.4 で囲んでいるため、3.2 / 3.3 のページからメソッドごと消えてしまいます。メソッド自体を #@since 3.2 にし、引数付きシグネチャと引数の説明だけを #@since 3.4 で分岐するのが正確です(Fiber.new の引数追加の分岐と同じ形)。イメージ:

#@since 3.2
#@since 3.4
### def each_caller_location(start = 1, length = nil) {|location| ... } -> nil
### def each_caller_location(range) {|location| ... } -> nil
#@else
### def each_caller_location {|location| ... } -> nil
#@end

...本文...
#@since 3.4
引数の意味は [m:Kernel.#caller_locations] と同じで、渡すフレームの範囲を指定できます。
#@end
...
#@end

相談2: [m:Kernel#caller_locations] はリンク切れになります

caller_locations は functions.md で module_function として定義されている(= Kernel.#caller_locations)ため、参照は [m:Kernel.#caller_locations] が正しいです。[m:Kernel#caller_locations](3 箇所)は /method/Kernel/i/caller_locations を指し、本番で 404 になります(実際に該当 URL が 404 であることも確認しました)。.# 記法に直してください(4.0 では Kernel?.caller_locations と表示されます)。

その他(例の挙動・参照 Thread::Backtrace::Location / NotImplementedError)は問題ありませんでした。

🤖 Generated with Claude Code

[Watson1978]

レビューありがとうございます。2 点とも対応しました。

相談1: each_caller_location の版

ご指摘のとおりでした。実機で確認した結果です。

3.1.6:  each_caller_location なし
3.2.11: 無引数:OK  引数(start,length):ArgumentError  引数(range):ArgumentError
3.3.12: 無引数:OK  引数(start,length):ArgumentError  引数(range):ArgumentError
3.4.10: 無引数:OK  引数(start,length):OK             引数(range):OK
4.0.6:  無引数:OK  引数(start,length):OK             引数(range):OK

ご提案の形にしました。メソッド自体を #@since 3.2 にし、引数付きシグネチャと
引数の説明だけを #@since 3.4 の入れ子にしています。

あわせて、シグネチャに引数があるのに - **param** が無かったので、
start / length / range の 3 つを [m:Kernel?.caller_locations] の記述に
揃えて追加しました。

版ごとに DB を生成して、出し分けを確認しています。

版	bitclust lookup --method='Thread.each_caller_location'
3.1	no such method
3.3	### def each_caller_location {|location| ... } -> nil
3.4 / 4.0	(start = 1, length = nil) と (range) の 2 本

相談2: Kernel#caller_locations

3 箇所とも直しました。1 点だけ、記法は .# ではなく ?. にしています。

docs/ReferenceManualFormatDigest.md に「モジュール関数 [m:Kernel?.open]
(旧記法の「.#」は「?.」に変わりました)」とあり、manual/api 配下の実使用も
?. が 724 箇所に対して .# が 3 箇所なので、移行後の記法に揃えました。
.# のほうが良ければ直します。

参考(本 PR 対象外): 同じファイルに既存のリンク切れが 2 件あります

今回の指摘を受けて、変更ファイルの [m:...] / [c:...] を DB と機械的に
突き合わせたところ、Thread.md に以前からあるものが 2 件見つかりました。

• [c:Thread#raise] (1 箇所) -- メソッドを c: で参照しており、
  [m:Thread#raise] が正しい記法です。
• [c:TimeoutError] (2 箇所) -- TimeoutError は 3.1〜4.0 のどれにも存在せず
  (defined?(TimeoutError) が nil)、実在するのは Timeout::Error だけです。
  マニュアルにも [c:Timeout::Error] しかありません。

同じファイルなので並行 PR にはしづらく、ご希望なら本 PR に含めて直します。

🤖 Generated with Claude Code

[znz]

2 点とも対応ありがとうございます。確認しました。

• thread_variables の順序: 実機で thread_variable_set(:cat, ...) → set("dog", ...) 後の thread_variables が [:cat, :dog](挿入順)になることを確認しました。新設の thread_variables エントリ・既存の thread_variable_set の例とも [:cat, :dog] に揃っています。
• each_caller_location の版: メソッド自体は 3.2 追加(doc/news/3_2_0.md の feature 16663)で #@since 3.2、(start, length) / (range) 引数版が #@since 3.4 にネストされている構成が実機の挙動と一致しています。3.2 / 3.4 で statichtml をビルドし、3.2 ページは引数無しシグネチャのみ、3.4 ページは両引数版が出ること・compileerror 0 を確認しました。

[m:Kernel#caller_locations] → [m:Kernel?.caller_locations] の module function 記法修正も解決を確認済みです。マージ可と考えます。