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 6f2e8959 docs(compute): attach the NewDatumWithoutOwning doc comment
and say what Release does to it (#1320)
6f2e8959 is described below
commit 6f2e89599a990f466b89374835762e8ab1a6e422
Author: singhpratech <[email protected]>
AuthorDate: Mon Sep 21 15:52:38 2026 -0400
docs(compute): attach the NewDatumWithoutOwning doc comment and say what
Release does to it (#1320)
### Rationale for this change
The comment above `NewDatumWithoutOwning` is separated from the declaration
by a blank line, so
`go doc` and pkg.go.dev show the function with no documentation at all. The
text itself has a
sentence with no main clause and ends in stray characters (`convenience
function.+-`). The
function's one hazard, a `Release` call that releases the caller's
reference (#1298), is the thing
a reader most needs to see and currently cannot.
### What changes are included in this PR?
The comment now sits on the declaration and states the contract: the
returned `Datum` owns nothing,
the caller keeps the value alive for as long as the `Datum` is in use and
must not call `Release` on
it, and since the `Datum` is an ordinary
`ArrayDatum`/`ChunkedDatum`/`RecordDatum`/`TableDatum`/
`ScalarDatum`, a `Release` call compiles and releases the caller's
reference, which with a C-backed
allocator or cdata-imported buffers frees memory under a live value. It
ends by pointing at
`NewDatum` for the owning case.
### Are these changes tested?
Documentation only. `go doc ./arrow/compute NewDatumWithoutOwning` renders
the two paragraphs;
gofmt and `go vet ./arrow/compute/` are clean.
### Are there any user-facing changes?
Documentation only. Whether a non-owning `Datum` should refuse `Release` (a
no-op, a distinct
type, or a panic) is a separate decision and stays with #1298; this change
does not close it.
---
arrow/compute/datum.go | 21 ++++++++++++++-------
1 file changed, 14 insertions(+), 7 deletions(-)
diff --git a/arrow/compute/datum.go b/arrow/compute/datum.go
index 7a296594..65dee0aa 100644
--- a/arrow/compute/datum.go
+++ b/arrow/compute/datum.go
@@ -269,14 +269,21 @@ func NewDatum(value interface{}) Datum {
}
}
-// NewDatumWithoutOwning is like NewDatum only it does not call Retain on
-// the passed in value (if applicable). This means that if the resulting
-// Datum should not have Release called on it and the original value needs
-// to outlive the Datum.
+// NewDatumWithoutOwning is like NewDatum but does not call Retain on the
+// value it is given. The Datum takes over whatever reference the caller
+// supplies, and Datum.Release consumes that reference: it is an ordinary
+// ArrayDatum, ChunkedDatum, RecordDatum, TableDatum or ScalarDatum whose
+// Release calls the wrapped value's Release.
//
-// Only use this if you know what you're doing. For the most part this is
-// just a convenience function.+-
-
+// Two call patterns follow from that. Wrapping a value the caller still owns
+// borrows it: the caller keeps the value alive for as long as the Datum is in
+// use and must not call Release on the Datum, because that would give up the
+// caller's own reference and, with a C-backed allocator or buffers imported
+// through the cdata package, free memory under a live value. Wrapping a
+// value created for the Datum transfers it: the Datum is then the only
+// handle, and it must eventually be released through the Datum or the
+// value's retained data leaks. NewDatum itself uses the second pattern,
+// retaining a Releasable and handing the new reference to this function.
func NewDatumWithoutOwning(value interface{}) Datum {
switch v := value.(type) {
case arrow.Array:
