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

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

このコミットは、Go言語の次期リリース（Go 1.1.xまたはそれ以降）で導入される予定のAPI変更を記録するapi/next.txtファイルを更新するものです。api/next.txtは、GoのAPI互換性ポリシーに従い、将来のリリースで追加または変更される公開API要素を追跡するために使用されます。このファイルへの変更は、Goの標準ライブラリに新しい機能が追加されたり、既存のAPIが改善されたりしたことを示しています。

コミット

commit 3c0a5b8636409ca69f6afa8309e6cbe299a5af1d
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Wed Apr 3 10:41:28 2013 -0700

    api: update next.txt.
    
    Update #4871
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/8287044

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

https://github.com/golang/go/commit/3c0a5b8636409ca69f6afa8309e6cbe299a5af1d

元コミット内容

このコミットの元々の内容は、api/next.txtファイルを更新することです。具体的には、Goの標準ライブラリにおけるいくつかの新しいAPI要素の追加と、既存のAPIの変更（主にnetパッケージにおける接続オプションの再設計とgo/docパッケージのノート構造の改善）が反映されています。

変更の背景

このコミットの背景には、Go言語の標準ライブラリの継続的な改善と機能拡張があります。api/next.txtは、Goのリリースプロセスにおいて重要な役割を果たします。Goは厳格なGo 1 Compatibility Promiseを持っており、Go 1.xリリースでは既存の公開APIの互換性を維持することが保証されています。しかし、新しい機能の追加や既存のAPIの改善は常に行われており、それらの変更はapi/next.txtに記録されます。

このコミットで追加されたAPIは、それぞれ特定のユースケースや改善要求に対応しています。例えば、database/sqlパッケージへのPingメソッドの追加はデータベース接続の健全性チェックを容易にし、SetMaxIdleConnsはデータベース接続プールの管理を改善します。netパッケージにおけるDialer構造体の導入は、ネットワーク接続の確立におけるオプション設定をより柔軟かつ統一的に行うための再設計です。また、go/docパッケージの変更は、ドキュメンテーション生成におけるノート（コメント内の特定の形式のメモ）の扱いをより構造化するためのものです。

前提知識の解説

  • Go 1 Compatibility Promise: Go言語のバージョン1以降のリリースにおいて、既存のプログラムが新しいバージョンでも動作し続けることを保証するポリシーです。これにより、Goのエコシステムは安定性を保ちつつ進化できます。ただし、新しいAPIの追加や内部実装の変更は行われます。
  • api/next.txt: Goプロジェクト内で管理されているテキストファイルで、次期Goリリースで導入される予定の公開APIの変更（追加、削除、変更）がリストアップされています。GoのAPI互換性チェックツールはこのファイルを参照し、互換性が維持されているかを確認します。
  • Goの標準ライブラリ: Go言語に同梱されている豊富なパッケージ群で、ネットワーキング、ファイルI/O、暗号化、データ構造など、幅広い機能を提供します。Goアプリケーション開発の基盤となります。
  • compress/gzipパッケージ: GZIP形式の圧縮データを読み書きするための機能を提供します。
  • database/sqlパッケージ: データベースにアクセスするための汎用的なインターフェースを提供します。特定のデータベースドライバに依存しない抽象化レイヤーです。
  • encoding/xmlパッケージ: XMLデータをエンコードおよびデコードするための機能を提供します。
  • go/buildパッケージ: Goのパッケージビルドプロセスに関する情報（Goソースファイルの解析、依存関係の解決など）を提供します。
  • go/docパッケージ: Goのソースコードからドキュメンテーションを生成するための機能を提供します。
  • netパッケージ: ネットワークI/Oのプリミティブを提供します。TCP/IP、UDP、Unixドメインソケットなどのネットワークプロトコルを扱います。
  • os/signalパッケージ: プロセスに送信されるシグナル（例: Ctrl+Cによる割り込み）を処理するための機能を提供します。

技術的詳細

このコミットは、api/next.txtの変更を通じて、Go標準ライブラリの複数のパッケージにおけるAPIの進化を示しています。

  1. compress/gzipパッケージ:

    • pkg compress/gzip, method (*Writer) Flush() error の追加: gzip.WriterにFlush()メソッドが追加されました。これにより、圧縮バッファの内容を強制的に基になるio.Writerに書き出すことができるようになります。これは、リアルタイム性の高いデータストリーム処理や、部分的に圧縮データを送信する必要がある場合に有用です。

  2. database/sqlパッケージ:

    • pkg database/sql, method (*DB) Ping() error の追加: sql.DBにPing()メソッドが追加されました。これは、データベースへの接続がまだ有効であるか、または確立可能であるかをチェックするために使用されます。アプリケーションがデータベースとの接続を維持していることを確認したり、接続が切断された場合に再接続を試みたりする際に役立ちます。
    • pkg database/sql, method (*DB) SetMaxIdleConns(int) の追加: sql.DBにSetMaxIdleConns()メソッドが追加されました。これは、アイドル状態の接続プールに保持される最大接続数を設定します。これにより、データベース接続の再利用が促進され、接続確立のオーバーヘッドが削減されます。

  3. encoding/xmlパッケージ:

    • pkg encoding/xml, type Decoder struct, DefaultSpace string の追加: xml.Decoder構造体にDefaultSpaceフィールドが追加されました。これは、XML要素のデフォルトの名前空間URIを設定するために使用されます。これにより、名前空間が明示的に指定されていないXML要素の処理が容易になります。

  4. go/buildパッケージ:

    • pkg go/build, type Context struct, InstallTag string の削除と pkg go/build, type Context struct, InstallSuffix string の追加: Context構造体のInstallTagフィールドがInstallSuffixに名称変更されました。これは、ビルド成果物のインストールパスに付加されるサフィックスをより正確に表現するための変更です。
    • pkg go/build, type Context struct, ReleaseTags []string の追加: Context構造体にReleaseTagsフィールドが追加されました。これは、特定のGoリリースバージョンに関連付けられたビルドタグ（例: go1.1, go1.2など）を管理するために使用されます。これにより、特定のGoバージョン向けに条件付きでコードをコンパイルする際に役立ちます。

  5. go/docパッケージ:

    • pkg go/doc, type Package struct, Notes map[string][]string の削除と、pkg go/doc, type Note struct および関連フィールドの追加、pkg go/doc, type Package struct, Notes map[string][]*Note の追加: go/docパッケージにおけるドキュメンテーションノートの表現が、より構造化されたNote型に置き換えられました。以前は単なる文字列のスライスでしたが、新しいNote型はBody（ノートの内容）、End、Pos（ソースコード内の位置）、UID（ユニークID）などのフィールドを持つようになりました。これにより、ドキュメンテーションツールがノートをより詳細に解析し、表示できるようになります。

  6. netパッケージ:

    • DialOptionインターフェースおよび関連するDialOpt, Deadline, LocalAddress, Network, Timeout関数、TCP, UDP変数の削除: 以前のDialOptionベースの接続オプション設定メカニズムが削除されました。
    • pkg net, type Dialer struct および関連フィールド（Deadline, LocalAddr, Timeout）の追加、pkg net, method (*Dialer) Dial(string, string) (Conn, error) の追加: ネットワーク接続の確立方法が、新しいDialer構造体とそのDialメソッドに集約されました。Dialer構造体は、接続のタイムアウト、ローカルアドレスのバインド、デッドラインなどのオプションをフィールドとして持ちます。これにより、接続オプションの管理がよりオブジェクト指向的かつ柔軟になり、将来的な拡張性も向上します。これは、Go 1.1で導入された重要な変更点の一つです。

  7. os/signalパッケージ:

    • pkg os/signal, func Stop(chan<- os.Signal) の追加: signal.Stop()関数が追加されました。これは、signal.Notify()で登録された特定のシグナルチャネルへのシグナル配信を停止するために使用されます。これにより、シグナルハンドリングのライフサイクル管理がより細かく制御できるようになります。

これらの変更は、Go言語が成熟し、より多様なユースケースに対応するために、標準ライブラリが継続的に改善されていることを示しています。特にnetパッケージのDialerへの移行は、ネットワークプログラミングにおける柔軟性と堅牢性を高めるための重要な再設計です。

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

