Adjust the way of determining FileHandle's compatibility mode for sync and async I/O to improve code readability

cpp/CMakeLists.txt

@@ -138,6 +138,7 @@ set(SOURCES
     "src/batch.cpp"
     "src/bounce_buffer.cpp"
     "src/buffer.cpp"
+    "src/compat_mode.cpp"
     "src/cufile/config.cpp"
     "src/cufile/driver.cpp"
     "src/defaults.cpp"

cpp/doxygen/main_page.md

@@ -80,7 +80,7 @@ When KvikIO is running in compatibility mode, it doesn't load `libcufile.so`. In
 
 The environment variable `KVIKIO_COMPAT_MODE` has three options (case-insensitive):
   - `ON` (aliases: `TRUE`, `YES`, `1`): Enable the compatibility mode.
-  - `OFF` (aliases: `FALSE`, `NO`, `0`): Disable the compatibility mode, and enforce cuFile I/O. GDS will be activated if the system requirements for cuFile are met and cuFile is properly configured. However, if the system is not suited for cuFile, I/O operations under the `OFF` option may error out, crash or hang.
+  - `OFF` (aliases: `FALSE`, `NO`, `0`): Disable the compatibility mode, and enforce cuFile I/O. GDS will be activated if the system requirements for cuFile are met and cuFile is properly configured. However, if the system is not suited for cuFile, I/O operations under the `OFF` option may error out.
   - `AUTO`: Try cuFile I/O first, and fall back to POSIX I/O if the system requirements for cuFile are not met.
 
 Under `AUTO`, KvikIO falls back to the compatibility mode:

cpp/include/kvikio/compat_mode.hpp

@@ -0,0 +1,150 @@
+/*
+ * Copyright (c) 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
+ *
+ *     http://www.apache.org/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 <cstdint>
+#include <string>
+
+#include <kvikio/file_utils.hpp>
+
+namespace kvikio {
+/**
+ * @brief I/O compatibility mode.
+ */
+enum class CompatMode : uint8_t {
+  OFF,  ///< Enforce cuFile I/O. GDS will be activated if the system requirements for cuFile are met
+        ///< and cuFile is properly configured. However, if the system is not suited for cuFile, I/O
+        ///< operations under the OFF option may error out.
+  ON,   ///< Enforce POSIX I/O.
+  AUTO,  ///< Try cuFile I/O first, and fall back to POSIX I/O if the system requirements for cuFile
+         ///< are not met.
+};
+
+namespace detail {
+/**
+ * @brief Parse a string into a CompatMode enum.
+ *
+ * @param compat_mode_str Compatibility mode in string format (case-insensitive). Valid values
+ * include:
+ *   - `ON` (alias: `TRUE`, `YES`, `1`)
+ *   - `OFF` (alias: `FALSE`, `NO`, `0`)
+ *   - `AUTO`
+ * @return A CompatMode enum.
+ */
+CompatMode parse_compat_mode_str(std::string_view compat_mode_str);
+
+}  // namespace detail
+
+// Forward declaration.
+class FileHandle;
+
+/**
+ * @brief Store and manage the compatibility mode data associated with a FileHandle.
+ */
+class CompatModeManager {
+ private:
+  CompatMode _compat_mode_requested{CompatMode::AUTO};
+  bool _is_compat_mode_preferred{true};
+  bool _is_compat_mode_preferred_for_async{true};
+
+ public:
+  /**
+   * @brief Construct an empty compatibility mode manager.
+   */
+  CompatModeManager() noexcept = default;
+
+  /**
+   * @brief Construct a compatibility mode manager associated with a FileHandle.
+   *
+   * According to the file path, requested compatibility mode, and the system configuration, the
+   * compatibility manager:
+   * - Infers the final compatibility modes for synchronous and asynchronous I/O paths,
+   * respectively.
+   * - Initializes the file wrappers and cuFile handle associated with a FileHandle.
+   *
+   * @param file_path Refer to
+   * FileHandle::FileHandle(std::string const&, std::string const&, mode_t, CompatMode).
+   * @param flags Same as above.
+   * @param mode Same as above.
+   * @param compat_mode_requested Same as above.
+   * @param file_handle Point to the FileHandle object that owns this compatibility mode manager.
+   */
+  CompatModeManager(std::string const& file_path,
+                    std::string const& flags,
+                    mode_t mode,
+                    CompatMode compat_mode_requested,
+                    FileHandle* file_handle);
+
+  ~CompatModeManager() noexcept                              = default;
+  CompatModeManager(const CompatModeManager&)                = default;
+  CompatModeManager& operator=(const CompatModeManager&)     = default;
+  CompatModeManager(CompatModeManager&&) noexcept            = default;
+  CompatModeManager& operator=(CompatModeManager&&) noexcept = default;
+
+  /**
+   * @brief Functionally identical to defaults::infer_compat_mode_if_auto(CompatMode).
+   *
+   * @param compat_mode Compatibility mode.
+   * @return If the given compatibility mode is CompatMode::AUTO, infer the final compatibility
+   * mode.
+   */
+  CompatMode infer_compat_mode_if_auto(CompatMode compat_mode) noexcept;
+
+  /**
+   * @brief Functionally identical to defaults::is_compat_mode_preferred(CompatMode).
+   *
+   * @param compat_mode Compatibility mode.
+   * @return Boolean answer.
+   */
+  bool is_compat_mode_preferred(CompatMode compat_mode) noexcept;
+
+  /**
+   * @brief Check if the compatibility mode for synchronous I/O of the associated FileHandle is
+   * expected to be CompatMode::ON.
+   *
+   * @return Boolean answer.
+   */
+  bool is_compat_mode_preferred() const noexcept;
+
+  /**
+   * @brief Check if the compatibility mode for asynchronous I/O of the associated FileHandle is
+   * expected to be CompatMode::ON.
+   *
+   * @return Boolean answer.
+   */
+  bool is_compat_mode_preferred_for_async() const noexcept;
+
+  /**
+   * @brief Retrieve the original compatibility mode requested.
+   *
+   * @return The original compatibility mode requested.
+   */
+  CompatMode compat_mode_requested() const noexcept;
+
+  /**
+   * @brief Determine if the asynchronous I/O can be performed or not (throw exceptions)
+   * according to the existing compatibility mode data in the manager.
+   *
+   * The asynchronous I/O cannot be performed, for instance, when compat_mode_requested() is
+   * CompatMode::OFF, is_compat_mode_preferred() is CompatMode::OFF, but
+   * is_compat_mode_preferred_for_async() is CompatMode::ON (due to missing cuFile stream API or
+   * cuFile configuration file).
+   */
+  void validate_compat_mode_for_async() const;
+};
+
+}  // namespace kvikio

