github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/runtime/traceback.go

// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package runtime

import (
	"github.com/shogo82148/std/unsafe"
)

// SetCgoTracebackは、Cコードからトレースバック情報を収集し、そのトレースバック情報をシンボル情報に変換するために使用する3つのC関数を記録します。
// これらは、cgoを使用するプログラムのスタックトレースを印刷するときに使用されます。
//
// トレースバックとコンテキスト関数は、シグナルハンドラから呼び出すことができるため、
// 非同期シグナルセーフ関数のみを使用する必要があります。
// シンボライザ関数は、プログラムがクラッシュしている間に呼び出される可能性があるため、
// メモリの使用に注意する必要があります。これらの関数のいずれも、Goにコールバックすることはできません。
//
// context関数は、構造体へのポインタを単一の引数として呼び出されます。
//
//	struct {
//		Context uintptr
//	}
//
// In C syntax, this struct will be
//
//	struct {
//		uintptr_t Context;
//	};
//
// Contextフィールドが0の場合、context関数は現在のトレースバックコンテキストを記録するために呼び出されます。
// おそらくスタックポインタとPCなど、後でスタックトレースを生成するために必要な現在の実行ポイントに関する情報をContextフィールドに記録する必要があります。
// この場合、context関数はCコードから呼び出されます。
//
// Contextフィールドが0でない場合、それは以前のcontext関数の呼び出しで返された値です。
// この場合、GoコードがCコードの呼び出し元に戻るとき、つまりコンテキストが不要になったときに呼び出されます。
// これにより、context関数は関連するリソースを解放できます。
//
// context関数が呼び出されるたびに完全なスタックトレースを記録し、
// traceback関数でそれを単にコピーすることが正しいと言えますが、
// 典型的なプログラムでは、context関数はそのコンテキストのためにトレースバックを記録することなく多数の呼び出しが行われます。
// context関数の呼び出しで完全なスタックトレースを記録することは、効率的ではない可能性があります。
//
// traceback関数は、構造体へのポインタを単一の引数として呼び出されます。
//
//	struct {
//		Context    uintptr
//		SigContext uintptr
//		Buf        *uintptr
//		Max        uintptr
//	}
//
// In C syntax, this struct will be
//
//	struct {
//		uintptr_t  Context;
//		uintptr_t  SigContext;
//		uintptr_t* Buf;
//		uintptr_t  Max;
//	};
//
// Contextフィールドが0の場合、現在のプログラム実行ポイントからトレースバックを収集するために使用されます。
// この場合、traceback関数はCコードから呼び出されます。
//
// それ以外の場合、Contextは以前のcontext関数の呼び出しで返された値です。
// traceback関数は、その保存されたプログラム実行ポイントからスタックトレースを収集する必要があります。
// traceback関数は、コンテキストが有効で変更されていないことがわかっている場合にのみ、
// コンテキストを記録した実行スレッド以外の実行スレッドから呼び出すことができます。
// traceback関数は、同じスレッドでコンテキストを記録した深い呼び出しスタックでも呼び出すことができます。
// traceback関数は、同じContext値で複数回呼び出されることがあります。
// 特定のコンテキスト値に対して最初に呼び出された場合、可能であれば結果をキャッシュするのが通常適切です。
//
// Unixシステムのシグナルハンドラからtraceback関数が呼び出された場合、
// SigContextはシグナルハンドラに渡されたシグナルコンテキスト引数です（uintptr_tにキャストされたCのucontext_t*）。
// これを使用して、シグナルが発生したポイントからトレースを開始できます。
// traceback関数がシグナルハンドラから呼び出されていない場合、SigContextはゼロになります。
//
// Bufはトレースバック情報を格納する場所です。
// Buf[0]が呼び出し元のPCであり、Buf[1]がその関数の呼び出し元のPCであるような、PC値である必要があります。
// Maxは格納するエントリの最大数です。
// 関数は、スタックのトップを示すためにゼロを格納する必要があります。
// または、呼び出し元が別のスタック、おそらくGoスタックにあることを示します。
//
// runtime.Callersとは異なり、返されるPC値は、
// シンボライザ関数に渡された場合、呼び出し命令のファイル/行を返す必要があります。
// 追加の減算は必要ありません。また、適切ではありません。
//
// すべてのプラットフォームで、トレースバック関数は、GoからCへの呼び出しとCからGoへの呼び出しの間でスタックトレースを要求する場合に呼び出されます。
// linux/amd64、linux/ppc64le、linux/arm64、およびfreebsd/amd64では、トレースバック関数は、cgo呼び出しを実行しているスレッドがシグナルを受信した場合にも呼び出されます。
// トレースバック関数は、いつ呼び出されるかについての仮定をするべきではありません。将来のGoのバージョンでは、追加の呼び出しが行われる可能性があります。
//
// シンボライザ関数は、構造体へのポインタを単一の引数として呼び出されます。
//
//	struct {
//		PC      uintptr // 情報を取得するプログラムカウンタ
//		File    *byte   // ファイル名（NULで終わる）
//		Lineno  uintptr // 行番号
//		Func    *byte   // 関数名（NULで終わる）
//		Entry   uintptr // 関数のエントリポイント
//		More    uintptr // このPCに対してさらに情報がある場合は非ゼロに設定します
//		Data    uintptr // ランタイムによって使用されない、関数で使用可能なデータ
//	}
//
// C言語の構文では、この構造体は次のようになります。
//
//	struct {
//		uintptr_t PC;
//		char*     File;
//		uintptr_t Lineno;
//		char*     Func;
//		uintptr_t Entry;
//		uintptr_t More;
//		uintptr_t Data;
//	};
//
// PCフィールドは、traceback関数の呼び出しで返される値です。
//
// トレースバック関数が特定のトレースバックに対して最初に呼び出された場合、
// PC以外のすべてのフィールドは0になります。
// 情報が利用できない場合は、フィールドを0/nilに設定して、他のフィールドを埋める必要があります。
// Dataフィールドは、呼び出し間で有用な情報を格納するために使用できます。
// Moreフィールドは、このPCに対してさらに情報がある場合は非ゼロに設定します。
// Moreが非ゼロに設定されている場合、同じPCで再度呼び出され、異なる情報を返すことができます（これはインライン関数で使用するために意図されています）。
// Moreがゼロの場合、次のPC値でトレースバック関数が呼び出されます。
// トレースバックが完了すると、PCがゼロに設定された状態で関数が1回呼び出されます。
// これは、情報を解放するために使用できます。
// 各呼び出しでは、Moreフィールドがゼロである場合を除き、構造体のフィールドが呼び出し前と同じ値に設定されたままになります。
// 関数は、呼び出し間で構造体ポインタのコピーを保持してはいけません。
//
// SetCgoTracebackを呼び出すとき、version引数は関数が受け取る構造体のバージョン番号です。
// 現在、これは0でなければなりません。
//
// シンボライザ関数がnilの場合、トレースバック関数の結果は数値として表示されます。
// トレースバック関数がnilの場合、シンボライザ関数は呼び出されません。
// コンテキスト関数がnilの場合、トレースバック関数はコンテキストフィールドが0に設定された状態でのみ呼び出されます。
// コンテキスト関数がnilの場合、GoからCへの呼び出しでは、C部分の呼び出しスタックのトレースバックは表示されません。
//
// SetCgoTracebackは、理想的にはinit関数から1回だけ呼び出す必要があります。
func SetCgoTraceback(version int, traceback, context, symbolizer unsafe.Pointer)