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

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

このコミットは、Go言語の標準ライブラリの一部である sync.Once パッケージの初期バージョンにおけるドキュメンテーションの改善に関するものです。具体的には、src/lib/once.go ファイル内のコメントが更新され、once パッケージとその主要な関数である Do の目的と使用方法がより明確に説明されています。

コミット

document once

このコミットは、once パッケージのドキュメンテーションを改善することを目的としています。

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

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

元コミット内容

document once

R=rsc
DELTA=14  (7 added, 5 deleted, 2 changed)
OCL=25818
CL=25834

変更の背景

このコミットが行われた2009年3月は、Go言語がまだ一般に公開される前の初期開発段階でした。この時期には、言語の機能や標準ライブラリが活発に設計・実装されており、それに伴いドキュメンテーションも整備されていました。

sync.Once パッケージは、特定の処理がアプリケーションのライフサイクル中に一度だけ実行されることを保証するための重要なユーティリティです。このような重要な機能については、開発者が正しく理解し、適切に使用できるように、明確で簡潔なドキュメンテーションが不可欠です。

このコミットの背景には、once パッケージの目的と Do 関数の振る舞いを、より分かりやすく、かつGoのドキュメンテーションの慣習に沿った形で記述するという意図があったと考えられます。特に、パッケージレベルのコメントと関数レベルのコメントを適切に配置し、重複を避けつつも必要な情報を提供するように調整されています。

前提知識の解説

Go言語の sync.Once パッケージ

sync.Once はGo言語の sync パッケージに含まれる型で、特定の関数が一度だけ実行されることを保証するために使用されます。これは、リソースの初期化、シングルトンパターンの実装、またはアプリケーション全体で一度だけ実行する必要があるセットアップ処理など、様々なシナリオで非常に役立ちます。

sync.Once の主な特徴は以下の通りです。

  • 一度だけ実行の保証: Once 型の Do メソッドに渡された関数は、複数のGoroutineから同時に呼び出されたとしても、一度だけ実行されることが保証されます。
  • スレッドセーフ: 内部的にミューテックス（sync.Mutex）を使用して同期を行うため、並行処理環境で安全に使用できます。
  • ブロッキング: 最初のGoroutineが Do に渡された関数を実行している間、他のGoroutineが同じ Once インスタンスの Do を呼び出すと、最初のGoroutineの関数が完了するまでブロックされます。これにより、初期化が完了する前にリソースが使用されることを防ぎます。
  • 遅延初期化 (Lazy Initialization): init 関数とは異なり、sync.Once はその初期化が必要になった時点で初めて実行されます。これは、アプリケーションの起動時にすべてのリソースを初期化する必要がない場合に特に有効です。

使用例:

package main

import (
	"fmt"
	"sync"
	"time"
)

var once sync.Once
var config string

func loadConfig() {
	fmt.Println("設定をロード中...")
	time.Sleep(2 * time.Second) // 時間のかかる初期化をシミュレート
	config = "アプリケーション設定がロードされました"
	fmt.Println("設定ロード完了")
}

func main() {
	var wg sync.WaitGroup

	for i := 0; i < 5; i++ {
		wg.Add(1)
		go func(id int) {
			defer wg.Done()
			fmt.Printf("Goroutine %d: Do() を呼び出し中...\n", id)
			once.Do(loadConfig) // loadConfig は一度だけ実行される
			fmt.Printf("Goroutine %d: 設定: %s\n", id, config)
		}(i)
	}

	wg.Wait()
	fmt.Println("すべてのGoroutineが完了しました。")
}

この例では、loadConfig 関数は once.Do(loadConfig) が複数回呼び出されても、一度だけ実行されます。

Go言語の init 関数

Go言語には、パッケージがインポートされた際に自動的に実行される init 関数という特別な関数があります。

  • 自動実行: init 関数は、パッケージが初期化される際に、main 関数が実行される前に自動的に呼び出されます。
  • 複数定義可能: 1つのパッケージ内に複数の init 関数を定義できます。それらは定義された順序で実行されます。
  • 引数なし、戻り値なし: init 関数は引数を取らず、戻り値もありません。
  • 用途: グローバル変数の初期化、外部リソースへの接続、登録処理など、プログラムの起動時に一度だけ実行する必要がある処理に使用されます。

sync.Once と init 関数の主な違いは、init がプログラム起動時に必ず実行されるのに対し、sync.Once は Do メソッドが呼び出されたときに初めて実行される（遅延初期化）という点です。このコミットの変更前のコメントにも「init 時に行われない一度限りの初期化のために」という記述があり、この違いが意識されていたことがわかります。

技術的詳細

このコミットの技術的な変更は、src/lib/once.go ファイル内のコメントの修正に限定されています。コードのロジック自体には変更がありません。

変更の核心は、once パッケージのドキュメンテーションの構造と表現の改善です。

  1. パッケージレベルのコメントの変更:

    • 変更前: // For one-time initialization that is not done during init. から始まる、once.Do(f) の使用方法と並行呼び出し時の振る舞いを説明するコメント。
    • 変更後: // This package provides a single function, Do, to run a function // exactly once, usually used as part of initialization. という簡潔なパッケージ概要に変更。これにより、パッケージの目的がより明確に伝わるようになりました。

  2. Do 関数へのコメントの追加:

    • 変更前: Do 関数には直接的なドキュメンテーションコメントがありませんでした。
    • 変更後: パッケージレベルのコメントから、Do 関数の具体的な使用方法と並行呼び出し時の振る舞いに関する説明が Do 関数自身のコメントとして移動・追加されました。これにより、Do 関数を呼び出す際にその振る舞いを直接確認できるようになり、ドキュメンテーションの可読性と発見性が向上しました。

