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

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

このコミットは、Go 1.1のリリースノートドキュメントである doc/go1.1.html に、net パッケージに追加された新しいネットワーク接続オプション設定機能 DialOpt および関連する DialOption インターフェース、そしてそれらを生成するヘルパー関数（Deadline, Timeout, Network, LocalAddress）に関する記述を追加するものです。これにより、Go 1.1で導入されたこれらの重要なAPI変更が公式ドキュメントに反映され、ユーザーが新しい機能について理解できるようになります。

コミット

commit fc4c5b14ef6906f981bf199a78c08942388fc03c
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Mon Mar 25 10:31:19 2013 -0700

    doc: add DialOpt and friends to go1.1.html
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/7725048

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

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

元コミット内容

doc: add DialOpt and friends to go1.1.html

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/7725048

変更の背景

Go言語の net パッケージにおける Dial 関数は、ネットワーク接続を確立するための基本的な機能を提供します。しかし、初期のバージョンでは Dial 関数の引数が固定されており、接続のタイムアウト設定、特定のネットワークインターフェースのバインド、特定のネットワークタイプ（TCP, UDPなど）の指定といった詳細な接続オプションを柔軟に設定することが困難でした。

Go 1.1では、この柔軟性の欠如を解消するために、Dial 関数にオプションを渡す新しいメカニズムが導入されました。これが DialOpt 関数と DialOption インターフェースです。この変更により、ユーザーは Dial 関数を呼び出す際に、複数のオプションをチェーンして渡すことができるようになり、より細かくネットワーク接続の挙動を制御できるようになりました。

このコミットは、Go 1.1のリリースノートドキュメント (go1.1.html) に、この新しい DialOpt および関連機能に関する公式な説明を追加することを目的としています。これにより、Go 1.1へのアップグレードを検討している開発者や、新機能について学びたい開発者が、これらの重要な変更点を容易に把握できるようになります。

前提知識の解説

Go言語の net パッケージ

net パッケージは、Go言語におけるネットワークI/Oの主要なインターフェースを提供します。TCP/IP、UDP、Unixドメインソケットなどのネットワークプロトコルを扱うための基本的な機能（接続の確立、データの送受信、リスニングなど）が含まれています。

  • net.Dial 関数: 最も基本的なネットワーク接続確立関数です。通常、Dial(network, address string) の形式で呼び出され、指定されたネットワーク（例: "tcp", "udp"）とアドレス（例: "localhost:8080"）に対して接続を試みます。成功すると net.Conn インターフェースを返します。

オプションパターン (Option Pattern)

Go言語では、関数の引数が多くなったり、将来的に引数を追加する可能性がある場合に、「オプションパターン」と呼ばれる設計パターンがよく用いられます。これは、関数に直接多くの引数を渡すのではなく、オプションを表す構造体やインターフェース、あるいは関数型オプション（Functional Options）を引数として渡す方法です。

このコミットで導入された DialOption インターフェースは、このオプションパターンの一種です。DialOption インターフェースを実装する型が、DialOpt 関数を通じて Dial 関数に渡され、接続の挙動をカスタマイズします。これにより、Dial 関数のシグネチャを変更することなく、将来的に新しい接続オプションを追加することが可能になります。

Go 1 互換性保証

Go言語は、Go 1リリース以降、互換性保証を非常に重視しています。これは、Go 1で書かれたプログラムが、将来のGoのバージョンでもコンパイルされ、動作し続けることを意味します。しかし、バグ修正やセキュリティ修正、あるいは既存のAPIの欠陥を修正するために、ごく稀にAPIの変更が許容される場合があります。このコミットメッセージにある「Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.」という記述は、Dial 関数の柔軟性の欠如が一種の「バグ」と見なされ、その修正のために新しいAPIが導入されたことを示唆しています。

技術的詳細

Go 1.1で導入された net パッケージの新しいネットワーク接続オプション機能は、主に以下の要素で構成されます。

  1. net.DialOpt 関数: これは net.Dial 関数とは異なり、DialOption を引数に取り、それらのオプションを適用した上でネットワーク接続を確立する新しい関数です。これにより、Dial の基本的な機能に加えて、より高度な設定が可能になります。

  2. net.DialOption インターフェース: このインターフェースは、ネットワーク接続のオプションを表します。具体的な実装は net パッケージ内部で行われ、ユーザーは直接このインターフェースを実装することは通常ありません。代わりに、後述するヘルパー関数を使って DialOption のインスタンスを取得します。

  3. DialOption を返すヘルパー関数: net パッケージには、特定の接続オプションを設定するための DialOption インターフェースを実装した値を返すヘルパー関数がいくつか追加されました。これらは、ユーザーが簡単に DialOpt 関数に渡せるオプションを作成するために提供されます。

    • net.Deadline(t time.Time): 接続試行の絶対的なデッドライン（期限）を設定します。指定された時刻までに接続が確立できない場合、接続試行は失敗します。これは、接続がいつまでも完了しない状況を防ぐために使用されます。

    • net.Timeout(d time.Duration): 接続試行の相対的なタイムアウト期間を設定します。指定された期間内に接続が確立できない場合、接続試行は失敗します。Deadline が絶対時刻であるのに対し、Timeout は現在時刻からの相対的な期間です。

    • net.Network(network string): 接続に使用するネットワークプロトコル（例: "tcp", "tcp4", "tcp6", "udp", "udp4", "udp6", "unix", "unixgram", "unixpacket"）を指定します。これにより、DialOpt 関数に渡されるネットワークタイプを明示的に制御できます。

    • net.LocalAddress(addr net.Addr): 接続元のローカルアドレスを指定します。これにより、特定のネットワークインターフェースやIPアドレスから接続を開始するように強制できます。例えば、複数のネットワークインターフェースを持つサーバーで、特定のインターフェースから外部に接続したい場合に有用です。

