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

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

このコミットは、Go言語のソースコードベースにおけるドキュメンテーションの更新を目的としています。具体的には、runtime/cgoパッケージに関する古くなったコメントを修正し、ファイルパスの参照を現在の正しい構造に合わせる変更が行われています。これは、コードの可読性と保守性を向上させるための重要な作業であり、特にGoランタイムとCgoの連携部分における正確な情報提供に貢献しています。

コミット

commit fec7aa952f37ad5aa2cfdfe44bdc0e7a02fe8783
Author: Shenghou Ma <minux.ma@gmail.com>
Date:   Thu Jan 19 17:13:33 2012 -0500

    doc: update out-of-date comments about runtime/cgo
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5532100

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

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

元コミット内容

このコミットの元の内容は、「doc: update out-of-date comments about runtime/cgo」であり、runtime/cgoに関する古くなったコメントを更新することを示しています。これは、主にファイルパスの参照を修正し、コードベースの進化に合わせてドキュメンテーションを最新の状態に保つためのものです。

変更の背景

Go言語の初期開発段階では、コードベースの構造やコンポーネントの名称が頻繁に変更されることがありました。このコミットが行われた2012年1月という時期は、Go言語がまだ活発に開発され、安定版リリース（Go 1）に向けて準備が進められていた時期にあたります。

変更の具体的な背景としては、GoのCgo関連のコードが、以前はlibcgoという独立したディレクトリや概念で扱われていたものが、src/pkg/runtime/cgoというGoランタイムの一部として統合・再編成されたことが挙げられます。この再編成に伴い、Goのリンカ（6l, 8l）やランタイムの内部コード、ビルドスクリプトなどに散在していた古いコメント内のファイルパス参照が、新しい構造に合わせて更新される必要がありました。

古くなったコメントは、新規開発者や既存の貢献者がコードを理解する上で混乱を招く可能性があり、また、コードの意図や依存関係を誤解させる原因にもなり得ます。そのため、このようなドキュメンテーションの正確性を保つことは、大規模なオープンソースプロジェクトにおいて非常に重要です。このコミットは、Goプロジェクトのコード品質と保守性を維持するための継続的な取り組みの一環として行われました。

前提知識の解説

このコミットの変更内容を深く理解するためには、以下のGo言語およびシステムプログラミングに関する前提知識が必要です。

  1. Go言語のランタイム (runtime): Goプログラムは、Goランタイムと呼ばれる非常に軽量な実行環境上で動作します。Goランタイムは、ガベージコレクション、ゴルーチン（軽量スレッド）のスケジューリング、メモリ管理、システムコールインターフェースなど、Goプログラムの実行に必要な低レベルな機能を提供します。Goランタイムのコードの多くはGoで書かれていますが、OSとのインタラクションやパフォーマンスが重要な部分はC言語やアセンブリ言語で書かれています。

  2. Cgo: Cgoは、GoプログラムからC言語の関数を呼び出したり、C言語のコードからGoの関数を呼び出したりするためのGoの機能です。これにより、既存のCライブラリをGoプロジェクトで再利用したり、Goでは実装が難しい低レベルな操作（例: OS固有のAPI呼び出し）を行ったりすることが可能になります。Cgoは、GoとCの間の呼び出し規約の変換、スタックの管理、スレッドローカルストレージ（TLS）の連携など、複雑な処理を内部で行います。

  3. リンカ (Linker): リンカは、コンパイラによって生成された複数のオブジェクトファイル（.oファイル）やライブラリを結合し、最終的な実行可能ファイルや共有ライブラリを生成するツールです。Goのビルドシステムでは、6l（amd64アーキテクチャ用）や8l（386アーキテクチャ用）といった独自のリンカが使用されます。これらのリンカは、Goの特殊な実行形式やランタイムの要件に合わせて設計されています。リンカは、プログラム内のシンボル（関数名や変数名）を解決し、適切なメモリアドレスに配置する役割も担います。

  4. TLS (Thread Local Storage): TLSは、マルチスレッド環境において、各スレッドがそれぞれ独立したデータを持つためのメカニズムです。通常、グローバル変数や静的変数はプロセス内のすべてのスレッドで共有されますが、TLSを使用すると、同じ変数名であっても各スレッドが独自のインスタンスを持つことができます。Goのランタイムでは、ゴルーチン（Goの軽量スレッド）のコンテキスト情報（例: 現在実行中のゴルーチンへのポインタg、現在のOSスレッドへのポインタm）を効率的にアクセスするために、TLSが利用されることがあります。特にCgoを介してCコードと連携する場合、OSスレッドのTLSとGoランタイムのTLSの間の連携が重要になります。

  5. アセンブリ言語 (.sファイル): Goランタイムの特定の機能、特にOSとの低レベルなインタラクション、コンテキストスイッチ、アトミック操作、または極めて高いパフォーマンスが要求される部分では、Go言語ではなく直接アセンブリ言語でコードが書かれています。これらのファイルは通常.s拡張子を持ち、特定のCPUアーキテクチャ（例: amd64, 386）とOS（例: darwin, linux）に特化しています。

  6. mkasmh.sh: Goのビルドプロセスで使用されるシェルスクリプトの一つで、アセンブリ言語のソースファイルからC言語のヘッダファイルを生成する役割を担います。これにより、アセンブリコードで定義された定数やオフセットなどを、C言語やGo言語のコードから参照できるようになります。

  7. runtime.h: GoランタイムのC言語部分で利用されるヘッダファイルです。Goランタイムの内部構造体（例: G (ゴルーチン), M (OSスレッド), P (プロセッサ)）の定義や、ランタイム内部で使用される定数などが含まれています。