この変更は、Goのドキュメンテーションツール（go doc など）がパッケージや関数のコメントをどのように解釈し、表示するかを考慮したものです。パッケージの概要はパッケージ宣言の直前に、関数の詳細はその関数の宣言の直前に記述するのがGoの慣習です。このコミットは、その慣習に沿ってドキュメンテーションを整理したと言えます。

内部的には、sync.Once は以下のようなシンプルなロジックで一度だけ実行を保証します（これはこのコミットの対象ではありませんが、背景知識として重要です）。

type Once struct {
	m    Mutex
	done uint32 // 0: not done, 1: done
}

func (o *Once) Do(f func()) {
	// Fast path.
	if atomic.LoadUint32(&o.done) == 1 {
		return
	}
	// Slow path.
	o.m.Lock()
	defer o.m.Unlock()
	if o.done == 0 {
		defer atomic.StoreUint32(&o.done, 1)
		f()
	}
}

（注：上記のコードは現在の sync.Once の簡略化された実装であり、コミット当時の src/lib/once.go の実際のコードとは異なります。コミット当時の once.go は、map[func()]*job と sync.Mutex を使用して、関数 f ごとに一度だけ実行を保証する、より実験的な実装でした。しかし、ドキュメンテーションの意図は同じです。）

このコミットは、この Do メソッドの振る舞いをユーザーに正確に伝えるためのドキュメンテーションの改善に焦点を当てています。

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

変更は src/lib/once.go ファイルのみです。

--- a/src/lib/once.go
+++ b/src/lib/once.go
@@ -2,13 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// For one-time initialization that is not done during init.
-// Wrap the initialization in a niladic function f() and call
-//	once.Do(f)
-// If multiple processes call once.Do(f) simultaneously
-// with the same f argument, only one will call f, and the
-// others will block until f finishes running.
-\n+// This package provides a single function, Do, to run a function
+// exactly once, usually used as part of initialization.
 package once
 
 import "sync"
@@ -21,6 +16,13 @@ type job struct {\n var jobs = make(map[func()]*job)\n var joblock sync.Mutex;\n \n+// Do is the the only exported piece of the package.\n+// For one-time initialization that is not done during init,\n+// wrap the initialization in a niladic function f() and call
+//	Do(f)
+// If multiple processes call Do(f) simultaneously
+// with the same f argument, only one will call f, and the
+// others will block until f finishes running.
 func Do(f func()) {\n 	joblock.Lock();\n 	j, present := jobs[f];\n```

**変更の概要:**

*   **削除された行**: 5行 (`-` で始まる行)
    *   パッケージ宣言 `package once` の直前にあった、`once.Do(f)` の使用方法と振る舞いを説明するコメントブロックが削除されました。
*   **追加された行**: 7行 (`+` で始まる行)
    *   パッケージ宣言 `package once` の直前に、パッケージの簡潔な説明 `// This package provides a single function, Do, to run a function // exactly once, usually used as part of initialization.` が追加されました。
    *   `Do` 関数の宣言の直前に、削除されたコメントブロックの内容とほぼ同じ説明が追加されました。ただし、`once.Do(f)` の代わりに `Do(f)` と記述されています。
*   **変更された行**: 2行
    *   これは、diffツールがコメントブロックの移動と内容のわずかな変更を検出した結果です。実質的には、コメントの再配置と微調整です。

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

このコミットは、Goのドキュメンテーションのベストプラクティスに沿って、`once` パッケージのドキュメンテーションを改善しています。

1.  **パッケージレベルの概要の明確化**:
    変更前は、パッケージの冒頭のコメントが `once.Do(f)` の具体的な使用方法に焦点を当てていました。変更後は、`// This package provides a single function, Do, to run a function // exactly once, usually used as part of initialization.` となり、パッケージ全体の目的がより簡潔かつ明確に示されています。これは、パッケージの役割を一目で理解するために重要です。

2.  **`Do` 関数への詳細なドキュメンテーションの移動**:
    `once` パッケージの主要な機能は `Do` 関数によって提供されます。そのため、`Do` 関数の具体的な使用方法、引数、そして並行呼び出し時の振る舞いに関する詳細な説明は、`Do` 関数自身のコメントとして記述されるのが最も適切です。この変更により、開発者が `Do` 関数の定義を見たときに、その機能と使い方をすぐに把握できるようになりました。
    特に、`once.Do(f)` から `Do(f)` への変更は、`Do` 関数がパッケージのトップレベルでエクスポートされていることを示唆しており、よりGoらしい呼び出し方を示しています。

このコミットは、機能的な変更ではなく、ドキュメンテーションの品質向上に特化したものです。しかし、良質なドキュメンテーションは、ライブラリの使いやすさ、理解しやすさ、そして最終的には採用率に大きく貢献するため、非常に重要な変更と言えます。特にGo言語では、`go doc` コマンドやGoLandなどのIDEがコメントを解析してドキュメンテーションを表示するため、コメントの質はコードの質と同じくらい重要視されます。

## 関連リンク

*   **Go言語 `sync.Once` の公式ドキュメンテーション**:
    [https://pkg.go.dev/sync#Once](https://pkg.go.dev/sync#Once)
*   **Go言語 `init` 関数の解説 (Go言語の仕様)**:
    [https://go.dev/ref/spec#Package_initialization](https://go.dev/ref/spec#Package_initialization)

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

*   **Go言語の公式ドキュメンテーション**: `sync.Once` および `init` 関数の概念理解のために参照しました。
*   **GitHubのコミット履歴**: 実際の変更内容と当時のコードの文脈を理解するために参照しました。