Bitmask Operations

Files
file	null_mask.hpp
	APIs for managing validity bitmasks.

Functions
size_type	cudf::state_null_count (mask_state state, size_type size)
	Returns the null count for a null mask of the specified state representing size elements. More...
std::size_t	cudf::bitmask_allocation_size_bytes (size_type number_of_bits, std::size_t padding_boundary=64)
	Computes the required bytes necessary to represent the specified number of bits with a given padding boundary. More...
size_type	cudf::num_bitmask_words (size_type number_of_bits)
	Returns the number of bitmask_type words required to represent the specified number of bits. More...
rmm::device_buffer	cudf::create_null_mask (size_type size, mask_state state, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Creates a device_buffer for use as a null value indicator bitmask of a column. More...
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())
	Sets a pre-allocated bitmask buffer to a given state in the range [begin_bit, end_bit) More...
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::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Creates a device_buffer from a slice of bitmask defined by a range of indices [begin_bit, end_bit). More...
rmm::device_buffer	cudf::copy_bitmask (column_view const &view, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Copies view's bitmask from the bits [view.offset(), view.offset() + view.size()) into a device_buffer More...
std::pair< rmm::device_buffer, size_type >	cudf::bitmask_and (table_view const &view, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Performs bitwise AND of the bitmasks of columns of a table. Returns a pair of resulting mask and count of unset bits. More...
std::pair< rmm::device_buffer, size_type >	cudf::bitmask_or (table_view const &view, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Performs bitwise OR of the bitmasks of columns of a table. Returns a pair of resulting mask and count of unset bits. More...
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())
	Given a validity bitmask, counts the number of null elements (unset bits) in the range [start, stop). More...

Detailed Description

Function Documentation

bitmask_allocation_size_bytes()

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

Computes the required bytes necessary to represent the specified number of bits with a given padding boundary.

Note

The Arrow specification for the null bitmask requires a 64B padding boundary.

Parameters

number_of_bits	The number of bits that need to be represented
padding_boundary	The value returned will be rounded up to a multiple of this value

Returns

The necessary number of bytes

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::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Performs bitwise AND of the bitmasks of columns of a table. Returns a pair of resulting mask and count of unset bits.

If any of the columns isn't nullable, it is considered all valid. If no column in the table is nullable, an empty bitmask is returned.

Parameters

view	The table of columns
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned device_buffer

Returns

A pair of resulting bitmask and count of unset bits

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::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Performs bitwise OR of the bitmasks of columns of a table. Returns a pair of resulting mask and count of unset bits.

If any of the columns isn't nullable, it is considered all valid. If no column in the table is nullable, an empty bitmask is returned.

Parameters

view	The table of columns
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned device_buffer

Returns

A pair of resulting bitmask and count of unset bits

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::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Creates a device_buffer from a slice of bitmask defined by a range of indices [begin_bit, end_bit).

Returns empty device_buffer if bitmask == nullptr.

Exceptions

cudf::logic_error	if begin_bit > end_bit
cudf::logic_error	if begin_bit < 0

Parameters

mask	Bitmask residing in device memory whose bits will be copied
begin_bit	Index of the first bit to be copied (inclusive)
end_bit	Index of the last bit to be copied (exclusive)
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned device_buffer

Returns

A device_buffer containing the bits [begin_bit, end_bit) from mask.

copy_bitmask() [2/2]

rmm::device_buffer cudf::copy_bitmask	(	column_view const &	view,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Copies view's bitmask from the bits [view.offset(), view.offset() + view.size()) into a device_buffer

Returns empty device_buffer if the column is not nullable

Parameters

view	Column view whose bitmask needs to be copied
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned device_buffer

Returns

A device_buffer containing the bits [view.offset(), view.offset() + view.size()) from view's bitmask.

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::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Creates a device_buffer for use as a null value indicator bitmask of a column.

Parameters

size	The number of elements to be represented by the mask
state	The desired state of the mask
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned device_buffer

Returns

A device_buffer for use as a null bitmask satisfying the desired size and state

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()
	)

Given a validity bitmask, counts the number of null elements (unset bits) in the range [start, stop).

If bitmask == nullptr, all elements are assumed to be valid and the function returns ``.

Exceptions

cudf::logic_error	if start > stop
cudf::logic_error	if start < 0

Parameters

bitmask	Validity bitmask residing in device memory.
start	Index of the first bit to count (inclusive).
stop	Index of the last bit to count (exclusive).
stream	CUDA stream used for device memory operations and kernel launches

Returns

The number of null elements in the specified range.

num_bitmask_words()

size_type cudf::num_bitmask_words

(

size_type

number_of_bits

)

Returns the number of bitmask_type words required to represent the specified number of bits.

Unlike bitmask_allocation_size_bytes, which returns the number of bytes needed for a bitmask allocation (including padding), this function returns the actual number bitmask_type elements necessary to represent number_of_bits. This is useful when one wishes to process all of the bits in a bitmask and ignore the padding/slack bits.

Parameters

number_of_bits

The number of bits that need to be represented

Returns

The necessary number of bitmask_type elements

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()
	)

Sets a pre-allocated bitmask buffer to a given state in the range [begin_bit, end_bit)

Sets [begin_bit, end_bit) bits of bitmask to valid if valid==true or null otherwise.

Parameters

bitmask	Pointer to bitmask (e.g. returned by column_viewnull_mask())
begin_bit	Index of the first bit to set (inclusive)
end_bit	Index of the last bit to set (exclusive)
valid	If true set all entries to valid; otherwise, set all to null
stream	CUDA stream used for device memory operations and kernel launches

state_null_count()

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

Returns the null count for a null mask of the specified state representing size elements.

Exceptions

std::invalid_argument

if state is UNINITIALIZED

Parameters

state	The state of the null mask
size	The number of elements represented by the mask

Returns

The count of null elements