scalar.hpp

查看此文件的文档。

/*
 * 版权所有 (c) 2019-2025, NVIDIA CORPORATION.
 *
 * 根据 Apache 许可证 2.0 版（“许可证”）获得许可；
 * 除非遵守许可证的规定，否则不得使用此文件。
 * 您可以在以下位置获取许可证副本：
 *
 * https://apache.ac.cn/licenses/LICENSE-2.0
 *
 * 除非适用法律要求或书面同意，根据许可证分发的软件
 * 按“原样”分发，不附带任何明示或默示的保证或条件。
 * 请参阅许可证，了解管理权限和限制的特定语言。
 *
 * limitations under the License.
 */
#pragma once

#include <cudf/column/column.hpp>
#include <cudf/detail/device_scalar.hpp>
#include <cudf/table/table.hpp>
#include <cudf/types.hpp>
#include <cudf/utilities/default_stream.hpp>
#include <cudf/utilities/memory_resource.hpp>
#include <cudf/utilities/traits.hpp>

#include <rmm/cuda_stream_view.hpp>
#include <rmm/device_buffer.hpp>
#include <rmm/device_scalar.hpp>

#include <string_view>

namespace CUDF_EXPORT cudf {
class scalar {
 public
 scalar() = delete;
 virtual ~scalar() = default;
 scalar& operator=(scalar const& other) = delete;
 scalar& operator=(scalar&& other) = delete;

 [[nodiscard]] data_type type() const noexcept; // 返回标量的类型。

 void set_valid_async(bool is_valid, rmm::cuda_stream_view stream = cudf::get_default_stream()); // 异步设置有效位。

 [[nodiscard]] bool is_valid(rmm::cuda_stream_view stream = cudf::get_default_stream()) const; // 获取有效位。

 bool* validity_data(); // 返回设备内存中有效位的原始指针。

 [[nodiscard]] bool const* validity_data() const; // 返回设备内存中有效位的常量原始指针。

 protected
 data_type _type{type_id::EMPTY}; // 标量类型
 cudf::detail::device_scalar<bool> _is_valid; // 包含有效位的设备内存

 scalar(scalar&& other) = default; // 标量的移动构造函数。

