This is an automated email from the ASF dual-hosted git repository.
zeroshade pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-go.git
The following commit(s) were added to refs/heads/main by this push:
new 3979556d docs(arrow/ipc): document that Writer and FileWriter are not
concurrency safe (#856)
3979556d is described below
commit 3979556d8d5c17bee93c9521484dd8d650a7c9e4
Author: Matt Topol <[email protected]>
AuthorDate: Thu Jun 18 16:09:19 2026 -0700
docs(arrow/ipc): document that Writer and FileWriter are not concurrency
safe (#856)
### Rationale for this change
Closes #55.
`arrow/ipc.Writer` and `arrow/ipc.FileWriter` wrap an arbitrary
`io.Writer` and write to it without any internal synchronization.
Calling `Write` (or `Close`) concurrently from multiple goroutines
therefore races on both the underlying sink and the writer's own state,
which can interleave output and corrupt the IPC stream — for example
writing the schema header more than once, as reported in #55.
Because an arbitrary `io.Writer` cannot be assumed to be safe for
concurrent use, the writer cannot make this safe on the caller's behalf.
The expectation that callers serialize writes was simply undocumented.
### What changes are included in this PR?
Documentation only. The type doc comments on `Writer` and `FileWriter`
now state that they are **not** safe for concurrent use, explain why
(interleaved/duplicated output via an unsynchronized `io.Writer`), and
direct callers that produce records from multiple goroutines to
serialize writes themselves — for example by funneling records through a
channel to a single goroutine that owns the writer.
No code or behavior changes.
### Are these changes tested?
No tests are needed — this is a documentation-only change. `gofmt`, `go
build`, and `go vet` are clean for `arrow/ipc`.
### Are there any user-facing changes?
No API or behavior changes; only added godoc on `ipc.Writer` and
`ipc.FileWriter`.
---
arrow/ipc/file_writer.go | 7 +++++++
arrow/ipc/writer.go | 8 ++++++++
2 files changed, 15 insertions(+)
diff --git a/arrow/ipc/file_writer.go b/arrow/ipc/file_writer.go
index 5b1320ba..0d970ba5 100644
--- a/arrow/ipc/file_writer.go
+++ b/arrow/ipc/file_writer.go
@@ -232,6 +232,13 @@ func (ps payloads) Release() {
}
// FileWriter is an Arrow file writer.
+//
+// FileWriter is not safe for concurrent use. It writes to the underlying
+// io.Writer without any synchronization, so concurrent calls to Write or Close
+// can interleave output and corrupt the file. Because an arbitrary io.Writer
+// cannot be assumed to be safe for concurrent use, callers that produce
records
+// from multiple goroutines must serialize writes themselves, for example by
+// sending records over a channel to a single goroutine that owns the
FileWriter.
type FileWriter struct {
w io.Writer
diff --git a/arrow/ipc/writer.go b/arrow/ipc/writer.go
index fa5db526..cd518f75 100644
--- a/arrow/ipc/writer.go
+++ b/arrow/ipc/writer.go
@@ -75,6 +75,14 @@ func hasNestedDict(data arrow.ArrayData) bool {
}
// Writer is an Arrow stream writer.
+//
+// Writer is not safe for concurrent use. It writes to the underlying io.Writer
+// without any synchronization, so concurrent calls to Write or Close can
+// interleave output and corrupt the stream (for example by emitting the schema
+// header more than once). Because an arbitrary io.Writer cannot be assumed to
+// be safe for concurrent use, callers that produce records from multiple
+// goroutines must serialize writes themselves, for example by sending records
+// over a channel to a single goroutine that owns the Writer.
type Writer struct {
w io.Writer
