Add a new remote I/O backend based on libcurl poll-based multi API

cpp/CMakeLists.txt

@@ -1,6 +1,6 @@
 # =============================================================================
 # cmake-format: off
-# SPDX-FileCopyrightText: Copyright (c) 2021-2025, NVIDIA CORPORATION.
+# SPDX-FileCopyrightText: Copyright (c) 2021-2026, NVIDIA CORPORATION.
 # SPDX-License-Identifier: Apache-2.0
 # cmake-format: on
 # =============================================================================
@@ -163,8 +163,16 @@ set(SOURCES
 )
 
 if(KvikIO_REMOTE_SUPPORT)
-  list(APPEND SOURCES "src/hdfs.cpp" "src/remote_handle.cpp" "src/detail/remote_handle.cpp"
-       "src/detail/tls.cpp" "src/detail/url.cpp" "src/shim/libcurl.cpp"
+  list(
+    APPEND
+    SOURCES
+    "src/hdfs.cpp"
+    "src/remote_handle.cpp"
+    "src/detail/remote_handle.cpp"
+    "src/detail/remote_handle_poll_based.cpp"
+    "src/detail/tls.cpp"
+    "src/detail/url.cpp"
+    "src/shim/libcurl.cpp"
   )
 endif()
 

cpp/include/kvikio/defaults.hpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2022-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -16,6 +16,7 @@
 #include <kvikio/compat_mode.hpp>
 #include <kvikio/error.hpp>
 #include <kvikio/http_status_codes.hpp>
+#include <kvikio/remote_backend_type.hpp>
 #include <kvikio/shim/cufile.hpp>
 #include <kvikio/threadpool_wrapper.hpp>
 
@@ -49,6 +50,9 @@ bool getenv_or(std::string_view env_var_name, bool default_val);
 template <>
 CompatMode getenv_or(std::string_view env_var_name, CompatMode default_val);
 
+template <>
+RemoteBackendType getenv_or(std::string_view env_var_name, RemoteBackendType default_val);
+
 template <>
 std::vector<int> getenv_or(std::string_view env_var_name, std::vector<int> default_val);
 
@@ -122,6 +126,9 @@ class defaults {
   bool _auto_direct_io_read;
   bool _auto_direct_io_write;
   bool _thread_pool_per_block_device;
+  RemoteBackendType _remote_backend;
+  std::size_t _remote_max_connections;
+  std::size_t _num_bounce_buffers;
 
   static unsigned int get_num_threads_from_env();
 
@@ -417,6 +424,58 @@ class defaults {
    * thread pool for all I/O operations.
    */
   static void set_thread_pool_per_block_device(bool flag);
+
+  /**
+   * @brief Get the current remote I/O backend type.
+   *
+   * @return The currently configured RemoteBackendType.
+   */
+  [[nodiscard]] static RemoteBackendType remote_backend();
+
+  /**
+   * @brief Set the remote I/O backend type.
+   *
+   * Note: Changing this after creating a RemoteHandle has no effect on existing handles. The
+   * backend is determined at RemoteHandle construction time.
+   *
+   * @param remote_backend The backend type to use for new RemoteHandle instances.
+   */
+  static void set_remote_backend(RemoteBackendType remote_backend);
+
+  /**
+   * @brief Get the maximum number of concurrent connections for poll-based remote I/O.
+   *
+   * Only applies when using RemoteBackendType::LIBCURL_MULTI_POLL.
+   *
+   * @return Maximum number of concurrent connections.
+   */
+  [[nodiscard]] static std::size_t remote_max_connections();
+
+  /**
+   * @brief Set the maximum number of concurrent connections for poll-based remote I/O.
+   *
+   * Only applies when using RemoteBackendType::LIBCURL_MULTI_POLL.
+   *
+   * @param remote_max_connections Maximum concurrent connections (must be positive).
+   */
+  static void set_remote_max_connections(std::size_t remote_max_connections);
+
+  /**
+   * @brief Get the number of bounce buffers used per connection for poll-based remote I/O.
+   *
+   * Controls k-way buffering: higher values allow more overlap between network I/O and H2D
+   * transfers but consume more pinned memory.
+   *
+   * @return Number of bounce buffers per connection.
+   */
+  [[nodiscard]] static std::size_t num_bounce_buffers();
+
+  /**
+   * @brief Set the number of bounce buffers used per connection for poll-based remote I/O.
+   *
+   * @param num_bounce_buffers Number of bounce buffers per connection (must be positive).
+   */
+  static void set_num_bounce_buffers(std::size_t num_bounce_buffers);
 };
 
 }  // namespace kvikio

cpp/include/kvikio/detail/remote_handle.hpp

@@ -1,12 +1,52 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
 
 #include <cstring>
 
+#include <kvikio/shim/libcurl.hpp>
+
 namespace kvikio::detail {
+/**
+ * @brief Check a libcurl easy interface return code and throw on error.
+ *
+ * @param err_code The CURLcode to check.
+ * @exception std::runtime_error if err_code is not CURLE_OK.
+ */
+#define KVIKIO_CHECK_CURL_EASY(err_code) \
+  kvikio::detail::check_curl_easy(err_code, __FILE__, __LINE__)
+
+/**
+ * @brief Check a libcurl multi interface return code and throw on error.
+ *
+ * @param err_code The CURLMcode to check.
+ * @exception std::runtime_error if err_code is not CURLM_OK.
+ */
+#define KVIKIO_CHECK_CURL_MULTI(err_code) \
+  kvikio::detail::check_curl_multi(err_code, __FILE__, __LINE__)
+
+/**
+ * @brief Check a libcurl easy interface return code and throw on error.
+ *
+ * @param err_code The CURLcode to check.
+ * @param filename Source filename for error reporting.
+ * @param line_number Source line number for error reporting.
+ * @exception std::runtime_error if err_code is not CURLE_OK.
+ */
+void check_curl_easy(CURLcode err_code, char const* filename, int line_number);
+
+/**
+ * @brief Check a libcurl multi interface return code and throw on error.
+ *
+ * @param err_code The CURLMcode to check.
+ * @param filename Source filename for error reporting.
+ * @param line_number Source line number for error reporting.
+ * @exception std::runtime_error if err_code is not CURLM_OK.
+ */
+void check_curl_multi(CURLMcode err_code, char const* filename, int line_number);
+
 /**
  * @brief Callback for `CURLOPT_WRITEFUNCTION` that copies received data into a `std::string`.
  *
@@ -20,4 +60,13 @@ std::size_t callback_get_string_response(char* data,
                                          std::size_t size,
                                          std::size_t num_bytes,
                                          void* userdata);
+
+/**
+ * @brief Set up the range request for libcurl. Use this method when HTTP range request is supposed.
+ *
+ * @param curl A curl handle
+ * @param file_offset File offset
+ * @param size read size
+ */
+void setup_range_request_impl(CurlHandle& curl, std::size_t file_offset, std::size_t size);
 }  // namespace kvikio::detail

cpp/include/kvikio/detail/remote_handle_poll_based.hpp

@@ -0,0 +1,133 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <memory>
+
+#include <kvikio/bounce_buffer.hpp>
+#include <kvikio/remote_handle.hpp>
+#include <kvikio/shim/libcurl.hpp>
+
+namespace kvikio::detail {
+
+/**
+ * @brief Manages a rotating set of bounce buffers for overlapping network I/O with H2D transfers.
+ *
+ * This class implements k-way buffering, rotating through buffers circularly: while one buffer
+ * receives data from the network, previously filled buffers can be asynchronously copied to device
+ * memory. When all buffers have been used, the class synchronizes the CUDA stream before reusing
+ * buffers.
+ */
+class BounceBufferManager {
+ public:
+  /**
+   * @brief Construct a BounceBufferManager with the specified number of bounce buffers.
+   *
+   * @param num_bounce_buffers Number of bounce buffers to allocate from the pool.
+   */
+  BounceBufferManager(std::size_t num_bounce_buffers);
+
+  /**
+   * @brief Get a pointer to the current bounce buffer's data.
+   *
+   * @return Pointer to the current buffer's memory.
+   */
+  void* data() const noexcept;
+
+  /**
+   * @brief Copy data from the current bounce buffer to device memory and rotate to the next buffer.
+   *
+   * Issues an asynchronous H2D copy and advances to the next buffer. When wrapping around to buffer
+   * 0, synchronizes the stream to ensure all previous copies have completed before reuse.
+   *
+   * @param dst Device memory destination pointer.
+   * @param size Number of bytes to copy.
+   * @param stream CUDA stream for the asynchronous copy.
+   * @exception kvikio::CUfileException if size exceeds bounce buffer capacity.
+   */
+  void copy(void* dst, std::size_t size, CUstream stream);
+
+ private:
+  std::size_t _bounce_buffer_idx{};
+  std::size_t _num_bounce_buffers{};
+  std::vector<CudaPinnedBounceBufferPool::Buffer> _bounce_buffers;
+};
+
+/**
+ * @brief Context for tracking the state of a single chunked transfer.
+ *
+ * Each concurrent connection has an associated TransferContext that tracks the destination buffer,
+ * transfer progress, and manages optional bounce buffers for GPU destinations.
+ */
+struct TransferContext {
+  bool overflow_error{};
+  bool is_host_mem{};
+  char* buf{};
+  CurlHandle* curl_easy_handle{};
+  std::size_t chunk_size{};
+  std::size_t bytes_transferred{};
+  std::optional<BounceBufferManager> _bounce_buffer_manager;
+};
+
+/**
+ * @brief Poll-based remote file handle using libcurl's multi interface.
+ *
+ * This class provides an alternative to the thread-pool-based remote I/O by using libcurl's multi
+ * interface with curl_multi_poll() for managing concurrent connections. It implements chunked
+ * parallel downloads with k-way buffering to overlap network transfers with host-to-device memory
+ * copies.
+ *
+ * @note Thread safety: The pread() method is protected by a mutex, making it safe to call from
+ * multiple threads, though calls will be serialized.
+ */
+class RemoteHandlePollBased {
+ private:
+  CURLM* _multi;
+  std::size_t _max_connections;
+  std::vector<std::unique_ptr<CurlHandle>> _curl_easy_handles;
+  std::vector<TransferContext> _transfer_ctxs;
+  RemoteEndpoint* _endpoint;
+  mutable std::mutex _mutex;
+
+ public:
+  /**
+   * @brief Construct a poll-based remote handle.
+   *
+   * Initializes the libcurl multi handle and creates the specified number of easy handles for
+   * concurrent transfers.
+   *
+   * @param endpoint Non-owning pointer to the remote endpoint. Must outlive this object.
+   * @param max_connections Maximum number of concurrent connections to use.
+   * @exception kvikio::CUfileException if task_size exceeds bounce_buffer_size.
+   * @exception kvikio::CUfileException if libcurl multi initialization fails.
+   */
+  RemoteHandlePollBased(RemoteEndpoint* endpoint, std::size_t max_connections);
+
+  /**
+   * @brief Destructor that cleans up libcurl multi resources.
+   *
+   * Removes all easy handles from the multi handle and performs cleanup. Errors during cleanup are
+   * logged but do not throw.
+   */
+  ~RemoteHandlePollBased() noexcept;
+
+  /**
+   * @brief Read data from the remote file into a buffer.
+   *
+   * Performs a parallel chunked read using multiple concurrent HTTP range requests. For device
+   * memory destinations, uses bounce buffers with k-way buffering to overlap network I/O with H2D
+   * transfers.
+   *
+   * @param buf Destination buffer (host or device memory).
+   * @param size Number of bytes to read.
+   * @param file_offset Offset in the remote file to start reading from.
+   * @return Number of bytes actually read.
+   * @exception std::overflow_error if the server returns more data than expected (may indicate the
+   * server doesn't support range requests).
+   * @exception std::runtime_error on libcurl errors.
+   */
+  std::size_t pread(void* buf, std::size_t size, std::size_t file_offset = 0);
+};
+}  // namespace kvikio::detail

cpp/include/kvikio/remote_backend_type.hpp

@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <cstdint>
+
+namespace kvikio {
+
+/**
+ * @brief Enum representing the backend implementation for remote file I/O operations.
+ *
+ * KvikIO supports multiple libcurl-based backends for fetching data from remote endpoints (S3,
+ * HTTP, etc.). Each backend has different performance characteristics.
+ */
+enum class RemoteBackendType : uint8_t {
+  LIBCURL_EASY,  ///< Use libcurl's easy interface with a thread pool for parallelism. Each chunk is
+                 ///< fetched by a separate thread using blocking curl_easy_perform() calls. This is
+                 ///< the default backend.
+  LIBCURL_MULTI_POLL,  ///< Use libcurl's multi interface with poll-based concurrent transfers. A
+                       ///< single call manages multiple concurrent connections using
+                       ///< curl_multi_poll(), with k-way buffering to overlap network I/O with
+                       ///< host-to-device transfers.
+};
+
+}  // namespace kvikio

cpp/include/kvikio/remote_handle.hpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
@@ -13,6 +13,7 @@
 
 #include <kvikio/defaults.hpp>
 #include <kvikio/error.hpp>
+#include <kvikio/remote_backend_type.hpp>
 #include <kvikio/threadpool_wrapper.hpp>
 #include <kvikio/utils.hpp>
 
@@ -291,13 +292,20 @@ class S3EndpointWithPresignedUrl : public RemoteEndpoint {
   static bool is_url_valid(std::string const& url) noexcept;
 };
 
+// Forward declaration
+namespace detail {
+class RemoteHandlePollBased;
+}
+
 /**
  * @brief Handle of remote file.
  */
 class RemoteHandle {
  private:
   std::unique_ptr<RemoteEndpoint> _endpoint;
   std::size_t _nbytes;
+  std::unique_ptr<detail::RemoteHandlePollBased> _poll_handle;
+  RemoteBackendType _remote_backend_type;
 
  public:
   /**
@@ -400,8 +408,9 @@ class RemoteHandle {
   RemoteHandle(std::unique_ptr<RemoteEndpoint> endpoint);
 
   // A remote handle is moveable but not copyable.
-  RemoteHandle(RemoteHandle&& o)               = default;
-  RemoteHandle& operator=(RemoteHandle&& o)    = default;
+  ~RemoteHandle();
+  RemoteHandle(RemoteHandle&& o);
+  RemoteHandle& operator=(RemoteHandle&& o);
   RemoteHandle(RemoteHandle const&)            = delete;
   RemoteHandle& operator=(RemoteHandle const&) = delete;