Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 14738] ファイルの概要

このコミットは、Go言語の標準ライブラリである runtime/debug パッケージ内の Stack() 関数が非推奨であることを明示的にドキュメントに追加する変更です。これにより、開発者に対して、より新しい runtime パッケージの Stack() 関数を使用するよう促しています。

コミット

commit e49a183b760c6ac84d9fe8f63c26d92b5e162c01
Author: Russ Cox <rsc@golang.org>
Date:   Sat Dec 22 17:23:50 2012 -0500

    runtime/debug: document that Stack is deprecated
    
    Fixes #4070.
    
    R=golang-dev, bradfitz
    CC=golang-dev
    https://golang.org/cl/7004050

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/e49a183b760c6ac84d9fe8f63c26d92b5e162c01

元コミット内容

runtime/debug: document that Stack is deprecated

このコミットは、runtime/debug パッケージの Stack 関数が非推奨であることをドキュメントに追加するものです。これは、Go言語のIssue #4070 を解決するために行われました。

変更の背景

Go言語には、プログラムの実行スタック情報を取得するための関数が複数存在します。初期のバージョンでは runtime/debug.Stack() がその役割を担っていましたが、より低レベルで柔軟なスタックトレース情報を提供する runtime.Stack() 関数が導入されました。

runtime/debug.Stack() は、内部的に runtime.Stack() を呼び出しており、その結果を整形して返していました。しかし、runtime.Stack() が提供する機能がより強力で、かつ直接的に利用できるようになったため、runtime/debug.Stack() の存在意義が薄れ、冗長であると判断されました。

この変更は、開発者が最新かつ推奨されるAPIを使用するように誘導し、将来的なコードの保守性やパフォーマンスの向上に寄与することを目的としています。Issue #4070 は、この非推奨化を公式にドキュメント化する必要があるという認識から提起されたものです。

前提知識の解説

  • スタックトレース (Stack Trace): プログラムが実行中にエラーや特定のイベントが発生した際に、その時点での関数呼び出しの履歴（コールスタック）を一覧表示したものです。デバッグやエラーの原因特定に不可欠な情報となります。Go言語では、panic が発生した際などに自動的にスタックトレースが出力されます。
  • runtime パッケージ: Go言語のランタイムシステムと直接対話するための低レベルな機能を提供するパッケージです。ガベージコレクション、ゴルーチン管理、プロファイリング、スタック情報取得など、Goプログラムの実行環境に関するコアな機能が含まれます。
  • runtime/debug パッケージ: runtime パッケージの機能の一部を、より高レベルで使いやすい形で提供するパッケージです。主にデバッグ用途に特化しており、スタックトレースの整形出力や、メモリプロファイルの取得などが行えます。
  • 非推奨 (Deprecated): ある機能やAPIが、将来のバージョンで削除される可能性がある、またはより良い代替手段が存在するため、使用が推奨されない状態を指します。非推奨とされた機能は、既存のコードとの互換性を保つためにすぐには削除されませんが、新規のコードでは使用を避けるべきとされます。
  • Go Issue #4070: このコミットが解決したGo言語のIssueです。通常、GoのIssueトラッカー（GitHub Issuesまたは旧来のGo Bug Tracker）で管理され、機能追加、バグ修正、ドキュメント改善などの議論が行われます。このIssueでは、runtime/debug.Stack の非推奨化と、その代替として runtime.Stack を使用すべきであることのドキュメント化が議論されました。

技術的詳細

Go言語のスタックトレース取得には、主に以下の2つの関数が関連します。

  1. runtime/debug.Stack() []byte:

    • この関数は、現在のゴルーチンのスタックトレースを整形されたバイトスライスとして返します。
    • 人間が読みやすい形式で、ファイル名、行番号、関数名、引数などが含まれます。
    • 内部的には runtime.Stack() を呼び出し、その結果をさらに加工して出力します。
    • このコミットにより、この関数が非推奨であることが明記されました。

  2. runtime.Stack(buf []byte, all bool) int:

    • この関数は、現在のゴルーチン（all が false の場合）またはすべてのゴルーチン（all が true の場合）のスタックトレースを buf に書き込みます。
    • 返り値は書き込まれたバイト数です。
    • runtime/debug.Stack() と比較して、より低レベルで、整形されていない生のスタックフレーム情報を提供します。これにより、開発者は必要に応じて独自の整形や解析を行うことができます。
    • runtime/debug.Stack() の代替として推奨される関数です。

このコミットの技術的な変更は、runtime/debug.Stack() のドキュメントコメントに、非推奨である旨と、runtime.Stack() を代替として使用すべきである旨の記述を追加した点にあります。これにより、コンパイラやリンカの動作に直接的な影響はありませんが、開発者がIDEの補完機能やドキュメントを参照した際に、非推奨の警告や代替案が提示されるようになります。

コアとなるコードの変更箇所

変更は src/pkg/runtime/debug/stack.go ファイルの Stack() 関数のドキュメントコメントに限定されています。

--- a/src/pkg/runtime/debug/stack.go
+++ b/src/pkg/runtime/debug/stack.go
@@ -29,6 +29,8 @@ func PrintStack() {
 // For each routine, it includes the source line information and PC value,
 // then attempts to discover, for Go functions, the calling function or
 // method and the text of the line containing the invocation.
+//
+// This function is deprecated. Use package runtime's Stack instead.
 func Stack() []byte {
 	return stack()
 }

コアとなるコードの解説

追加された行は以下の通りです。

//
// This function is deprecated. Use package runtime's Stack instead.

これは、Go言語のドキュメンテーションツール（go doc コマンドや godoc サーバーなど）が解析するコメントであり、Stack() 関数の説明に追記されます。

  • //: Go言語における単一行コメントの開始。
  • This function is deprecated.: この関数が非推奨であることを明確に示しています。
  • Use package runtime's Stack instead.: 代替として runtime パッケージの Stack 関数を使用すべきであることを指示しています。

このコメントの追加により、go doc runtime/debug Stack のようなコマンドを実行した際に、この非推奨の警告が表示されるようになります。これは、Go言語のAPI設計における重要なプラクティスであり、APIの進化と改善を開発者に透過的に伝えるための仕組みです。

関連リンク

参考にした情報源リンク