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

このコミットは、Go言語の公式ドキュメントである doc/go1.html および doc/go1.tmpl を更新し、os パッケージの ProcessState 型に関する記述を追加・修正するものです。また、ドキュメント全体で go fix ツールへの参照の書式を改善しています。

コミット

commit 5cff0299931d9f114ca3b3f40aa1e5bb62e2ad08
Author: Rob Pike <r@golang.org>
Date:   Fri Feb 24 13:08:11 2012 +1100

    doc/go1: document ProcessState
    Also reformat the "go fix" references to make them look better by using the non-CW space.
    
    Fixes #3087.
    
    R=golang-dev, bradfitz
    CC=golang-dev
    https://golang.org/cl/5695057

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

https://github.com/golang/go/commit/5cff0299931d9f114ca3b3f40aa1e5bb62e2ad08

元コミット内容

このコミットの元の内容は以下の通りです。

• doc/go1: ProcessState をドキュメント化する。
• go fix への参照を、非コード幅スペースを使用してより見栄えが良くなるように再フォーマットする。
• Issue #3087 を修正する。

変更の背景

このコミットは、主にGo 1リリースに向けたドキュメントの整備の一環として行われました。Go言語の進化に伴い、os パッケージにおけるプロセスの状態管理に関するAPIが変更され、特に Waitmsg 型がよりポータブルな ProcessState 型に置き換えられました。この変更は、異なるオペレーティングシステム間での互換性を高めることを目的としています。

また、ドキュメント内で go fix コマンドへの参照が頻繁に登場しますが、その表示形式が統一されていなかったり、視覚的に読みにくい部分があったため、可読性向上のために書式が調整されました。

Fixes #3087 とあるように、このコミットはGoのIssueトラッカーで報告されていた特定の課題（Issue 3087）を解決するものです。Issue 3087は、os.ProcessState のドキュメントが不足していること、特に Sys および SysUsage メソッドが返す値の型アサーションに関する情報が欠けていることを指摘していました。

前提知識の解説

Go言語の os パッケージ

os パッケージは、オペレーティングシステムとの相互作用のための機能を提供します。これには、ファイル操作、プロセス管理、環境変数へのアクセスなどが含まれます。

os.Process と os.ProcessState

• os.Process: 実行中の外部プロセスを表す構造体です。プロセスのID（PID）や、プロセスを終了させるための Kill メソッド、プロセスの終了を待つ Wait メソッドなどがあります。
• os.ProcessState: Process.Wait メソッドが返す型で、終了したプロセスの状態に関する情報（終了コード、CPU時間、システム固有の情報など）をカプセル化します。Go 1以前は Waitmsg という型が使われていましたが、Go 1で ProcessState に変更され、よりポータブルなインターフェースが提供されるようになりました。

ProcessState.Sys と ProcessState.SysUsage

これらのメソッドは、ProcessState からシステム固有の情報を取得するために使用されます。

• Sys() interface{}: プロセスに関するシステム固有の情報を返します。戻り値の型は interface{} であり、具体的な型はオペレーティングシステムによって異なります。例えばUnix系システムでは syscall.WaitStatus 型に型アサーションできます。
• SysUsage() interface{}: プロセスが消費したシステムリソースに関するシステム固有の情報を返します。これも interface{} を返し、Unix系システムでは syscall.Rusage 型に型アサーションできます。

これらのメソッドが interface{} を返すのは、Go言語がクロスプラットフォームであることを重視しているためです。異なるOSではプロセスの状態やリソース使用状況の表現方法が異なるため、共通のインターフェースを提供しつつ、必要に応じてユーザーがシステム固有の型にキャストして詳細情報を取得できるように設計されています。

syscall パッケージ

syscall パッケージは、低レベルのシステムコールインターフェースを提供します。これは通常、特定のオペレーティングシステムの機能に直接アクセスする必要がある場合に使用されます。syscall.WaitStatus や syscall.Rusage は、それぞれプロセスの終了ステータスやリソース使用状況を詳細に表すシステム固有の構造体です。

go fix ツール

