emkornfield commented on code in PR #48345: URL: https://github.com/apache/arrow/pull/48345#discussion_r2723677385
########## cpp/src/arrow/util/alp/alp_wrapper.cc: ########## @@ -0,0 +1,435 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +#include "arrow/util/alp/alp_wrapper.h" + +#include <cmath> +#include <optional> + +#include "arrow/util/alp/alp.h" +#include "arrow/util/alp/alp_constants.h" +#include "arrow/util/alp/alp_sampler.h" +#include "arrow/util/logging.h" +#include "arrow/util/ubsan.h" + +namespace arrow { +namespace util { +namespace alp { + +namespace { + +// ---------------------------------------------------------------------- +// AlpHeader + +/// \brief Header structure for ALP compression blocks +/// +/// Contains page-level metadata for ALP compression. The num_elements field +/// stores the total element count for the page, allowing per-vector element +/// counts to be inferred (all vectors except the last have vector_size elements). +/// +/// Note: num_elements is uint32_t because Parquet page headers use i32 for num_values. +/// See: https://github.com/apache/parquet-format/blob/master/src/main/thrift/parquet.thrift +/// +/// Note: log_vector_size stores the base-2 logarithm of the vector size. +/// The actual vector size is computed as: 1u << log_vector_size (i.e., 2^log_vector_size). +/// For example, log_vector_size=10 means vector_size=1024. +/// This allows representing any power-of-2 vector size up to 2^255 in a single byte. +/// +/// Header format (version 1): +/// +/// +---------------------------------------------------+ +/// | AlpHeader (8 bytes) | +/// +---------------------------------------------------+ +/// | Offset | Field | Size | +/// +---------+---------------------+-------------------+ +/// | 0 | version | 1 byte (uint8) | +/// | 1 | compression_mode | 1 byte (uint8) | +/// | 2 | integer_encoding | 1 byte (uint8) | +/// | 3 | log_vector_size | 1 byte (uint8) | +/// | 4 | num_elements | 4 bytes (uint32) | +/// +---------------------------------------------------+ +/// +/// Page-level layout (metadata-at-start for efficient random access): +/// +/// +-------------------------------------------------------------------+ +/// | [AlpHeader (8B)] | +/// | [VectorInfo₀ | VectorInfo₁ | ... | VectorInfoₙ] ← Metadata | +/// | [Data₀ | Data₁ | ... | Dataₙ] ← Data sections | +/// +-------------------------------------------------------------------+ +/// +/// This layout enables O(1) random access to any vector by: +/// 1. Reading all VectorInfo first (contiguous, cache-friendly) +/// 2. Computing data offsets from VectorInfo +/// 3. Seeking directly to the target vector's data +/// +/// \note version must remain the first field to allow reading the rest +/// of the header based on version number. +struct AlpHeader { + /// Version number. Must remain the first field for version-based parsing. + uint8_t version = 0; + /// Compression mode (currently only kAlp is supported). + uint8_t compression_mode = static_cast<uint8_t>(AlpMode::kAlp); + /// Integer encoding method used (currently only kForBitPack is supported). + uint8_t integer_encoding = static_cast<uint8_t>(AlpIntegerEncoding::kForBitPack); + /// Log base 2 of vector size. Actual vector size = 1u << log_vector_size. + /// For example: 10 means 2^10 = 1024 elements per vector. + uint8_t log_vector_size = 0; + /// Total number of elements in the page (uint32_t since Parquet uses i32). + /// Per-vector element count is inferred: vector_size for all but the last vector. + uint32_t num_elements = 0; + + /// \brief Get the size in bytes of the AlpHeader for a version + /// + /// \param[in] v the version number + /// \return the size in bytes + static constexpr size_t GetSizeForVersion(uint8_t v) { + // Version 1 header is 8 bytes + return (v == 1) ? 8 : 0; + } + + /// \brief Check whether the given version is valid + /// + /// \param[in] v the version to check + /// \return the version if valid, otherwise asserts + static uint8_t IsValidVersion(uint8_t v) { + ARROW_CHECK(v == 1) << "invalid_version: " << static_cast<int>(v); + return v; + } + + /// \brief Compute the actual vector size from log_vector_size + /// + /// \return the vector size (2^log_vector_size) + uint32_t GetVectorSize() const { return 1u << log_vector_size; } + + /// \brief Compute log base 2 of a power-of-2 value + /// + /// \param[in] value a power-of-2 value + /// \return the log base 2 of value + static uint8_t Log2(uint32_t value) { + ARROW_CHECK(value > 0 && (value & (value - 1)) == 0) + << "value_must_be_power_of_2: " << value; + uint8_t log = 0; Review Comment: nit: more efficient to use count leading zeros? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
