column_view.hpp

Go to the documentation of this file.

/*
 * Copyright (c) 2019-2025, NVIDIA CORPORATION.
 *
 * Licensed 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.
 */
#pragma once
 
#include <cudf/types.hpp>
#include <cudf/utilities/error.hpp>
#include <cudf/utilities/prefetch.hpp>
#include <cudf/utilities/span.hpp>
#include <cudf/utilities/traits.hpp>
#include <cudf/utilities/type_dispatcher.hpp>
 
#include <limits>
#include <type_traits>
#include <vector>
 
namespace CUDF_EXPORT cudf {
namespace detail {
class column_view_base {
 public:
  template <typename T = void,
            CUDF_ENABLE_IF(std::is_same_v<T, void> or is_rep_layout_compatible<T>())>
  T const* head() const noexcept
  {
    return static_cast<T const*>(get_data());
  }
 
  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
  T const* data() const noexcept
  {
    return head<T>() + _offset;
  }
 
  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
  T const* begin() const noexcept
  {
    return data<T>();
  }
 
  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
  T const* end() const noexcept
  {
    return begin<T>() + size();
  }
 
  [[nodiscard]] size_type size() const noexcept { return _size; }
 
  [[nodiscard]] bool is_empty() const noexcept { return size() == 0; }
 
  [[nodiscard]] data_type type() const noexcept { return _type; }
 
  [[nodiscard]] bool nullable() const noexcept { return nullptr != _null_mask; }
 
  [[nodiscard]] size_type null_count() const { return _null_count; }
 
  [[nodiscard]] size_type null_count(
    size_type begin,
    size_type end,
    rmm::cuda_stream_view stream = cudf::get_default_stream()) const;
 
  [[nodiscard]] bool has_nulls() const { return null_count() > 0; }
 
  [[nodiscard]] bool has_nulls(size_type begin,
                               size_type end,
                               rmm::cuda_stream_view stream = cudf::get_default_stream()) const
  {
    return null_count(begin, end, stream) > 0;
  }
 
  [[nodiscard]] bitmask_type const* null_mask() const noexcept { return _null_mask; }
 
  [[nodiscard]] size_type offset() const noexcept { return _offset; }
 
 protected:
  [[nodiscard]] virtual void const* get_data() const noexcept { return _data; }
 
  data_type _type{type_id::EMPTY};   
  size_type _size{};                 
  void const* _data{};               
  bitmask_type const* _null_mask{};  
  mutable size_type _null_count{};   
  size_type _offset{};               
 
  column_view_base()                        = default;
  virtual ~column_view_base()               = default;
  column_view_base(column_view_base const&) = default;  
  column_view_base(column_view_base&&)      = default;  
  column_view_base& operator=(column_view_base const&) = default;
  column_view_base& operator=(column_view_base&&) = default;
 
  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);
};
 
}  // namespace detail
 
class column_view : public detail::column_view_base {
 public:
  column_view() = default;
 