go fix は、Go言語のツールチェーンに含まれるコマンドラインツールです。Go言語のバージョンアップに伴うAPIの変更や非推奨化に対応するために、古いGoコードを自動的に新しいAPIに書き換える機能を提供します。これにより、開発者は手動でコードを修正する手間を省き、スムーズに新しいGoバージョンへ移行できます。例えば、このコミットで言及されている os.Waitmsg から os.ProcessState への変更のような、互換性のないAPI変更に対して go fix がコードを自動修正することが期待されます。

HTMLの <code> タグと非コード幅スペース

HTMLの <code> タグは、コードの断片を表すために使用されます。通常、ブラウザは <code> タグ内のテキストを等幅フォントで表示します。 「非コード幅スペース (non-CW space)」とは、等幅フォントで表示される <code> タグ内で、通常のスペース（半角スペース）ではなく、文字幅が異なるスペース（例えば、全角スペースや、特定のUnicodeスペース文字）を使用することで、視覚的なレイアウトを調整するテクニックを指します。このコミットでは、go fix の間に通常の半角スペースではなく、go と fix を別々の <code> タグで囲み、その間にスペースを入れることで、go fix が一つのコマンドとしてではなく、go と fix という二つの単語が並んでいるように見せる意図があったと考えられます。これは、go がGoコマンドラインツール自体を指し、fix がそのサブコマンドであることを明確にするための書式調整です。

技術的詳細

このコミットの主要な技術的変更点は以下の通りです。

1. ProcessState のドキュメント化の強化:

   • os.Process.Wait が返す Waitmsg 型が、よりポータブルな ProcessState 型に置き換えられたことが明記されています。
   • ProcessState が常に終了したプロセスを記述すること、およびポータビリティの懸念からインターフェースが簡素化されたことが説明されています。
   • ProcessState.Sys および ProcessState.SysUsage メソッドが返す値が interface{} 型であり、Unix系システムではそれぞれ syscall.WaitStatus および syscall.Rusage に型アサーションできることが具体的に記述されました。これは、Issue 3087で指摘されていた重要な情報です。

2. go fix 参照の書式変更:

   • ドキュメント全体で <code>go fix</code> と記述されていた箇所が、<code>go</code> <code>fix</code> のように、go と fix の間にスペースを挟んでそれぞれを <code> タグで囲む形式に変更されました。これにより、go コマンドとそのサブコマンドである fix が視覚的に区別され、より明確な表現になっています。

3. go fix の更新動作の記述:

   • Process.Wait の変更に関して、go fix がゼロ引数を削除する（Process.Wait(0) のような呼び出しを Process.Wait() に変更する）ことが追記されました。
   • その他の変更はコンパイラによって捕捉され、手動での更新が必要であることも明記されています。これは、go fix がすべての変更を自動的に処理できるわけではないという現実的な情報を提供しています。

これらの変更は、Go 1リリースにおけるAPIの安定化と、それに対応するドキュメントの正確性および利便性の向上に貢献しています。特に、ProcessState の詳細な説明は、Goプログラムが異なるOS環境でプロセスの状態をより正確に扱う上で不可欠な情報です。

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

このコミットは、Go言語のドキュメントファイルである doc/go1.html と doc/go1.tmpl のみを変更しています。Go言語のソースコード自体には変更はありません。

具体的な変更箇所は以下の通りです。

doc/go1.html および doc/go1.tmpl

• go fix への参照の書式変更:

  -Running <code>go fix</code> will convert expressions of the form <code>m[k] = ignored,
  +Running <code>go</code> <code>fix</code> will convert expressions of the form <code>m[k] = ignored,
  

  上記のように、<code>go fix</code> が <code>go</code> <code>fix</code> に変更されています。これはドキュメント全体で複数回行われています。