cpp/include/kvikio/defaults.hpp

@@ -14,11 +14,6 @@
  * limitations under the License.
  */
 
-// Enable documentation of the enum.
-/**
- * @file
- */
-
 #pragma once
 
 #include <cstddef>
@@ -29,35 +24,13 @@
 
 #include <BS_thread_pool.hpp>
 
+#include <kvikio/compat_mode.hpp>
 #include <kvikio/shim/cufile.hpp>
 
-namespace kvikio {
 /**
- * @brief I/O compatibility mode.
+ * @brief KvikIO namespace.
  */
-enum class CompatMode : uint8_t {
-  OFF,  ///< Enforce cuFile I/O. GDS will be activated if the system requirements for cuFile are met
-        ///< and cuFile is properly configured. However, if the system is not suited for cuFile, I/O
-        ///< operations under the OFF option may error out, crash or hang.
-  ON,   ///< Enforce POSIX I/O.
-  AUTO,  ///< Try cuFile I/O first, and fall back to POSIX I/O if the system requirements for cuFile
-         ///< are not met.
-};
-
-namespace detail {
-/**
- * @brief Parse a string into a CompatMode enum.
- *
- * @param compat_mode_str Compatibility mode in string format(case-insensitive). Valid values
- * include:
- *   - `ON` (alias: `TRUE`, `YES`, `1`)
- *   - `OFF` (alias: `FALSE`, `NO`, `0`)
- *   - `AUTO`
- * @return A CompatMode enum.
- */
-CompatMode parse_compat_mode_str(std::string_view compat_mode_str);
-
-}  // namespace detail
+namespace kvikio {
 
 template <typename T>
 T getenv_or(std::string_view env_var_name, T default_val)

cpp/include/kvikio/error.hpp

@@ -17,6 +17,7 @@
 
 #include <cstring>
 #include <exception>
+#include <string>
 #include <system_error>
 
 #include <kvikio/shim/cuda.hpp>
@@ -71,7 +72,7 @@ void cuda_driver_try_2(CUresult error, int line_number, char const* filename)
 {
   if (error == CUDA_ERROR_STUB_LIBRARY) {
     throw Exception{std::string{"CUDA error at: "} + std::string(filename) + ":" +
-                    KVIKIO_STRINGIFY(line_number) +
+                    std::to_string(line_number) +
                     ": CUDA_ERROR_STUB_LIBRARY("
                     "The CUDA driver loaded is a stub library)"};
   }
@@ -82,9 +83,8 @@ void cuda_driver_try_2(CUresult error, int line_number, char const* filename)
     CUresult err_str_status  = cudaAPI::instance().GetErrorString(error, &err_str);
     if (err_name_status == CUDA_ERROR_INVALID_VALUE) { err_name = "unknown"; }
     if (err_str_status == CUDA_ERROR_INVALID_VALUE) { err_str = "unknown"; }
-    throw Exception{std::string{"CUDA error at: "} + filename + ":" +
-                    KVIKIO_STRINGIFY(line_number) + ": " + std::string(err_name) + "(" +
-                    std::string(err_str) + ")"};
+    throw Exception{std::string{"CUDA error at: "} + filename + ":" + std::to_string(line_number) +
+                    ": " + std::string(err_name) + "(" + std::string(err_str) + ")"};
   }
 }
 
@@ -97,7 +97,7 @@ void cufile_try_2(CUfileError_t error, int line_number, char const* filename)
       CUDA_DRIVER_TRY(cuda_error);
     }
     throw Exception{std::string{"cuFile error at: "} + filename + ":" +
-                    KVIKIO_STRINGIFY(line_number) + ": " +
+                    std::to_string(line_number) + ": " +
                     cufileop_status_error((CUfileOpError)std::abs(error.err))};
   }
 }