 scalar(scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个标量对象来构造新的标量对象。

 scalar(data_type type,
 bool is_valid = false,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 构造新的标量对象。
};

namespace detail {
template <typename T>
class fixed_width_scalar : public scalar {
 static_assert(is_fixed_width<T>(), "意外的非固定宽度类型。");

 public
 using value_type = T; // 标量持有的值的类型。

 fixed_width_scalar() = delete;
 ~fixed_width_scalar() override = default;

 fixed_width_scalar(fixed_width_scalar&& other) = default; // fixed_width_scalar 的移动构造函数。

 fixed_width_scalar& operator=(fixed_width_scalar const& other) = delete;
 fixed_width_scalar& operator=(fixed_width_scalar&& other) = delete;

 fixed_width_scalar(fixed_width_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 fixed-width scalar 对象来构造新的 fixed-width scalar 对象。

 void set_value(T value, rmm::cuda_stream_view stream = cudf::get_default_stream()); // 设置标量的值。

 [[nodiscard]] T value(rmm::cuda_stream_view stream = cudf::get_default_stream()) const; // 获取标量的值。

 T* data(); // 返回设备内存中值的原始指针。

 [[nodiscard]] T const* data() const; // 返回设备内存中值的常量原始指针。

 protected
 rmm::device_scalar<T> _data; // 包含值的设备内存

 fixed_width_scalar(T value,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 构造新的固定宽度标量对象。

 fixed_width_scalar(rmm::device_scalar<T>&& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从现有设备内存构造新的固定宽度标量对象。
};

} // namespace detail

template <typename T>
class numeric_scalar : public detail::fixed_width_scalar<T> {
 static_assert(is_numeric<T>(), "意外的非数值类型。");

 public
 numeric_scalar() = delete;
 ~numeric_scalar() override = default;

 numeric_scalar(numeric_scalar&& other) = default; // numeric_scalar 的移动构造函数。

 numeric_scalar& operator=(numeric_scalar const& other) = delete;
 numeric_scalar& operator=(numeric_scalar&& other) = delete;

 numeric_scalar(numeric_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 numeric scalar 对象来构造新的 numeric scalar 对象。

 numeric_scalar(T value,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 构造新的数值标量对象。

 numeric_scalar(rmm::device_scalar<T>&& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从现有设备内存构造新的数值标量对象。
};

template <typename T>
class fixed_point_scalar : public scalar {
 static_assert(is_fixed_point<T>(), "意外的非 fixed_point 类型。");

 public
 using rep_type = typename T::rep; // fixed_point 的底层表示类型。
 using value_type = T; // 标量持有的值的类型。

 fixed_point_scalar() = delete;
 ~fixed_point_scalar() override = default;

 fixed_point_scalar(fixed_point_scalar&& other) = default; // fixed_point_scalar 的移动构造函数。

 fixed_point_scalar& operator=(fixed_point_scalar const& other) = delete;
 fixed_point_scalar& operator=(fixed_point_scalar&& other) = delete;

 fixed_point_scalar(fixed_point_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 fixed_point scalar 对象来构造新的 fixed_point scalar 对象。

 fixed_point_scalar(rep_type value,
 numeric::scale_type scale,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从代表性值和比例构造新的 fixed_point scalar 对象。

 fixed_point_scalar(rep_type value,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从值和默认 0 比例构造新的 fixed_point scalar 对象。

 fixed_point_scalar(T value,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从 fixed_point 数构造新的 fixed_point scalar 对象。

 fixed_point_scalar(rmm::device_scalar<rep_type>&& data,
 numeric::scale_type scale,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从现有设备内存构造新的 fixed_point scalar 对象。

 [[nodiscard]] rep_type value(rmm::cuda_stream_view stream = cudf::get_default_stream()) const; // 获取 fixed_point scalar 的原始值。

 [[nodiscard]] T fixed_point_value(// 将 fixed_point scalar 的值作为 fixed_point 类型获取。
 rmm::cuda_stream_view stream = cudf::get_default_stream()) const;

 rep_type* data(); // 返回设备内存中值的原始指针。

 [[nodiscard]] rep_type const* data() const; // 返回设备内存中值的常量原始指针。

 protected
 rmm::device_scalar<rep_type> _data; // 包含原始值的设备内存
};

class string_scalar : public scalar {
 public
 using value_type = cudf::string_view;

 string_scalar() = delete;
 ~string_scalar() override = default;

 string_scalar(string_scalar&& other) = default; // string_scalar 的移动构造函数。

 // string_scalar(string_scalar const& other) = delete;
 string_scalar& operator=(string_scalar const& other) = delete;
 string_scalar& operator=(string_scalar&& other) = delete;

 string_scalar(string_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 string scalar 对象来构造新的 string scalar 对象。

 string_scalar(std::string_view string,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从主机 std::string_view 构造新的 string scalar 对象。

 string_scalar(value_type const& source,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从 cudf::string_view 构造新的 string scalar 对象。

 string_scalar(rmm::device_scalar<value_type>& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从 string_view 的现有 device_scalar 构造新的 string scalar 对象。

 string_scalar(rmm::device_buffer&& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从现有 device_buffer 构造新的 string scalar 对象。

 [[nodiscard]] std::string to_string(// 将设备字符串转换为主机 std::string。
 rmm::cuda_stream_view stream = cudf::get_default_stream()) const;

 [[nodiscard]] value_type value(rmm::cuda_stream_view stream = cudf::get_default_stream()) const; // 将字符串值获取为 cudf::string_view。

 [[nodiscard]] size_type size() const; // 获取字符串的大小（以字节为单位）。

 [[nodiscard]] char const* data() const; // 返回设备内存中值的常量原始指针。

 protected
 rmm::device_buffer _data{}; // 包含字符串数据的设备内存
};

template <typename T>
class chrono_scalar : public detail::fixed_width_scalar<T> {
 static_assert(is_chrono<T>(), "意外的非 chrono 类型");

 public
 chrono_scalar() = delete;
 ~chrono_scalar() override = default;

 chrono_scalar(chrono_scalar&& other) = default; // chrono_scalar 的移动构造函数。

 chrono_scalar& operator=(chrono_scalar const& other) = delete;
 chrono_scalar& operator=(chrono_scalar&& other) = delete;

 chrono_scalar(chrono_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 chrono scalar 对象来构造新的 chrono scalar 对象。

 chrono_scalar(T value,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 构造新的 chrono scalar 对象。

 chrono_scalar(rmm::device_scalar<T>&& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从现有设备内存构造新的 chrono scalar 对象。
};

template <typename T>
class timestamp_scalar : public chrono_scalar<T> {
 public
 static_assert(is_timestamp<T>(), "意外的非 timestamp 类型");
 using chrono_scalar<T>::chrono_scalar;
 using rep_type = typename T::rep; // timestamp 的底层表示类型。

 timestamp_scalar() = delete;

 timestamp_scalar(timestamp_scalar&& other) = default; // timestamp_scalar 的移动构造函数。

 timestamp_scalar(timestamp_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 timestamp scalar 对象来构造新的 timestamp scalar 对象。

 template <typename Duration2>
 timestamp_scalar(Duration2 const& value,
 bool is_valid,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从 std::chrono::duration 构造新的 timestamp scalar 对象。

 rep_type ticks_since_epoch(rmm::cuda_stream_view stream); // 返回自 epoch 以来的时间戳（以 tick 数表示）。
};

template <typename T>
class duration_scalar : public chrono_scalar<T> {
 public
 static_assert(is_duration<T>(), "意外的非 duration 类型");
 using chrono_scalar<T>::chrono_scalar;
 using rep_type = typename T::rep; // duration 的底层表示类型。

 duration_scalar() = delete;

 duration_scalar(duration_scalar&& other) = default; // duration_scalar 的移动构造函数。

 duration_scalar(duration_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 duration scalar 对象来构造新的 duration scalar 对象。

 duration_scalar(rep_type value,
 bool is_valid,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从 tick 数构造新的 duration scalar 对象。

 rep_type count(rmm::cuda_stream_view stream); // 返回 duration（以 tick 数表示）。
};

class list_scalar : public scalar {
 public
 list_scalar() = delete;
 ~list_scalar() override = default;

 list_scalar(list_scalar&& other) = default; // list_scalar 的移动构造函数。

 list_scalar& operator=(list_scalar const& other) = delete;
 list_scalar& operator=(list_scalar&& other) = delete;

 list_scalar(list_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 list scalar 对象来构造新的 list scalar 对象。

 list_scalar(cudf::column_view const& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从列视图构造新的 list scalar 对象。

 list_scalar(cudf::column&& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从列构造新的 list scalar 对象。

 [[nodiscard]] column_view view() const; // 返回列表元素的 column_view。

 private
 cudf::column _data; // 包含列表元素的设备内存
};

class struct_scalar : public scalar {
 public
 struct_scalar() = delete;
 ~struct_scalar() override = default;

 struct_scalar(struct_scalar&& other) = default; // struct_scalar 的移动构造函数。
 struct_scalar& operator=(struct_scalar const& other) = delete;
 struct_scalar& operator=(struct_scalar&& other) = delete;

 struct_scalar(struct_scalar const& other,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 通过深度复制另一个 struct scalar 对象来构造新的 struct scalar 对象。

 struct_scalar(table_view const& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从表视图构造新的 struct scalar 对象。

 struct_scalar(host_span<column_view const> data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从主机列视图跨度构造新的 struct scalar 对象。

 struct_scalar(table&& data,
 bool is_valid = true,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 从表构造新的 struct scalar 对象。

 [[nodiscard]] table_view view() const; // 返回结构体字段的 table_view。

 private
 table _data; // 包含结构体字段的设备内存

 void assert_valid_size(); // 断言 _data 包含一个有效的结构体（0 行，N 列）。

 static table init_data(table&& data,// 初始化表数据，断言它是一个有效的结构体（0 行，N 列）。
 bool is_valid,
 rmm::cuda_stream_view stream,
 rmm::device_async_resource_ref mr);
};
 // 组结束
} // 命名空间 CUDF_EXPORT cudf