このコミット自体は、Goのソースコードではなく、GoのAPI変更を記録するapi/next.txtファイルのみを変更しています。したがって、直接的なGoのコアコードの変更はありません。

api/next.txtの変更内容は以下の通りです。

--- a/api/next.txt
+++ b/api/next.txt
@@ -28,6 +28,7 @@ pkg bytes, func TrimPrefix([]uint8, []uint8) []uint8
 pkg bytes, func TrimSuffix([]uint8, []uint8) []uint8
 pkg bytes, method (*Buffer) Grow(int)
 pkg bytes, method (*Reader) WriteTo(io.Writer) (int64, error)
+pkg compress/gzip, method (*Writer) Flush() error
 pkg crypto/hmac, func Equal([]uint8, []uint8) bool
 pkg crypto/tls, const TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA uint16
 pkg crypto/tls, const TLS_RSA_WITH_AES_256_CBC_SHA uint16
@@ -61,6 +62,8 @@ pkg crypto/x509, type PEMCipher int
 pkg crypto/x509, type SystemRootsError struct
 pkg crypto/x509, type VerifyOptions struct, KeyUsages []ExtKeyUsage
 pkg crypto/x509, var IncorrectPasswordError error
+pkg database/sql, method (*DB) Ping() error
+pkg database/sql, method (*DB) SetMaxIdleConns(int)
 pkg database/sql/driver, type Queryer interface { Query }
 pkg database/sql/driver, type Queryer interface, Query(string, []Value) (Rows, error)
 pkg debug/elf, method (*File) DynString(DynTag) ([]string, error)
@@ -89,6 +92,7 @@ pkg encoding/json, method (Number) String() string
 pkg encoding/json, type Number string
 pkg encoding/xml, func EscapeText(io.Writer, []uint8) error
 pkg encoding/xml, method (*Encoder) Indent(string, string)
+pkg encoding/xml, type Decoder struct, DefaultSpace string
 pkg go/ast, func NewCommentMap(*token.FileSet, Node, []*CommentGroup) CommentMap
 pkg go/ast, method (CommentMap) Comments() []*CommentGroup
 pkg go/ast, method (CommentMap) Filter(Node) CommentMap
@@ -96,14 +100,20 @@ pkg go/ast, method (CommentMap) String() string
 pkg go/ast, method (CommentMap) Update(Node, Node) Node
 pkg go/ast, type ChanType struct, Arrow token.Pos
 pkg go/ast, type CommentMap map[Node][]*CommentGroup
-pkg go/build, type Context struct, InstallTag string
+pkg go/build, type Context struct, InstallSuffix string
+pkg go/build, type Context struct, ReleaseTags []string
 pkg go/build, type Package struct, IgnoredGoFiles []string
 pkg go/build, type Package struct, SwigCXXFiles []string
 pkg go/build, type Package struct, SwigFiles []string
 pkg go/doc, type Example struct, EmptyOutput bool
 pkg go/doc, type Example struct, Order int
 pkg go/doc, type Example struct, Play *ast.File
-pkg go/doc, type Package struct, Notes map[string][]string
+pkg go/doc, type Note struct
+pkg go/doc, type Note struct, Body string
+pkg go/doc, type Note struct, End token.Pos
+pkg go/doc, type Note struct, Pos token.Pos
+pkg go/doc, type Note struct, UID string
+pkg go/doc, type Package struct, Notes map[string][]*Note
 pkg go/doc, var IllegalPrefixes []string
 pkg go/format, func Node(io.Writer, *token.FileSet, interface{}) error
 pkg go/format, func Source([]uint8) ([]uint8, error)
@@ -339,27 +349,24 @@ pkg math/big, method (*Int) UnmarshalJSON([]uint8) error
 pkg math/big, method (*Rat) Float64() (float64, bool)
 pkg math/big, method (*Rat) SetFloat64(float64) *Rat
 pkg mime/multipart, method (*Writer) SetBoundary(string) error
-pkg net, func Deadline(time.Time) DialOption
-pkg net, func DialOpt(string, ...DialOption) (Conn, error)
 pkg net, func ListenUnixgram(string, *UnixAddr) (*UnixConn, error)
