位掩码操作

文件
文件	null_mask.hpp
	用于管理有效性位掩码的 API。

函数
size_type	cudf::state_null_count (mask_state state, size_type size)
	返回表示 size 个元素的、指定 state 的空掩码的空值计数。 更多...
std::size_t	cudf::bitmask_allocation_size_bytes (size_type number_of_bits, std::size_t padding_boundary=64)
	计算表示指定位数并给定填充边界所需的字节数。 更多...
size_type	cudf::num_bitmask_words (size_type number_of_bits)
	返回表示指定位数所需的 bitmask_type 字数。 更多...
rmm::device_buffer	cudf::create_null_mask (size_type size, mask_state state, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	创建一个 device_buffer 用作 column 的空值指示符位掩码。 更多...
void	cudf::set_null_mask (bitmask_type *bitmask, size_type begin_bit, size_type end_bit, bool valid, rmm::cuda_stream_view stream=cudf::get_default_stream())
	将预分配的位掩码缓冲区在范围 [begin_bit, end_bit) 内设置为给定状态。 更多...
rmm::device_buffer	cudf::copy_bitmask (bitmask_type const *mask, size_type begin_bit, size_type end_bit, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	从由索引范围 [begin_bit, end_bit) 定义的位掩码切片创建 device_buffer。 更多...
rmm::device_buffer	cudf::copy_bitmask (column_view const &view, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	将 view 的位掩码从位 [view.offset(), view.offset() + view.size()) 复制到 device_buffer 中。 更多...
std::pair< rmm::device_buffer, size_type >	cudf::bitmask_and (table_view const &view, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	对表的列的位掩码执行按位 AND 操作。返回结果掩码和未设置位的计数对。 更多...
std::pair< rmm::device_buffer, size_type >	cudf::bitmask_or (table_view const &view, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	对表的列的位掩码执行按位 OR 操作。返回结果掩码和未设置位的计数对。 更多...
cudf::size_type	cudf::null_count (bitmask_type const *bitmask, size_type start, size_type stop, rmm::cuda_stream_view stream=cudf::get_default_stream())
	给定有效性位掩码，计算范围 [start, stop) 内空元素（未设置位）的数量。 更多...

详细描述

函数文档

bitmask_allocation_size_bytes()

std::size_t cudf::bitmask_allocation_size_bytes	(	size_type	number_of_bits,
		std::size_t	padding_boundary = 64
	)

计算表示指定位数并给定填充边界所需的字节数。

注意

Arrow 规范要求空值位掩码具有 64B 的填充边界。

参数

number_of_bits	需要表示的位数
padding_boundary	返回的值将向上舍入到此值的倍数

返回值

所需的字节数

bitmask_and()

std::pair<rmm::device_buffer, size_type> cudf::bitmask_and	(	table_view const &	view,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

对表的列的位掩码执行按位 AND 操作。返回结果掩码和未设置位的计数对。

如果任何列不可空，则认为所有元素均有效。如果表中没有可空列，则返回空位掩码。

参数

view	列组成的表
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回的 device_buffer 的设备内存资源

返回值

结果位掩码和未设置位的计数对

bitmask_or()

std::pair<rmm::device_buffer, size_type> cudf::bitmask_or	(	table_view const &	view,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

对表的列的位掩码执行按位 OR 操作。返回结果掩码和未设置位的计数对。

如果任何列不可空，则认为所有元素均有效。如果表中没有可空列，则返回空位掩码。

参数

view	列组成的表
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回的 device_buffer 的设备内存资源

返回值

结果位掩码和未设置位的计数对

copy_bitmask() [1/2]

rmm::device_buffer cudf::copy_bitmask	(	bitmask_type const *	mask,
		size_type	begin_bit,
		size_type	end_bit,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

从由索引范围 [begin_bit, end_bit) 定义的位掩码切片创建 device_buffer。

如果 bitmask == nullptr，则返回空的 device_buffer。

异常

cudf::logic_error	如果 begin_bit > end_bit
cudf::logic_error	如果 begin_bit < 0

参数

mask	位于设备内存中的位掩码，其位将被复制
begin_bit	要复制的第一个位的索引（包含）
end_bit	要复制的最后一个位的索引（不包含）
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回的 device_buffer 的设备内存资源

返回值

一个 device_buffer，包含来自 mask 的位 [begin_bit, end_bit)。

copy_bitmask() [2/2]

rmm::device_buffer cudf::copy_bitmask	(	column_view const &	view,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

将 view 的位掩码从位 [view.offset(), view.offset() + view.size()) 复制到 device_buffer 中。

如果列不可空，则返回空的 device_buffer

参数

view	需要复制位掩码的列视图
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回的 device_buffer 的设备内存资源

返回值

一个 device_buffer，包含来自 view 的位掩码的位 [view.offset(), view.offset() + view.size())。

create_null_mask()

rmm::device_buffer cudf::create_null_mask	(	size_type	size,
		mask_state	state,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

创建一个 device_buffer 用作 column 的空值指示符位掩码。

参数

size	掩码需要表示的元素数量
state	掩码的期望状态
stream	用于设备内存操作和内核启动的 CUDA 流
mr	用于分配返回的 device_buffer 的设备内存资源

返回值

一个用作空值位掩码的 device_buffer，满足期望的大小和状态

null_count()

cudf::size_type cudf::null_count	(	bitmask_type const *	bitmask,
		size_type	start,
		size_type	stop,
		rmm::cuda_stream_view	stream = cudf::get_default_stream()
	)

给定有效性位掩码，计算范围 [start, stop) 内空元素（未设置位）的数量。

如果 bitmask == nullptr，则假定所有元素都有效，函数返回 ``。

异常

cudf::logic_error	如果 start > stop
cudf::logic_error	如果 start < 0

参数

bitmask	位于设备内存中的有效性位掩码。
start	要计数的第一个位的索引（包含）。
stop	要计数的最后一个位的索引（不包含）。
stream	用于设备内存操作和内核启动的 CUDA 流

返回值

指定范围内的空元素数量。

num_bitmask_words()

size_type cudf::num_bitmask_words

(

size_type

number_of_bits

)

返回表示指定位数所需的 bitmask_type 字数。

与 bitmask_allocation_size_bytes 返回位掩码分配所需字节数（包括填充）不同，此函数返回表示 number_of_bits 所需的 bitmask_type 元素的实际数量。当希望处理位掩码中的所有位并忽略填充/冗余位时，这很有用。

参数

number_of_bits

需要表示的位数

返回值

所需的 bitmask_type 元素数量

set_null_mask()

void cudf::set_null_mask	(	bitmask_type *	bitmask,
		size_type	begin_bit,
		size_type	end_bit,
		bool	valid,
		rmm::cuda_stream_view	stream = cudf::get_default_stream()
	)

将预分配的位掩码缓冲区在范围 [begin_bit, end_bit) 内设置为给定状态

如果 valid==true，将位掩码的 [begin_bit, end_bit) 位设置为有效；否则设置为 null。

参数

bitmask	指向位掩码的指针（例如，由 column_viewnull_mask() 返回）
begin_bit	要设置的第一个位的索引（包含）
end_bit	要设置的最后一个位的索引（不包含）
valid	如果为 true，将所有条目设置为有效；否则，将所有条目设置为 null
stream	用于设备内存操作和内核启动的 CUDA 流

state_null_count()

size_type cudf::state_null_count	(	mask_state	state,
		size_type	size
	)

返回表示 size 个元素的、指定 state 的空掩码的空值计数。

异常

std::invalid_argument

如果状态为 UNINITIALIZED

参数

state	空掩码的状态
size	掩码表示的元素数量

返回值

空元素的计数