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

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

このコミットは、Go言語のGo 1リリースに関する公式ドキュメント（doc/go1.htmlおよびdoc/go1.tmpl）の更新を目的としています。具体的には、flagパッケージ、runtimeパッケージ、およびtestingパッケージにおけるGo 1での変更点や新機能について、ドキュメントに追記・修正を行っています。また、ドキュメント内で使用されるコード例（doc/progs/go1.go）も更新されています。

コミット

commit 531ded922f4eeb8c4634924b935599165b9f407b
Author: Rob Pike <r@golang.org>
Date:   Fri Jan 20 15:38:03 2012 -0800

    doc/go1: flag, runtime, testing
    
    R=golang-dev, dsymonds, gri
    CC=golang-dev
    https://golang.org/cl/5557076

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

https://github.com/golang/go/commit/531ded922f4eeb8c4634924b935599165b9f407b

元コミット内容

doc/go1: flag, runtime, testing

このコミットは、Go 1リリースに関するドキュメント（doc/go1）において、flag、runtime、testingの各パッケージに関する記述を更新するものです。

変更の背景

Go 1は、Go言語にとって最初の安定版リリースであり、将来の互換性を保証する重要なマイルストーンでした。このリリースでは、言語仕様、標準ライブラリ、ツールチェインなど、多岐にわたる変更と改善が加えられました。ユーザーがGo 1に移行する際に混乱を避けるため、また新機能や変更点を正確に伝えるために、公式ドキュメントの整備は不可欠でした。

このコミットは、Go 1のリリースノートまたは移行ガイドの一部として、特に以下のパッケージにおける変更点を明確にするために行われました。

  • flagパッケージ: コマンドライン引数のパースを扱うパッケージ。インターフェースの変更と新機能の追加がありました。
  • runtimeパッケージ: Goランタイムの低レベルな機能を提供するパッケージ。システム情報取得のための新機能が追加されました。
  • testingパッケージ: テストとベンチマークをサポートするパッケージ。ベンチマーク機能の強化がありました。

これらの変更は、既存のGoプログラムに影響を与える可能性があったり、新しいプログラミングパターンを可能にするものであったため、ドキュメントでの詳細な説明が求められました。

前提知識の解説

Go 1リリースとその互換性保証

Go 1は、Go言語の歴史において非常に重要なリリースです。このリリース以降、Goチームは「Go 1互換性保証」を導入し、Go 1で書かれたプログラムは、将来のGoのバージョンでも動作し続けることを約束しました。これは、Go言語が安定したプラットフォームとして広く採用される上で極めて重要な要素でした。Go 1のドキュメントは、この互換性保証の基盤となる変更点をユーザーに伝える役割を担っていました。

Go言語の標準パッケージ

Go言語は、豊富な標準ライブラリを提供しており、これらは「パッケージ」として組織されています。各パッケージは特定の機能を提供し、Goプログラムの構築において基本的な構成要素となります。

  • flagパッケージ: コマンドライン引数を解析するための機能を提供します。flag.Parse()を呼び出すことで、定義されたフラグがコマンドラインから読み込まれ、対応する変数に値が設定されます。
  • runtimeパッケージ: Goランタイムシステムとのインタラクションを提供します。ガベージコレクション、ゴルーチン管理、OSとの連携など、低レベルな機能が含まれます。
  • testingパッケージ: Goプログラムのテストとベンチマークを記述するためのフレームワークを提供します。go testコマンドによって実行され、ユニットテスト、ベンチマークテスト、例（Example）などをサポートします。

flag.Valueインターフェース

flagパッケージにおいて、カスタムのコマンドラインフラグ型を定義するために使用されるインターフェースです。このインターフェースを実装することで、任意の型をコマンドラインフラグとして扱えるようになります。主なメソッドはSet(string) errorとString() stringです。

time.Duration型

timeパッケージで定義されている型で、時間の長さを表します。例えば、10s（10秒）、1h30m（1時間30分）のように、時間単位を含む文字列からパースしたり、そのようにフォーマットしたりできます。

GOMAXPROCS環境変数

