column_view.hpp
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2019-2023, NVIDIA CORPORATION.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #pragma once
17 
18 #include <cudf/types.hpp>
19 #include <cudf/utilities/error.hpp>
20 #include <cudf/utilities/span.hpp>
23 
24 #include <limits>
25 #include <type_traits>
26 #include <vector>
27 
33 namespace cudf {
34 namespace detail {
54  public:
71  template <typename T = void,
72  CUDF_ENABLE_IF(std::is_same_v<T, void> or is_rep_layout_compatible<T>())>
73  T const* head() const noexcept
74  {
75  return static_cast<T const*>(_data);
76  }
77 
90  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
91  T const* data() const noexcept
92  {
93  return head<T>() + _offset;
94  }
95 
106  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
107  T const* begin() const noexcept
108  {
109  return data<T>();
110  }
111 
122  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
123  T const* end() const noexcept
124  {
125  return begin<T>() + size();
126  }
127 
133  [[nodiscard]] size_type size() const noexcept { return _size; }
134 
140  [[nodiscard]] bool is_empty() const noexcept { return size() == 0; }
141 
147  [[nodiscard]] data_type type() const noexcept { return _type; }
148 
158  [[nodiscard]] bool nullable() const noexcept { return nullptr != _null_mask; }
159 
165  [[nodiscard]] size_type null_count() const { return _null_count; }
166 
182 
190  [[nodiscard]] bool has_nulls() const { return null_count() > 0; }
191 
204  [[nodiscard]] bool has_nulls(size_type begin, size_type end) const
205  {
206  return null_count(begin, end) > 0;
207  }
208 
217  [[nodiscard]] bitmask_type const* null_mask() const noexcept { return _null_mask; }
218 
225  [[nodiscard]] size_type offset() const noexcept { return _offset; }
226 
227  protected:
228  data_type _type{type_id::EMPTY};
230  void const* _data{};
232  mutable size_type _null_count{};
236 
238  column_view_base() = default;
239  ~column_view_base() = default;
240  column_view_base(column_view_base const&) = default;
242 
254 
280  size_type size,
281  void const* data,
282  bitmask_type const* null_mask,
284  size_type offset = 0);
285 };
286 
288  public:
289  protected:
290 };
291 } // namespace detail
292 
314  public:
315  column_view() = default;
316 
317  // these pragmas work around the nvcc issue where if a column_view is used
318  // inside of a __device__ code path, these functions will end up being created
319  // as __host__ __device__ because they are explicitly defaulted. However, if
320  // they then end up being called by a simple __host__ function
321  // (eg std::vector destructor) you get a compile error because you're trying to
322  // call a __host__ __device__ function from a __host__ function.
323 #ifdef __CUDACC__
324 #pragma nv_exec_check_disable
325 #endif
326  ~column_view() = default;
327 #ifdef __CUDACC__
328 #pragma nv_exec_check_disable
329 #endif
330  column_view(column_view const&) = default;
331  column_view(column_view&&) = default;
332 
337  column_view& operator=(column_view const&) = default;
344 
372  size_type size,
373  void const* data,
374  bitmask_type const* null_mask,
376  size_type offset = 0,
377  std::vector<column_view> const& children = {});
378 
385  [[nodiscard]] column_view child(size_type child_index) const noexcept
386  {
387  return _children[child_index];
388  }
389 
395  [[nodiscard]] size_type num_children() const noexcept { return _children.size(); }
396 
402  auto child_begin() const noexcept { return _children.cbegin(); }
403 
409  auto child_end() const noexcept { return _children.cend(); }
410 
419  template <typename T, CUDF_ENABLE_IF(cudf::is_numeric<T>() or cudf::is_chrono<T>())>
421  : column_view(
422  cudf::data_type{cudf::type_to_id<T>()}, data.size(), data.data(), nullptr, 0, 0, {})
423  {
424  CUDF_EXPECTS(
425  data.size() <= static_cast<std::size_t>(std::numeric_limits<cudf::size_type>::max()),
426  "Data exceeds the column size limit",
427  std::overflow_error);
428  }
429 
441  template <typename T, CUDF_ENABLE_IF(cudf::is_numeric<T>() or cudf::is_chrono<T>())>
442  [[nodiscard]] operator device_span<T const>() const
443  {
444  CUDF_EXPECTS(type() == cudf::data_type{cudf::type_to_id<T>()},
445  "Device span type must match column view type.");
446  CUDF_EXPECTS(!nullable(), "A nullable column view cannot be converted to a device span.");
447  return device_span<T const>(data<T>(), size());
448  }
449 
450  private:
452 
453  std::vector<column_view> _children{};
454 }; // namespace cudf
456 
478  public:
479  mutable_column_view() = default;
480 
481  ~mutable_column_view() = default;
482 
485 
497 
524  size_type size,
525  void* data,
528  size_type offset = 0,
529  std::vector<mutable_column_view> const& children = {});
530 
546  template <typename T = void,
547  CUDF_ENABLE_IF(std::is_same_v<T, void> or is_rep_layout_compatible<T>())>
548  T* head() const noexcept
549  {
550  return const_cast<T*>(detail::column_view_base::head<T>());
551  }
552 
565  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
566  T* data() const noexcept
567  {
568  return const_cast<T*>(detail::column_view_base::data<T>());
569  }
570 
581  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
582  T* begin() const noexcept
583  {
584  return const_cast<T*>(detail::column_view_base::begin<T>());
585  }
586 
597  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
598  T* end() const noexcept
599  {
600  return const_cast<T*>(detail::column_view_base::end<T>());
601  }
602 
612  [[nodiscard]] bitmask_type* null_mask() const noexcept
613  {
614  return const_cast<bitmask_type*>(detail::column_view_base::null_mask());
615  }
616 
624  void set_null_count(size_type new_null_count);
625 
632  [[nodiscard]] mutable_column_view child(size_type child_index) const noexcept
633  {
634  return mutable_children[child_index];
635  }
636 
642  [[nodiscard]] size_type num_children() const noexcept { return mutable_children.size(); }
643 
649  auto child_begin() const noexcept { return mutable_children.begin(); }
650 
656  auto child_end() const noexcept { return mutable_children.end(); }
657 
663  operator column_view() const;
664 
665  private:
667 
668  std::vector<mutable_column_view> mutable_children;
669 };
670 
678 
701 
724 
725 namespace detail {
741 std::size_t shallow_hash(column_view const& input);
742 
764 bool is_shallow_equivalent(column_view const& lhs, column_view const& rhs);
765 } // namespace detail
766 } // namespace cudf
cudf::mutable_column_view::child_begin
auto child_begin() const noexcept
Returns iterator to the beginning of the ordered sequence of child column-views.
Definition: column_view.hpp:649
cudf::bit_cast
column_view bit_cast(column_view const &input, data_type type)
Zero-copy cast between types with the same size and compatible underlying representations.
cudf::mutable_column_view::num_children
size_type num_children() const noexcept
Returns the number of child columns.
Definition: column_view.hpp:642
cudf::mutable_column_view::operator=
mutable_column_view & operator=(mutable_column_view &&)=default
Move assignment operator.
cudf::detail::column_view_base::_data
void const * _data
Pointer to device memory containing elements.
Definition: column_view.hpp:230
cudf::mutable_column_view::operator=
mutable_column_view & operator=(mutable_column_view const &)=default
Copy assignment operator.
cudf::detail::shallow_hash
std::size_t shallow_hash(column_view const &input)
Computes a hash value from the shallow state of the specified column.
cudf::detail::column_view_base::_size
size_type _size
Number of elements.
Definition: column_view.hpp:229
cudf::column_view::child_begin
auto child_begin() const noexcept
Returns iterator to the beginning of the ordered sequence of child column-views.
Definition: column_view.hpp:402
cudf::size_type
int32_t size_type
Row index type for columns and tables.
Definition: types.hpp:80
cudf::column_view::num_children
size_type num_children() const noexcept
Returns the number of child columns.
Definition: column_view.hpp:395
cudf::column_view
A non-owning, immutable view of device data as a column of elements, some of which may be null as ind...
Definition: column_view.hpp:313
cudf::detail::column_view_base::offset
size_type offset() const noexcept
Returns the index of the first element relative to the base memory allocation, i.e....
Definition: column_view.hpp:225
types.hpp
Type declarations for libcudf.
cudf::mutable_column_view::begin
T * begin() const noexcept
Return first element (accounting for offset) when underlying data is casted to the specified type.
Definition: column_view.hpp:582
cudf::detail::is_shallow_equivalent
bool is_shallow_equivalent(column_view const &lhs, column_view const &rhs)
Uses only shallow state to determine if two column_views view equivalent columns.
cudf::column_view::bit_cast
friend column_view bit_cast(column_view const &input, data_type type)
Zero-copy cast between types with the same size and compatible underlying representations.
cudf::mutable_column_view
A non-owning, mutable view of device data as a column of elements, some of which may be null as indic...
Definition: column_view.hpp:477
cudf::detail::column_view_base::_offset
size_type _offset
Definition: column_view.hpp:235
cudf::mutable_column_view::mutable_column_view
mutable_column_view(mutable_column_view &&)=default
Move constructor.
cudf::column_view::column_view
column_view(column_view &&)=default
Move constructor.
cudf::detail::column_view_base::operator=
column_view_base & operator=(column_view_base &&)=default
Move assignment operator.
cudf::column_view::child_end
auto child_end() const noexcept
Returns iterator to the end of the ordered sequence of child column-views.
Definition: column_view.hpp:409
cudf::mutable_column_view::data
T * data() const noexcept
Returns the underlying data casted to the specified type, plus the offset.
Definition: column_view.hpp:566
cudf::bitmask_type
uint32_t bitmask_type
Bitmask type stored as 32-bit unsigned integer.
Definition: types.hpp:81
cudf::detail::column_view_base::null_count
size_type null_count(size_type begin, size_type end) const
Returns the count of null elements in the range [begin, end)
CUDF_ENABLE_IF
#define CUDF_ENABLE_IF(...)
Convenience macro for SFINAE as an unnamed template parameter.
Definition: traits.hpp:50
cudf::detail::column_view_base::column_view_base
column_view_base(column_view_base const &)=default
Copy constructor.
cudf::detail::column_view_base
A non-owning, immutable view of device data as a column of elements, some of which may be null as ind...
Definition: column_view.hpp:53
cudf::mutable_column_view::child_end
auto child_end() const noexcept
Returns iterator to the end of the ordered sequence of child column-views.
Definition: column_view.hpp:656
cudf::count_descendants
size_type count_descendants(column_view parent)
Counts the number of descendants of the specified parent.
cudf::detail::column_view_base::null_count
size_type null_count() const
Returns the count of null elements.
Definition: column_view.hpp:165
cudf::detail::mutable_column_view_base
Definition: column_view.hpp:287
cudf::detail::column_view_base::operator=
column_view_base & operator=(column_view_base const &)=default
Copy assignment operator.
cudf::mutable_column_view::null_mask
bitmask_type * null_mask() const noexcept
Returns raw pointer to the underlying bitmask allocation.
Definition: column_view.hpp:612
cudf::column_view::operator=
column_view & operator=(column_view &&)=default
Move assignment operator.
cudf::data_type
Indicator for the logical data type of an element in a column.
Definition: types.hpp:228
cudf::column_view::column_view
column_view(data_type type, size_type size, void const *data, bitmask_type const *null_mask, size_type null_count, size_type offset=0, std::vector< column_view > const &children={})
Construct a column_view from pointers to device memory for the elements and bitmask of the column.
cudf::mutable_column_view::child
mutable_column_view child(size_type child_index) const noexcept
Returns a reference to the specified child.
Definition: column_view.hpp:632
cudf::detail::column_view_base::has_nulls
bool has_nulls() const
Indicates if the column contains null elements, i.e., null_count() > 0
Definition: column_view.hpp:190
cudf::detail::column_view_base::column_view_base
column_view_base(column_view_base &&)=default
Move constructor.
cudf
cuDF interfaces
Definition: aggregation.hpp:34
cudf::column_view::column_view
column_view(column_view const &)=default
Copy constructor.
cudf::mutable_column_view::head
T * head() const noexcept
Returns pointer to the base device memory allocation casted to the specified type.
Definition: column_view.hpp:548
cudf::mutable_column_view::mutable_column_view
mutable_column_view(mutable_column_view const &)=default
Copy constructor.
cudf::detail::column_view_base::nullable
bool nullable() const noexcept
Indicates if the column can contain null elements, i.e., if it has an allocated bitmask.
Definition: column_view.hpp:158
cudf::mutable_column_view::mutable_column_view
mutable_column_view(data_type type, size_type size, void *data, bitmask_type *null_mask, size_type null_count, size_type offset=0, std::vector< mutable_column_view > const &children={})
Construct a mutable_column_view from pointers to device memory for the elements and bitmask of the co...
cudf::is_chrono
constexpr bool is_chrono()
Indicates whether the type T is a chrono type.
Definition: traits.hpp:420
cudf::detail::column_view_base::data
T const * data() const noexcept
Returns the underlying data casted to the specified type, plus the offset.
Definition: column_view.hpp:91
cudf::mutable_column_view::set_null_count
void set_null_count(size_type new_null_count)
Set the null count.
cudf::detail::column_view_base::type
data_type type() const noexcept
Returns the element data_type
Definition: column_view.hpp:147
cudf::detail::column_view_base::begin
T const * begin() const noexcept
Return first element (accounting for offset) after underlying data is casted to the specified type.
Definition: column_view.hpp:107
cudf::detail::column_view_base::end
T const * end() const noexcept
Return one past the last element after underlying data is casted to the specified type.
Definition: column_view.hpp:123
cudf::detail::column_view_base::_null_mask
bitmask_type const * _null_mask
Definition: column_view.hpp:231
cudf::column_view::operator=
column_view & operator=(column_view const &)=default
Copy assignment operator.
cudf::detail::column_view_base::has_nulls
bool has_nulls(size_type begin, size_type end) const
Indicates if the column contains null elements in the range [begin, end), i.e., null_count(begin,...
Definition: column_view.hpp:204
cudf::detail::column_view_base::size
size_type size() const noexcept
Returns the number of elements in the column.
Definition: column_view.hpp:133
cudf::column_view::child
column_view child(size_type child_index) const noexcept
Returns the specified child.
Definition: column_view.hpp:385
cudf::device_span
Device version of C++20 std::span with reduced feature set.
Definition: span.hpp:277
type_dispatcher.hpp
Defines the mapping between cudf::type_id runtime type information and concrete C++ types.
traits.hpp
cudf::mutable_column_view::bit_cast
friend mutable_column_view bit_cast(mutable_column_view const &input, data_type type)
Zero-copy cast between types with the same size and compatible underlying representations.
cudf::detail::column_view_base::head
T const * head() const noexcept
Returns pointer to the base device memory allocation casted to the specified type.
Definition: column_view.hpp:73
cudf::detail::column_view_base::column_view_base
column_view_base(data_type type, size_type size, void const *data, bitmask_type const *null_mask, size_type null_count, size_type offset=0)
Construct a column_view_base from pointers to device memory for the elements and bitmask of the colum...
cudf::mutable_column_view::end
T * end() const noexcept
Return one past the last element after underlying data is casted to the specified type.
Definition: column_view.hpp:598
cudf::detail::column_view_base::is_empty
bool is_empty() const noexcept
Returns true if size() returns zero, or false otherwise.
Definition: column_view.hpp:140
CUDF_EXPECTS
#define CUDF_EXPECTS(...)
Macro for checking (pre-)conditions that throws an exception when a condition is violated.
Definition: error.hpp:146
error.hpp
cudf::detail::column_view_base::null_mask
bitmask_type const * null_mask() const noexcept
Returns raw pointer to the underlying bitmask allocation.
Definition: column_view.hpp:217
cudf::detail::column_view_base::_type
data_type _type
Element type.
Definition: column_view.hpp:228
cudf::detail::column_view_base::_null_count
size_type _null_count
The number of null elements.
Definition: column_view.hpp:234