column_factories.hpp

转到此文件的文档。

/*
 * Copyright (c) 2019-2025, NVIDIA CORPORATION.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * https://apache.ac.cn/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#pragma once

#include <cudf/column/column.hpp>
#include <cudf/types.hpp>
#include <cudf/utilities/default_stream.hpp>
#include <cudf/utilities/memory_resource.hpp>
#include <cudf/utilities/span.hpp>
#include <cudf/utilities/traits.hpp>

#include <rmm/cuda_stream_view.hpp>

namespace CUDF_EXPORT cudf {
/**
 * @brief Constructs an empty column of the specified data type.
 *
 * @param type Logical data type of the column.
 * @return An empty column of the specified type.
 */
std::unique_ptr<column> make_empty_column(data_type type);

/**
 * @brief Creates an empty column of the specified type ID.
 *
 * @param id Type ID of the column.
 * @return An empty column of the specified type.
 */
std::unique_ptr<column> make_empty_column(type_id id);

/**
 * @brief Construct column with sufficient uninitialized storage to hold `size` elements of the
 * specified numeric type.
 *
 * @param type Numeric data type of the column.
 * @param size Number of elements in the column.
 * @param state Indicates the desired null mask allocation state.
 * @param stream CUDA stream used for device memory operations.
 * @param mr Device memory resource to use for allocations.
 * @return A unique_ptr to the newly created column.
 */
std::unique_ptr<column> make_numeric_column(
 data_type type,
 size_type size,
 mask_state state = mask_state::UNALLOCATED,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());

/**
 * @brief Construct column with sufficient uninitialized storage to hold `size` elements of the
 * specified numeric type, optionally providing a null mask and count.
 *
 * @param type Numeric data type of the column.
 * @param size Number of elements in the column.
 * @param null_mask Optional, device bitmask to indicate null values. Size must be `size`.
 * @param null_count The number of null values in the column.
 * @param stream CUDA stream used for device memory operations.
 * @param mr Device memory resource to use for allocations.
 * @return A unique_ptr to the newly created column.
 */
template <typename B>
std::unique_ptr<column> make_numeric_column(
 data_type type,
 size_type size,
 B&& null_mask,
 size_type null_count,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())
{
 CUDF_EXPECTS(is_numeric(type), "无效，非数值类型。");
 return std::make_unique<column>(type,
 size,
 rmm::device_buffer{size * cudf::size_of(type), stream, mr},
 std::forward<B>(null_mask),
 null_count);
}

/**
 * @brief Construct column with sufficient uninitialized storage to hold `size` elements of the
 * specified fixed point type.
 *
 * @param type Fixed point data type of the column.
 * @param size Number of elements in the column.
 * @param state Indicates the desired null mask allocation state.
 * @param stream CUDA stream used for device memory operations.
 * @param mr Device memory resource to use for allocations.
 * @return A unique_ptr to the newly created column.
 */
std::unique_ptr<column> make_fixed_point_column(
 data_type type,
 size_type size,
 mask_state state = mask_state::UNALLOCATED,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());

/**
 * @brief Construct column with sufficient uninitialized storage to hold `size` elements of the
 * specified fixed point type, optionally providing a null mask and count.
 *
 * @param type Fixed point data type of the column.
 * @param size Number of elements in the column.
 * @param null_mask Optional, device bitmask to indicate null values. Size must be `size`.
 * @param null_count The number of null values in the column.
 * @param stream CUDA stream used for device memory operations.
 * @param mr Device memory resource to use for allocations.
 * @return A unique_ptr to the newly created column.
 */
template <typename B>
std::unique_ptr<column> make_fixed_point_column(
 data_type type,
 size_type size,
 B&& null_mask,
 size_type null_count,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())
{
 CUDF_EXPECTS(is_fixed_point(type), "无效，非定点类型。");
 return std::make_unique<column>(type,
 size,
 rmm::device_buffer{size * cudf::size_of(type), stream, mr},
 std::forward<B>(null_mask),
 null_count);
}

/**
 * @brief Construct column with sufficient uninitialized storage to hold `size` elements of the
 * specified timestamp type.
 *
 * @param type Timestamp data type of the column.
 * @param size Number of elements in the column.
 * @param state Indicates the desired null mask allocation state.
 * @param stream CUDA stream used for device memory operations.
 * @param mr Device memory resource to use for allocations.
 * @return A unique_ptr to the newly created column.
 */
std::unique_ptr<column> make_timestamp_column(
 data_type type,
 size_type size,
 mask_state state = mask_state::UNALLOCATED,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());

/**
 * @brief Construct column with sufficient uninitialized storage to hold `size` elements of the
 * specified timestamp type, optionally providing a null mask and count.
 *
 * @param type Timestamp data type of the column.
 * @param size Number of elements in the column.
 * @param null_mask Optional, device bitmask to indicate null values. Size must be `size`.
 * @param null_count The number of null values in the column.
 * @param stream CUDA stream used for device memory operations.
 * @param mr Device memory resource to use for allocations.
 * @return A unique_ptr to the newly created column.
 */
template <typename B>
std::unique_ptr<column> make_timestamp_column(
 data_type type,
 size_type size,
 B&& null_mask,
 size_type null_count,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())
{
 CUDF_EXPECTS(is_timestamp(type), "无效，非时间戳类型。");
 return std::make_unique<column>(type,
 size,
 rmm::device_buffer{size * cudf::size_of(type), stream, mr},
 std::forward<B>(null_mask),
 null_count);
}

/**
 * @brief Construct column with sufficient uninitialized storage to hold `size` elements of the
 * specified duration type.
 *
 * @param type Duration data type of the column.
 * @param size Number of elements in the column.
 * @param state Indicates the desired null mask allocation state.
 * @param stream CUDA stream used for device memory operations.
 * @param mr Device memory resource to use for allocations.
 * @return A unique_ptr to the newly created column.
 */
std::unique_ptr<column> make_duration_column(
 data_type type,
 size_type size,
 mask_state state = mask_state::UNALLOCATED,
 rmm::cuda_stream_view stream = cudf::get_default_stream(),
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());

/**
 * @brief Construct column with sufficient uninitialized storage to hold `size` elements of the
 * specified duration type, optionally providing a null mask and count.
 *
 * @param type Duration data type of the column.
 * @param size Number of elements in the column.
 * @param null_mask Optional, device bitmask to indicate null values. Size must be `size`.
 * @param null_count The number of null values in the column.
 * @param stream CUDA stream used for device memory operations.