Column Nullmask

group column_nullmask

Functions

size_type state_null_count(mask_state state, size_type size)

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

Throws:

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

std::size_t 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

size_type 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

rmm::device_buffer 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())

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

void 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

rmm::device_buffer 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())

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.

Throws:

• 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.

rmm::device_buffer 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())

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.

std::pair<rmm::device_buffer, size_type> 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())

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

std::pair<rmm::device_buffer, size_type> 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())

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

cudf::size_type 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 ``.

Throws:

• 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.