Add comments. Minor adjustment

cpp/include/kvikio/compat_mode.hpp

@@ -49,9 +49,11 @@ CompatMode parse_compat_mode_str(std::string_view compat_mode_str);
 
 }  // namespace detail
 
+// Forward declaration.
+class FileHandle;
+
 /**
- * @brief
- *
+ * @brief Store and manage the compatibility mode data associated with a FileHandle.
  */
 class CompatModeManager {
  private:
@@ -60,36 +62,87 @@ class CompatModeManager {
   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,
-                    FileWrapper& file_direct_on,
-                    FileWrapper& file_direct_off,
-                    CUFileHandleWrapper& cufile_handle);
+                    FileHandle* file_handle);
+
   ~CompatModeManager() noexcept                              = default;
   CompatModeManager(const CompatModeManager&)                = default;
   CompatModeManager& operator=(const CompatModeManager&)     = default;
   CompatModeManager(CompatModeManager&&) noexcept            = default;
   CompatModeManager& operator=(CompatModeManager&&) noexcept = default;
 
-  void compat_mode_reset(CompatMode compat_mode_requested);
-
+  /**
+   * @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 should be performed or not (throw exceptions)
-   * according to `_compat_mode_requested`, `_is_compat_mode_preferred`, and
-   * `_is_compat_mode_preferred_for_async`.
+   * according to the existing compatibility mode data in the manager.
+   *
+   * The asynchronous I/O should not 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();
 };

cpp/include/kvikio/file_handle.hpp

@@ -49,10 +49,11 @@ class FileHandle {
   // We use two file descriptors, one opened with the O_DIRECT flag and one without.
   FileWrapper _file_direct_on{};
   FileWrapper _file_direct_off{};
-  CUFileHandleWrapper _cufile_handle{};
   bool _initialized{false};
   mutable std::size_t _nbytes{0};  // The size of the underlying file, zero means unknown.
+  CUFileHandleWrapper _cufile_handle{};
   CompatModeManager _compat_mode_manager;
+  friend class CompatModeManager;
 
  public:
   static constexpr mode_t m644 = S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH;

cpp/src/compat_mode.cpp

@@ -17,11 +17,11 @@
 #include <algorithm>
 #include <cassert>
 #include <stdexcept>
-#include <utility>
 
 #include <kvikio/compat_mode.hpp>
 #include <kvikio/cufile/config.hpp>
 #include <kvikio/error.hpp>
+#include <kvikio/file_handle.hpp>
 #include <kvikio/shim/cufile.hpp>
 
 namespace kvikio {
@@ -49,19 +49,10 @@ CompatMode parse_compat_mode_str(std::string_view compat_mode_str)
 
 }  // namespace detail
 
-void CompatModeManager::compat_mode_reset(CompatMode compat_mode_requested)
-{
-  _compat_mode_requested    = compat_mode_requested;
-  _is_compat_mode_preferred = (infer_compat_mode_if_auto(_compat_mode_requested) == CompatMode::ON);
-}
-
 CompatMode CompatModeManager::infer_compat_mode_if_auto(CompatMode compat_mode) noexcept
 {
   if (compat_mode == CompatMode::AUTO) {
-    static auto inferred_compat_mode_for_auto = []() -> CompatMode {
-      return is_cufile_available() ? CompatMode::OFF : CompatMode::ON;
-    }();
-    return inferred_compat_mode_for_auto;
+    return is_cufile_available() ? CompatMode::OFF : CompatMode::ON;
   }
   return compat_mode;
 }
@@ -92,18 +83,21 @@ CompatModeManager::CompatModeManager(std::string const& file_path,
                                      std::string const& flags,
                                      mode_t mode,
                                      CompatMode compat_mode_requested_v,
-                                     FileWrapper& file_direct_on,
-                                     FileWrapper& file_direct_off,
-                                     CUFileHandleWrapper& cufile_handle)
+                                     FileHandle* file_handle)
 {
-  file_direct_off.open(file_path, flags, false, mode);
+  if (file_handle == nullptr) {
+    throw std::invalid_argument(
+      "The compatibility mode manager does not have a proper owning file handle.");
+  }
+
+  file_handle->_file_direct_off.open(file_path, flags, false, mode);
   _is_compat_mode_preferred = is_compat_mode_preferred(compat_mode_requested_v);
 
   // Nothing to do in compatibility mode
   if (_is_compat_mode_preferred) { return; }
 
   try {
-    file_direct_on.open(file_path, flags, true, mode);
+    file_handle->_file_direct_on.open(file_path, flags, true, mode);
   } catch (...) {
     // Try to open the file with the O_DIRECT flag. Fall back to compatibility mode, if it fails.
     if (compat_mode_requested_v == CompatMode::AUTO) {
@@ -115,7 +109,7 @@ CompatModeManager::CompatModeManager(std::string const& file_path,
 
   if (_is_compat_mode_preferred) { return; }
 
-  auto error_code = cufile_handle.register_handle(file_direct_on.fd());
+  auto error_code = file_handle->_cufile_handle.register_handle(file_handle->_file_direct_on.fd());
   assert(error_code.has_value());
 
   // For the AUTO mode, if the first cuFile API call fails, fall back to the compatibility

cpp/src/file_handle.cpp

@@ -34,9 +34,7 @@ FileHandle::FileHandle(std::string const& file_path,
                        std::string const& flags,
                        mode_t mode,
                        CompatMode compat_mode)
-  : _initialized{true},
-    _compat_mode_manager{
-      file_path, flags, mode, compat_mode, _file_direct_on, _file_direct_off, _cufile_handle}
+  : _initialized{true}, _compat_mode_manager{file_path, flags, mode, compat_mode, this}
 {
 }