Public Member Functions | Friends | List of all members
cudf::mutable_column_view Class Reference

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

#include <column_view.hpp>

Inheritance diagram for cudf::mutable_column_view:
cudf::detail::column_view_base

Public Member Functions

 mutable_column_view (mutable_column_view const &)=default
 
 mutable_column_view (mutable_column_view &&)=default
 
mutable_column_viewoperator= (mutable_column_view const &)=default
 
mutable_column_viewoperator= (mutable_column_view &&)=default
 
 mutable_column_view (data_type type, size_type size, void *data, bitmask_type *null_mask=nullptr, size_type null_count=cudf::UNKNOWN_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. More...
 
template<typename T = void>
T * head () const noexcept
 Returns pointer to the base device memory allocation casted to the specified type. More...
 
template<typename T >
T * data () const noexcept
 Returns the underlying data casted to the specified type, plus the offset. More...
 
template<typename T >
T * begin () const noexcept
 Return first element (accounting for offset) when underlying data is casted to the specified type. More...
 
template<typename T >
T * end () const noexcept
 Return one past the last element after underlying data is casted to the specified type. More...
 
bitmask_type * null_mask () const noexcept
 Returns raw pointer to the underlying bitmask allocation. More...
 
void set_null_count (size_type new_null_count)
 Set the null count. More...
 
mutable_column_view child (size_type child_index) const noexcept
 Returns a reference to the specified child. More...
 
size_type num_children () const noexcept
 Returns the number of child columns.
 
auto child_begin () const noexcept
 Returns iterator to the beginning of the ordered sequence of child column-views.
 
auto child_end () const noexcept
 Returns iterator to the end of the ordered sequence of child column-views.
 
 operator column_view () const
 Converts a mutable view into an immutable view. More...
 
- Public Member Functions inherited from cudf::detail::column_view_base
template<typename T = void>
T const * head () const noexcept
 Returns pointer to the base device memory allocation casted to the specified type. More...
 
template<typename T >
T const * data () const noexcept
 Returns the underlying data casted to the specified type, plus the offset. More...
 
template<typename T >
T const * begin () const noexcept
 Return first element (accounting for offset) after underlying data is casted to the specified type. More...
 
template<typename T >
T const * end () const noexcept
 Return one past the last element after underlying data is casted to the specified type. More...
 
size_type size () const noexcept
 Returns the number of elements in the column.
 
size_type is_empty () const noexcept
 Returns true if size() returns zero, or false otherwise.
 
data_type type () const noexcept
 Returns the element data_type
 
bool nullable () const noexcept
 Indicates if the column can contain null elements, i.e., if it has an allocated bitmask. More...
 
size_type null_count () const
 Returns the count of null elements. More...
 
size_type null_count (size_type begin, size_type end) const
 Returns the count of null elements in the range [begin, end) More...
 
bool has_nulls () const
 Indicates if the column contains null elements, i.e., null_count() > 0 More...
 
bool has_nulls (size_type begin, size_type end) const
 Indicates if the column contains null elements in the range [begin, end), i.e., null_count(begin, end) > 0 More...
 
bitmask_type const * null_mask () const noexcept
 Returns raw pointer to the underlying bitmask allocation. More...
 
size_type offset () const noexcept
 Returns the index of the first element relative to the base memory allocation, i.e., what is returned from head<T>().
 

Friends

mutable_column_view logical_cast (mutable_column_view const &input, data_type type)
 Zero-copy cast between types with the same underlying representation. More...
 

Additional Inherited Members

- Protected Member Functions inherited from cudf::detail::column_view_base
 column_view_base (column_view_base const &)=default
 
 column_view_base (column_view_base &&)=default
 
column_view_baseoperator= (column_view_base const &)=default
 
column_view_baseoperator= (column_view_base &&)=default
 
 column_view_base (data_type type, size_type size, void const *data, bitmask_type const *null_mask=nullptr, size_type null_count=UNKNOWN_NULL_COUNT, size_type offset=0)
 Construct a column_view_base from pointers to device memory for the elements and bitmask of the column. More...
 
- Protected Attributes inherited from cudf::detail::column_view_base
data_type _type {type_id::EMPTY}
 Element type.
 
size_type _size {}
 Number of elements.
 
void const * _data {}
 Pointer to device memory containing elements.
 
bitmask_type const * _null_mask {}
 
size_type _null_count {}
 The number of null elements.
 
size_type _offset {}
 

Detailed Description

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.

Definition at line 388 of file column_view.hpp.

Constructor & Destructor Documentation

◆ mutable_column_view()

cudf::mutable_column_view::mutable_column_view ( data_type  type,
size_type  size,
void *  data,
bitmask_type *  null_mask = nullptr,
size_type  null_count = cudf::UNKNOWN_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 the null count of the null_mask is not specified, it defaults to UNKNOWN_NULL_COUNT. The first invocation of null_count() will then compute the null count.

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

Exceptions
cudf::logic_errorif size < 0
cudf::logic_errorif size > 0 but data == nullptr
cudf::logic_errorif type.id() == EMPTY but data != nullptr or null_mask != nullptr
cudf::logic_errorif null_count > 0, but null_mask == nullptr
cudf::logic_errorif offset < 0
Parameters
typeThe element type
sizeThe number of elements
dataPointer to device memory containing the column elements
null_maskOptional, pointer to device memory containing the null indicator bitmask
null_countOptional, the number of null elements.
offsetoptional, index of the first element
childrenoptional, depending on the element type, child columns may contain additional data

Member Function Documentation

◆ begin()

template<typename T >
T* cudf::mutable_column_view::begin ( ) const
inlinenoexcept

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

Template Parameters
TThe desired type
Returns
T* Pointer to the first element after casting

Definition at line 480 of file column_view.hpp.

◆ child()

mutable_column_view cudf::mutable_column_view::child ( size_type  child_index) const
inlinenoexcept

Returns a reference to the specified child.

Parameters
child_indexThe index of the desired child
Returns
mutable_column_view The requested child mutable_column_view

Definition at line 525 of file column_view.hpp.

◆ data()

template<typename T >
T* cudf::mutable_column_view::data ( ) const
inlinenoexcept

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

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

@TODO Clarify behavior for variable-width types.

Template Parameters
TThe type to cast to
Returns
T* Typed pointer to underlying data, including the offset

Definition at line 467 of file column_view.hpp.

◆ end()

template<typename T >
T* cudf::mutable_column_view::end ( ) const
inlinenoexcept

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

Template Parameters
TThe desired type
Returns
T* Pointer to one past the last element after casting

Definition at line 493 of file column_view.hpp.

◆ head()

template<typename T = void>
T* cudf::mutable_column_view::head ( ) const
inlinenoexcept

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

Note
If offset() == 0, then head<T>() == data<T>()
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
Thetype to cast to
Returns
T* Typed pointer to underlying data

Definition at line 450 of file column_view.hpp.

◆ null_mask()

bitmask_type* cudf::mutable_column_view::null_mask ( ) const
inlinenoexcept

Returns raw pointer to the underlying bitmask allocation.

Note
This function does not account for the offset().
If null_count() == 0, this may return nullptr.

Definition at line 505 of file column_view.hpp.

◆ operator column_view()

cudf::mutable_column_view::operator column_view ( ) const

Converts a mutable view into an immutable view.

Returns
column_view An immutable view of the mutable view's elements

◆ set_null_count()

void cudf::mutable_column_view::set_null_count ( size_type  new_null_count)

Set the null count.

Exceptions
cudf::logic_errorif new_null_count > 0 and nullable() == false
Parameters
new_null_countThe new null count

Friends And Related Function Documentation

◆ logical_cast

mutable_column_view logical_cast ( mutable_column_view const &  input,
data_type  type 
)
friend

Zero-copy cast between types with the same underlying representation.

This is similar to reinterpret_cast or bit_cast in that it gives a view of the same raw bits as a different type. Unlike reinterpret_cast however, this cast is only allowed on types that have the same width and underlying representation. For example, the way timestamp types are laid out in memory is equivalent to an integer representing a duration since a fixed epoch; logically casting to the same integer type (INT32 for days, INT64 for others) results in a raw view of the duration count. However, an INT32 column cannot be logically cast to INT64 as the sizes differ, nor can an INT32 columm be logically cast to a FLOAT32 since what the bits represent differs.

The validity of the conversion can be checked with cudf::is_logically_castable().

Exceptions
cudf::logic_errorif the specified cast is not possible, i.e., is_logically_castable(input.type(), type) is false.
Parameters
inputThe mutable_column_view to cast from
typeThe data_type to cast to
Returns
New mutable_column_view wrapping the same data as input but cast to type

The documentation for this class was generated from the following file: