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

このコミットは、Go言語の次期リリース（Go 1.2と推測される）で導入されるAPIの変更を記録するapi/next.txtと、Go 1互換性保証の例外となるAPIを記録するapi/except.txtファイルを更新するものです。主に、Go標準ライブラリの様々なパッケージにわたる新しい関数、メソッド、インターフェースの追加が反映されています。

コミット

commit a3695fb2273d458974a02bc19f1606f10e6ff388
Author: Rob Pike <r@golang.org>
Date:   Tue Aug 20 11:14:45 2013 +1000

    api: update next.txt, except.txt
    
    R=golang-dev, bradfitz
    CC=golang-dev
    https://golang.org/cl/12926046

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

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

元コミット内容

api: update next.txt, except.txt

R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/12926046

変更の背景

Go言語は、バージョン1.0以降、APIの安定性を非常に重視しており、Go 1互換性保証（Go 1 Compatibility Promise）を掲げています。これは、Go 1でリリースされたプログラムは、Go 1.xの将来のリリースでもコンパイルされ、動作し続けることを保証するものです。しかし、言語や標準ライブラリの進化に伴い、新しい機能や改善が導入されることがあります。

api/next.txtは、次のメジャーリリース（このコミットの時点ではGo 1.2が想定される）で追加される予定の新しい公開APIを追跡するために使用されます。これにより、開発者は将来の変更を事前に把握し、必要に応じてコードを適応させる準備ができます。

一方、api/except.txtは、Go 1互換性保証の例外となるAPIをリストアップするために使用されます。これは通常、特定のプラットフォームや特殊なケースでのみ利用可能であったり、互換性保証の対象外とされたりするAPIが含まれます。

このコミットは、Go 1.2のリリースに向けた開発プロセスの一環として、これらのAPIリストを最新の状態に保つために行われました。特に、testingパッケージのRegisterCover関数がexcept.txtに追加されたことは、この関数が一般的なAPIとしてではなく、特定の目的（コードカバレッジツールなど）のために内部的に使用されることを示唆しています。

前提知識の解説

Go 1互換性保証 (Go 1 Compatibility Promise)

Go言語の最も重要な設計原則の一つに、後方互換性の維持があります。Go 1.0のリリース以降、Goチームは「Go 1互換性保証」を導入しました。これは、Go 1で書かれたプログラムは、Go 1.xの将来のバージョンでもコンパイルされ、動作し続けることを保証するものです。この保証は、Go言語が安定したプラットフォームとして広く採用される上で極めて重要な役割を果たしています。

この保証の対象となるのは、主にGo言語の仕様と標準ライブラリの公開APIです。しかし、一部のAPIは、特定のプラットフォームに依存したり、実験的な性質を持っていたり、あるいは内部的な利用を意図していたりするため、この保証の対象外となることがあります。これらがapi/except.txtにリストされます。

`api/next.txt`と`api/except.txt`

Goプロジェクトのソースコードリポジトリには、api/next.txtとapi/except.txtという特別なファイルが存在します。

api/next.txt: 次のメジャーリリース（例: Go 1.2、Go 1.3など）で追加される予定の新しい公開APIのリストです。Goチームは、新しいAPIを追加する際に、まずこのファイルにそのAPIのシグネチャを追記します。これにより、APIの追加が公式に記録され、レビュープロセスの一部となります。このファイルに記載されたAPIは、次のリリースで安定版として提供されることが期待されます。
api/except.txt: Go 1互換性保証の例外となるAPIのリストです。ここに記載されたAPIは、Go 1互換性保証の対象外であり、将来のリリースで変更または削除される可能性があります。これらは通常、特定のOSやアーキテクチャに特化したAPI、あるいはGoの内部実装に深く関わるAPIなど、一般的なアプリケーション開発者が直接利用することを意図していないものが含まれます。

これらのファイルは、Go言語のAPI進化を管理し、開発者に対して透明性を提供するための重要なメカニズムです。

Go言語のencodingパッケージは、様々なデータ形式（JSON, XML, Gobなど）との間でデータをエンコード/デコードするための共通インターフェースを提供します。このコミットで追加されたBinaryMarshaler, BinaryUnmarshaler, TextMarshaler, TextUnmarshalerインターフェースは、カスタム型がバイナリ形式やテキスト形式で自身をエンコード/デコードする方法を定義するためのものです。