-pkg net, func LocalAddress(Addr) DialOption
 pkg net, func LookupNS(string) ([]*NS, error)
-pkg net, func Network(string) DialOption
-pkg net, func Timeout(time.Duration) DialOption
+pkg net, method (*Dialer) Dial(string, string) (Conn, error)
 pkg net, method (*IPConn) ReadMsgIP([]uint8, []uint8) (int, int, int, *IPAddr, error)
 pkg net, method (*IPConn) WriteMsgIP([]uint8, []uint8, *IPAddr) (int, int, error)
 pkg net, method (*UDPConn) ReadMsgUDP([]uint8, []uint8) (int, int, int, *UDPAddr, error)
 pkg net, method (*UDPConn) WriteMsgUDP([]uint8, []uint8, *UDPAddr) (int, int, error)
 pkg net, method (*UnixConn) CloseRead() error
 pkg net, method (*UnixConn) CloseWrite() error
-pkg net, type DialOption interface, unexported methods
+pkg net, type Dialer struct
+pkg net, type Dialer struct, Deadline time.Time
+pkg net, type Dialer struct, LocalAddr Addr
+pkg net, type Dialer struct, Timeout time.Duration
 pkg net, type IPAddr struct, Zone string
 pkg net, type NS struct
 pkg net, type NS struct, Host string
 pkg net, type TCPAddr struct, Zone string
 pkg net, type UDPAddr struct, Zone string
-pkg net, var TCP DialOption
-pkg net, var UDP DialOption
 pkg net/http, func ParseTime(string) (time.Time, error)
 pkg net/http, method (*Request) PostFormValue(string) string
 pkg net/http, method (*ServeMux) Handler(*Request) (Handler, string)
@@ -384,6 +391,7 @@ pkg net/smtp, method (*Client) Hello(string) error
 pkg net/textproto, func TrimBytes([]uint8) []uint8
 pkg net/textproto, func TrimString(string) string
 pkg os, method (FileMode) IsRegular() bool
+pkg os/signal, func Stop(chan<- os.Signal)
 pkg reflect, const SelectDefault SelectDir
 pkg reflect, const SelectRecv SelectDir
 pkg reflect, const SelectSend SelectDir

コアとなるコードの解説

このコミットは、GoのAPI互換性チェックのメカニズムの一部であるapi/next.txtファイルを更新するものです。このファイル自体は実行可能なコードではありませんが、Goの標準ライブラリの公開APIがどのように進化しているかを示す重要なドキュメントです。

api/next.txtの各行は、pkg <package_path>, <type_or_func_signature>の形式で、Goの公開API要素を表します。このファイルに追加された行は新しいAPI要素の導入を、削除された行は既存API要素の削除または変更（通常はより新しいAPIへの置き換え）を示します。

このコミットで追加・削除された各API要素の具体的なコード変更は、このコミットの範囲外で行われた、それぞれの機能追加や改善を実装する別のコミットによって導入されています。このapi/next.txtの更新は、それらの変更がGoのAPI互換性ポリシーに準拠していることを公式に記録するステップです。

例えば、pkg database/sql, method (*DB) Ping() errorが追加されたということは、database/sqlパッケージのDB型にPingメソッドが追加された実際のGoコードの変更が、このapi/next.txtの更新よりも前に（または同時に）行われていることを意味します。

特に注目すべきはnetパッケージの変更です。これは、以前の関数ベースのDialOptionメカニズムから、より構造化されたDialer型とそれに関連するメソッドへの移行を示しています。これにより、ネットワーク接続の確立におけるオプション設定がより柔軟かつ統一的に扱えるようになります。これは、Go 1.1リリースにおける重要なAPIの再設計の一つでした。

関連リンク

参考にした情報源リンク

  • Goの公式ドキュメンテーション
  • Goのソースコードリポジトリ (特にapi/next.txtの履歴と、関連するパッケージのソースコード)
  • GoのメーリングリストやIssueトラッカー (コミットメッセージに記載されているIssue #4871やCL 8287044など)
  • Go 1.1のリリースノートや関連するブログ記事 (当時の情報源)