  // these pragmas work around the nvcc issue where if a column_view is used
  // inside of a __device__ code path, these functions will end up being created
  // as __host__ __device__ because they are explicitly defaulted.  However, if
  // they then end up being called by a simple __host__ function
  // (eg std::vector destructor) you get a compile error because you're trying to
  // call a __host__ __device__ function from a __host__ function.
#ifdef __CUDACC__
#pragma nv_exec_check_disable
#endif
  ~column_view() override = default;
#ifdef __CUDACC__
#pragma nv_exec_check_disable
#endif
  column_view(column_view const&) = default;  
  column_view(column_view&&)      = default;  
  column_view& operator=(column_view const&) = default;
  column_view& operator=(column_view&&) = default;
 
  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 = {});
 
  [[nodiscard]] column_view child(size_type child_index) const noexcept
  {
    return _children[child_index];
  }
 
  [[nodiscard]] size_type num_children() const noexcept { return _children.size(); }
 
  auto child_begin() const noexcept { return _children.cbegin(); }
 
  auto child_end() const noexcept { return _children.cend(); }
 
  template <typename T, CUDF_ENABLE_IF(cudf::is_numeric<T>() or cudf::is_chrono<T>())>
  column_view(device_span<T const> data)
    : column_view(
        cudf::data_type{cudf::type_to_id<T>()}, data.size(), data.data(), nullptr, 0, 0, {})
  {
    CUDF_EXPECTS(
      data.size() <= static_cast<std::size_t>(std::numeric_limits<cudf::size_type>::max()),
      "Data exceeds the column size limit",
      std::overflow_error);
  }
 
  template <typename T, CUDF_ENABLE_IF(cudf::is_numeric<T>() or cudf::is_chrono<T>())>
  [[nodiscard]] operator device_span<T const>() const
  {
    CUDF_EXPECTS(type() == cudf::data_type{cudf::type_to_id<T>()},
                 "Device span type must match column view type.");
    CUDF_EXPECTS(!nullable(), "A nullable column view cannot be converted to a device span.");
    return device_span<T const>(data<T>(), size());
  }
 
 protected:
  void const* get_data() const noexcept override;
 
 private:
  friend column_view bit_cast(column_view const& input, data_type type);
 
  std::vector<column_view> _children{};  
};  // namespace cudf
 
class mutable_column_view : public detail::column_view_base {
 public:
  mutable_column_view() = default;
 
  ~mutable_column_view() override {
    // Needed so that the first instance of the implicit destructor for any TU isn't 'constructed'
    // from a host+device function marking the implicit version also as host+device
  };
 
  mutable_column_view(mutable_column_view const&) = default;  
  mutable_column_view(mutable_column_view&&)      = default;  
  mutable_column_view& operator=(mutable_column_view const&) = default;
  mutable_column_view& operator=(mutable_column_view&&) = default;
 
  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 = {});
 
  template <typename T = void,
            CUDF_ENABLE_IF(std::is_same_v<T, void> or is_rep_layout_compatible<T>())>
  T* head() const noexcept
  {
    return const_cast<T*>(detail::column_view_base::head<T>());
  }
 
  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
  T* data() const noexcept
  {
    return const_cast<T*>(detail::column_view_base::data<T>());
  }
 
  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
  T* begin() const noexcept
  {
    return const_cast<T*>(detail::column_view_base::begin<T>());
  }
 
  template <typename T, CUDF_ENABLE_IF(is_rep_layout_compatible<T>())>
  T* end() const noexcept
  {
    return const_cast<T*>(detail::column_view_base::end<T>());
  }
 
  [[nodiscard]] bitmask_type* null_mask() const noexcept
  {
    return const_cast<bitmask_type*>(detail::column_view_base::null_mask());
  }
 
  void set_null_count(size_type new_null_count);
 
  [[nodiscard]] mutable_column_view child(size_type child_index) const noexcept
  {
    return mutable_children[child_index];
  }
 
  [[nodiscard]] size_type num_children() const noexcept { return mutable_children.size(); }
 
  auto child_begin() const noexcept { return mutable_children.begin(); }
 
  auto child_end() const noexcept { return mutable_children.end(); }
 
  operator column_view() const;
 
 protected:
  [[nodiscard]] void const* get_data() const noexcept override;
 
 private:
  friend mutable_column_view bit_cast(mutable_column_view const& input, data_type type);
 
  std::vector<mutable_column_view> mutable_children;
};
 
size_type count_descendants(column_view parent);
 
column_view bit_cast(column_view const& input, data_type type);
 
mutable_column_view bit_cast(mutable_column_view const& input, data_type type);
 
namespace detail {
std::size_t shallow_hash(column_view const& input);
 
bool is_shallow_equivalent(column_view const& lhs, column_view const& rhs);
 
}  // namespace detail
}  // namespace CUDF_EXPORT cudf