BinaryMarshaler / BinaryUnmarshaler: 型が自身をバイナリ形式に変換したり、バイナリ形式から自身を再構築したりするためのメソッドを定義します。
TextMarshaler / TextUnmarshaler: 型が自身をテキスト形式に変換したり、テキスト形式から自身を再構築したりするためのメソッドを定義します。これは、fmt.Stringerのような単純な文字列変換とは異なり、より構造化されたテキスト表現（例: time.TimeのRFC3339形式）を意図しています。

これらのインターフェースを実装することで、カスタム型はGoの標準エンコーディングパッケージ（例: json, xml）や、その他のデータシリアライゼーションライブラリとシームレスに連携できるようになります。

`sync/atomic`パッケージのアトミック操作

sync/atomicパッケージは、低レベルのアトミックなプリミティブ操作を提供します。アトミック操作とは、複数のゴルーチンが同時にアクセスしても、その操作全体が中断されずに完了することが保証される操作のことです。これにより、ミューテックスなどのロック機構を使用せずに、共有メモリ上の変数を安全に操作できます。

このコミットで追加されたSwap関数群（SwapInt32, SwapInt64, SwapPointer, SwapUint32, SwapUint64, SwapUintptr）は、指定されたメモリ位置の値を新しい値と交換し、元の値を返すアトミック操作です。これは、ロックフリーなデータ構造やアルゴリズムを実装する際に非常に有用です。

`testing.TB`インターフェース

testingパッケージは、Go言語のテストフレームワークを提供します。testing.Tはテスト関数に渡される型で、テストの実行、ログ出力、エラー報告などを行います。testing.Bはベンチマーク関数に渡される型です。

testing.TBインターフェースは、testing.Tとtesting.Bの両方が共通して実装するメソッド群を定義します。これにより、テストとベンチマークの両方で共通のヘルパー関数を作成し、コードの重複を避けることができます。このコミットでTBインターフェースに多数のメソッドが追加されたことは、テストとベンチマークの共通機能が拡充されたことを意味します。

技術的詳細

このコミットは、Go言語の標準ライブラリにおけるAPIの進化を反映しています。具体的には、以下の主要な変更が含まれています。

encodingパッケージの汎用エンコーディング/デコーディングインターフェースの追加: BinaryMarshaler, BinaryUnmarshaler, TextMarshaler, TextUnmarshalerインターフェースが追加されました。これにより、任意のGo型が、自身をバイナリまたはテキスト形式に変換し、またその逆を行うための標準的なメカニズムを提供できるようになります。これは、json.Marshalerやxml.Marshalerのような特定のエンコーディング形式に特化したインターフェースとは異なり、より汎用的なシリアライゼーションのニーズに対応します。例えば、カスタムのデータ構造をファイルに保存したり、ネットワーク経由で送信したりする際に、これらのインターフェースを実装することで、一貫したエンコーディング/デコーディングロジックを提供できます。
sync/atomicパッケージへのSwap操作の追加: SwapInt32, SwapInt64, SwapPointer, SwapUint32, SwapUint64, SwapUintptrといったアトミックなSwap関数が追加されました。これらの関数は、指定されたポインタが指す値を新しい値とアトミックに交換し、交換前の値を返します。これは、ロックを使用せずに共有変数を更新する際に非常に重要です。例えば、参照カウンタの実装、ロックフリーキューやスタックの実装、あるいは一度だけ初期化される変数の管理などに利用できます。これにより、並行処理のパフォーマンスが向上し、デッドロックのリスクを低減できます。
testing.TBインターフェースの拡充: testing.TBインターフェースに、Error, Errorf, Fail, FailNow, Failed, Fatal, Fatalf, Log, Logf, Skip, SkipNow, Skipf, Skippedといった、testing.Tとtesting.Bの両方で利用可能なメソッドが多数追加されました。これにより、テストとベンチマークの両方で共通のロギング、エラー報告、スキップなどの機能を利用できるようになり、テストヘルパー関数の記述がより柔軟になります。例えば、共通のセットアップやクリーンアップロジックを持つヘルパー関数を作成する際に、*testing.Tまたは*testing.Bのどちらでも動作するようにtesting.TBを引数に取ることができます。
その他のAPI追加:
- archive/zip: (*File) DataOffset()メソッドが追加され、ZIPファイル内のデータオフセットを取得できるようになりました。これは、ZIPファイルの構造をより詳細に操作する必要がある場合に有用です。
- bufio: (*Reader) Reset(io.Reader)と(*Writer) Reset(io.Writer)メソッドが追加されました。これにより、既存のbufio.Readerやbufio.Writerを再利用して、新しいio.Readerまたはio.Writerに接続できるようになり、オブジェクトの再割り当てを避けてパフォーマンスを向上させることができます。
- go/build: Package構造体にAllTags []stringフィールドが追加されました。これは、Goのビルドシステムが認識するすべてのビルドタグ（例: linux, amd64, go1.1など）をパッケージ情報として提供します。
- net: IP型にMarshalText()とUnmarshalText()メソッドが追加され、IPアドレスをテキスト形式でエンコード/デコードできるようになりました。
- runtime/debug: SetMaxStack(int)とSetMaxThreads(int)関数が追加されました。これらは、Goプログラムのスタックサイズとスレッド数の上限を動的に設定するためのデバッグ目的の関数です。
- time: Time型にMarshalBinary(), UnmarshalBinary(), MarshalText(), UnmarshalText()メソッドが追加され、time.Timeオブジェクトをバイナリまたはテキスト形式でシリアライズ/デシリアライズできるようになりました。これは、encodingパッケージの新しいインターフェースと連携して動作します。

これらの変更は、Go言語がより堅牢で、高性能で、柔軟なシステムプログラミング言語として進化していることを示しています。特に、並行処理、データシリアライゼーション、テストの分野での改善が顕著です。

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

このコミット自体は、Go言語のソースコード（.goファイル）を直接変更するものではなく、GoのAPI変更を記録するテキストファイルであるapi/except.txtとapi/next.txtを更新するものです。

`api/except.txt`の変更

--- a/api/except.txt
+++ b/api/except.txt
@@ -5,5 +5,6 @@ pkg syscall (darwin-amd64), func Fchflags(string, int) error
 pkg syscall (darwin-amd64-cgo), func Fchflags(string, int) error
 pkg syscall (freebsd-386), func Fchflags(string, int) error
 pkg syscall (freebsd-amd64), func Fchflags(string, int) error
+pkg testing, func RegisterCover(Cover)
 pkg text/template/parse, type DotNode bool
 pkg text/template/parse, type Node interface { Copy, String, Type }

pkg testing, func RegisterCover(Cover) が追加されました。これは、testingパッケージのRegisterCover関数がGo 1互換性保証の対象外であることを示します。

`api/next.txt`の変更

api/next.txtには、以下の新しいAPIが追加されました。

pkg archive/zip, method (*File) DataOffset() (int64, error)
pkg bufio, method (*Reader) Reset(io.Reader)
pkg bufio, method (*Writer) Reset(io.Writer)
pkg encoding, type BinaryMarshaler interface { MarshalBinary }
pkg encoding, type BinaryMarshaler interface, MarshalBinary() ([]uint8, error)
pkg encoding, type BinaryUnmarshaler interface { UnmarshalBinary }
pkg encoding, type BinaryUnmarshaler interface, UnmarshalBinary([]uint8) error
pkg encoding, type TextMarshaler interface { MarshalText }
pkg encoding, type TextMarshaler interface, MarshalText() ([]uint8, error)
pkg encoding, type TextUnmarshaler interface { UnmarshalText }
pkg encoding, type TextUnmarshaler interface, UnmarshalText([]uint8) error
pkg encoding/xml, method (*Encoder) EncodeElement(interface{}, StartElement) error
pkg encoding/xml, method (*Encoder) EncodeToken(Token) error
pkg encoding/xml, method (StartElement) End() EndElement
pkg encoding/xml, type Marshaler interface { MarshalXML }
pkg encoding/xml, type Marshaler interface, MarshalXML(*Encoder, StartElement) error
pkg encoding/xml, type MarshalerAttr interface { MarshalXMLAttr }
pkg encoding/xml, type MarshalerAttr interface, MarshalXMLAttr(Name) (Attr, error)
pkg encoding/xml, type Unmarshaler interface { UnmarshalXML }
pkg encoding/xml, type Unmarshaler interface, UnmarshalXML(*Decoder, StartElement) error
pkg encoding/xml, type UnmarshalerAttr interface { UnmarshalXMLAttr }
pkg encoding/xml, type UnmarshalerAttr interface, UnmarshalXMLAttr(Attr) error
pkg go/build, type Package struct, AllTags []string
pkg net, method (*IP) UnmarshalText([]uint8) error
pkg net, method (IP) MarshalText() ([]uint8, error)
pkg runtime/debug, func SetMaxStack(int) int
pkg runtime/debug, func SetMaxThreads(int) int
pkg sync/atomic, func SwapInt32(*int32, int32) int32
pkg sync/atomic, func SwapInt64(*int64, int64) int64
pkg sync/atomic, func SwapPointer(*unsafe.Pointer, unsafe.Pointer) unsafe.Pointer
pkg sync/atomic, func SwapUint32(*uint32, uint32) uint32
pkg sync/atomic, func SwapUint64(*uint64, uint64) uint64
pkg sync/atomic, func SwapUintptr(*uintptr, uintptr) uintptr
pkg testing, type TB interface, Error(...interface{})
pkg testing, type TB interface, Errorf(string, ...interface{})
pkg testing, type TB interface, Fail()
pkg testing, type TB interface, FailNow()
pkg testing, type TB interface, Failed() bool
pkg testing, type TB interface, Fatal(...interface{})
pkg testing, type TB interface, Fatalf(string, ...interface{})
pkg testing, type TB interface, Log(...interface{})
pkg testing, type TB interface, Logf(string, ...interface{})
pkg testing, type TB interface, Skip(...interface{})
pkg testing, type TB interface, SkipNow()
pkg testing, type TB interface, Skipf(string, ...interface{})
pkg testing, type TB interface, Skipped() bool
pkg testing, type TB interface, unexported methods
pkg time, method (*Time) UnmarshalBinary([]uint8) error
pkg time, method (*Time) UnmarshalText([]uint8) error
pkg time, method (Time) MarshalBinary() ([]uint8, error)
pkg time, method (Time) MarshalText() ([]uint8, error)

これらのエントリは、Go 1.2リリースで導入される新しい公開APIを示しています。

コアとなるコードの解説

このコミット自体は、Go言語のランタイムや標準ライブラリの具体的な実装コードを変更するものではありません。その代わりに、GoプロジェクトのAPI管理プロセスの一部として、将来のAPI変更を文書化する役割を担っています。

api/next.txtとapi/except.txtは、Goのビルドシステムによって利用され、APIの互換性チェックが行われます。例えば、新しいAPIがapi/next.txtに記載されていない場合、または既存のAPIがapi/except.txtに記載されずに変更された場合、ビルドプロセスでエラーが発生し、APIの互換性違反が検出されます。

したがって、このコミットの「コアとなるコードの解説」は、これらのテキストファイルがGoプロジェクトのAPI管理と互換性保証において果たす役割に焦点を当てます。

api/next.txt: このファイルは、GoのAPIレビュープロセスにおいて重要な役割を果たします。新しいAPIが提案されると、まずこのファイルに追加され、Goチームのメンバーによってレビューされます。これにより、APIの設計の一貫性、命名規則の遵守、および将来の互換性への影響が評価されます。このファイルに記載されたAPIは、次のメジャーリリースで安定版として提供されることが約束されます。
api/except.txt: このファイルは、Go 1互換性保証の例外を明示的に宣言するために使用されます。ここに記載されたAPIは、Go 1互換性保証の対象外であり、GoチームはこれらのAPIを将来のリリースで変更または削除する自由を持ちます。これは通常、特定のプラットフォームに依存するAPIや、Goの内部実装に深く関連するAPIなど、一般的な開発者が直接利用することを意図していないものに適用されます。testing.RegisterCoverがここに追加されたのは、この関数がGoのテストカバレッジツールのような特定の目的のために内部的に使用されることを示唆しています。

これらのファイルは、Go言語のAPIの進化を透明かつ管理された方法で進めるための、重要なメタデータとプロセスの一部です。

参考にした情報源リンク

Go言語の公式ドキュメント
Go言語のソースコードリポジトリ（api/next.txtとapi/except.txtのファイル自体）
Go開発者メーリングリストのアーカイブ
Goの各バージョンのリリースノート
Goのencoding, sync/atomic, testingパッケージのドキュメント
Goのarchive/zip, bufio, go/build, net, runtime/debug, timeパッケージのドキュメント

comemo