Speed up unary not kernel by 50%, add BooleanBuffer::from_bitwise_unary

[alamb]

Which issue does this PR close?

• part of Consolidate bitwise operation implementations #8806
• broken out from Add Buffer::from_bitwise_unary and Buffer::from_bitwise_binary me… #8854

Rationale for this change

The current implementation of the unary not kernel has an extra allocation when operating on sliced data which is not necessary.

Also, we can generate more optimal code by processing u64 words at a time when the buffer is already u64 aligned (see #8807)

Also, it is hard to find the code to create new Buffers by copying bits

What changes are included in this PR?

1. Introduce BooleanBuffer::from_bitwise_unary and BooleanBuffer::from_bits
2. Deprecate bitwise_unary_op_helper

Are these changes tested?

Yes with new tests and benchmarks

Are there any user-facing changes?

new PAPI

[Dandandan]

this could use push_unchecked as well (for consistency)?

[alamb]

Good idea -- done in 469f2ad

[alamb]

BTW I wrote a version of this code to handle works for byte aligned, but it actually seems to have made performance worse, so I am going to update the comments and leave it this way

What I tried

    /// Like [`Self::from_bitwise_unary_op`] but optimized for the case where the
    /// input is aligned to byte boundaries
    fn try_from_aligned_bitwise_unary_op<F>(
        left: &[u8],
        len_in_bits: usize,
        op: &mut F,
    ) -> Option<Self>
    where
        F: FnMut(u64) -> u64,
    {
        // safety: all valid bytes are valid u64s
        let (left_prefix, left_u64s, left_suffix) = unsafe { left.align_to::<u64>() };
        // if there is no prefix or suffix, the buffer is aligned and we can do
        // the operation directly on u64s
        if left_prefix.is_empty() && left_suffix.is_empty() {
            let result_u64s: Vec<u64> = left_u64s.iter().map(|l| op(*l)).collect();
            let buffer = Buffer::from(result_u64s);
            return Some(BooleanBuffer::new(buffer, 0, len_in_bits));
        }

        let mut result = MutableBuffer::with_capacity(
            left_prefix.len() + left_u64s.len() * 8 + left_suffix.len(),
        );
        let prefix_u64 = op(Self::byte_slice_to_u64(left_prefix));

        result.extend_from_slice(&prefix_u64.to_be_bytes()[0..left_prefix.len()]);

        assert!(result.capacity() >= result.len() + left_u64s.len() * 8);
        for &left in left_u64s.iter() {
            // SAFETY: we asserted there is enough capacity above
            unsafe {
                result.push_unchecked(op(left));
            }
        }

        let suffix_u64 = op(Self::byte_slice_to_u64(left_suffix));
        result.extend_from_slice(&suffix_u64.to_be_bytes()[0..left_suffix.len()]);

        Some(BooleanBuffer::new(result.into(), 0, len_in_bits))
    }

diff --git a/arrow-buffer/src/buffer/boolean.rs b/arrow-buffer/src/buffer/boolean.rs
index 97674c18843..285888b3a7c 100644
--- a/arrow-buffer/src/buffer/boolean.rs
+++ b/arrow-buffer/src/buffer/boolean.rs
@@ -18,10 +18,11 @@
 use crate::bit_chunk_iterator::BitChunks;
 use crate::bit_iterator::{BitIndexIterator, BitIndexU32Iterator, BitIterator, BitSliceIterator};
 use crate::{
-    BooleanBufferBuilder, Buffer, MutableBuffer, bit_util, buffer_bin_and, buffer_bin_or,
-    buffer_bin_xor, buffer_unary_not,
+    BooleanBufferBuilder, Buffer, MutableBuffer, ToByteSlice, bit_util, buffer_bin_and,
+    buffer_bin_or, buffer_bin_xor, buffer_unary_not,
 };

+use crate::bit_util::get_remainder_bits;
 use std::ops::{BitAnd, BitOr, BitXor, Not};

 /// A slice-able [`Buffer`] containing bit-packed booleans
@@ -200,14 +201,37 @@ impl BooleanBuffer {
         // the operation directly on u64s
         if left_prefix.is_empty() && left_suffix.is_empty() {
             let result_u64s: Vec<u64> = left_u64s.iter().map(|l| op(*l)).collect();
-            Some(BooleanBuffer::new(
-                Buffer::from(result_u64s),
-                0,
-                len_in_bits,
-            ))
-        } else {
-            None
+            let buffer = Buffer::from(result_u64s);
+            return Some(BooleanBuffer::new(buffer, 0, len_in_bits));
         }
+
+        let mut result = MutableBuffer::with_capacity(
+            left_prefix.len() + left_u64s.len() * 8 + left_suffix.len(),
+        );
+        let prefix_u64 = op(Self::byte_slice_to_u64(left_prefix));
+
+        result.extend_from_slice(&prefix_u64.to_be_bytes()[0..left_prefix.len()]);
+
+        assert!(result.capacity() >= result.len() + left_u64s.len() * 8);
+        for &left in left_u64s.iter() {
+            // SAFETY: we asserted there is enough capacity above
+            unsafe {
+                result.push_unchecked(op(left));
+            }
+        }
+
+        let suffix_u64 = op(Self::byte_slice_to_u64(left_suffix));
+        result.extend_from_slice(&suffix_u64.to_be_bytes()[0..left_suffix.len()]);
+
+        Some(BooleanBuffer::new(result.into(), 0, len_in_bits))
+    }
+
+    /// convert the bytes into a u64 suitable for opeartion
+    fn byte_slice_to_u64(src: &[u8]) -> u64 {
+        let num_bytes = src.len();
+        let mut bytes = [0u8; 8];
+        bytes[0..num_bytes].copy_from_slice(src);
+        u64::from_be_bytes(bytes)
     }

     /// Returns the number of set bits in this buffer
diff --git a/arrow-buffer/src/util/bit_util.rs b/arrow-buffer/src/util/bit_util.rs

This PR

not_slice_24            time:   [81.729 ns 82.091 ns 82.587 ns]

When I tried fancier code for byte alignment:

not_slice_24            time:   [121.13 ns 122.69 ns 124.52 ns]

[alamb]

Good idea -- done in 469f2ad

[alamb]

run benchmark boolean_kernels

[alamb-ghbot]

🤖 ./gh_compare_arrow.sh gh_compare_arrow.sh Running
Linux aal-dev 6.14.0-1018-gcp #19~24.04.1-Ubuntu SMP Wed Sep 24 23:23:09 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux
Comparing alamb/unary_op (1bd1321) to 20cd096 diff
BENCH_NAME=boolean_kernels
BENCH_COMMAND=cargo bench --features=arrow,async,test_common,experimental --bench boolean_kernels
BENCH_FILTER=
BENCH_BRANCH_NAME=alamb_unary_op
Results will be posted here when complete

[alamb-ghbot]

🤖: Benchmark completed

Details

group            alamb_unary_op                         main
-----            --------------                         ----
and              1.00    273.4±2.54ns        ? ?/sec    1.01    274.9±8.53ns        ? ?/sec
and_sliced_1     1.00   1229.7±9.23ns        ? ?/sec    1.00   1227.9±4.24ns        ? ?/sec
and_sliced_24    1.00    241.7±1.63ns        ? ?/sec    1.01    243.7±7.94ns        ? ?/sec
not              1.00    145.1±4.05ns        ? ?/sec    1.50    217.7±1.84ns        ? ?/sec
not_slice_24     1.00    192.5±1.60ns        ? ?/sec    1.16    224.1±2.67ns        ? ?/sec
not_sliced_1     1.00    618.5±3.31ns        ? ?/sec    1.14   704.6±15.29ns        ? ?/sec
or               1.00    251.0±2.93ns        ? ?/sec    1.00    250.3±2.81ns        ? ?/sec
or_sliced_1      1.00  1095.1±11.06ns        ? ?/sec    1.00   1097.0±5.30ns        ? ?/sec
or_sliced_24     1.00    241.4±1.85ns        ? ?/sec    1.00    241.6±3.08ns        ? ?/sec

[Dandandan]

Very nice!

[alamb]

This PR introduced a very subtle bug, see

• Fix nullif kernel #9087