interop.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2020-2025, NVIDIA CORPORATION.
 * SPDX-License-Identifier: Apache-2.0
 */
 
#pragma once
 
#include <cudf/column/column.hpp>
#include <cudf/detail/transform.hpp>
#include <cudf/strings/strings_column_view.hpp>
#include <cudf/table/table.hpp>
#include <cudf/table/table_view.hpp>
#include <cudf/types.hpp>
#include <cudf/utilities/export.hpp>
#include <cudf/utilities/memory_resource.hpp>
#include <cudf/utilities/span.hpp>
 
#include <rmm/resource_ref.hpp>
 
#include <utility>
 
struct DLManagedTensor;
 
struct ArrowDeviceArray;
 
struct ArrowSchema;
 
struct ArrowArray;
 
struct ArrowArrayStream;
 
// These are types from arrow that we are forward declaring for our API to
// avoid needing to include nanoarrow headers.
typedef int32_t ArrowDeviceType;  // NOLINT
 
#define ARROW_DEVICE_CUDA 2  // NOLINT
 
namespace CUDF_EXPORT cudf {
std::unique_ptr<table> from_dlpack(
  DLManagedTensor const* managed_tensor,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
DLManagedTensor* to_dlpack(
  table_view const& input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
  // end of group
 
struct column_metadata {
  std::string name;                            
  std::string timezone;                        
  std::optional<int32_t> precision;            
  std::vector<column_metadata> children_meta;  
 
  column_metadata(std::string _name) : name(std::move(_name)) {}
  column_metadata() = default;
};
 
using unique_schema_t = std::unique_ptr<ArrowSchema, void (*)(ArrowSchema*)>;
 
using unique_device_array_t = std::unique_ptr<ArrowDeviceArray, void (*)(ArrowDeviceArray*)>;
 
using owned_columns_t = std::vector<std::unique_ptr<cudf::column>>;
 
template <typename ViewType>
struct custom_view_deleter {
  explicit custom_view_deleter(owned_columns_t&& owned) : owned_mem_{std::move(owned)} {}
 
  void operator()(ViewType* ptr) const { delete ptr; }
 
  owned_columns_t owned_mem_;  
};
 
using unique_table_view_t =
  std::unique_ptr<cudf::table_view, custom_view_deleter<cudf::table_view>>;
 
using unique_column_view_t =
  std::unique_ptr<cudf::column_view, custom_view_deleter<cudf::column_view>>;
 
namespace interop {
 
struct arrow_array_container;
 
cudf::column_metadata get_column_metadata(cudf::column_view const& input);
 
std::vector<cudf::column_metadata> get_table_metadata(cudf::table_view const& input);
 
class arrow_column {
 public:
  arrow_column(cudf::column&& input,
               column_metadata const& metadata,
               rmm::cuda_stream_view stream      = cudf::get_default_stream(),
               rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  arrow_column(ArrowSchema&& schema,
               ArrowDeviceArray&& input,
               rmm::cuda_stream_view stream      = cudf::get_default_stream(),
               rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  arrow_column(ArrowSchema&& schema,
               ArrowArray&& input,
               rmm::cuda_stream_view stream      = cudf::get_default_stream(),
               rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  arrow_column(ArrowArrayStream&& input,
               rmm::cuda_stream_view stream      = cudf::get_default_stream(),
               rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  void to_arrow_schema(
    ArrowSchema* output,
    rmm::cuda_stream_view stream      = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()) const;
 
  void to_arrow(ArrowDeviceArray* output,
                ArrowDeviceType device_type       = ARROW_DEVICE_CUDA,
                rmm::cuda_stream_view stream      = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()) const;
 
  [[nodiscard]] column_view view() const;
 
 private:
  std::shared_ptr<arrow_array_container>
    container;  
  owned_columns_t view_columns;  
  column_view cached_view;
};
 
class arrow_table {
 public:
  arrow_table(cudf::table&& input,
              cudf::host_span<column_metadata const> metadata,
              rmm::cuda_stream_view stream      = cudf::get_default_stream(),
              rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  arrow_table(ArrowSchema&& schema,
              ArrowDeviceArray&& input,
              rmm::cuda_stream_view stream      = cudf::get_default_stream(),
              rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  arrow_table(ArrowSchema&& schema,
              ArrowArray&& input,
              rmm::cuda_stream_view stream      = cudf::get_default_stream(),
              rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  arrow_table(ArrowArrayStream&& input,
              rmm::cuda_stream_view stream      = cudf::get_default_stream(),
              rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  void to_arrow_schema(
    ArrowSchema* output,
    rmm::cuda_stream_view stream      = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()) const;
 
  void to_arrow(ArrowDeviceArray* output,
                ArrowDeviceType device_type       = ARROW_DEVICE_CUDA,
                rmm::cuda_stream_view stream      = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()) const;
 
  [[nodiscard]] table_view view() const;
 
 private:
  std::shared_ptr<arrow_array_container>
    container;  
  owned_columns_t view_columns;  
  table_view cached_view;
};
 
}  // namespace interop
 
unique_schema_t to_arrow_schema(cudf::table_view const& input,
                                cudf::host_span<column_metadata const> metadata);
 
unique_device_array_t to_arrow_device(
  cudf::table&& table,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
unique_device_array_t to_arrow_device(
  cudf::column&& col,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
unique_device_array_t to_arrow_device(
  cudf::table_view const& table,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
unique_device_array_t to_arrow_device(
  cudf::column_view const& col,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
unique_device_array_t to_arrow_host(
  cudf::table_view const& table,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
unique_device_array_t to_arrow_host(
  cudf::column_view const& col,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
unique_device_array_t to_arrow_host_stringview(
  cudf::strings_column_view const& col,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::unique_ptr<cudf::table> from_arrow(
  ArrowSchema const* schema,
  ArrowArray const* input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::unique_ptr<cudf::column> from_arrow_column(
  ArrowSchema const* schema,
  ArrowArray const* input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::unique_ptr<table> from_arrow_host(
  ArrowSchema const* schema,
  ArrowDeviceArray const* input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::unique_ptr<table> from_arrow_stream(
  ArrowArrayStream* input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::unique_ptr<column> from_arrow_stream_column(
  ArrowArrayStream* input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::unique_ptr<column> from_arrow_host_column(
  ArrowSchema const* schema,
  ArrowDeviceArray const* input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
unique_table_view_t from_arrow_device(
  ArrowSchema const* schema,
  ArrowDeviceArray const* input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
unique_column_view_t from_arrow_device_column(
  ArrowSchema const* schema,
  ArrowDeviceArray const* input,
  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
  // end of group
}  // namespace CUDF_EXPORT cudf