scalar_device_view.cuh

前往此文件的文档。

/*
 * 版权所有 (c) 2019-2024, NVIDIA CORPORATION.
 *
 * 根据 Apache 许可证版本 2.0 (以下简称“许可证”) 获得许可；
 * 除非遵守许可证，否则不得使用此文件。
 * 您可以在以下位置获取许可证的副本：
 *
 * https://apache.ac.cn/licenses/LICENSE-2.0
 *
 * 除非适用法律要求或书面同意，否则软件
 * 根据许可证分发，不提供任何形式的担保，无论是明示还是暗示。
 * 包括但不限于对适销性、特定用途适用性和非侵权的担保。
 * 有关根据许可证授予的权限和限制的特定语言，请参见许可证。
 * limitations under the License.
 */
#pragma once

#include <cudf/scalar/scalar.hpp>
#include <cudf/strings/string_view.hpp>
#include <cudf/types.hpp>

namespace CUDF_EXPORT cudf {
namespace detail {
/// scalar 在设备上的非拥有视图，它是可平凡复制的，可在 CUDA 设备代码中使用。
class scalar_device_view_base {
 public
 ~scalar_device_view_base() = default;

 /// 返回值类型。
 [[nodiscard]] __host__ __device__ data_type type() const noexcept { return _type; }

 /// 返回标量是否持有一个有效值（即，非空）。
 [[nodiscard]] __device__ bool is_valid() const noexcept { return *_is_valid; }

 /// 更新值的有效性。
 __device__ void set_valid(bool is_valid) noexcept { *_is_valid = is_valid; }

 protected
 data_type _type{type_id::EMPTY};
 bool* _is_valid{};

 /// 从设备指针和有效性布尔值构造新的 scalar 设备视图基对象。
 scalar_device_view_base(data_type type, bool* is_valid) : _type(type), _is_valid(is_valid) {}

 scalar_device_view_base() = default;
};

/// 一种类型擦除的 scalar_device_view，其值为固定宽度类型。
class fixed_width_scalar_device_view_base : public detail::scalar_device_view_base {
 public
 /// 返回存储值的引用。
 template <typename T>
 __device__ T& value() noexcept
 {
 return *data<T>();
 }

 /// 返回存储值的 const 引用。
 template <typename T>
 __device__ T const& value() const noexcept
 {
 return *data<T>();
 }

 /// 在标量中存储值。
 template <typename T>
 __device__ void set_value(T value)
 {
 *static_cast<T*>(_data) = value;
 }

 /// 返回设备内存中值的原始指针。
 template <typename T>
 __device__ T* data() noexcept
 {
 return static_cast<T*>(_data);
 }

 /// 返回设备内存中值的 const 原始指针。
 template <typename T>
 __device__ T const* data() const noexcept
 {
 return static_cast<T const*>(_data);
 }

 protected
 void* _data{};

 /// 构造一个新的固定宽度 scalar 设备视图对象。
 fixed_width_scalar_device_view_base(data_type type, void* data, bool* is_valid)
 : detail::scalar_device_view_base(type, is_valid), _data(data)
 {
 }
};

/// 一种 scalar_device_view 类型，其值为固定宽度类型。
template <typename T>
class fixed_width_scalar_device_view : public detail::fixed_width_scalar_device_view_base {
 public
 /// 标量的值类型。
 using value_type = T;

 /// 返回存储值的引用。
 __device__ T& value() noexcept { return fixed_width_scalar_device_view_base::value<T>(); }

 /// 返回存储值的 const 引用。
 __device__ T const& value() const noexcept
 {
 return fixed_width_scalar_device_view_base::value<T>();
 }

 /// 在标量中存储值。
 __device__ void set_value(T value) { fixed_width_scalar_device_view_base::set_value<T>(value); }

 /// 返回设备内存中值的原始指针。
 __device__ T* data() noexcept { return fixed_width_scalar_device_view_base::data<T>(); }

 /// 返回设备内存中值的 const 原始指针。
 __device__ T const* data() const noexcept
 {
 return fixed_width_scalar_device_view_base::data<T>();
 }

 protected
 /// 构造一个新的固定宽度 scalar 设备视图对象。
 fixed_width_scalar_device_view(data_type type, T* data, bool* is_valid)
 : detail::fixed_width_scalar_device_view_base(type, data, is_valid)
 {
 }
};

} // namespace detail

/// 一种 scalar_device_view 类型，存储指向数值的指针。
template <typename T>
class numeric_scalar_device_view : public detail::fixed_width_scalar_device_view<T> {
 public
 /// 从数据指针和有效性指针构造新的数值 scalar 设备视图对象。
 numeric_scalar_device_view(data_type type, T* data, bool* is_valid)
 : detail::fixed_width_scalar_device_view<T>(type, data, is_valid)
 {
 }
};

/// 一种 scalar_device_view 类型，存储指向 fixed_point 值的指针。
template <typename T>
class fixed_point_scalar_device_view : public detail::scalar_device_view_base {
 public
 /// fixed_point 值的表示类型。
 using rep_type = typename T::rep;

 /// 从数据指针和有效性指针构造新的定点 scalar 设备视图对象。
 fixed_point_scalar_device_view(data_type type, rep_type* data, bool* is_valid)
 : detail::scalar_device_view_base(type, is_valid), _data(data)
 {
 }

 /// 在标量中存储值。
 __device__ void set_value(rep_type value) { *_data = value; }

 /// 获取标量的值，作为 rep_type。
 __device__ rep_type const& rep() const noexcept { return *_data; }

 private
 rep_type* _data{};
};

/// 一种 scalar_device_view 类型，存储指向字符串值的指针。
class string_scalar_device_view : public detail::scalar_device_view_base {
 public
 using ValueType = cudf::string_view;

 /// 从字符串数据、大小和有效性指针构造新的字符串 scalar 设备视图对象。
 string_scalar_device_view(data_type type, char const* data, bool* is_valid, size_type size)
 : detail::scalar_device_view_base(type, is_valid), _data(data), _size(size)
 {
 }

 /// 返回此标量值的 string_view。
 [[nodiscard]] __device__ ValueType value() const noexcept
 {
 return ValueType{this->data(), _size};
 }

 /// 返回设备内存中字符串的原始指针。
 [[nodiscard]] __device__ char const* data() const noexcept
 {
 return static_cast<char const*>(_data);
 }

 /// 返回字符串的大小（字节）。
 [[nodiscard]] __device__ size_type size() const noexcept { return _size; }

 private
 char const* _data{};
 size_type _size;
};

/// 一种 scalar_device_view 类型，存储指向时间戳值的指针。
template <typename T>
class timestamp_scalar_device_view : public detail::fixed_width_scalar_device_view<T> {
 public
 /// 构造一个新的时间戳 scalar 设备视图对象。
 timestamp_scalar_device_view(data_type type, T* data, bool* is_valid)
 : detail::fixed_width_scalar_device_view<T>(type, data, is_valid)
 {
 }
};

/// 一种 scalar_device_view 类型，存储指向 duration 值的指针。
template <typename T>
class duration_scalar_device_view : public detail::fixed_width_scalar_device_view<T> {
 public
 /// 从数据指针和有效性指针构造新的 duration scalar 设备视图对象。