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:
230  void const* _data{};
234  mutable size_type _null_count{};
237 
238  column_view_base() = default;
239  ~column_view_base() = default;
240  column_view_base(column_view_base const&) = default;
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;
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{};
455 }; // namespace cudf
456 
478  public:
479  mutable_column_view() = default;
480 
481  ~mutable_column_view() = default;
482 
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
A non-owning, immutable view of device data as a column of elements, some of which may be null as ind...
column_view(column_view &&)=default
Move constructor.
size_type num_children() const noexcept
Returns the number of child columns.
auto child_begin() const noexcept
Returns iterator to the beginning of the ordered sequence of child column-views.
column_view & operator=(column_view &&)=default
Move assignment operator.
column_view & operator=(column_view const &)=default
Copy assignment operator.
auto child_end() const noexcept
Returns iterator to the end of the ordered sequence of child column-views.
column_view child(size_type child_index) const noexcept
Returns the specified child.
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.
column_view(column_view const &)=default
Copy constructor.
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.
Indicator for the logical data type of an element in a column.
Definition: types.hpp:227
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
size_type null_count(size_type begin, size_type end) const
Returns the count of null elements in the range [begin, end)
T const * end() const noexcept
Return one past the last element after underlying data is casted to the specified type.
data_type type() const noexcept
Returns the element data_type
column_view_base(column_view_base &&)=default
Move constructor.
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...
bitmask_type const * _null_mask
size_type null_count() const
Returns the count of null elements.
size_type _size
Number of elements.
column_view_base & operator=(column_view_base const &)=default
Copy assignment operator.
column_view_base & operator=(column_view_base &&)=default
Move assignment operator.
size_type size() const noexcept
Returns the number of elements in the column.
T const * begin() const noexcept
Return first element (accounting for offset) after underlying data is casted to the specified type.
T const * data() const noexcept
Returns the underlying data casted to the specified type, plus the offset.
Definition: column_view.hpp:91
size_type offset() const noexcept
Returns the index of the first element relative to the base memory allocation, i.e....
data_type _type
Element type.
size_type _null_count
The number of null elements.
T const * head() const noexcept
Returns pointer to the base device memory allocation casted to the specified type.
Definition: column_view.hpp:73
void const * _data
Pointer to device memory containing elements.
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,...
bool has_nulls() const
Indicates if the column contains null elements, i.e., null_count() > 0
bitmask_type const * null_mask() const noexcept
Returns raw pointer to the underlying bitmask allocation.
bool nullable() const noexcept
Indicates if the column can contain null elements, i.e., if it has an allocated bitmask.
column_view_base(column_view_base const &)=default
Copy constructor.
bool is_empty() const noexcept
Returns true if size() returns zero, or false otherwise.
A non-owning, mutable view of device data as a column of elements, some of which may be null as indic...
T * head() const noexcept
Returns pointer to the base device memory allocation casted to the specified type.
size_type num_children() const noexcept
Returns the number of child columns.
T * begin() const noexcept
Return first element (accounting for offset) when underlying data is casted to the specified type.
void set_null_count(size_type new_null_count)
Set the null count.
auto child_begin() const noexcept
Returns iterator to the beginning of the ordered sequence of child column-views.
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...
T * data() const noexcept
Returns the underlying data casted to the specified type, plus the offset.
mutable_column_view(mutable_column_view const &)=default
Copy constructor.
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.
mutable_column_view & operator=(mutable_column_view &&)=default
Move assignment operator.
mutable_column_view & operator=(mutable_column_view const &)=default
Copy assignment operator.
auto child_end() const noexcept
Returns iterator to the end of the ordered sequence of child column-views.
bitmask_type * null_mask() const noexcept
Returns raw pointer to the underlying bitmask allocation.
mutable_column_view child(size_type child_index) const noexcept
Returns a reference to the specified child.
mutable_column_view(mutable_column_view &&)=default
Move constructor.
T * end() const noexcept
Return one past the last element after underlying data is casted to the specified type.
std::size_t shallow_hash(column_view const &input)
Computes a hash value from the shallow state of the specified column.
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.
#define CUDF_EXPECTS(...)
Macro for checking (pre-)conditions that throws an exception when a condition is violated.
Definition: error.hpp:170
int32_t size_type
Row index type for columns and tables.
Definition: types.hpp:80
uint32_t bitmask_type
Bitmask type stored as 32-bit unsigned integer.
Definition: types.hpp:81
constexpr bool is_chrono()
Indicates whether the type T is a chrono type.
Definition: traits.hpp:444
#define CUDF_ENABLE_IF(...)
Convenience macro for SFINAE as an unnamed template parameter.
Definition: traits.hpp:50
@ EMPTY
Always null with no underlying data.
cuDF interfaces
Definition: aggregation.hpp:34
column_view bit_cast(column_view const &input, data_type type)
Zero-copy cast between types with the same size and compatible underlying representations.
size_type count_descendants(column_view parent)
Counts the number of descendants of the specified parent.
Device version of C++20 std::span with reduced feature set.
Definition: span.hpp:277
Defines the mapping between cudf::type_id runtime type information and concrete C++ types.
Type declarations for libcudf.