column_view.hpp
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2019-2022, 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 
170  [[nodiscard]] size_type null_count() const;
171 
187 
195  [[nodiscard]] bool has_nulls() const { return null_count() > 0; }
196 
209  [[nodiscard]] bool has_nulls(size_type begin, size_type end) const
210  {
211  return null_count(begin, end) > 0;
212  }
213 
222  [[nodiscard]] bitmask_type const* null_mask() const noexcept { return _null_mask; }
223 
230  [[nodiscard]] size_type offset() const noexcept { return _offset; }
231 
232  protected:
233  data_type _type{type_id::EMPTY};
235  void const* _data{};
237  mutable size_type _null_count{};
241 
243  column_view_base() = default;
244  ~column_view_base() = default;
245  column_view_base(column_view_base const&) = default;
247 
259 
289  size_type size,
290  void const* data,
291  bitmask_type const* null_mask = nullptr,
292  size_type null_count = UNKNOWN_NULL_COUNT,
293  size_type offset = 0);
294 };
295 
297  public:
298  protected:
299 };
300 } // namespace detail
301 
323  public:
324  column_view() = default;
325 
326  // these pragmas work around the nvcc issue where if a column_view is used
327  // inside of a __device__ code path, these functions will end up being created
328  // as __host__ __device__ because they are explicitly defaulted. However, if
329  // they then end up being called by a simple __host__ function
330  // (eg std::vector destructor) you get a compile error because you're trying to
331  // call a __host__ __device__ function from a __host__ function.
332 #pragma nv_exec_check_disable
333  ~column_view() = default;
334 #pragma nv_exec_check_disable
335  column_view(column_view const&) = default;
336  column_view(column_view&&) = default;
337 
342  column_view& operator=(column_view const&) = default;
349 
381  size_type size,
382  void const* data,
383  bitmask_type const* null_mask = nullptr,
384  size_type null_count = UNKNOWN_NULL_COUNT,
385  size_type offset = 0,
386  std::vector<column_view> const& children = {});
387 
394  [[nodiscard]] column_view child(size_type child_index) const noexcept
395  {
396  return _children[child_index];
397  }
398 
404  [[nodiscard]] size_type num_children() const noexcept { return _children.size(); }
405 
411  auto child_begin() const noexcept { return _children.cbegin(); }
412 
418  auto child_end() const noexcept { return _children.cend(); }
419 
428  template <typename T, CUDF_ENABLE_IF(cudf::is_numeric<T>() or cudf::is_chrono<T>())>
430  : column_view(
431  cudf::data_type{cudf::type_to_id<T>()}, data.size(), data.data(), nullptr, 0, 0, {})
432  {
433  CUDF_EXPECTS(
434  data.size() < static_cast<std::size_t>(std::numeric_limits<cudf::size_type>::max()),
435  "Data exceeds the maximum size of a column view.");
436  }
437 
449  template <typename T, CUDF_ENABLE_IF(cudf::is_numeric<T>() or cudf::is_chrono<T>())>
450  [[nodiscard]] operator device_span<T const>() const
451  {
452  CUDF_EXPECTS(type() == cudf::data_type{cudf::type_to_id<T>()},
453  "Device span type must match column view type.");
454  CUDF_EXPECTS(!nullable(), "A nullable column view cannot be converted to a device span.");
455  return device_span<T const>(data<T>(), size());
456  }
457 
458  private:
460 
461  std::vector<column_view> _children{};
462 }; // namespace cudf
464 
486  public:
487  mutable_column_view() = default;
488 
489  ~mutable_column_view() = default;
490 
493 
505 
536  size_type size,
537  void* data,
538  bitmask_type* null_mask = nullptr,
539  size_type null_count = cudf::UNKNOWN_NULL_COUNT,
540  size_type offset = 0,
541  std::vector<mutable_column_view> const& children = {});
542 
558  template <typename T = void,
559  CUDF_ENABLE_IF(std::is_same_v<T, void> or is_rep_layout_compatible<T>())>
560  T* head() const noexcept
561  {
562  return const_cast<T*>(detail::column_view_base::head<T>());
563  }
564 
577  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
578  T* data() const noexcept
579  {
580  return const_cast<T*>(detail::column_view_base::data<T>());
581  }
582 
593  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
594  T* begin() const noexcept
595  {
596  return const_cast<T*>(detail::column_view_base::begin<T>());
597  }
598 
609  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
610  T* end() const noexcept
611  {
612  return const_cast<T*>(detail::column_view_base::end<T>());
613  }
614 
624  [[nodiscard]] bitmask_type* null_mask() const noexcept
625  {
626  return const_cast<bitmask_type*>(detail::column_view_base::null_mask());
627  }
628 
636  void set_null_count(size_type new_null_count);
637 
644  [[nodiscard]] mutable_column_view child(size_type child_index) const noexcept
645  {
646  return mutable_children[child_index];
647  }
648 
654  [[nodiscard]] size_type num_children() const noexcept { return mutable_children.size(); }
655 
661  auto child_begin() const noexcept { return mutable_children.begin(); }
662 
668  auto child_end() const noexcept { return mutable_children.end(); }
669 
675  operator column_view() const;
676 
677  private:
679 
680  std::vector<mutable_column_view> mutable_children;
681 };
682 
690 
713 
736 
737 namespace detail {
753 std::size_t shallow_hash(column_view const& input);
754 
776 bool is_shallow_equivalent(column_view const& lhs, column_view const& rhs);
777 } // namespace detail
778 } // 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:661
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:654
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:235
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:234
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:411
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:404
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:322
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:230
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:594
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:485
cudf::detail::column_view_base::_offset
size_type _offset
Definition: column_view.hpp:240
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:418
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:578
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::column_view::column_view
column_view(data_type type, size_type size, void const *data, bitmask_type const *null_mask=nullptr, size_type null_count=UNKNOWN_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::mutable_column_view
mutable_column_view(data_type type, size_type size, void *data, bitmask_type *null_mask=nullptr, size_type null_count=cudf::UNKNOWN_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::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:668
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.
cudf::detail::mutable_column_view_base
Definition: column_view.hpp:296
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:624
cudf::column_view::operator=
column_view & operator=(column_view &&)=default
Move assignment operator.
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=nullptr, size_type null_count=UNKNOWN_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::data_type
Indicator for the logical data type of an element in a column.
Definition: types.hpp:236
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:644
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:195
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:560
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::is_chrono
constexpr bool is_chrono()
Indicates whether the type T is a chrono type.
Definition: traits.hpp:402
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_EXPECTS
#define CUDF_EXPECTS(cond, reason)
Macro for checking (pre-)conditions that throws an exception when a condition is violated.
Definition: error.hpp:113
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:236
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:209
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:394
cudf::device_span
Device version of C++20 std::span with reduced feature set.
Definition: span.hpp:285
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::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:610
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
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:222
cudf::detail::column_view_base::_type
data_type _type
Element type.
Definition: column_view.hpp:233
cudf::detail::column_view_base::_null_count
size_type _null_count
The number of null elements.
Definition: column_view.hpp:239