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

このコミットは、Go言語の標準ライブラリであるnetパッケージ内のReadMsgUnixおよびWriteMsgUnix関数のドキュメントを改善することを目的としています。具体的には、これらの関数の引数と戻り値に関する説明が追加され、より明確なAPIリファレンスが提供されています。

コミット

commit e38c5fb23da137c822455126628a5b2bb68fc440
Author: Russ Cox <rsc@golang.org>
Date:   Thu Mar 8 08:36:40 2012 -0500

    net: document ReadMsgUnix, WriteMsgUnix
    
    Fixes #3247.
    
    R=golang-dev, jsing
    CC=golang-dev
    https://golang.org/cl/5784051

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

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

元コミット内容

net: document ReadMsgUnix, WriteMsgUnix

Fixes #3247.

R=golang-dev, jsing
CC=golang-dev
https://golang.org/cl/5784051

変更の背景

このコミットは、Go言語のIssue #3247を修正するために行われました。Issue #3247は、netパッケージのReadMsgUnixおよびWriteMsgUnix関数に関するドキュメントが不足している、または不明確であるという問題提起でした。これらの関数はUnixドメインソケットにおける高度なメッセージ送受信（特に補助データ、out-of-band dataの扱い）を扱うため、その利用方法を正確に理解するためには詳細なドキュメントが不可欠です。

既存のReadFromUnix関数のドキュメントも、戻り値に関する記述が「return address」から「source address」へと修正されており、より正確な表現に改善されています。これは、APIの意図をより明確に伝えるための一般的なドキュメント改善の一環と考えられます。

前提知識の解説

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

Unixドメインソケットは、同じホストマシン上で動作するプロセス間通信 (IPC: Inter-Process Communication) の一種です。TCP/IPソケットがネットワークを介した通信に使用されるのに対し、Unixドメインソケットはファイルシステム上のパス名（例: /tmp/mysocket）をアドレスとして使用し、カーネル内で直接データをやり取りするため、ネットワークオーバーヘッドがなく、非常に高速です。

Unixドメインソケットは、ストリーム型（TCPに類似）とデータグラム型（UDPに類似）の2種類があります。このコミットで関連するReadMsgUnixやWriteMsgUnixは、データグラム型ソケットや、ストリーム型ソケットで補助データ（ancillary data）をやり取りする際に特に重要になります。

補助データ (Ancillary Data / Out-of-Band Data)

ソケット通信において、通常のデータ（ペイロード）とは別に、制御情報やファイルディスクリプタなどの特殊な情報を送受信するメカニズムを「補助データ」または「out-of-band data」と呼びます。Unixドメインソケットでは、sendmsg()やrecvmsg()システムコールを使用して、この補助データをやり取りできます。

補助データの一般的な用途には以下のようなものがあります。

• ファイルディスクリプタの転送: あるプロセスが開いているファイルディスクリプタを別のプロセスに渡すことができます。これは、特権分離されたプロセス間でリソースを共有する際に非常に有用です。
• 認証情報: ピアのユーザーIDやグループIDなどの認証情報を転送できます。
• ソケットオプション: ソケットに関する特定のオプション情報をやり取りできます。

Go言語のnetパッケージでは、これらの補助データをバイトスライスoob（out-of-bandの略）として扱います。

ReadMsgUnixとWriteMsgUnix関数

GoのnetパッケージにおけるReadMsgUnixとWriteMsgUnixは、Unixドメインソケットを介してメッセージと補助データを送受信するための低レベルAPIです。

• ReadMsgUnix(b, oob []byte) (n, oobn, flags int, addr *UnixAddr, err error):

  • b: 受信したペイロードデータが格納されるバイトスライス。
  • oob: 受信した補助データが格納されるバイトスライス。
  • n: bにコピーされたペイロードのバイト数。
  • oobn: oobにコピーされた補助データのバイト数。
  • flags: 受信メッセージに関連するフラグ（例: MSG_TRUNC, MSG_CTRUNCなど）。
  • addr: 送信元のアドレス。
  • err: エラー情報。

• WriteMsgUnix(b, oob []byte, addr *UnixAddr) (n, oobn int, err error):

  • b: 送信するペイロードデータを含むバイトスライス。
  • oob: 送信する補助データを含むバイトスライス。
  • addr: 送信先のアドレス。
  • n: 送信されたペイロードのバイト数。
  • oobn: 送信された補助データのバイト数。
  • err: エラー情報。

これらの関数は、Unixドメインソケットの高度な機能、特にファイルディスクリプタの転送などを実装する際に不可欠です。

技術的詳細

このコミットの技術的詳細は、Go言語のドキュメンテーション慣習と、UnixドメインソケットのAPIの正確な表現に焦点を当てています。

Go言語では、エクスポートされた関数、変数、型などには、その直前にコメントを記述することでドキュメントとして扱われます。このコメントはgo docコマンドやGoの公式ドキュメントサイト（pkg.go.devなど）で参照されます。したがって、ドキュメントコメントの正確性と網羅性は非常に重要です。

変更点を見ると、ReadMsgUnixとWriteMsgUnixの関数シグネチャの直前に、それぞれの引数と戻り値の意味を詳細に説明するコメントが追加されています。