Goランタイムが同時に実行できるOSスレッドの最大数を制御する環境変数です。この値を設定することで、Goプログラムが利用するCPUコア数を調整し、並行処理のパフォーマンスに影響を与えることができます。

testing.B型

testingパッケージにおいて、ベンチマーク関数に渡される型です。ベンチマークの実行回数（b.N）や、ベンチマークの開始・停止、エラー報告などの機能を提供します。

技術的詳細

このコミットでドキュメントが更新された主な技術的変更点は以下の通りです。

flagパッケージの変更

  1. flag.ValueインターフェースのSetメソッドの変更: Go 1以前は、flag.ValueインターフェースのSetメソッドは成功/失敗を示すboolを返していました。Go 1からは、エラーの詳細を伝えるためにerror型を返すように変更されました。

    • 変更前: Set(string) bool
    • 変更後: Set(string) error この変更により、カスタムフラグの実装者は、より詳細なエラーハンドリングが可能になりました。既存のコードは手動で修正する必要がありました。

  2. Durationフラグの追加: flagパッケージに、新しいフラグ型Durationが追加されました。これにより、time.Duration型の値をコマンドライン引数として直接受け取ることができるようになりました。値は10s、1h30mなどの形式で指定します。

    • 例: var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion") この新機能は、時間間隔を指定するコマンドライン引数を扱う際に非常に便利です。既存のコードには影響を与えません。

runtimeパッケージの変更

  1. runtime.NumCPU関数の追加: runtimeパッケージに、引数を取らない新しい関数runtime.NumCPU()が追加されました。この関数は、オペレーティングシステムカーネルが報告する、並列実行に利用可能なCPUの数を返します。
    • この値は、GOMAXPROCS環境変数の設定を決定する際に役立ちます。
    • 既存のコードには影響を与えません。

testingパッケージの変更

  1. testing.B型への新メソッド追加: ベンチマーク関数に渡されるtesting.B型に、testing.T型と同様のロギングおよび失敗報告のための新しいメソッドが追加されました。これにより、ベンチマーク実行中にログを出力したり、ベンチマークの失敗を報告したりすることが可能になりました。
    • 例: b.Fatalf("expected %q; got %q", expect, got)
    • ベンチマークの正確性を検証するために、b.StopTimer()とb.StartTimer()を使ってベンチマーク対象外の処理時間を計測から除外する機能も強化されました。
    • 既存のコードには直接的な影響はありませんが、printlnやpanicを使用していた既存のベンチマークは、新しいインターフェースに更新することが推奨されました。

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

このコミットは主にドキュメントの更新であるため、Go言語のランタイムやライブラリのソースコード自体を変更するものではありません。変更されたのは、Go 1のリリースに関するドキュメントファイルと、そのドキュメント内で使用されるサンプルコードです。

doc/go1.html および doc/go1.tmpl の変更点（抜粋）:

--- a/doc/go1.html
+++ b/doc/go1.html
@@ -850,6 +850,32 @@ to be implemented in the future.
 No changes will be needed.
 </p>
 