@@ -111,7 +111,7 @@ void cufile_check_bytes_done_2(ssize_t nbytes_done, int line_number, char const*
                        ? std::string(cufileop_status_error((CUfileOpError)err))
                        : std::string(std::strerror(err));
     throw Exception{std::string{"cuFile error at: "} + filename + ":" +
-                    KVIKIO_STRINGIFY(line_number) + ": " + msg};
+                    std::to_string(line_number) + ": " + msg};
   }
 }
 

cpp/include/kvikio/file_handle.hpp

@@ -25,13 +25,15 @@
 #include <utility>
 
 #include <kvikio/buffer.hpp>
+#include <kvikio/compat_mode.hpp>
 #include <kvikio/cufile/config.hpp>
 #include <kvikio/defaults.hpp>
 #include <kvikio/error.hpp>
 #include <kvikio/file_utils.hpp>
 #include <kvikio/parallel_operation.hpp>
 #include <kvikio/posix_io.hpp>
 #include <kvikio/shim/cufile.hpp>
+#include <kvikio/shim/cufile_h_wrapper.hpp>
 #include <kvikio/stream.hpp>
 #include <kvikio/utils.hpp>
 
@@ -45,23 +47,13 @@ namespace kvikio {
 class FileHandle {
  private:
   // We use two file descriptors, one opened with the O_DIRECT flag and one without.
-  FileWrapper _fd_direct_on{};
-  FileWrapper _fd_direct_off{};
+  FileWrapper _file_direct_on{};
+  FileWrapper _file_direct_off{};
   bool _initialized{false};
-  CompatMode _compat_mode{CompatMode::AUTO};
   mutable std::size_t _nbytes{0};  // The size of the underlying file, zero means unknown.
   CUFileHandleWrapper _cufile_handle{};
-
-  /**
-   * @brief Given a requested compatibility mode, whether it is expected to reduce to `ON` for
-   * asynchronous I/O.
-   *
-   * @param requested_compat_mode Requested compatibility mode.
-   * @return True if POSIX I/O fallback will be used; false for cuFile I/O.
-   * @exception std::runtime_error When the requested compatibility mode is `OFF`, but cuFile
-   * batch/stream library symbol is missing, or cuFile configuration file is missing.
-   */
-  bool is_compat_mode_preferred_for_async(CompatMode requested_compat_mode);
+  CompatModeManager _compat_mode_manager;
+  friend class CompatModeManager;
 
  public:
   static constexpr mode_t m644 = S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH;
@@ -444,27 +436,13 @@ class FileHandle {
                                          CUstream stream     = nullptr);
 
   /**
-   * @brief Returns `true` if the compatibility mode is expected to be `ON` for this file.
-   *
-   * Compatibility mode can be explicitly enabled in object creation. The mode is also enabled
-   * automatically, if file cannot be opened with the `O_DIRECT` flag, or if the system does not
-   * meet the requirements for the cuFile library under the `AUTO` compatibility mode.
-   *
-   * @return Boolean answer.
-   */
-  [[nodiscard]] bool is_compat_mode_preferred() const noexcept;
-
-  /**
-   * @brief Returns `true` if the compatibility mode is expected to be `ON` for the asynchronous I/O
-   * on this file.
-   *
-   * For asynchronous I/O, the compatibility mode can be automatically enabled if the cuFile batch
-   * and stream symbols are missing, or if the cuFile configuration file is missing, or if
-   * `is_compat_mode_preferred()` returns true.
+   * @brief Get the associated compatibility mode manager, which can be used to query the original
+   * requested compatibility mode or the expected compatibility modes for synchronous and
+   * asynchronous I/O.
    *
-   * @return Boolean answer.
+   * @return The associated compatibility mode manager.
    */
-  [[nodiscard]] bool is_compat_mode_preferred_for_async() const noexcept;
+  const CompatModeManager& get_compat_mode_manager() const noexcept;
 };
 
 }  // namespace kvikio

cpp/src/batch.cpp

@@ -60,7 +60,7 @@ void BatchHandle::submit(std::vector<BatchOp> const& operations)
   std::vector<CUfileIOParams_t> io_batch_params;
   io_batch_params.reserve(operations.size());
   for (auto const& op : operations) {
-    if (op.file_handle.is_compat_mode_preferred()) {
+    if (op.file_handle.get_compat_mode_manager().is_compat_mode_preferred()) {
       throw CUfileException("Cannot submit a FileHandle opened in compatibility mode");
     }