null_mask.hpp
前往此文件的文档。
1 /*
2  * Copyright (c) 2019-2024, NVIDIA CORPORATION.
3  *
4  * 根据 Apache 许可证 2.0 版本 (“许可证”) 获得许可；
5  * 除非遵守许可证，否则不得使用此文件。
6  * 您可以获取许可证的副本：
7  *
8  * https://apache.ac.cn/licenses/LICENSE-2.0
9  *
10  * 除非适用法律要求或书面同意，否则根据许可证分发的软件是
11  * 在“按原样”的基础上分发的，
12  * 不附带任何明示或暗示的担保或条件。
13  * 请参阅许可证以了解管理权限和
14  * 限制的特定语言。
15  */
16 #pragma once
17 
18 #include <cudf/types.hpp>
19 #include <cudf/utilities/default_stream.hpp>
20 #include <cudf/utilities/export.hpp>
21 #include <cudf/utilities/memory_resource.hpp>
22 #include <cudf/utilities/span.hpp>
23 
24 #include <rmm/device_buffer.hpp>
25 
26 #include <vector>
27 
28 namespace CUDF_EXPORT cudf {
29 
47 /**
48  * @brief 返回表示 size 元素的指定状态的 null 掩码的 null 计数。
49  *
50  * @param state null 掩码的状态。
51  * @param size 列中的元素数量。
52  * @return null 掩码的 null 计数。
53  */
54 size_type state_null_count(mask_state state, size_type size);
55 
61 /**
62  * @brief 计算表示指定位数以及给定填充边界所需的字节数。
63  *
64  * @param number_of_bits 要表示的位数。
65  * @param padding_boundary 返回大小必须对齐的字节数。
66  * @return 位掩码所需的字节数，向上取整到下一个`padding_boundary`的倍数。
67  */
68 std::size_t bitmask_allocation_size_bytes(size_type number_of_bits,
69  std::size_t padding_boundary = 64);
70 
77 /**
78  * @brief 返回表示指定位数所需的 bitmask_type 单词数。
79  *
80  * @param number_of_bits 要表示的位数。
81  * @return 位掩码所需的`bitmask_type`单词数。
82  */
83 size_type num_bitmask_words(size_type number_of_bits);
84 
90 /**
91  * @brief 创建一个 device_buffer，用于作为列的空值指示符位掩码。
92  *
93  * @param size 列中的元素数量。
94  * @param state null 掩码的状态。
95  * @param stream 用于分配的 CUDA 流。
96  * @param mr 用于分配的设备内存资源
97  * @return 一个 device_buffer，包含 size_type::state_null_count(state, size) 个 null 值。
98  */
99 rmm::device_buffer create_null_mask(
100  size_type size,
101  mask_state state,
102  rmm::cuda_stream_view stream = cudf::get_default_stream(),
103  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
104 
109 /**
110  * @brief 将预分配的位掩码缓冲区在范围 [begin_bit, end_bit) 内设置为给定状态
111  *
112  * @param bitmask 指向位掩码开头的指针
113  * @param begin_bit 起始位索引（包含）
114  * @param end_bit 结束位索引（不包含）
115  * @param valid 布尔值，指示是将位设置为有效 (true) 还是 null (false)
116  * @param stream 用于操作的 CUDA 流
117  */
118 void set_null_mask(bitmask_type* bitmask,
119  size_type begin_bit,
120  size_type end_bit,
121  bool valid,
122  rmm::cuda_stream_view stream = cudf::get_default_stream());
123 
132 /**
133  * @brief 将位掩码中的连续位范围复制到新的位掩码中
134  *
135  * @param mask 指向输入位掩码开头的指针
136  * @param begin_bit 起始位索引（包含）
137  * @param end_bit 结束位索引（不包含）
138  * @param stream 用于操作的 CUDA 流
139  * @param mr 用于分配的设备内存资源
140  * @return 包含复制位的新 device_buffer
141  */
142 rmm::device_buffer copy_bitmask(
143  bitmask_type const* mask,
144  size_type begin_bit,
145  size_type end_bit,
146  rmm::cuda_stream_view stream = cudf::get_default_stream(),
147  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
148 
151 /**
152  * @brief 将视图的位掩码从位 [view.offset(), view.offset() + view.size()) 复制到 device_buffer 中
153  *
154  * @param view 要复制掩码的 column_view
155  * @param stream 用于操作的 CUDA 流
156  * @param mr 用于分配的设备内存资源
157  * @return 包含复制位的新 device_buffer
158  */
159 rmm::device_buffer copy_bitmask(
160  column_view const& view,
161  rmm::cuda_stream_view stream = cudf::get_default_stream(),
162  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
163 
168 /**
169  * @brief 对表的列的位掩码执行按位 AND 运算。
170  * 返回结果掩码和 null 计数的对。
171  *
172  * @param view 要执行 AND 运算的表（column）视图
173  * @param stream 用于操作的 CUDA 流
174  * @param mr 用于分配的设备内存资源
175  * @return 结果掩码和 null 计数的对。
176  */
177 std::pair<rmm::device_buffer, size_type> bitmask_and(
178  table_view const& view,
179  rmm::cuda_stream_view stream = cudf::get_default_stream(),
180  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
181 
185 /**
186  * @brief 对表的列的位掩码执行按位 OR 运算。
187  * 返回结果掩码和 null 计数的对。
188  *
cudf
189  * @param view 要执行 OR 运算的表（column）视图
190  * @param stream 用于操作的 CUDA 流
191  * @param mr 用于分配的设备内存资源
192  * @return 结果掩码和 null 计数的对。
193  */
194 std::pair<rmm::device_buffer, size_type> bitmask_or(
195  table_view const& view,