Skip to content

Commit e56e0a4

Browse files
anjakefalaamoebaSChakravorti21assignUser
committed
GH-34535: [C++] Move ChunkResolver to the public API (#44357)
### Rationale for this change Adopting #40226. The creation and return of a shared_ptr does result in some performance overhead, that makes a difference for a performance-sensitive application. If someone could use ChunkResolver to learn the indices, they could then instead access the data directly. ### What changes are included in this PR? - [X] Updates to documentation (thanks to @ SChakravorti21 ) - [X] Moving `ChunkResolver` to public API, and updating all references to it in the code ### Are these changes tested? There seemed to be comprehensive tests already: https://github.com/apache/arrow/blob/main/cpp/src/arrow/chunked_array_test.cc#L324 If an edgecase is missing, I'd be happy to add it. ### Are there any user-facing changes? `ChunkResolver` and `TypedChunkLocation` are now in the public API. * GitHub Issue: #34535 Lead-authored-by: Anja Kefala <[email protected]> Co-authored-by: anjakefala <[email protected]> Co-authored-by: Bryce Mecum <[email protected]> Co-authored-by: SChakravorti21 <[email protected]> Co-authored-by: SChakravorti21<[email protected]> Co-authored-by: Jacob Wujciak-Jens <[email protected]> Signed-off-by: Felipe Oliveira Carvalho <[email protected]>
1 parent bc8251f commit e56e0a4

11 files changed

Lines changed: 55 additions & 37 deletions

File tree

‎cpp/src/arrow/chunk_resolver.cc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
#include "arrow/array.h"
2727
#include "arrow/record_batch.h"
2828

29-
namespace arrow::internal {
29+
namespace arrow {
3030

3131
namespace {
3232
template <typename T>
@@ -167,4 +167,4 @@ void ChunkResolver::ResolveManyImpl(int64_t n_indices, const uint64_t* logical_i
167167
logical_index_vec, out_chunk_location_vec, chunk_hint);
168168
}
169169

170-
} // namespace arrow::internal
170+
} // namespace arrow

‎cpp/src/arrow/chunk_resolver.h‎

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,12 @@
2727
#include "arrow/type_fwd.h"
2828
#include "arrow/util/macros.h"
2929

30-
namespace arrow::internal {
30+
namespace arrow {
3131

32-
struct ChunkResolver;
32+
class ChunkResolver;
3333

3434
template <typename IndexType>
35-
struct TypedChunkLocation {
35+
struct ARROW_EXPORT TypedChunkLocation {
3636
/// \brief Index of the chunk in the array of chunks
3737
///
3838
/// The value is always in the range `[0, chunks.size()]`. `chunks.size()` is used
@@ -41,7 +41,7 @@ struct TypedChunkLocation {
4141

4242
/// \brief Index of the value in the chunk
4343
///
44-
/// The value is UNDEFINED if chunk_index >= chunks.size()
44+
/// The value is UNDEFINED if `chunk_index >= chunks.size()`
4545
IndexType index_in_chunk = 0;
4646

4747
TypedChunkLocation() = default;
@@ -61,7 +61,7 @@ using ChunkLocation = TypedChunkLocation<int64_t>;
6161

6262
/// \brief An utility that incrementally resolves logical indices into
6363
/// physical indices in a chunked array.
64-
struct ARROW_EXPORT ChunkResolver {
64+
class ARROW_EXPORT ChunkResolver {
6565
private:
6666
/// \brief Array containing `chunks.size() + 1` offsets.
6767
///
@@ -76,14 +76,11 @@ struct ARROW_EXPORT ChunkResolver {
7676

7777
public:
7878
explicit ChunkResolver(const ArrayVector& chunks) noexcept;
79+
7980
explicit ChunkResolver(const std::vector<const Array*>& chunks) noexcept;
81+
8082
explicit ChunkResolver(const RecordBatchVector& batches) noexcept;
8183

82-
/// \brief Construct a ChunkResolver from a vector of chunks.size() + 1 offsets.
83-
///
84-
/// The first offset must be 0 and the last offset must be the logical length of the
85-
/// chunked array. Each offset before the last represents the starting logical index of
86-
/// the corresponding chunk.
8784
explicit ChunkResolver(std::vector<int64_t> offsets) noexcept
8885
: offsets_(std::move(offsets)), cached_chunk_(0) {
8986
#ifndef NDEBUG
@@ -115,11 +112,11 @@ struct ARROW_EXPORT ChunkResolver {
115112
/// The returned ChunkLocation contains the chunk index and the within-chunk index
116113
/// equivalent to the logical index.
117114
///
118-
/// \pre index >= 0
119-
/// \post location.chunk_index in [0, chunks.size()]
115+
/// \pre `index >= 0`
116+
/// \post `location.chunk_index` in `[0, chunks.size()]`
120117
/// \param index The logical index to resolve
121118
/// \return ChunkLocation with a valid chunk_index if index is within
122-
/// bounds, or with chunk_index == chunks.size() if logical index is
119+
/// bounds, or with `chunk_index == chunks.size()` if logical index is
123120
/// `>= chunked_array.length()`.
124121
inline ChunkLocation Resolve(int64_t index) const {
125122
const auto cached_chunk = cached_chunk_.load(std::memory_order_relaxed);
@@ -133,13 +130,13 @@ struct ARROW_EXPORT ChunkResolver {
133130
/// The returned ChunkLocation contains the chunk index and the within-chunk index
134131
/// equivalent to the logical index.
135132
///
136-
/// \pre index >= 0
137-
/// \post location.chunk_index in [0, chunks.size()]
133+
/// \pre `index >= 0`
134+
/// \post `location.chunk_index` in `[0, chunks.size()]`
138135
/// \param index The logical index to resolve
139136
/// \param hint ChunkLocation{} or the last ChunkLocation returned by
140137
/// this ChunkResolver.
141138
/// \return ChunkLocation with a valid chunk_index if index is within
142-
/// bounds, or with chunk_index == chunks.size() if logical index is
139+
/// bounds, or with `chunk_index == chunks.size()` if logical index is
143140
/// `>= chunked_array.length()`.
144141
inline ChunkLocation ResolveWithHint(int64_t index, ChunkLocation hint) const {
145142
assert(hint.chunk_index < static_cast<uint32_t>(offsets_.size()));
@@ -281,4 +278,13 @@ struct ARROW_EXPORT ChunkResolver {
281278
}
282279
};
283280

284-
} // namespace arrow::internal
281+
// Explicitly instantiate template base struct, for DLL linking on Windows
282+
template struct TypedChunkLocation<int32_t>;
283+
template struct TypedChunkLocation<int16_t>;
284+
template struct TypedChunkLocation<int8_t>;
285+
template struct TypedChunkLocation<uint8_t>;
286+
template struct TypedChunkLocation<uint16_t>;
287+
template struct TypedChunkLocation<uint32_t>;
288+
template struct TypedChunkLocation<int64_t>;
289+
template struct TypedChunkLocation<uint64_t>;
290+
} // namespace arrow

‎cpp/src/arrow/chunk_resolver_benchmark.cc‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,6 @@
2828

2929
namespace arrow {
3030

31-
using internal::ChunkResolver;
32-
using internal::TypedChunkLocation;
33-
3431
namespace {
3532

3633
int64_t constexpr kChunkedArrayLength = std::numeric_limits<uint16_t>::max();

‎cpp/src/arrow/chunked_array.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ class ARROW_EXPORT ChunkedArray {
199199
private:
200200
template <typename T, typename V>
201201
friend class ::arrow::stl::ChunkedArrayIterator;
202-
internal::ChunkResolver chunk_resolver_;
202+
ChunkResolver chunk_resolver_;
203203
ARROW_DISALLOW_COPY_AND_ASSIGN(ChunkedArray);
204204
};
205205

‎cpp/src/arrow/chunked_array_test.cc‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,6 @@
3636

3737
namespace arrow {
3838

39-
using internal::ChunkLocation;
40-
using internal::ChunkResolver;
41-
using internal::TypedChunkLocation;
42-
4339
class TestChunkedArray : public ::testing::Test {
4440
protected:
4541
virtual void Construct() {

‎cpp/src/arrow/compute/kernels/chunked_internal.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ struct ResolvedChunk {
5252

5353
class ChunkedArrayResolver {
5454
private:
55-
::arrow::internal::ChunkResolver resolver_;
55+
ChunkResolver resolver_;
5656
std::vector<const Array*> chunks_;
5757

5858
public:

‎cpp/src/arrow/compute/kernels/vector_sort.cc‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@
2424
namespace arrow {
2525

2626
using internal::checked_cast;
27-
using internal::ChunkLocation;
2827

2928
namespace compute {
3029
namespace internal {
@@ -852,7 +851,7 @@ class TableSorter {
852851
const RecordBatchVector batches_;
853852
const SortOptions& options_;
854853
const NullPlacement null_placement_;
855-
const ::arrow::internal::ChunkResolver left_resolver_, right_resolver_;
854+
const ::arrow::ChunkResolver left_resolver_, right_resolver_;
856855
const std::vector<ResolvedSortKey> sort_keys_;
857856
uint64_t* indices_begin_;
858857
uint64_t* indices_end_;

‎cpp/src/arrow/compute/kernels/vector_sort_internal.h‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -749,9 +749,9 @@ struct ResolvedTableSortKey {
749749
order(order),
750750
null_count(null_count) {}
751751

752-
using LocationType = ::arrow::internal::ChunkLocation;
752+
using LocationType = ::arrow::ChunkLocation;
753753

754-
ResolvedChunk GetChunk(::arrow::internal::ChunkLocation loc) const {
754+
ResolvedChunk GetChunk(::arrow::ChunkLocation loc) const {
755755
return {chunks[loc.chunk_index], loc.index_in_chunk};
756756
}
757757

‎cpp/src/arrow/stl_iterator.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,7 @@ class ChunkedArrayIterator {
237237
}
238238

239239
private:
240-
arrow::internal::ChunkLocation GetChunkLocation(int64_t index) const {
240+
arrow::ChunkLocation GetChunkLocation(int64_t index) const {
241241
assert(chunked_array_);
242242
return chunked_array_->chunk_resolver_.Resolve(index);
243243
}

‎docs/source/cpp/api/array.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@
1919
Arrays
2020
======
2121

22+
Base classes
23+
============
24+
2225
.. doxygenclass:: arrow::ArrayData
2326
:project: arrow_cpp
2427
:members:
@@ -85,6 +88,17 @@ Chunked Arrays
8588
:project: arrow_cpp
8689
:members:
8790

91+
.. doxygenstruct:: arrow::ChunkLocation
92+
:project: arrow_cpp
93+
:members:
94+
95+
.. doxygenstruct:: arrow::TypedChunkLocation
96+
:project: arrow_cpp
97+
:members:
98+
99+
.. doxygenclass:: arrow::ChunkResolver
100+
:project: arrow_cpp
101+
:members:
88102

89103
Utilities
90104
=========

0 commit comments

Comments
 (0)