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

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

このコミットは、Go言語のnetパッケージにおけるUnixドメインソケット関連のドキュメントを更新するものです。具体的には、UnixConn、UnixListener、および関連するAPIのドキュメントを修正し、プラットフォーム間のAPIドキュメントのギャップを埋めることを目的としています。

コミット

commit 8a448ef950b6756fd19d9c42cc9d70b951bcd73f
Author: Mikio Hara <mikioh.mikioh@gmail.com>
Date:   Sun Mar 31 16:48:18 2013 +0900

    net: update documentation for UnixConn, UnixListener and related stuff
    
    Closes the API documentation gap between platforms.
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/8063044

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

https://github.com/golang/go/commit/8a448ef950b6756fd19d9c42cc9d70b951bcd73f

元コミット内容

net: update documentation for UnixConn, UnixListener and related stuff

Closes the API documentation gap between platforms.

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

変更の背景

このコミットの主な背景は、Go言語のnetパッケージにおけるUnixドメインソケット関連のAPIドキュメントに、プラットフォーム間で一貫性のない記述が存在していたことです。特に、UnixConnやUnixListenerといった型、およびそれらに関連する関数のドキュメントが、異なるOS（例: Plan 9とPOSIX準拠システム）で提供される機能の記述において、微妙な差異や不足を抱えていました。

Go言語はクロスプラットフォーム開発を強く意識しており、APIの振る舞いやドキュメントは、可能な限り全てのサポート対象プラットフォームで一貫していることが望ましいとされています。このコミットは、その一貫性を高めるために、特にListenUnixgram関数のドキュメント記述を修正し、どのプラットフォームでも同じように理解できるよう調整することを目的としています。これにより、開発者が異なるOS環境でGoのネットワーク機能を利用する際に、ドキュメントの記述によって混乱が生じることを防ぎ、よりスムーズな開発体験を提供しようとしています。

前提知識の解説

Unixドメインソケット (Unix Domain Sockets, UDS)

Unixドメインソケットは、同じホストマシン上で動作するプロセス間通信 (IPC: Inter-Process Communication) の一種です。TCP/IPソケットがネットワークを介した通信に使用されるのに対し、Unixドメインソケットはファイルシステム上のパス（通常はファイル）をアドレスとして使用し、カーネルを介してプロセス間でデータを交換します。ネットワークスタックを介さないため、TCP/IPソケットよりも高速でオーバーヘッドが少ないという特徴があります。ストリーム型（TCPに類似）とデータグラム型（UDPに類似）の2種類があります。

Go言語のnetパッケージ

Go言語の標準ライブラリであるnetパッケージは、ネットワークI/Oのプリミティブを提供します。TCP/IP、UDP、Unixドメインソケットなど、様々なネットワークプロトコルを扱うための型や関数が含まれています。

  • net.UnixConn: Unixドメインソケットの接続を表す型です。データグラム型ソケットの場合、ReadFromやWriteToメソッドを使って、パケット単位で送信元/送信先アドレスを指定してデータの送受信が可能です。
  • net.UnixListener: Unixドメインソケットのリスナーを表す型です。着信接続を待ち受け、新しいUnixConnを確立するために使用されます。
  • net.ListenUnixgram: Unixデータグラムソケットをリッスンするための関数です。指定されたローカルアドレスにバインドし、データグラムパケットの受信を開始します。

ReadFromとWriteToメソッド

これらのメソッドは、データグラム指向のネットワーク接続（UDPやUnixデータグラムソケットなど）でよく使用されます。

  • ReadFrom(b []byte) (n int, addr Addr, err error): データを読み込み、そのデータがどこから来たのか（送信元アドレス）も返します。
  • WriteTo(b []byte, addr Addr) (n int, err error): データを書き込み、そのデータがどこへ送られるのか（送信先アドレス）を指定します。

これらのメソッドは、接続が確立された後も、個々のパケットに対して異なる送信元/送信先アドレスを扱う必要がある場合に特に重要です。

unixgramネットワーク

netパッケージでUnixドメインソケットを扱う際に指定するネットワークタイプの一つです。これはデータグラム型のUnixドケットを意味し、UDPのようにコネクションレスでパケット単位の通信を行います。

技術的詳細

このコミットは、Go言語のnetパッケージ内のUnixドメインソケット関連のドキュメント、特にListenUnixgram関数の説明文を修正しています。変更の核心は、ListenUnixgramが返すUnixConnのReadFromおよびWriteToメソッドに関する記述の順序と表現の調整です。

元のドキュメントでは、ListenUnixgramが返す接続cのReadFromとWriteToメソッドが「パケットごとのアドレス指定でパケットを受信および送信するために使用できる」と記述されていました。この記述自体は正しいのですが、変更後のドキュメントでは、まず「ネットワークnetは"unixgram"でなければならない」という前提条件を先に述べ、その後に「返された接続のReadFromおよびWriteToメソッドは、パケットごとのアドレス指定でパケットを受信および送信するために使用できる」と記述の順序を入れ替えています。

