Column Classes#

group column_classes
class column#
#include <column.hpp>

A container of nullable device data as a column of elements.

Public Functions

column(column const &other, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

Construct a new column object by deep copying the contents of other.

Uses the specified stream and device_memory_resource for all allocations and copies.

Parameters:

  • other – The column to copy

  • stream – CUDA stream used for device memory operations.

  • mr – Device memory resource to use for all device memory allocations

column(column &&other) noexcept#

Move the contents from other to create a new column.

After the move, other.size() == 0 and other.type() = {EMPTY}

Parameters:

other – The column whose contents will be moved into the new column

template<typename T>
inline column(rmm::device_uvector<T> &&other, rmm::device_buffer &&null_mask, size_type null_count)#

Construct a new column by taking ownership of the contents of a device_uvector.

Parameters:

  • other – The device_uvector whose contents will be moved into the new column.

  • null_mask – Column’s null value indicator bitmask. May be empty if null_count is 0.

  • null_count – The count of null elements.

template<typename B1, typename B2 = rmm::device_buffer>
inline column(data_type dtype, size_type size, B1 &&data, B2 &&null_mask, size_type null_count, std::vector<std::unique_ptr<column>> &&children = {})#

Construct a new column from existing device memory.

Note

This constructor is primarily intended for use in column factory functions.

Throws:

cudf::logic_error – if size < 0

Parameters:

  • dtype – The element type

  • size – The number of elements in the column

  • data – The column’s data

  • null_mask – Column’s null value indicator bitmask. May be empty if null_count is 0.

  • null_count – Optional, the count of null elements.

  • children – Optional, vector of child columns

explicit column(column_view view, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

Construct a new column by deep copying the contents of a column_view.

This accounts for the column_view’s offset.

Parameters:

  • view – The view to copy

  • stream – CUDA stream used for device memory operations.

  • mr – Device memory resource to use for all device memory allocations

inline data_type type() const noexcept#

Returns the column’s logical element type.

Returns:

The column’s logical element type

inline size_type size() const noexcept#

Returns the number of elements.

Returns:

The number of elements

inline size_type null_count() const#

Returns the count of null elements.

Returns:

The number of null elements

void set_null_mask(rmm::device_buffer &&new_null_mask, size_type new_null_count)#

Sets the column’s null value indicator bitmask to new_null_mask.

Throws:

cudf::logic_error – if new_null_count is larger than 0 and the size of new_null_mask does not match the size of this column.

Parameters:

  • new_null_mask – New null value indicator bitmask (rvalue overload & moved) to set the column’s null value indicator mask. May be empty if new_null_count is 0.

  • new_null_count – The count of null elements.

void set_null_mask(rmm::device_buffer const &new_null_mask, size_type new_null_count, rmm::cuda_stream_view stream = cudf::get_default_stream())#

Sets the column’s null value indicator bitmask to new_null_mask.

Throws:

cudf::logic_error – if new_null_count is larger than 0 and the size of new_null_mask does not match the size of this column.

Parameters:

  • new_null_mask – New null value indicator bitmask (lvalue overload & copied) to set the column’s null value indicator mask. May be empty if new_null_count is 0.

  • new_null_count – The count of null elements

  • stream – The stream on which to perform the allocation and copy. Uses the default CUDF stream if none is specified.

void set_null_count(size_type new_null_count)#

Updates the count of null elements.

Throws:

cudf::logic_error – if new_null_count > 0 and nullable() == false

Parameters:

new_null_count – The new null count.

inline bool nullable() const noexcept#

Indicates whether it is possible for the column to contain null values, i.e., it has an allocated null mask.

This may return false iff null_count() == 0.

May return true even if null_count() == 0. This function simply indicates whether the column has an allocated null mask.

Returns:

true The column can hold null values

Returns:

false The column cannot hold null values

inline bool has_nulls() const noexcept#

Indicates whether the column contains null elements.

Returns:

true One or more elements are null

Returns:

false Zero elements are null

inline size_type num_children() const noexcept#

Returns the number of child columns.

Returns:

The number of child columns

inline column &child(size_type child_index) noexcept#

Returns a reference to the specified child.

Parameters:

child_index – Index of the desired child

Returns:

Reference to the desired child

inline column const &child(size_type child_index) const noexcept#

Returns a const reference to the specified child.

Parameters:

child_index – Index of the desired child

Returns:

Const reference to the desired child

contents release() noexcept#

Releases ownership of the column’s contents.

It is the caller’s responsibility to query the size(), null_count(), type() before invoking release().

After calling release() on a column it will be empty, i.e.:

Returns:

A contents struct containing the data, null mask, and children of the column.

column_view view() const#

Creates an immutable, non-owning view of the column’s data and children.

Returns:

The immutable, non-owning view

inline operator column_view() const#

Implicit conversion operator to a column_view.

This allows passing a column object directly into a function that requires a column_view. The conversion is automatic.

Returns:

Immutable, non-owning column_view

mutable_column_view mutable_view()#

Creates a mutable, non-owning view of the column’s data, null mask, and children.

Returns:

The mutable, non-owning view

inline operator mutable_column_view()#

Implicit conversion operator to a mutable_column_view.

This allows passing a column object into a function that accepts a mutable_column_view. The conversion is automatic.

The caller is expected to update the null count appropriately if the null mask is modified.

Returns:

Mutable, non-owning mutable_column_view

struct contents#
#include <column.hpp>

Wrapper for the contents of a column.

Returned by column::release().

Public Members

std::unique_ptr<rmm::device_buffer> data#

data device memory buffer

std::unique_ptr<rmm::device_buffer> null_mask#

null mask device memory buffer

std::vector<std::unique_ptr<column>> children#

child columns

struct nullate#

Indicates the presence of nulls at compile-time or runtime.

If used at compile-time, this indicator can tell the optimizer to include or exclude any null-checking clauses.

struct DYNAMIC#

nullate::DYNAMIC defers the determination of nullability to run time rather than compile time. The calling code is responsible for specifying whether or not nulls are present using the constructor parameter at run time.

Public Functions

inline explicit constexpr DYNAMIC(bool b) noexcept#

Create a runtime nullate object.

See also

cudf::column_device_view::optional_begin for example usage

Parameters:

b – True if nulls are expected in the operation in which this object is applied.

inline constexpr operator bool() const noexcept#

Returns true if nulls are expected in the operation in which this object is applied.

Returns:

true if nulls are expected in the operation in which this object is applied, otherwise false

Public Members

bool value#

True if nulls are expected.

struct NO : public cuda::std::bool_constant<false>#
struct YES : public cuda::std::bool_constant<true>#
class column_device_view : public cudf::detail::column_device_view_base#

An immutable, non-owning view of device data as a column of elements that is trivially copyable and usable in CUDA device code.

Subclassed by cudf::detail::lists_column_device_view, cudf::detail::structs_column_device_view

Public Types

using count_it = thrust::counting_iterator<size_type>#

Counting iterator.

template<typename T>
using const_iterator = thrust::transform_iterator<detail::value_accessor<T>, count_it>#

Iterator for navigating this column.

template<typename T, typename Nullate>
using const_optional_iterator = thrust::transform_iterator<detail::optional_accessor<T, Nullate>, count_it>#

Optional iterator for navigating this column.

template<typename T, bool has_nulls>
using const_pair_iterator = thrust::transform_iterator<detail::pair_accessor<T, has_nulls>, count_it>#

Pair iterator for navigating this column.

template<typename T, bool has_nulls>
using const_pair_rep_iterator = thrust::transform_iterator<detail::pair_rep_accessor<T, has_nulls>, count_it>#

Pair rep iterator for navigating this column.

Each row value is accessed in its representative form.

Public Functions

column_device_view(column_device_view const&) = default#

Copy constructor.

column_device_view(column_device_view&&) = default#

Move constructor.

column_device_view &operator=(column_device_view const&) = default#

Copy assignment operator.

Returns:

Reference to this object

column_device_view &operator=(column_device_view&&) = default#

Move assignment operator.

Returns:

Reference to this object (after transferring ownership)

column_device_view(column_view column, void *h_ptr, void *d_ptr)#

Creates an instance of this class using the specified host memory pointer (h_ptr) to store child objects and the device memory pointer (d_ptr) as a base for any child object pointers.

Parameters:

  • column – Column view from which to create this instance.

  • h_ptr – Host memory pointer on which to place any child data.

  • d_ptr – Device memory pointer on which to base any child pointers.

inline column_device_view slice(size_type offset, size_type size) const noexcept#

Get a new column_device_view which is a slice of this column.

Example: 

// column = column_device_view([1, 2, 3, 4, 5, 6, 7])
auto c = column.slice(1, 3);
// c = column_device_view([2, 3, 4])
auto c1 = column.slice(2, 3);
// c1 = column_device_view([3, 4, 5])

Parameters:

  • offset – The index of the first element in the slice

  • size – The number of elements in the slice

Returns:

A slice of this column

template<typename T>
inline T element(size_type element_index) const noexcept#

Returns reference to element at the specified index.

If the element at the specified index is NULL, i.e., is_null(element_index) == true, then any attempt to use the result will lead to undefined behavior.

This function accounts for the offset.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false. Specializations of this function may exist for types T where is_rep_layout_compatible<T> is false.

Template Parameters:

T – The element type

Parameters:

element_index – Position of the desired element

Returns:

reference to the element at the specified index

template<typename T>
inline const_iterator<T> begin() const#

Return an iterator to the first element of the column.

This iterator only supports columns where has_nulls() == false. Using it with columns where has_nulls() == true will result in undefined behavior when accessing null elements.

This function does not participate in overload resolution if column_device_view::has_element_accessor<T>() is false.

For columns with null elements, use make_null_replacement_iterator.

Template Parameters:

T – Type of the elements in the column

Returns:

An iterator to the first element of the column

template<typename T>
inline const_iterator<T> end() const#

Returns an iterator to the element following the last element of the column.

This iterator only supports columns where has_nulls() == false. Using it with columns where has_nulls() == true will result in undefined behavior when accessing null elements.

This function does not participate in overload resolution if column_device_view::has_element_accessor<T>() is false.

For columns with null elements, use make_null_replacement_iterator.

Returns:

An iterator to the element following the last element of the column

template<typename T, typename Nullate>
inline auto optional_begin(Nullate has_nulls) const#

Return an optional iterator to the first element of the column.

Dereferencing the returned iterator returns a cuda::std::optional<T>.

The element of this iterator contextually converts to bool. The conversion returns true if the object contains a value and false if it does not contain a value.

Calling this method with nullate::DYNAMIC defers the assumption of nullability to runtime with the caller indicating if the column has nulls. The nullate::DYNAMIC is useful when an algorithm is going to execute on multiple iterators and all the combinations of iterator types are not required at compile time.

template<typename T>
void some_function(cudf::column_view<T> const& col_view){
   auto d_col = cudf::column_device_view::create(col_view);
   // Create a `DYNAMIC` optional iterator
   auto optional_iterator =
      d_col->optional_begin<T>(cudf::nullate::DYNAMIC{col_view.has_nulls()});
}

Calling this method with nullate::YES means that the column supports nulls and the optional returned might not contain a value.

Calling this method with nullate::NO means that the column has no null values and the optional returned will always contain a value.

template<typename T, bool has_nulls>
void some_function(cudf::column_view<T> const& col_view){
   auto d_col = cudf::column_device_view::create(col_view);
   if constexpr(has_nulls) {
     auto optional_iterator = d_col->optional_begin<T>(cudf::nullate::YES{});
     //use optional_iterator
   } else {
     auto optional_iterator = d_col->optional_begin<T>(cudf::nullate::NO{});
     //use optional_iterator
   }
}

This function does not participate in overload resolution if column_device_view::has_element_accessor<T>() is false.

Throws:

  • cudf::logic_error – if the column is not nullable and has_nulls evaluates to true.

  • cudf::logic_error – if column datatype and Element type mismatch.

Template Parameters:

  • T – The type of elements in the column

  • Nullate – A cudf::nullate type describing how to check for nulls

Parameters:

has_nulls – A cudf::nullate type describing how to check for nulls

Returns:

An optional iterator to the first element of the column

template<typename T, bool has_nulls>
inline const_pair_iterator<T, has_nulls> pair_begin() const#

Return a pair iterator to the first element of the column.

Dereferencing the returned iterator returns a thrust::pair<T, bool>.

If an element at position i is valid (or has_nulls == false), then for p = *(iter + i), p.first contains the value of the element at i and p.second == true.

Else, if the element at i is null, then the value of p.first is undefined and p.second == false.

This function does not participate in overload resolution if column_device_view::has_element_accessor<T>() is false.

Throws:
Returns:

A pair iterator to the first element of the column

template<typename T, bool has_nulls>
inline const_pair_rep_iterator<T, has_nulls> pair_rep_begin() const#

Return a pair iterator to the first element of the column.

Dereferencing the returned iterator returns a thrust::pair<rep_type, bool>, where rep_type is device_storage_type<T>, the type used to store the value on the device.

If an element at position i is valid (or has_nulls == false), then for p = *(iter + i), p.first contains the value of the element at i and p.second == true.

Else, if the element at i is null, then the value of p.first is undefined and p.second == false.

This function does not participate in overload resolution if column_device_view::has_element_accessor<T>() is false.

Throws:
Returns:

A pair iterator to the first element of the column

template<typename T, typename Nullate>
inline auto optional_end(Nullate has_nulls) const#

Return an optional iterator to the element following the last element of the column.

The returned iterator represents a cuda::std::optional<T> element.

This function does not participate in overload resolution if column_device_view::has_element_accessor<T>() is false.

Throws:
Template Parameters:

  • T – The type of elements in the column

  • Nullate – A cudf::nullate type describing how to check for nulls

Parameters:

has_nulls – A cudf::nullate type describing how to check for nulls

Returns:

An optional iterator to the element following the last element of the column

template<typename T, bool has_nulls>
inline const_pair_iterator<T, has_nulls> pair_end() const#

Return a pair iterator to the element following the last element of the column.

This function does not participate in overload resolution if column_device_view::has_element_accessor<T>() is false.

Throws:
Returns:

A pair iterator to the element following the last element of the column

template<typename T, bool has_nulls>
inline const_pair_rep_iterator<T, has_nulls> pair_rep_end() const#

Return a pair iterator to the element following the last element of the column.

This function does not participate in overload resolution if column_device_view::has_element_accessor<T>() is false.

Throws:
Returns:

A pair iterator to the element following the last element of the column

void destroy()#

Destroy the column_device_view object.

Note

Does not free the column data, simply frees the device memory allocated to hold the child views.

inline column_device_view child(size_type child_index) const noexcept#

Returns the specified child.

Parameters:

child_index – The index of the desired child

Returns:

column_view The requested child column_view

inline device_span<column_device_view const> children() const noexcept#

Returns a span containing the children of this column.

Returns:

A span containing the children of this column

inline size_type num_child_columns() const noexcept#

Returns the number of child columns.

Returns:

The number of child columns

Public Static Functions

template<typename T>
static inline constexpr bool has_element_accessor()#

For a given T, indicates if column_device_view::element<T>() has a valid overload.

Template Parameters:

T – The element type

Returns:

true if column_device_view::element<T>() has a valid overload, false otherwise

static std::unique_ptr<column_device_view, std::function<void(column_device_view*)>> create(column_view source_view, rmm::cuda_stream_view stream = cudf::get_default_stream())#

Factory to construct a column view that is usable in device memory.

Allocates and copies views of source_view’s children to device memory to make them accessible in device code.

If source_view.num_children() == 0, then no device memory is allocated.

Returns a std::unique_ptr<column_device_view> with a custom deleter to free the device memory allocated for the children.

A column_device_view should be passed by value into GPU kernels.

Parameters:

  • source_view – The column_view to make usable in device code

  • stream – CUDA stream used for device memory operations for children columns.

Returns:

A unique_ptr to a column_device_view that makes the data from source_view available in device memory.

static std::size_t extent(column_view const &source_view)#

Return the size in bytes of the amount of memory needed to hold a device view of the specified column and it’s children.

Parameters:

source_view – The column_view to use for this calculation.

Returns:

number of bytes to store device view in GPU memory

class mutable_column_device_view : public cudf::detail::column_device_view_base#

A mutable, non-owning view of device data as a column of elements that is trivially copyable and usable in CUDA device code.

Public Types

using count_it = thrust::counting_iterator<size_type>#

Counting iterator.

template<typename T>
using iterator = thrust::transform_iterator<detail::mutable_value_accessor<T>, count_it>#

Iterator for navigating this column.

Public Functions

mutable_column_device_view(mutable_column_device_view const&) = default#

Copy constructor.

mutable_column_device_view(mutable_column_device_view&&) = default#

Move constructor.

mutable_column_device_view &operator=(mutable_column_device_view const&) = default#

Copy assignment operator.

Returns:

Reference to this object

mutable_column_device_view &operator=(mutable_column_device_view&&) = default#

Move assignment operator.

Returns:

Reference to this object (after transferring ownership)

mutable_column_device_view(mutable_column_view column, void *h_ptr, void *d_ptr)#

Creates an instance of this class using the specified host memory pointer (h_ptr) to store child objects and the device memory pointer (d_ptr) as a base for any child object pointers.

Parameters:

  • column – Column view from which to create this instance.

  • h_ptr – Host memory pointer on which to place any child data.

  • d_ptr – Device memory pointer on which to base any child pointers.

template<typename T = void>
inline T *head() const noexcept#

Returns pointer to the base device memory allocation casted to the specified type.

This function will only participate in overload resolution if is_rep_layout_compatible<T>() or std::is_same_v<T,void> are true.

Note

If offset() == 0, then head<T>() == data<T>()

Note

It should be rare to need to access the head<T>() allocation of a column, and instead, accessing the elements should be done via data<T>().

Template Parameters:

The – type to cast to

Returns:

Typed pointer to underlying data

template<typename T>
inline T *data() const noexcept#

Returns the underlying data casted to the specified type, plus the offset.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false.

Note

If offset() == 0, then head<T>() == data<T>()

Template Parameters:

T – The type to cast to

Returns:

Typed pointer to underlying data, including the offset

template<typename T>
inline T &element(size_type element_index) const noexcept#

Returns reference to element at the specified index.

This function accounts for the offset.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false. Specializations of this function may exist for types T where is_rep_layout_compatible<T> is false.

Template Parameters:

T – The element type

Parameters:

element_index – Position of the desired element

Returns:

Reference to the element at the specified index

inline bitmask_type *null_mask() const noexcept#

Returns raw pointer to the underlying bitmask allocation.

Note

This function does not account for the offset().

Note

If null_count() == 0, this may return nullptr.

Returns:

Raw pointer to the underlying bitmask allocation

template<typename T>
inline iterator<T> begin()#

Return first element (accounting for offset) after underlying data is casted to the specified type.

This function does not participate in overload resolution if mutable_column_device_view::has_element_accessor<T>() is false.

Template Parameters:

T – The desired type

Returns:

Pointer to the first element after casting

template<typename T>
inline iterator<T> end()#

Return one past the last element after underlying data is casted to the specified type.

This function does not participate in overload resolution if mutable_column_device_view::has_element_accessor<T>() is false.

Template Parameters:

T – The desired type

Returns:

Pointer to one past the last element after casting

inline mutable_column_device_view child(size_type child_index) const noexcept#

Returns the specified child.

Parameters:

child_index – The index of the desired child

Returns:

The requested child column_view

inline void set_mask_word(size_type word_index, bitmask_type new_word) const noexcept#

Updates the specified bitmask word in the null_mask() with a new word.

Note

It is undefined behavior to call this function if nullable() == false.

Parameters:

  • word_index – The index of the word to update

  • new_word – The new bitmask word

void destroy()#

Destroy the mutable_column_device_view object.

Note

Does not free the column data, simply frees the device memory allocated to hold the child views.

Public Static Functions

static std::unique_ptr<mutable_column_device_view, std::function<void(mutable_column_device_view*)>> create(mutable_column_view source_view, rmm::cuda_stream_view stream = cudf::get_default_stream())#

Factory to construct a column view that is usable in device memory.

Allocates and copies views of source_view’s children to device memory to make them accessible in device code.

If source_view.num_children() == 0, then no device memory is allocated.

Returns a std::unique_ptr<mutable_column_device_view> with a custom deleter to free the device memory allocated for the children.

A mutable_column_device_view should be passed by value into GPU kernels.

Parameters:

  • source_view – The column_view to make usable in device code

  • stream – CUDA stream used for device memory operations for children columns.

Returns:

A unique_ptr to a mutable_column_device_view that makes the data from source_view available in device memory.

template<typename T>
static inline constexpr bool has_element_accessor()#

For a given T, indicates if mutable_column_device_view::element<T>() has a valid overload.

Returns:

true if mutable_column_device_view::element<T>() has a valid overload, false

static std::size_t extent(mutable_column_view source_view)#

Return the size in bytes of the amount of memory needed to hold a device view of the specified column and it’s children.

Parameters:

source_view – The column_view to use for this calculation.

Returns:

The size in bytes of the amount of memory needed to hold a device view of the specified column and it’s children

class column_view : public cudf::detail::column_view_base#
#include <column_view.hpp>

A non-owning, immutable view of device data as a column of elements, some of which may be null as indicated by a bitmask.

A column_view can be constructed implicitly from a cudf::column, or may be constructed explicitly from a pointer to pre-existing device memory.

Unless otherwise noted, the memory layout of the column_view’s data and bitmask is expected to adhere to the Arrow Physical Memory Layout Specification: https://arrow.apache.org/docs/memory_layout.html

Because column_view is non-owning, no device memory is allocated nor freed when column_view objects are created or destroyed.

To enable zero-copy slicing, a column_view has an offset that indicates the index of the first element in the column relative to the base device memory allocation. By default, offset() is zero.

Subclassed by cudf::dictionary_column_view, cudf::lists_column_view, cudf::strings_column_view, cudf::structs_column_view, cudf::tdigest::tdigest_column_view

Public Functions

column_view(column_view const&) = default#

Copy constructor.

column_view(column_view&&) = default#

Move constructor.

column_view &operator=(column_view const&) = default#

Copy assignment operator.

Returns:

Reference to this object

column_view &operator=(column_view&&) = default#

Move assignment operator.

Returns:

Reference to this object

column_view(data_type type, size_type size, void const *data, bitmask_type const *null_mask, size_type null_count, size_type offset = 0, std::vector<column_view> const &children = {})#

Construct a column_view from pointers to device memory for the elements and bitmask of the column.

If null_count() is zero, null_mask is optional.

If type is EMPTY, the specified null_count will be ignored and null_count() will always return the same value as size()

Throws:
Parameters:

  • type – The element type

  • size – The number of elements

  • data – Pointer to device memory containing the column elements

  • null_mask – Pointer to device memory containing the null indicator bitmask

  • null_count – The number of null elements.

  • offset – Optional, index of the first element

  • children – Optional, depending on the element type, child columns may contain additional data

inline column_view child(size_type child_index) const noexcept#

Returns the specified child.

Parameters:

child_index – The index of the desired child

Returns:

The requested child column_view

inline size_type num_children() const noexcept#

Returns the number of child columns.

Returns:

The number of child columns

inline auto child_begin() const noexcept#

Returns iterator to the beginning of the ordered sequence of child column-views.

Returns:

An iterator to a column_view referencing the first child column

inline auto child_end() const noexcept#

Returns iterator to the end of the ordered sequence of child column-views.

Returns:

An iterator to a column_view one past the end of the child columns

template<typename T>
inline column_view(device_span<T const> data)#

Construct a column view from a device_span<T>.

Only numeric and chrono types are supported.

Template Parameters:

T – The device span type. Must be const and match the column view’s type.

Parameters:

data – A typed device span containing the column view’s data.

template<typename T>
inline operator device_span<T const>() const#

Converts a column view into a device span.

Only numeric and chrono data types are supported. The column view must not be nullable.

Template Parameters:

T – The device span type. Must be const and match the column view’s type.

Throws:
Returns:

A typed device span of the column view’s data.

class mutable_column_view : public cudf::detail::column_view_base#
#include <column_view.hpp>

A non-owning, mutable view of device data as a column of elements, some of which may be null as indicated by a bitmask.

A mutable_column_view can be constructed implicitly from a cudf::column, or may be constructed explicitly from a pointer to pre-existing device memory.

Unless otherwise noted, the memory layout of the mutable_column_view’s data and bitmask is expected to adhere to the Arrow Physical Memory Layout Specification: https://arrow.apache.org/docs/memory_layout.html

Because mutable_column_view is non-owning, no device memory is allocated nor freed when mutable_column_view objects are created or destroyed.

To enable zero-copy slicing, a mutable_column_view has an offset that indicates the index of the first element in the column relative to the base device memory allocation. By default, offset() is zero.

Public Functions

mutable_column_view(mutable_column_view const&) = default#

Copy constructor.

mutable_column_view(mutable_column_view&&) = default#

Move constructor.

mutable_column_view &operator=(mutable_column_view const&) = default#

Copy assignment operator.

Returns:

Reference to this object

mutable_column_view &operator=(mutable_column_view&&) = default#

Move assignment operator.

Returns:

Reference to this object (after transferring ownership)

mutable_column_view(data_type type, size_type size, void *data, bitmask_type *null_mask, size_type null_count, size_type offset = 0, std::vector<mutable_column_view> const &children = {})#

Construct a mutable_column_view from pointers to device memory for the elements and bitmask of the column.

If type is EMPTY, the specified null_count will be ignored and null_count() will always return the same value as size()

Throws:
Parameters:

  • type – The element type

  • size – The number of elements

  • data – Pointer to device memory containing the column elements

  • null_mask – Pointer to device memory containing the null indicator bitmask

  • null_count – The number of null elements.

  • offset – Optional, index of the first element

  • children – Optional, depending on the element type, child columns may contain additional data

template<typename T = void>
inline T *head() const noexcept#

Returns pointer to the base device memory allocation casted to the specified type.

This function will only participate in overload resolution if is_rep_layout_compatible<T>() or std::is_same_v<T,void> are true.

Note

If offset() == 0, then head<T>() == data<T>()

Note

It should be rare to need to access the head<T>() allocation of a column, and instead, accessing the elements should be done via data<T>().

Template Parameters:

The – type to cast to

Returns:

Typed pointer to underlying data

template<typename T>
inline T *data() const noexcept#

Returns the underlying data casted to the specified type, plus the offset.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false.

Note

If offset() == 0, then head<T>() == data<T>()

Template Parameters:

T – The type to cast to

Returns:

Typed pointer to underlying data, including the offset

template<typename T>
inline T *begin() const noexcept#

Return first element (accounting for offset) after underlying data is casted to the specified type.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false.

Template Parameters:

T – The desired type

Returns:

Pointer to the first element after casting

template<typename T>
inline T *end() const noexcept#

Return one past the last element after underlying data is casted to the specified type.

This function does not participate in overload resolution if is_rep_layout_compatible<T> is false.

Template Parameters:

T – The desired type

Returns:

Pointer to one past the last element after casting

inline bitmask_type *null_mask() const noexcept#

Returns raw pointer to the underlying bitmask allocation.

Note

This function does not account for the offset().

Note

If null_count() == 0, this may return nullptr.

Returns:

Raw pointer to the underlying bitmask allocation

void set_null_count(size_type new_null_count)#

Set the null count.

Throws:

cudf::logic_error – if new_null_count > 0 and nullable() == false

Parameters:

new_null_count – The new null count

inline mutable_column_view child(size_type child_index) const noexcept#

Returns a reference to the specified child.

Parameters:

child_index – The index of the desired child

Returns:

The requested child mutable_column_view

inline size_type num_children() const noexcept#

Returns the number of child columns.

Returns:

The number of child columns

inline auto child_begin() const noexcept#

Returns iterator to the beginning of the ordered sequence of child column-views.

Returns:

An iterator to a mutable_column_view referencing the first child column

inline auto child_end() const noexcept#

Returns iterator to the end of the ordered sequence of child column-views.

Returns:

An iterator to a mutable_column_view to the element following the last child column

operator column_view() const#

Converts a mutable view into an immutable view.

Returns:

An immutable view of the mutable view’s elements

Contents:

This Page