+<h3 id=\"flag\">The flag package</h3>
+
+<p>
+In Go 1, the interface <a href=\"/pkg/flag/#Value\"><code>flag.Value</code></a> has changed slightly.
+The <code>Set</code> method now returns an <code>error</code> instead of
+a <code>bool</code> to indicate success or failure.
+</p>
+
+<p>
+There is also a new kind of flag, <code>Duration</code>, to support argument
+values specifying time intervals.
+Values for such flags must be given units, just as <code>time.Duration</code>
+formats them: <code>10s</code>, <code>1h30m</code>, etc.
+</p>
+
+<pre><!--{{code \"progs/go1.go\" `/timeout/`}}\n+-->var timeout = flag.Duration(&#34;timeout&#34;, 30*time.Second, &#34;how long to wait for completion&#34;)</pre>
+
+<p>
+<em>Updating</em>:
+Programs that implement their own flags will need minor manual fixes to update their
+<code>Set</code> methods.
+The <code>Duration</code> flag is new and affects no existing code.
+</p>
+
+
 <h3 id=\"go\">The go/* packages</h3>
 
 <p>
@@ -1064,6 +1089,20 @@ and <code>os.FileMode</code> API.
 Code that needs system-specific file details will need to be updated by hand.
 </p>
 
+<h3 id=\"runtime\">The runtime package</h3>
+
+<p>
+The <code>runtime</code> package in Go 1 includes a new niladic function,
+<a href=\"/pkg/runtime/#NumCPU\"><code>runtime.NumCPU</code></a>, that returns the number of CPUs available
+for parallel execution, as reported by the operating system kernel.
+Its value can inform the setting of <code>GOMAXPROCS</code>.
+</p>
+
+<p>
+<em>Updating</em>:
+No existing code is affected.
+</p>
+
 <h3 id=\"strconv\">The strconv package</h3>
 
 <p>
@@ -1159,6 +1198,35 @@ a cast that must be added by hand; gofix will warn about it.\n </p>\n \n \n+<h3 id=\"testing\">The testing package</h3>\n+\n+<p>\n+The testing package has a type, <code>B</code>, passed as an argument to benchmark functions.\n+In Go 1, <code>B</code> has new methods, analogous to those of <code>T</code>, enabling\n+logging and failure reporting.\n+</p>\n+\n+<pre><!--{{code \"progs/go1.go\" `/func.*Benchmark/` `/^}/`}}\n+-->func BenchmarkSprintf(b *testing.B) {\n+    // Verify correctness before running benchmark.\n+    b.StopTimer()\n+    got := fmt.Sprintf(&#34;%x&#34;, 23)\n+    const expect = &#34;17&#34;\n+    if expect != got {\n+        b.Fatalf(&#34;expected %q; got %q&#34;, expect, got)\n+    }\n+    b.StartTimer()\n+    for i := 0; i &lt; b.N; i++ {\n+        fmt.Sprintf(&#34;%x&#34;, 23)\n+    }\n+}</pre>\n+\n+<p>\n+<em>Updating</em>:\n+Existing code is unaffected, although benchmarks that use <code>println</code>\n+or <code>panic</code> should be updated to the new interface.\n+</p>\n```

**`doc/progs/go1.go` の変更点（抜粋）:**

```diff
--- a/doc/progs/go1.go
+++ b/doc/progs/go1.go
@@ -8,13 +8,16 @@ package main
 
 import (
 	"errors"
+	"flag"
 	"fmt"
 	"log"
+	"testing"
 	"time"
 	"unicode"
 )
 
 func main() {
+\tflag.Parse()\n 	stringAppend()\n 	mapDelete()\n 	mapIteration()\n@@ -26,6 +29,8 @@ func main() {\n \ttimePackage()\n }\n \n+var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion")\n+\n func mapDelete() {\n 	m := map[string]int{"7": 7, "23": 23}\n 	k := "7"\n@@ -187,3 +192,17 @@ func init() {\n 	go initializationFunction(c)\n 	PackageGlobal = <-c\n }\n+\n+func BenchmarkSprintf(b *testing.B) {\n+\t// Verify correctness before running benchmark.\n+\tb.StopTimer()\n+\tgot := fmt.Sprintf("%x", 23)\n+\tconst expect = "17"\n+\tif expect != got {\n+\t\tb.Fatalf("expected %q; got %q", expect, got)\n+\t}\n+\tb.StartTimer()\n+\tfor i := 0; i < b.N; i++ {\n+\t\tfmt.Sprintf("%x", 23)\n+\t}\n+}\n```

## コアとなるコードの解説

### ドキュメント (`doc/go1.html`, `doc/go1.tmpl`) の変更

これらのファイルは、Go 1のリリースノートまたは移行ガイドのHTMLおよびテンプレートバージョンです。追加されたセクションは、Go 1で導入された`flag`、`runtime`、`testing`パッケージの具体的な変更点を説明しています。

*   **`flag`パッケージのセクション**:
    *   `flag.Value`インターフェースの`Set`メソッドが`bool`から`error`を返すように変更されたことについて説明しています。これは、より詳細なエラー報告を可能にするための重要な変更です。
    *   新しい`flag.Duration`型の導入について説明しています。これにより、コマンドラインから直接時間間隔（例: `10s`, `1h30m`）を指定できるようになり、利便性が向上しました。
    *   既存のコードへの影響（`Set`メソッドの修正が必要な場合があること）と、`Duration`フラグが既存コードに影響しないことが明記されています。

*   **`runtime`パッケージのセクション**:
    *   `runtime.NumCPU()`関数の追加について説明しています。この関数は、利用可能なCPUコア数を取得するために使用され、`GOMAXPROCS`の設定に役立つことが示唆されています。
    *   既存のコードには影響がないことが明記されています。

*   **`testing`パッケージのセクション**:
    *   `testing.B`型に、`testing.T`と同様のロギングおよび失敗報告メソッドが追加されたことについて説明しています。これにより、ベンチマークのテスト中に詳細な情報を提供したり、ベンチマークの前提条件が満たされない場合に失敗を報告したりすることが可能になりました。
    *   `b.StopTimer()`と`b.StartTimer()`を使用して、ベンチマークのセットアップや検証にかかる時間を計測から除外するベストプラクティスが示されています。
    *   既存のベンチマークコードは影響を受けないものの、`println`や`panic`を使用している場合は新しいインターフェースに更新することが推奨されています。

### サンプルコード (`doc/progs/go1.go`) の変更

このファイルは、上記のドキュメントセクションで参照されるコード例を含んでいます。

*   **`flag`パッケージの例**:
    *   `flag`パッケージと`time`パッケージがインポートされ、`main`関数内で`flag.Parse()`が呼び出されています。これは、コマンドラインフラグを解析するために必須のステップです。
    *   `var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion")`という行が追加され、`flag.Duration`の使用例を示しています。これにより、`--timeout`フラグで時間間隔を指定できるようになります。

*   **`testing`パッケージの例**:
    *   `testing`パッケージがインポートされています。
    *   `BenchmarkSprintf`というベンチマーク関数が追加されています。この関数は、`testing.B`型の新しいメソッドの使用例を示しています。
        *   `b.StopTimer()`と`b.StartTimer()`を使って、ベンチマーク対象外の初期検証処理（`fmt.Sprintf`の正確性チェック）を計測から除外しています。
        *   `b.Fatalf`を使用して、検証が失敗した場合にベンチマークを停止し、エラーメッセージを報告しています。これは、ベンチマークの信頼性を高める上で非常に重要です。

これらの変更は、Go 1の重要な新機能とAPIの変更をユーザーに効果的に伝えるためのドキュメントとコード例の整備であり、Go言語の安定性と使いやすさを向上させるための取り組みの一環です。

## 関連リンク

*   Go 1リリースに関する変更リスト（Gerrit Code Review）: [https://golang.org/cl/5557076](https://golang.org/cl/5557076)
*   Go 1リリースノート（公式ドキュメント）: このコミットが更新しているドキュメント自体がGo 1のリリースノートの一部です。

## 参考にした情報源リンク

*   Go 1 Release Notes (Go公式ドキュメント): このコミットが更新している内容そのものが情報源です。
*   Go Programming Language Specification (Go公式ドキュメント): Go言語の基本的な概念やパッケージの動作を理解するために参照しました。
*   `flag` package documentation (GoDoc): [https://pkg.go.dev/flag](https://pkg.go.dev/flag)
*   `runtime` package documentation (GoDoc): [https://pkg.go.dev/runtime](https://pkg.go.dev/runtime)
*   `testing` package documentation (GoDoc): [https://pkg.go.dev/testing](https://pkg.go.dev/testing)
*   `time` package documentation (GoDoc): [https://pkg.go.dev/time](https://pkg.go.dev/time)
*   Go 1 Compatibility Guarantee: [https://go.dev/doc/go1compat](https://go.dev/doc/go1compat)
*   Go言語の歴史とバージョン管理に関する一般的な知識。
*   Go言語のベンチマークに関する一般的な知識。
*   Go言語のコマンドライン引数処理に関する一般的な知識。
*   Go言語の並行処理と`GOMAXPROCS`に関する一般的な知識。