[インデックス 17312] ファイルの概要
このコミットは、Go言語の標準ライブラリ encoding/xml パッケージにおいて、XMLエンコーダがトークンをエンコードした後に内部バッファを適切にフラッシュするように修正するものです。これにより、エンコードされたXMLデータが即座に基になる io.Writer に書き込まれるようになり、特にストリーミング処理や、エンコード後にすぐにデータが必要となるシナリオでの予期せぬ遅延や不整合が解消されます。
コミット
commit 43a39bfd7fde223b741fc05ee5ac8a336e2a8f0a
Author: Dominik Honnef <dominik.honnef@gmail.com>
Date: Mon Aug 19 10:14:10 2013 +1000
encoding/xml: flush buffer after encoding token
R=rsc, bradfitz, adg
CC=golang-dev
https://golang.org/cl/13004046
GitHub上でのコミットページへのリンク
https://github.com/golang/go/commit/43a39bfd7fde223b741fc05ee5ac8a336e2a8f0a
元コミット内容
encoding/xml: トークンエンコード後にバッファをフラッシュする
変更の背景
この変更の背景には、encoding/xml パッケージの Encoder がXMLトークン（要素の開始タグ、終了タグ、コメント、処理命令など）をエンコードする際に、内部バッファを使用しているという実装上の特性があります。以前の実装では、EncodeToken メソッドがトークンを内部バッファに書き込んだ後、そのバッファがすぐに基になる io.Writer にフラッシュされない可能性がありました。
これにより、以下のような問題が発生する可能性がありました。
- データの遅延:
EncodeTokenが完了しても、エンコードされたXMLデータが実際にはまだ内部バッファに留まっており、基になるio.Writerに書き出されていないため、データがすぐに利用できない。これは、特にネットワークストリームやファイルへの書き込みなど、リアルタイム性が求められるシナリオで問題となります。 - 不完全な出力:
Encoderが明示的にFlushされる前に、プログラムが終了したり、エラーが発生したりした場合、バッファに残っていたデータが失われ、不完全なXML出力が生成される可能性がありました。 - テストの困難さ:
EncodeTokenの呼び出し直後に、出力されたXMLデータを検証しようとすると、バッファリングのために期待するデータが得られないことがあり、テストの記述やデバッグが困難になる。
このコミットは、EncodeToken が呼び出された後、エンコードされたトークンが確実に基になる io.Writer に書き込まれるようにすることで、これらの問題を解決することを目的としています。
前提知識の解説
このコミットを理解するためには、以下のGo言語の概念と encoding/xml パッケージの基本的な動作を理解しておく必要があります。
io.Writerインターフェース: Go言語における基本的なI/Oインターフェースの一つで、データを書き込むためのWrite([]byte) (n int, err error)メソッドを定義しています。ファイル、ネットワーク接続、メモリバッファなど、様々な出力先がこのインターフェースを実装しています。- バッファリングI/O: 効率的なI/O操作のために、多くのI/Oライブラリは内部バッファを使用します。データはまず小さなチャンクでバッファに書き込まれ、バッファがいっぱいになったり、明示的にフラッシュされたりするまで、基になる
io.Writerには書き込まれません。これにより、システムコールやディスクI/Oの回数を減らし、パフォーマンスを向上させます。 encoding/xmlパッケージ: Go言語でXMLデータをエンコード（Goの構造体からXMLへ）およびデコード（XMLからGoの構造体へ）するための標準ライブラリです。xml.Encoder: XMLデータをio.Writerに書き込むための型です。xml.Token: XMLドキュメントの構成要素（開始要素、終了要素、文字データ、コメント、処理命令など）を表すインターフェースです。Encoder.EncodeToken(t Token) error: 指定されたTokenをXML形式でエンコードし、内部バッファを介して基になるio.Writerに書き込むメソッドです。printer構造体:xml.Encoderの内部で使われるヘルパー構造体で、実際のXML文字列の構築とバッファリングを担当します。io.Writerをラップし、効率的な書き込みのために内部バッファを持っています。printer.Flush():printerの内部バッファに蓄積されたデータを、基になるio.Writerに強制的に書き出すメソッドです。printer.cachedWriteError():printerが書き込み中に発生したエラーをキャッシュし、それを返すためのメソッドです。以前の実装では、このメソッドがEncodeTokenの最後に呼び出されていましたが、これはバッファのフラッシュを保証するものではありませんでした。
技術的詳細
encoding/xml パッケージの Encoder は、内部的に printer という構造体を使用してXMLデータの構築と出力を行っています。この printer は、bytes.Buffer のような内部バッファを持ち、Write メソッドが呼び出されるたびに、まずそのバッファにデータを書き込みます。バッファがいっぱいになったり、明示的に Flush が呼び出されたりするまで、データは基になる io.Writer には書き出されません。
このコミット以前の EncodeToken メソッドの実装では、XMLトークンをエンコードして printer のバッファに書き込んだ後、p.cachedWriteError() を呼び出して終了していました。cachedWriteError() は、書き込み中に発生したエラーをチェックするだけであり、バッファの内容をフラッシュする機能は持っていませんでした。
したがって、EncodeToken が呼び出された後でも、エンコードされたXMLデータは printer の内部バッファに留まり、基になる io.Writer には書き込まれない可能性がありました。これは、特に EncodeToken を呼び出した直後に、出力ストリームからデータを読み取ろうとするようなシナリオで問題を引き起こします。例えば、bytes.Buffer を io.Writer として Encoder に渡した場合、EncodeToken の呼び出し後すぐに buf.String() を呼び出しても、期待するXMLデータが得られないことがありました。
このコミットは、EncodeToken メソッドの最後に p.cachedWriteError() の代わりに p.Flush() を呼び出すように変更することで、この問題を解決します。p.Flush() は printer の内部バッファの内容を強制的に基になる io.Writer に書き出すため、EncodeToken が完了した時点で、エンコードされたXMLデータが確実に外部に公開されるようになります。
これにより、encoding/xml パッケージの Encoder の動作がより予測可能になり、ストリーミングXML処理や、エンコードされたXMLデータを即座に利用する必要があるアプリケーションでの信頼性が向上します。
コアとなるコードの変更箇所
diff --git a/src/pkg/encoding/xml/marshal.go b/src/pkg/encoding/xml/marshal.go
index a6ee5d5128..06bdec4f73 100644
--- a/src/pkg/encoding/xml/marshal.go
+++ b/src/pkg/encoding/xml/marshal.go
@@ -196,7 +196,6 @@ func (enc *Encoder) EncodeToken(t Token) error {
\tp.WriteString("<!--")
\tp.Write(t)
\tp.WriteString("-->")
-\t\treturn p.cachedWriteError()
case ProcInst:
\tif t.Target == "xml" || !isNameString(t.Target) {
\t\treturn fmt.Errorf("xml: EncodeToken of ProcInst with invalid Target")
@@ -219,7 +218,7 @@ func (enc *Encoder) EncodeToken(t Token) error {
\tp.Write(t)
\tp.WriteString(">")
}\n-\treturn p.cachedWriteError()
+\treturn p.Flush()
}\n
type printer struct {\ndiff --git a/src/pkg/encoding/xml/marshal_test.go b/src/pkg/encoding/xml/marshal_test.go
index 8d9239eb4a..31d4d4d853 100644
--- a/src/pkg/encoding/xml/marshal_test.go
+++ b/src/pkg/encoding/xml/marshal_test.go
@@ -1076,6 +1076,15 @@ func TestMarshalWriteIOErrors(t *testing.T) {\n \t}\n }\n \n+func TestEncodeTokenFlush(t *testing.T) {\n+\tvar buf bytes.Buffer\n+\tenc := NewEncoder(&buf)\n+\tenc.EncodeToken(StartElement{Name: Name{Local: "some-tag"}})\n+\tif g, w := buf.String(), "<some-tag>"; g != w {\n+\t\tt.Errorf("Encoder wrote %q, want %q", g, w)\n+\t}\n+}\n+\n func BenchmarkMarshal(b *testing.B) {\n \tfor i := 0; i < b.N; i++ {\n \t\tMarshal(atomValue)\n```
## コアとなるコードの解説
変更は主に `src/pkg/encoding/xml/marshal.go` ファイルの `EncodeToken` メソッドにあります。
* **変更前**:
`EncodeToken` メソッドの最後で、`p.cachedWriteError()` が呼び出されていました。これは、`printer` 構造体内で発生した書き込みエラーをチェックし、それを返すためのものでした。しかし、この呼び出し自体は `printer` の内部バッファをフラッシュする動作を含んでいませんでした。
```go
// marshal.go (before)
// ...
case Comment:
p.WriteString("<!--")
p.Write(t)
p.WriteString("-->")
return p.cachedWriteError() // ここが変更点
// ...
// marshal.go (before)
// ...
case CharData:
p.Write(t)
p.WriteString(">")
}
return p.cachedWriteError() // ここが変更点
```
* **変更後**:
`p.cachedWriteError()` の呼び出しが削除され、代わりに `p.Flush()` が呼び出されるようになりました。`p.Flush()` は `printer` の内部バッファに蓄積されたすべてのデータを、基になる `io.Writer` に強制的に書き出します。これにより、`EncodeToken` が正常に完了した時点で、エンコードされたXMLトークンが確実に外部に書き出されることが保証されます。
```go
// marshal.go (after)
// ...
case Comment:
p.WriteString("<!--")
p.Write(t)
p.WriteString("-->")
// return p.cachedWriteError() // 削除
case ProcInst:
// ...
// marshal.go (after)
// ...
case CharData:
p.Write(t)
p.WriteString(">")
}
return p.Flush() // 追加
```
また、`src/pkg/encoding/xml/marshal_test.go` には、この変更の動作を検証するための新しいテストケース `TestEncodeTokenFlush` が追加されています。
* **`TestEncodeTokenFlush`**:
このテストは `bytes.Buffer` を `Encoder` の出力先として使用し、`EncodeToken` を呼び出した直後に `buf.String()` を使ってバッファの内容を検証しています。このテストが成功するということは、`EncodeToken` の呼び出し後すぐにデータがフラッシュされ、バッファから読み取れる状態になっていることを意味します。
```go
// marshal_test.go (new test)
func TestEncodeTokenFlush(t *testing.T) {
var buf bytes.Buffer
enc := NewEncoder(&buf)
enc.EncodeToken(StartElement{Name: Name{Local: "some-tag"}})
if g, w := buf.String(), "<some-tag>"; g != w {
t.Errorf("Encoder wrote %q, want %q", g, w)
}
}
```
この変更により、`encoding/xml.Encoder` の `EncodeToken` メソッドは、より直感的で期待通りの動作をするようになり、バッファリングによる予期せぬ遅延やデータ不整合の問題が解消されました。
## 関連リンク
* Go CL 13004046: [https://golang.org/cl/13004046](https://golang.org/cl/13004046)
## 参考にした情報源リンク
* Go CL 13004046 (上記と同じ)
* Go言語 `encoding/xml` パッケージのドキュメント: [https://pkg.go.dev/encoding/xml](https://pkg.go.dev/encoding/xml)
* Go言語 `io` パッケージのドキュメント: [https://pkg.go.dev/io](https://pkg.go.dev/io)
* Go言語 `bytes` パッケージのドキュメント: [https://pkg.go.dev/bytes](https://pkg.go.dev/bytes)
* Go言語のバッファリングI/Oに関する一般的な情報 (例: `bufio` パッケージなど)