Go 並行処理

ゴルーチンのライフタイム

規範的: ゴルーチンを生成するときは、いつ終了するか、または終了するかどうかを明確にしてください。

ゴルーチンはチャネルの送受信でブロックされてリークする可能性があります。GC は、他のゴルーチンがチャネルへの参照を保持していない場合でも、ブロックされたゴルーチンを終了しません。リークしていない飛行中のゴルーチンでも、パニック (閉じたチャネルへの送信)、データレース、メモリ問題、リソースリークが発生します。

コアルール

1. すべてのゴルーチンに停止メカニズムが必要 — 予測可能な終了時刻、キャンセル信号、またはその両方
2. コードはゴルーチンの終了を待つことが可能である必要がある
3. init() にゴルーチンを配置しない — 代わりに (Close、Stop、Shutdown などの) ライフサイクルメソッドを公開する
4. 同期をスコープ内に保つ — 関数スコープに制限し、ロジックを同期関数に分解する

// Good: WaitGroup で明確なライフタイム
var wg sync.WaitGroup
for item := range queue {
    wg.Add(1)
    go func() { defer wg.Done(); process(ctx, item) }()
}
wg.Wait()

// Bad: 停止または待機する方法がない
go func() { for { flush(); time.Sleep(delay) } }()

go.uber.org/goleak でリークをテストしてください。

原則: ゴルーチンをどのように停止するかを知らずに開始しないでください。

停止/完了チャネルパターン、ゴルーチン待機戦略、またはライフサイクル管理ワーカーを実装するときは、references/GOROUTINE-PATTERNS.md を読んでください。

---

通信による共有

"メモリを共有することによって通信するのではなく、代わりに通信することによってメモリを共有しなさい。"

これは Go の基盤となる並行処理設計原則です。所有権の譲渡とオーケストレーション用に チャネル を使用してください — 1 つのゴルーチンが値を生成し、別のゴルーチンが消費する場合です。複数のゴルーチンが共有状態にアクセスし、チャネルが不要な複雑さを追加する場合は、ミューテックス を使用してください。

デフォルトはチャネル。 問題が本質的にゴルーチン間のデータ受け渡しではなく、共有データ構造 (キャッシュやカウンターなど) を保護することである場合は、sync.Mutex / sync.RWMutex にフォールバックします。

---

同期関数

規範的: 非同期関数よりも同期関数を優先してください。

メリット	理由
ローカライズされたゴルーチン	ライフタイムを推論しやすい
リークとレースを回避	リソースリークとデータレースを防ぎやすい
テストしやすい	ポーリングなしで入出力を確認できる
呼び出し元の柔軟性	必要に応じて呼び出し元が並行性を追加できる

助言: 呼び出し元で不要な並行性を削除することはかなり困難です (時には不可能です)。必要に応じて呼び出し元に並行性を追加させてください。

呼び出し元がゴルーチンでラップする可能性のある同期優先 API を書くときは、references/GOROUTINE-PATTERNS.md を読んでください。

---

ゼロ値ミューテックス

sync.Mutex と sync.RWMutex のゼロ値は有効です — ほぼ ミューテックスへのポインタが必要になることはありません。

// Good: ゼロ値は有効          // Bad: 不要なポインタ
var mu sync.Mutex              mu := new(sync.Mutex)

ミューテックスを埋め込まない — Lock/Unlock を実装の詳細に保つために、名前付き mu フィールドを使用してください。エクスポートされた API ではありません。

ミューテックス保護構造の実装またはミューテックスフィールドの構造化方法を決定するときは、references/SYNC-PRIMITIVES.md を読んでください。

---

チャネル方向

規範的: 可能な限りチャネル方向を指定してください。

方向はエラーを防ぎ (コンパイラが受け取り専用チャネルのクローズをキャッチ)、所有権を伝え、自己説明的です。

func produce(out chan<- int) { /* 送信専用 */ }
func consume(in <-chan int)  { /* 受信専用 */ }
func transform(in <-chan int, out chan<- int) { /* 両方 */ }

チャネルサイズ: 1 または 0

チャネルのサイズは 0 (バッファなし) または 1 である必要があります。その他のサイズには以下の正当化が必要です:

• サイズをどのように決定したか
• 負荷下でチャネルがいっぱいになるのを何が防ぐか
• ライターがブロックされるとどうなるか

c := make(chan int)    // バッファなし — Good
c := make(chan int, 1) // サイズ 1 — Good
c := make(chan int, 64) // 任意 — 正当化が必要

エラーが発生しやすいパターンの詳細なチャネル方向の例を確認するときは、references/SYNC-PRIMITIVES.md を読んでください。

---

アトミック操作

型安全なアトミック操作用に atomic.Bool、atomic.Int64 などを使用します (Go 1.19 以降の stdlib sync/atomic、または go.uber.org/atomic)。生の int32/int64 フィールドは、一部のコードパスでアトミックアクセスを忘れやすくなります。

// Good: 型安全                  // Bad: 忘れやすい
var running atomic.Bool          var running int32 // atomic
running.Store(true)              atomic.StoreInt32(&running, 1)
running.Load()                   running == 1 // race!

sync/atomic と go.uber.org/atomic の選択、または構造体でのアトミック状態フラグの実装を行うときは、references/SYNC-PRIMITIVES.md を読んでください。

---

並行性ドキュメント

助言: 操作タイプから明らかでない場合は、スレッド安全性をドキュメント化してください。

Go ユーザーは読み取り専用操作が並行使用に対して安全であると想定し、変更操作は安全ではないと想定しています。以下の場合は並行性をドキュメント化します:

1. 読み取り対変更が不明確 — 例: LRU 状態を変更する Lookup
2. API が同期を提供 — 例: スレッド安全なクライアント
3. インターフェースに並行性要件がある — 型定義でドキュメント化

---

Context 使用方法

context.Context ガイダンス (パラメータの配置、構造体ストレージ、カスタムタイプ、導出パターン) については、専用の go-context スキルを参照してください。

---

チャネルでのバッファプーリング

バッファされたチャネルをフリーリストとして使用して、割り当てられたバッファを再利用します。この "漏れているバッファ" パターンはノンブロッキング操作用に select と default を使用します。

再利用可能なバッファを持つワーカープールを実装するとき、またはチャネルベースのプールと sync.Pool の間で選択するときは、references/BUFFER-POOLING.md を読んでください。

---

高度なパターン

チャネルのチャネルを使用したリクエスト-レスポンス多重化、またはコア間の CPU バウンド並列計算を実装するときは、references/ADVANCED-PATTERNS.md を読んでください。

---

関連スキル

• コンテキスト伝播: ゴルーチンを通じてキャンセル、デッドライン、またはリクエストスコープの値を渡すときは、go-context を参照してください
• エラーハンドリング: ゴルーチンからエラーを伝播する、または errgroup を使用するときは、go-error-handling を参照してください
• 防御的強化: API の境界での共有状態を保護する、または cleanup に defer を使用するときは、go-defensive を参照してください
• インターフェース設計: 同期プリミティブを持つ型のレシーバー型を選択するときは、go-interfaces を参照してください

外部リソース

• Never start a goroutine without knowing how it will stop — Dave Cheney
• Rethinking Classical Concurrency Patterns — Bryan Mills (GopherCon 2018)
• When Go programs end — Go Time podcast
• go.uber.org/goleak — テスト用ゴルーチンリーク検出器
• go.uber.org/atomic — 型安全なアトミック操作