This is an automated email from the ASF dual-hosted git repository.
wesm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new a226e88 ARROW-4244: [Format] Clarify padding/alignment
rationale/recommendation.
a226e88 is described below
commit a226e885f52de0f8ffcb2fbb0c53f3dc215db11d
Author: Micah Kornfield <[email protected]>
AuthorDate: Tue Jan 22 19:49:59 2019 -0600
ARROW-4244: [Format] Clarify padding/alignment rationale/recommendation.
I think this makes it the spec more consistent (but I might have
misunderstood the intent).
Author: Micah Kornfield <[email protected]>
Author: emkornfield <[email protected]>
Closes #3388 from emkornfield/clarify_padding_spec and squashes the
following commits:
10c74f13f <emkornfield> Add emphasis on preferred padding/alignment.
5cdde6f35 <Micah Kornfield> more clarification
454f06547 <Micah Kornfield> remove parenthetical that doesn't make sense
anymore
aac1f8fb3 <Micah Kornfield> Clarify padding/alignment rationale.
---
docs/source/format/Layout.rst | 25 ++++++++++++++-----------
1 file changed, 14 insertions(+), 11 deletions(-)
diff --git a/docs/source/format/Layout.rst b/docs/source/format/Layout.rst
index f3e5290..efe0594 100644
--- a/docs/source/format/Layout.rst
+++ b/docs/source/format/Layout.rst
@@ -64,9 +64,11 @@ Base requirements
data
* It is required to have all the contiguous memory buffers in an IPC payload
aligned at 8-byte boundaries. In other words, each buffer must start at
- an aligned 8-byte offset.
-* The general recommendation is to align the buffers at 64-byte boundary, but
- this is not absolutely necessary.
+ an aligned 8-byte offset. Additionally, each buffer should be padded to a
multiple
+ of 8 bytes.
+* For performance reasons it **preferred/recommended** to align buffers to a
+ 64-byte boundary and pad to a multiple of 64 bytes, but this is not
absolutely
+ necessary. The rationale is discussed in more details below.
* Any relative type can have null slots
* Arrays are immutable once created. Implementations can provide APIs to mutate
an array, but applying mutations will require a new array data structure to
@@ -122,14 +124,16 @@ practices for optimized memory access:
* Elements in numeric arrays will be guaranteed to be retrieved via aligned
access.
* On some architectures alignment can help limit partially used cache lines.
-* 64 byte alignment is recommended by the `Intel performance guide`_ for
- data-structures over 64 bytes (which will be a common case for Arrow Arrays).
-Recommending padding to a multiple of 64 bytes allows for using `SIMD`_
instructions
+The recommendation for 64 byte alignment comes from the `Intel performance
guide`_
+that recommends alignment of memory to match SIMD register width.
+The specific padding length was chosen because it matches the largest known
+SIMD instruction registers available as of April 2016 (Intel AVX-512).
+
+The recommended padding of 64 bytes allows for using `SIMD`_ instructions
consistently in loops without additional conditional checks.
This should allow for simpler, efficient and CPU cache-friendly code.
-The specific padding length was chosen because it matches the largest known
-SIMD instruction registers available as of April 2016 (Intel AVX-512). In other
+In other
words, we can load the entire 64-byte buffer into a 512-bit wide SIMD register
and get data-level parallelism on all the columnar values packed into the
64-byte
buffer. Guaranteed padding can also allow certain compilers
@@ -162,9 +166,8 @@ Null bitmaps
Any relative type can have null value slots, whether primitive or nested type.
An array with nulls must have a contiguous memory buffer, known as the null (or
-validity) bitmap, whose length is a multiple of 64 bytes (as discussed above)
-and large enough to have at least 1 bit for each array
-slot.
+validity) bitmap, whose length is a multiple of 8 bytes (64 bytes recommended)
+and large enough to have at least 1 bit for each array slot.
Whether any array slot is valid (non-null) is encoded in the respective bits of
this bitmap. A 1 (set bit) for index ``j`` indicates that the value is not
null,
