This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new cd08139b50 Improve safety documentation of the `Array` trait (#9314)
cd08139b50 is described below
commit cd08139b50c3495fb42d37ed875c6f12da34d917
Author: Andrew Lamb <[email protected]>
AuthorDate: Mon Feb 2 10:11:47 2026 -0500
Improve safety documentation of the `Array` trait (#9314)
# Which issue does this PR close?
<!--
We generally require a GitHub issue to be filed for all bug fixes and
enhancements and this helps us generate change logs for our releases.
You can link an issue to this PR using the GitHub syntax.
-->
- Closes #NNN.
# Rationale for this change
Per discussion on
https://github.com/apache/arrow-rs/pull/9234#pullrequestreview-3708950936
@scovich noted that it would be good to point out the core reason it is
hard/impossible to implement Array safetly
# What changes are included in this PR?
Update the comments on `Array` to try and capture the thread.
# Are these changes tested?
By CI
# Are there any user-facing changes?
Docs only, no functional changes
---
arrow-array/src/array/mod.rs | 13 +++++++++++--
1 file changed, 11 insertions(+), 2 deletions(-)
diff --git a/arrow-array/src/array/mod.rs b/arrow-array/src/array/mod.rs
index abc4091fe3..0d8125a2a1 100644
--- a/arrow-array/src/array/mod.rs
+++ b/arrow-array/src/array/mod.rs
@@ -78,7 +78,7 @@ pub use list_view_array::*;
use crate::iterator::ArrayIter;
-/// An array in the [arrow columnar
format](https://arrow.apache.org/docs/format/Columnar.html)
+/// An array in the [Arrow Columnar
Format](https://arrow.apache.org/docs/format/Columnar.html)
///
/// # Safety
///
@@ -87,7 +87,16 @@ use crate::iterator::ArrayIter;
/// translate into panics or undefined behavior. For example, a value computed
based on `len`
/// may be used as a direct index into memory regions without checks.
///
-/// Use it at your own risk knowing that this trait might be sealed in the
future.
+/// Note that it is likely impossible to correctly implement the trait for a
+/// third party type, as substantial arrow-rs functionality is based on the
+/// return values of [`Array::data_type`] and third party types cannot extend
+/// the [`DataType`] enum. So any code that attempts casting based on data type
+/// (including internal arrow library code) risks a panic or undefined
behavior.
+/// See [this discussion] for more details.
+///
+/// This trait might be sealed in the future. Use at your own risk.
+///
+/// [this discussion]:
https://github.com/apache/arrow-rs/pull/9234#pullrequestreview-3708950936
pub unsafe trait Array: std::fmt::Debug + Send + Sync {
/// Returns the array as [`Any`] so that it can be
/// downcasted to a specific implementation.