技術的詳細

このコミットの技術的詳細は、Goのビルドシステム、ランタイム、およびCgoの内部構造におけるパス参照の正確性に関わっています。

Goのソースコードは、srcディレクトリ以下に整理されており、各パッケージやツールが特定のパスに配置されています。初期のGo開発では、Cgoに関連するC言語のコードがlibcgoという独立したディレクトリに存在していた時期がありました。しかし、Goランタイムの進化に伴い、Cgoの機能がGoランタイムのコア部分に密接に統合され、そのコードがsrc/pkg/runtime/cgoというパスに移動・再編成されました。

この変更は、Goのリンカ（6l, 8l）がTLSオフセットなどのOS固有の定数を参照する際のコメント、make.bashスクリプトがビルドするパッケージのリスト、runtime/cgo内のCソースコードがリンカやアセンブリファイル内の関連コードを参照する際のコメント、mkasmh.shスクリプトがアセンブリコード内のTLSオフセットに関するコメント、そしてruntime.h内のランタイム構造体に関するコメントに影響を与えました。

具体的には、以下のようなパスの変更が行われています。

  • ../../libcgo/ から ../../pkg/runtime/cgo/ または cgo/ へ: これは、CgoのC言語部分がlibcgoからsrc/pkg/runtime/cgoに移動したことを反映しています。リンカのソースコード（src/cmd/6l/obj.c, src/cmd/8l/obj.c）やruntime/cgo内のCソースコード（src/pkg/runtime/cgo/gcc_darwin_386.c, src/pkg/runtime/cgo/gcc_darwin_amd64.c）のコメントで、TLSオフセットなどの詳細が説明されているファイルのパスが更新されました。

  • ../../pkg/runtime/darwin/386/sys.s から ../sys_darwin_386.s へ: これは、Goランタイムのアセンブリファイル（sys.s）のパスが変更されたことを示唆しています。src/pkg/runtime/cgo/gcc_darwin_386.cやsrc/pkg/runtime/sys_darwin_amd64.sのコメントで、TLSオフセットの計算や利用に関する参照が更新されています。

  • libcgo から runtime/cgo へ: src/make.bashスクリプト内のコメントで、ビルドされるパッケージのリストにおいて、libcgoという古い名称がruntime/cgoという新しい名称に更新されました。これは、ビルドシステムが認識するコンポーネント名の変更を反映しています。

  • libcgo から runtime/cgo へ (runtime.h内): src/pkg/runtime/runtime.h内のG（ゴルーチン）構造体のstackguardとstackbaseフィールドに関するコメントで、これらのフィールドがリンカ、libmach、そしてlibcgoによっても認識されているという記述が、runtime/cgoに更新されました。これは、Goランタイムのスタック管理とCgoの連携における責任範囲の変更、または名称の統一を意味します。

これらの変更は、単なるコメントの修正に留まらず、Goの内部コンポーネント間の依存関係や役割分担がどのように進化してきたかを示唆しています。正確なコメントは、将来のコード変更やデバッグ作業において、開発者が正しいファイルやコンポーネントを参照するための重要な手がかりとなります。

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

このコミットでは、主にコメント内のファイルパス参照が変更されています。以下に主要な変更箇所を抜粋して示します。

1. src/cmd/6l/obj.c Goのamd64リンカのソースコード。TLSオフセットに関するコメントのパスを修正。

--- a/src/cmd/6l/obj.c
+++ b/src/cmd/6l/obj.c
@@ -190,7 +190,7 @@ main(int argc, char *argv[])
  	case Hdarwin:	/* apple MACH */
  	\t/*
  	\t * OS X system constant - offset from 0(GS) to our TLS.
- \t\t * Explained in ../../libcgo/darwin_amd64.c.
+ \t\t * Explained in ../../pkg/runtime/cgo/gcc_darwin_amd64.c.
  	\t */
  	\ttlsoffset = 0x8a0;
  	\tmachoinit();
@@ -209,8 +209,8 @@ main(int argc, char *argv[])
  	\t/*
  	\t * ELF uses TLS offset negative from FS.
  	\t * Translate 0(FS) and 8(FS) into -16(FS) and -8(FS).
- \t\t * Also known to ../../pkg/runtime/linux/amd64/sys.s
- \t\t * and ../../libcgo/linux_amd64.s.
+ \t\t * Also known to ../../pkg/runtime/sys_linux_amd64.s
+ \t\t * and ../../pkg/runtime/cgo/gcc_linux_amd64.c.
  	\t */
  	\ttlsoffset = -16;
  	\telfinit();

2. src/cmd/8l/obj.c Goの386リンカのソースコード。TLSオフセットに関するコメントのパスを修正。

--- a/src/cmd/8l/obj.c
+++ b/src/cmd/8l/obj.c
@@ -218,7 +218,7 @@ main(int argc, char *argv[])
  	case Hdarwin:	/* apple MACH */
  	\t/*
  	\t * OS X system constant - offset from %gs to our TLS.
- \t\t * Explained in ../../libcgo/darwin_386.c.
+ \t\t * Explained in ../../pkg/runtime/cgo/gcc_darwin_386.c.
  	\t */
  	\ttlsoffset = 0x468;
  	\tmachoinit();
@@ -237,8 +237,8 @@ main(int argc, char *argv[])
  	\t/*
  	\t * ELF uses TLS offsets negative from %gs.
  	\t * Translate 0(GS) and 4(GS) into -8(GS) and -4(GS).
- \t\t * Also known to ../../pkg/runtime/linux/386/sys.s
- \t\t * and ../../libcgo/linux_386.c.
+ \t\t * Also known to ../../pkg/runtime/sys_linux_386.s
+ \t\t * and ../../pkg/runtime/cgo/gcc_linux_386.c.
  	\t */
  	\ttlsoffset = -8;
  	\telfinit();

3. src/make.bash Goのビルドスクリプト。ビルド対象のパッケージリストに関するコメントを修正。

--- a/src/make.bash
+++ b/src/make.bash
@@ -75,7 +75,7 @@ $USE_GO_TOOL ||
 ) || exit 1
 bash "$GOROOT"/src/clean.bash
 
-# pkg builds libcgo and the Go programs in cmd.
+# pkg builds runtime/cgo and the Go programs in cmd.
 for i in lib9 libbio libmach cmd
 do
  	echo; echo; echo %%%% making $i %%%%; echo

4. src/pkg/runtime/cgo/gcc_darwin_386.c Darwin/386向けのCgoランタイムコード。TLS初期化に関するコメントのパスを修正。

--- a/src/pkg/runtime/cgo/gcc_darwin_386.c
+++ b/src/pkg/runtime/cgo/gcc_darwin_386.c
@@ -39,8 +39,8 @@ inittls(void)\n \t *\n \t * The linker and runtime hard-code these constant offsets\n \t * from %gs where we expect to find m and g.\n-\t * Known to ../cmd/8l/obj.c:/468\n-\t * and to ../pkg/runtime/darwin/386/sys.s:/468
+\t * Known to ../../../cmd/8l/obj.c:/468\n+\t * and to ../sys_darwin_386.s:/468
 \t *\n \t * This is truly disgusting and a bit fragile, but taking care\n \t * of it here protects the rest of the system from damage.

5. src/pkg/runtime/cgo/gcc_darwin_amd64.c Darwin/amd64向けのCgoランタイムコード。TLS初期化に関するコメントのパスを修正。

--- a/src/pkg/runtime/cgo/gcc_darwin_amd64.c
+++ b/src/pkg/runtime/cgo/gcc_darwin_amd64.c
@@ -27,8 +27,8 @@ inittls(void)\n \t *\n \t * The linker and runtime hard-code these constant offsets\n \t * from %gs where we expect to find m and g.\n-\t * Known to ../cmd/6l/obj.c:/8a0\n-\t * and to ../pkg/runtime/darwin/amd64/sys.s:/8a0
+\t * Known to ../../../cmd/6l/obj.c:/8a0\n+\t * and to ../sys_darwin_amd64.s:/8a0
 \t *\n \t * As disgusting as on the 386; same justification.\n \t */