この変更は、単なる語順の変更以上の意味を持ちます。

  1. 明確性の向上: ListenUnixgramを使用する際の最も重要な制約であるネットワークタイプ（"unixgram"であること）を先に提示することで、関数の利用条件をより明確にしています。これにより、開発者は関数を呼び出す前に必要な前提条件をすぐに理解できます。
  2. プラットフォーム間のドキュメント一貫性: コミットメッセージにある「Closes the API documentation gap between platforms.」という記述が示すように、この変更は異なるプラットフォーム（例: unixsock_plan9.goとunixsock_posix.go）で提供されるListenUnixgramのドキュメント記述を統一することを目的としています。Goのコードベースでは、特定のOS向けのファイル（例: _plan9.go, _posix.go）にOS固有の実装やドキュメントが含まれることがありますが、APIの振る舞いに関する高レベルなドキュメントは一貫しているべきです。この修正は、その一貫性を確保するためのものです。
  3. 冗長なコメントの削除: src/pkg/net/unixsock.go、src/pkg/net/unixsock_plan9.go、src/pkg/net/unixsock_posix.goの各ファイルから、冒頭の「Unix domain sockets」や「Unix domain sockets stubs for Plan 9」といった一般的なコメントが削除されています。これらのコメントは、ファイルの内容を説明するものでしたが、パッケージレベルのドキュメントやファイル名自体から十分に推測できるため、冗長と判断された可能性があります。これにより、コードの簡潔性が向上しています。

全体として、このコミットは機能的な変更ではなく、Goの標準ライブラリのドキュメント品質と一貫性を向上させるための、細部への配慮がなされた改善です。

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

diff --git a/src/pkg/net/unixsock.go b/src/pkg/net/unixsock.go
index 977ff91031..21a19eca2c 100644
--- a/src/pkg/net/unixsock.go
+++ b/src/pkg/net/unixsock.go
@@ -2,8 +2,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.\n 
-// Unix domain sockets
-\n package net
 \n // UnixAddr represents the address of a Unix domain socket end point.
 diff --git a/src/pkg/net/unixsock_plan9.go b/src/pkg/net/unixsock_plan9.go
index 00a0be5b08..0390207f0f 100644
--- a/src/pkg/net/unixsock_plan9.go
+++ b/src/pkg/net/unixsock_plan9.go
@@ -2,8 +2,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.\n 
-// Unix domain sockets stubs for Plan 9
-\n package net
 \n import (
 @@ -133,9 +131,9 @@ func (l *UnixListener) File() (*os.File, error) {
 }\n \n // ListenUnixgram listens for incoming Unix datagram packets addressed
-// to the local address laddr.  The returned connection c\'s ReadFrom
-// and WriteTo methods can be used to receive and send packets with
-// per-packet addressing.  The network net must be \"unixgram\".
+// to the local address laddr.  The network net must be \"unixgram\".
+// The returned connection\'s ReadFrom and WriteTo methods can be used
+// to receive and send packets with per-packet addressing.
 func ListenUnixgram(net string, laddr *UnixAddr) (*UnixConn, error) {
 \treturn nil, syscall.EPLAN9
 }\ndiff --git a/src/pkg/net/unixsock_posix.go b/src/pkg/net/unixsock_posix.go
index abdff09a8a..760d38f273 100644
--- a/src/pkg/net/unixsock_posix.go
+++ b/src/pkg/net/unixsock_posix.go
@@ -4,8 +4,6 @@
 \n // +build darwin freebsd linux netbsd openbsd windows
 \n-// Unix domain sockets
-\n package net
 \n import (
 @@ -344,9 +342,9 @@ func (l *UnixListener) SetDeadline(t time.Time) (err error) {\n func (l *UnixListener) File() (f *os.File, err error) { return l.fd.dup() }\n \n // ListenUnixgram listens for incoming Unix datagram packets addressed
-// to the local address laddr.  The returned connection c\'s ReadFrom
-// and WriteTo methods can be used to receive and send packets with
-// per-packet addressing.  The network net must be \"unixgram\".
+// to the local address laddr.  The network net must be \"unixgram\".
+// The returned connection\'s ReadFrom and WriteTo methods can be used
+// to receive and send packets with per-packet addressing.
 func ListenUnixgram(net string, laddr *UnixAddr) (*UnixConn, error) {
 \tswitch net {\n \tcase \"unixgram\":

コアとなるコードの解説

このコミットでは、主に3つのファイルで変更が行われています。

  1. src/pkg/net/unixsock.go:

    • // Unix domain sockets というコメント行が削除されました。これは、このファイルがUnixドメインソケットに関連するものであることを示す一般的なコメントでしたが、パッケージ名やファイル名からその役割は明らかであるため、冗長と判断されたようです。

  2. src/pkg/net/unixsock_plan9.go:

    • // Unix domain sockets stubs for Plan 9 というコメント行が削除されました。これも同様に冗長なコメントの削除です。
    • ListenUnixgram関数のドキュメントコメントが変更されました。
      • 変更前: The returned connection c's ReadFrom and WriteTo methods can be used to receive and send packets with per-packet addressing. The network net must be "unixgram".
      • 変更後: The network net must be "unixgram". The returned connection's ReadFrom and WriteTo methods can be used to receive and send packets with per-packet addressing.
      • この変更は、ListenUnixgramを使用する際の必須条件である「ネットワークnetが"unixgram"であること」を先に記述し、その後に返される接続のメソッドに関する説明を続けることで、ドキュメントの論理的な流れを改善し、より明確にしています。

  3. src/pkg/net/unixsock_posix.go:

    • // Unix domain sockets というコメント行が削除されました。これも冗長なコメントの削除です。
    • ListenUnixgram関数のドキュメントコメントがunixsock_plan9.goと同様に変更されました。これにより、Plan 9とPOSIX準拠システム（darwin, freebsd, linux, netbsd, openbsd, windows）の両方で、ListenUnixgramのドキュメントが一貫したものになりました。

これらの変更は、Goの標準ライブラリのドキュメント品質と、異なるプラットフォーム間でのAPIドキュメントの一貫性を向上させるためのものです。機能的な変更は一切なく、純粋にドキュメントの改善に焦点を当てています。

関連リンク

参考にした情報源リンク