これらの機能が連携することで、開発者は DialOpt(Network("tcp4"), Timeout(5*time.Second), LocalAddress(localAddr), "example.com:80") のように、複数のオプションを組み合わせて柔軟なネットワーク接続を確立できるようになりました。

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

このコミットは、Go 1.1のリリースノートドキュメントである doc/go1.1.html ファイルに対して行われました。

--- a/doc/go1.1.html
+++ b/doc/go1.1.html
@@ -707,6 +707,19 @@ clearly a mistake in Go 1.0.
 Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
 </li>
 
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package includes a new function,
+<a href="/pkg/net/#DialOpt"><code>DialOpt</code></a>, to supply options to
+<a href="/pkg/net/#Dial"><code>Dial</code></a>.
+Each option is represented by a new
+<a href="/pkg/net/#DialOption"><code>DialOption</code></a> interface.
+The new functions
+<a href="/pkg/net/#Deadline"><code>Deadline</code></a>,
+<a href="/pkg/net/#Timeout"><code>Timeout</code></a>,
+<a href="/pkg/net/#Network"><code>Network</code></a>, and
+<a href="/pkg/net/#LocalAddress"><code>LocalAddress</code></a> return a <code>DialOption</code>.
+</li>
+
 <li>
 The new <a href="/pkg/net/http/cookiejar/">net/http/cookiejar</a> package provides the basics for managing HTTP cookies.
 </li>
@@ -732,7 +745,7 @@ which do ASCII-only trimming of leading and trailing spaces.
 </li>
 
 <li> TODO:
-<code>net</code>: DialOption, DialOpt, ListenUnixgram, LookupNS, IPConn.ReadMsgIP, IPConn.WriteMsgIP, UDPConn.ReadMsgUDP, UDPConn.WriteMsgUDP, UnixConn.CloseRead, UnixConn.CloseWrite
+<code>net</code>: ListenUnixgram, LookupNS, IPConn.ReadMsgIP, IPConn.WriteMsgIP, UDPConn.ReadMsgUDP, UDPConn.WriteMsgUDP, UnixConn.CloseRead, UnixConn.CloseWrite
 </li>
 
 <li>

具体的には、以下の変更が行われました。

  1. 新規項目の追加: go1.1.html の既存のリスト項目（<li>）の間に、net パッケージの新しい DialOpt 関数と DialOption インターフェース、および関連するヘルパー関数（Deadline, Timeout, Network, LocalAddress）に関する新しいリスト項目が追加されました。この項目は、これらの新機能の概要と、それらがどのように連携して Dial 関数にオプションを提供するのかを説明しています。

  2. TODOリストの更新: 以前のTODOリストには、まだドキュメント化されていない net パッケージの機能として DialOption と DialOpt が含まれていました。今回のコミットでこれらの機能がドキュメントに追加されたため、TODOリストからこれらの項目が削除されました。

コアとなるコードの解説

追加されたHTMLスニペットは、Go 1.1のリリースノートにおいて、net パッケージの重要な変更点をユーザーに伝えるためのものです。

<li>
The <a href="/pkg/net/"><code>net</code></a> package includes a new function,
<a href="/pkg/net/#DialOpt"><code>DialOpt</code></a>, to supply options to
<a href="/pkg/net/#Dial"><code>Dial</code></a>.
Each option is represented by a new
<a href="/pkg/net/#DialOption"><code>DialOption</code></a> interface.
The new functions
<a href="/pkg/net/#Deadline"><code>Deadline</code></a>,
<a href="/pkg/net/#Timeout"><code>Timeout</code></a>,
<a href="/pkg/net/#Network"><code>Network</code></a>, and
<a href="/pkg/net/#LocalAddress"><code>LocalAddress</code></a> return a <code>DialOption</code>.
</li>

このHTMLコードは、以下の情報を簡潔にまとめています。

  • net パッケージの変更: net パッケージに新しい機能が追加されたことを明示しています。
  • DialOpt 関数の導入: Dial 関数にオプションを供給するための新しい関数 DialOpt が導入されたことを説明しています。これは、従来の Dial 関数では難しかった詳細な接続設定を可能にするためのものです。
  • DialOption インターフェース: 各オプションが DialOption という新しいインターフェースによって表現されることを示しています。これにより、オプションの追加や拡張が容易になります。
  • DialOption を生成するヘルパー関数: Deadline, Timeout, Network, LocalAddress といった新しい関数が DialOption を返すことを説明しています。これらの関数は、ユーザーが具体的なオプション値を簡単に作成し、DialOpt 関数に渡せるようにするためのユーティリティです。

このドキュメントの追加により、Go 1.1のユーザーは、ネットワーク接続の挙動をより細かく制御できるようになったことを認識し、これらの新しいAPIを効果的に利用するための手がかりを得ることができます。

関連リンク

  • Go 1.1 Release Notes (公式ドキュメント): https://go.dev/doc/go1.1 (このコミットが変更したファイルの内容を含む、Go 1.1の公式リリースノート)
  • Go net package documentation: https://pkg.go.dev/net (Goの net パッケージの最新ドキュメント。DialOpt や DialOption の詳細なAPIリファレンスが含まれる)

参考にした情報源リンク