6. src/pkg/runtime/mkasmh.sh アセンブリヘッダ生成スクリプト。TLSオフセットに関するコメントのパスを修正。

--- a/src/pkg/runtime/mkasmh.sh
+++ b/src/pkg/runtime/mkasmh.sh
@@ -34,8 +34,8 @@ case "$GOARCH" in\n 386)\n \t# The offsets 0 and 4 are also known to:\n \t#\t../../cmd/8l/pass.c:/D_GS\n-\t#\t../../libcgo/linux_386.c:/^threadentry\n-\t#\t../../libcgo/darwin_386.c:/^threadentry
+\t#\tcgo/gcc_linux_386.c:/^threadentry\n+\t#\tcgo/gcc_darwin_386.c:/^threadentry
 \tcase "$GOOS" in\n \twindows)\n \t\techo '#define\tget_tls(r)\tMOVL 0x14(FS), r'
@@ -89,8 +89,8 @@ amd64)\n \t*)\n \t\t# The offsets 0 and 8 are known to:\n \t\t#\t../../cmd/6l/pass.c:/D_GS\n-\t\t#\t../../libcgo/linux_amd64.c:/^threadentry\n-\t\t#\t../../libcgo/darwin_amd64.c:/^threadentry
+\t\t#\tcgo/gcc_linux_amd64.c:/^threadentry\n+\t\t#\tcgo/gcc_darwin_amd64.c:/^threadentry
 \t\t#\n \t\techo '#define\tget_tls(r)'\n \t\techo '#define\tg(r) 0(GS)'

7. src/pkg/runtime/runtime.h GoランタイムのCヘッダファイル。G構造体のフィールドに関するコメントを修正。

--- a/src/pkg/runtime/runtime.h
+++ b/src/pkg/runtime/runtime.h
@@ -168,8 +168,8 @@ struct	Gobuf\n };\n struct	G\n {\n-\tbyte*\tstackguard;\t// cannot move - also known to linker, libmach, libcgo\n-\tbyte*\tstackbase;\t// cannot move - also known to libmach, libcgo
+\tbyte*\tstackguard;\t// cannot move - also known to linker, libmach, runtime/cgo\n+\tbyte*\tstackbase;\t// cannot move - also known to libmach, runtime/cgo
 \tDefer*\tdefer;\n \tPanic*\tpanic;\n \tGobuf\tsched;

8. src/pkg/runtime/sys_darwin_386.s Darwin/386向けのアセンブリファイル。TLS設定に関するコメントのパスを修正。

--- a/src/pkg/runtime/sys_darwin_386.s
+++ b/src/pkg/runtime/sys_darwin_386.s
@@ -338,7 +338,7 @@ TEXT runtime·setldt(SB),7,$32\n \t * To accommodate that rewrite, we translate the\n \t * address and limit here so that 0x468(GS) maps to 0(address).\n \t *\n-\t * See ../../../../libcgo/darwin_386.c for the derivation\n+\t * See cgo/gcc_darwin_386.c:/468 for the derivation
 \t * of the constant.\n \t */\n \tSUBL\t$0x468, BX

9. src/pkg/runtime/sys_darwin_amd64.s Darwin/amd64向けのアセンブリファイル。TLS設定に関するコメントのパスを修正。

--- a/src/pkg/runtime/sys_darwin_amd64.s
+++ b/src/pkg/runtime/sys_darwin_amd64.s
@@ -327,8 +327,8 @@ TEXT runtime·mach_semaphore_signal_all(SB),7,$0\n // set tls base to DI\n TEXT runtime·settls(SB),7,$32\n \t/*\n-\t* Same as in ../386/sys.s:/ugliness, different constant.\n-\t* See ../../../../libcgo/darwin_amd64.c for the derivation\n+\t* Same as in sys_darwin_386.s:/ugliness, different constant.\n+\t* See cgo/gcc_darwin_amd64.c for the derivation
 \t* of the constant.\n \t*/\n \tSUBQ $0x8a0, DI

コアとなるコードの解説

このコミットにおける「コアとなるコードの変更」は、Goのランタイム、リンカ、およびCgoの連携に関するコメント内のファイルパスの参照を、Goソースツリーの現在の構造に合わせて更新することです。これは、コードの機能的な変更ではなく、ドキュメンテーションの正確性を高めるためのものです。

各ファイルの変更は、以下のような意味合いを持ちます。

  • src/cmd/6l/obj.c および src/cmd/8l/obj.c: これらのファイルはGoのリンカのソースコードであり、それぞれamd64と386アーキテクチャに対応しています。変更されたコメントは、OS X (Darwin) および Linux 環境におけるTLS (Thread Local Storage) のオフセットに関する説明です。TLSは、各スレッドが独自のデータを持つためのメカニズムであり、GoランタイムがゴルーチンやM（OSスレッド）の情報を効率的に管理するために利用されます。これらのコメントは、TLSオフセットの具体的な値がどこで定義され、どのように利用されているかを示すために、関連するCgoのCソースファイル（例: gcc_darwin_amd64.c）やランタイムのアセンブリファイル（例: sys_linux_amd64.s）へのパスを指していました。古いパス../../libcgo/が../../pkg/runtime/cgo/や../../pkg/runtime/sys_に修正されたのは、Cgo関連のコードがsrc/pkg/runtime/cgoに統合され、ランタイムのアセンブリファイルがsrc/pkg/runtime/sys_以下に整理されたことを反映しています。

  • src/make.bash: Goのビルドプロセスを制御するシェルスクリプトです。変更されたコメントは、スクリプトがビルドする主要なパッケージのリストに関するものです。以前はlibcgoという名称で参照されていたCgo関連のビルドターゲットが、runtime/cgoという現在のパッケージ名に更新されました。これは、Goのビルドシステムが内部的にCgoコンポーネントをどのように認識しているかの変更を反映しています。

  • src/pkg/runtime/cgo/gcc_darwin_386.c および src/pkg/runtime/cgo/gcc_darwin_amd64.c: これらのファイルは、Darwin（macOS）環境におけるCgoのランタイムサポートのためのC言語ソースコードです。TLSの初期化（inittls関数）に関するコメントが変更されています。これらのコメントは、リンカやランタイムのアセンブリコードが、%gsレジスタからの特定のオフセットにm（OSスレッド）とg（ゴルーチン）のポインタを見つけることを「知っている」と説明しています。変更は、これらのオフセットがどこで「知られている」かを示す参照パスを、../../../cmd/8l/obj.c（リンカ）や../sys_darwin_386.s（ランタイムのアセンブリファイル）といった現在の正しいパスに更新したものです。これは、GoとCgoがTLSを介してどのように連携し、ゴルーチンとOSスレッドのコンテキストを管理しているかを示す重要な手がかりとなります。

  • src/pkg/runtime/mkasmh.sh: このシェルスクリプトは、GoランタイムのアセンブリコードからCヘッダファイルを生成するために使用されます。変更されたコメントは、TLSオフセットに関する定数が、CgoのCソースファイル（例: cgo/gcc_linux_386.c）内のthreadentry関数でも「知られている」ことを示しています。パスが../../libcgo/からcgo/に短縮されたのは、mkasmh.shからの相対パスが変更されたためです。これは、アセンブリコードとCgoのCコードがTLSオフセットに関してどのように協調しているかを示しています。

  • src/pkg/runtime/runtime.h: GoランタイムのC言語ヘッダファイルです。G（ゴルーチン）構造体内のstackguardとstackbaseフィールドに関するコメントが変更されています。これらのフィールドは、Goのスタック管理において非常に重要であり、スタックのオーバーフロー検出などに使用されます。コメントは、これらのフィールドがリンカ、libmach、そして以前はlibcgoによっても認識されていることを示していました。このlibcgoがruntime/cgoに更新されたのは、CgoがGoランタイムのスタック管理と密接に連携していることを示し、そのコンポーネント名が変更されたことを反映しています。

  • src/pkg/runtime/sys_darwin_386.s および src/pkg/runtime/sys_darwin_amd64.s: これらのファイルは、Darwin環境におけるGoランタイムの低レベルなシステムコールやTLS設定を行うアセンブリコードです。変更されたコメントは、TLSベースアドレスの設定に関するもので、特定の定数（例: 0x468や0x8a0）の導出元としてCgoのCソースファイル（例: cgo/gcc_darwin_386.c）を参照していました。パスが../../../../libcgo/からcgo/に修正されたのは、これらのアセンブリファイルからCgoのCソースファイルへの相対パスが変更されたためです。これは、GoランタイムがOSのTLSメカニズムとどのように連携し、Cgoを介したCコードとの相互運用性を実現しているかを示すものです。

総じて、これらの変更は、Goの内部コンポーネント（リンカ、ランタイム、Cgo）間の相互参照を正確に保ち、コードベースの進化に合わせてドキュメンテーションを最新の状態に維持するための、地道ながらも重要な作業です。これにより、Goの複雑な低レベルな部分を理解しようとする開発者にとって、より正確で信頼性の高い情報が提供されることになります。

関連リンク

参考にした情報源リンク