• ReadMsgUnixのドキュメントでは、b、oob、n、oobn、flags、addrの各戻り値が何を表すのかが明確に記述されています。特に、oobが「associated out-of-band data」であること、flagsが「flags that were set on the packet」であること、そしてaddrが「source address of the packet」であることが強調されています。
• WriteMsgUnixのドキュメントでは、bとoobがそれぞれ「payload from b」と「associated out-of-band data from oob」であること、そして戻り値が「number of payload and out-of-band bytes written」であることが明記されています。

また、既存のReadFromUnix関数のドキュメントも修正されています。元々は「return address」と記述されていた部分が「source address」に変更されています。これは、データグラムソケットにおいて、受信したパケットの「送信元アドレス」を返すというAPIの正確な意味を反映したものです。return addressという表現は、関数呼び出しの戻りアドレスと混同される可能性があり、誤解を招く恐れがあったため、より適切な用語に修正されました。

これらの変更は、GoのAPIドキュメントの品質向上と、ユーザーがこれらの低レベルなソケットAPIをより安全かつ正確に利用できるようにするための重要なステップです。

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

変更はsrc/pkg/net/unixsock_posix.goファイルに集中しています。

--- a/src/pkg/net/unixsock_posix.go
+++ b/src/pkg/net/unixsock_posix.go
@@ -208,8 +208,8 @@ func (c *UnixConn) SetWriteBuffer(bytes int) error {
 }
 
 // ReadFromUnix reads a packet from c, copying the payload into b.
-// It returns the number of bytes copied into b and the return address
-// that was on the packet.
+// It returns the number of bytes copied into b and the source address
+// of the packet.
 //
 // ReadFromUnix can be made to time out and return
 // an error with Timeout() == true after a fixed time limit;
@@ -264,6 +264,11 @@ func (c *UnixConn) WriteTo(b []byte, addr Addr) (n int, err error) {
 	return c.WriteToUnix(b, a)
 }
 
+// ReadMsgUnix reads a packet from c, copying the payload into b
+// and the associated out-of-band data into oob.
+// It returns the number of bytes copied into b, the number of
+// bytes copied into oob, the flags that were set on the packet,
+// and the source address of the packet.
 func (c *UnixConn) ReadMsgUnix(b, oob []byte) (n, oobn, flags int, addr *UnixAddr, err error) {
 	if !c.ok() {
 		return 0, 0, 0, nil, syscall.EINVAL
@@ -276,6 +281,9 @@ func (c *UnixConn) ReadMsgUnix(b, oob []byte) (n, oobn, flags int, addr *UnixAdd
 	return
 }
 
+// WriteMsgUnix writes a packet to addr via c, copying the payload from b
+// and the associated out-of-band data from oob.  It returns the number
+// of payload and out-of-band bytes written.
 func (c *UnixConn) WriteMsgUnix(b, oob []byte, addr *UnixAddr) (n, oobn int, err error) {
 	if !c.ok() {
 		return 0, 0, syscall.EINVAL

コアとなるコードの解説

このコミットは、Goのコードベースにおけるドキュメンテーションのベストプラクティスを示しています。実際の関数のロジックには変更がなく、追加されたのはすべてコメント行です。

1. ReadFromUnixのドキュメント修正:

   • 変更前: // It returns the number of bytes copied into b and the return address
   • 変更後: // It returns the number of bytes copied into b and the source address
   • return addressという曖昧な表現をsource addressという明確な表現に修正し、APIの挙動をより正確に伝えています。

2. ReadMsgUnixの新規ドキュメント追加:

   • この関数は、ペイロードデータ (b) と補助データ (oob) の両方を読み取るためのものです。
   • 追加されたコメントは、bがペイロード、oobが補助データであることを明記し、さらに戻り値であるn（ペイロードバイト数）、oobn（補助データバイト数）、flags（パケットに設定されたフラグ）、addr（送信元アドレス）のそれぞれについて詳細な説明を提供しています。これにより、開発者はこの関数が返す複数の値の意味を正確に理解できます。

3. WriteMsgUnixの新規ドキュメント追加:

   • この関数は、ペイロードデータ (b) と補助データ (oob) の両方を書き込むためのものです。
   • 追加されたコメントは、bがペイロード、oobが補助データであることを明記し、戻り値が「payload and out-of-band bytes written」であることを示しています。これにより、開発者はこの関数がどのようにデータを送信し、その結果として何が返されるのかを明確に把握できます。

これらのドキュメントの追加と修正により、GoのnetパッケージのUnixドメインソケット関連APIの使いやすさと理解度が大幅に向上しました。特に、補助データのような複雑な概念を扱う関数においては、このような詳細なドキュメントが開発者の誤用を防ぎ、正しい実装を促進するために不可欠です。

関連リンク

• Go Issue #3247: https://github.com/golang/go/issues/3247
• Go CL 5784051: https://golang.org/cl/5784051

参考にした情報源リンク

• Go言語 net パッケージ公式ドキュメント: https://pkg.go.dev/net
• Unixドメインソケット (Wikipedia): https://ja.wikipedia.org/wiki/Unix%E3%83%89%E3%83%A1%E3%82%A4%E3%83%B3%E3%82%BD%E3%82%B1%E3%83%83%E3%83%88
• sendmsg(2) / recvmsg(2) manページ (補助データに関する情報): https://man7.org/linux/man-pages/man2/sendmsg.2.html
• Go言語のドキュメンテーションの書き方 (Go Doc): https://go.dev/blog/godoc