This is an automated email from the ASF dual-hosted git repository.
kou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 5037ab14f2 GH-36621: [C++] Add documentation for
ACERO_ALIGNMENT_HANDLING (#36622)
5037ab14f2 is described below
commit 5037ab14f2a7686c38f6653b5f39ebe7feaf200f
Author: Weston Pace <[email protected]>
AuthorDate: Thu Jul 13 22:36:11 2023 -0700
GH-36621: [C++] Add documentation for ACERO_ALIGNMENT_HANDLING (#36622)
### Rationale for this change
To document an existing environment variable that was not documented.
### What changes are included in this PR?
Adds a documentation section for this environment variable.
### Are these changes tested?
No, there are only docs.
### Are there any user-facing changes?
New documentation
* Closes: #36621
Lead-authored-by: Weston Pace <[email protected]>
Co-authored-by: Antoine Pitrou <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>
---
docs/source/cpp/env_vars.rst | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/docs/source/cpp/env_vars.rst b/docs/source/cpp/env_vars.rst
index 06fd73ffd0..e849073592 100644
--- a/docs/source/cpp/env_vars.rst
+++ b/docs/source/cpp/env_vars.rst
@@ -26,6 +26,29 @@ Arrow C++ at runtime. Many of these variables are inspected
only once per
process (for example, when the Arrow C++ DLL is loaded), so you cannot assume
that changing their value later will have an effect.
+.. envvar:: ACERO_ALIGNMENT_HANDLING
+
+ Arrow C++'s Acero module performs computation on streams of data. This
+ computation may involve a form of "type punning" that is technically
+ undefined behavior if the underlying array is not properly aligned. On
+ most modern CPUs this is not an issue, but some older CPUs may crash or
+ suffer poor performance. For this reason it is recommended that all
+ incoming array buffers are properly aligned, but some data sources
+ such as :ref:`Flight <flight-rpc>` may produce unaligned buffers.
+
+ The value of this environment variable controls what will happen when
+ Acero detects an unaligned buffer:
+
+ - ``warn``: a warning is emitted
+ - ``ignore``: nothing, alignment checking is disabled
+ - ``reallocate``: the buffer is reallocated to a properly aligned address
+ - ``error``: the operation fails with an error
+
+ The default behavior is ``warn``. On modern hardware it is usually safe
+ to change this to ``ignore``. Changing to ``reallocate`` is the safest
+ option but this will have a significant performance impact as the buffer
+ will need to be copied.
+
.. envvar:: ARROW_DEBUG_MEMORY_POOL
Enable rudimentary memory checks to guard against buffer overflows.