• ProcessState に関する新しい段落の追加:

  @@ -1463,9 +1463,27 @@ Also, the function <code>Wait</code> is gone; only the method of
   the <code>Process</code> type persists.
   </p>
   
  +<p>
  +The <code>Waitmsg</code> type returned by
  +<a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a>
  +has been replaced with a more portable
  +<a href="/pkg/os/#ProcessState"><code>ProcessState</code></a>
  +type with accessor methods to recover information about the
  +process.
  +Because of changes to <code>Wait</code>, the <code>ProcessState</code>
  +value always describes an exited process.
  +Portability concerns simplified the interface in other ways, but the values returned by the
  +<a href="/pkg/os/#ProcessState.Sys"><code>ProcessState.Sys</code></a> and
  +<a href="/pkg/os/#ProcessState.SysUsage"><code>ProcessState.SysUsage</code></a>
  +methods can be type-asserted to underlying system-specific data structures such as
  +<a href="/pkg/syscall/#WaitStatus"><code>syscall.WaitStatus</code></a> and
  +<a href="/pkg/syscall/#Rusage"><code>syscall.Rusage</code></a> on Unix.
  +</p>
  +
   <p>
   <em>Updating</em>:\n-All changes will be caught by the compiler and must be updated by hand.\n+Running <code>go</code> <code>fix</code> will drop a zero argument to <code>Process.Wait</code>.\n+All other changes will be caught by the compiler and must be updated by hand.\n     </p>
  

  この差分は、os.ProcessState に関する詳細な説明が追加されたことを示しています。特に、Waitmsg から ProcessState への移行、ProcessState が常に終了したプロセスを記述すること、そして Sys および SysUsage メソッドの戻り値の型アサーションに関する情報が追加されています。

コアとなるコードの解説

このコミットは、Go言語のドキュメントの更新であり、Go言語のランタイムやライブラリのコアコード自体を変更するものではありません。したがって、ここで「コアとなるコード」とは、Go 1リリースノートのドキュメント (doc/go1.html と doc/go1.tmpl) を指します。

追加された ProcessState に関する段落は、Go 1で導入された os.ProcessState 型の重要性と、それがどのように使用されるべきかを開発者に伝えるためのものです。

具体的には、以下の点が強調されています。

• Waitmsg から ProcessState への移行: 以前の Waitmsg 型が ProcessState に置き換えられたこと。これはGo 1におけるAPIのクリーンアップとポータビリティ向上の一環です。
• ポータビリティの向上: ProcessState がよりポータブルな型であること。これは、異なるオペレーティングシステム間でプロセスの状態を統一的に扱うためのGoの設計思想を反映しています。
• ProcessState の役割: ProcessState が、終了したプロセスに関する情報を取得するためのアクセサメソッドを持つこと。
• Sys と SysUsage の詳細: これらのメソッドが interface{} を返す理由と、Unix系システムで syscall.WaitStatus や syscall.Rusage に型アサーションできること。これにより、開発者は必要に応じて低レベルのシステム固有の情報にアクセスできます。

go fix への参照の書式変更は、ドキュメントの視覚的な一貫性と可読性を向上させるためのものです。go と fix を別々に <code> タグで囲むことで、go がコマンドラインツール自体を指し、fix がそのサブコマンドであることを明確に示しています。これは、Goのコマンドラインツールの使い方をより正確に表現するための細かな配慮です。

これらの変更は、Go 1のリリースに伴うAPIの変更を開発者が理解し、既存のコードを新しいAPIに移行する際に役立つ情報を提供することを目的としています。

関連リンク

• Go言語の公式ドキュメント: https://go.dev/doc/
• os パッケージのドキュメント: https://pkg.go.dev/os
• syscall パッケージのドキュメント: https://pkg.go.dev/syscall
• Go 1リリースノート: https://go.dev/doc/go1 (このコミットが変更しているドキュメントの最終版)
• Go Issue 3087: os.ProcessState のドキュメントに関する元のIssue。GitHubのGoリポジトリのIssueトラッカーで検索することで詳細を確認できます。

参考にした情報源リンク

• Go言語の公式ドキュメント (特にGo 1リリースノートの関連セクション)
• Go言語の os および syscall パッケージのドキュメント
• Go言語の go fix ツールの機能に関する情報
• Go言語のIssueトラッカー (Issue 3087)
• GitHubのコミット履歴
• Go言語のコミュニティフォーラムやブログ記事 (一般的なGoのAPI変更やツールの使い方に関する情報)