file_handle.hpp

/*
 * Copyright (c) 2021-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 <sys/stat.h>
#include <sys/types.h>

#include <cstddef>
#include <cstdlib>
#include <stdexcept>
#include <system_error>
#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>

namespace kvikio {

class FileHandle {
 private
 // We use two file descriptors, one opened with the O_DIRECT flag and one without.
 FileWrapper _file_direct_on{};
 FileWrapper _file_direct_off{};
 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
 // 644 is a common setting of Unix file permissions: read and write for owner, read-only for group
 // and others.
 static constexpr mode_t m644 = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
 FileHandle() noexcept = default;

 FileHandle(std::string const& file_path,
 std::string const& flags = "r",
 mode_t mode = m644,
 CompatMode compat_mode = defaults::compat_mode());

 FileHandle(FileHandle const&) = delete;
 FileHandle& operator=(FileHandle const&) = delete;
 FileHandle(FileHandle&& o) noexcept;
 FileHandle& operator=(FileHandle&& o) noexcept;
 ~FileHandle() noexcept;

 [[nodiscard]] bool closed() const noexcept;

 void close() noexcept;

 [[nodiscard]] CUfileHandle_t handle();

 [[nodiscard]] int fd(bool o_direct = false) const noexcept;

 [[nodiscard]] int fd_open_flags(bool o_direct = false) const;

 [[nodiscard]] std::size_t nbytes() const;

 std::size_t read(void* devPtr_base,
 std::size_t size,
 std::size_t file_offset,
 std::size_t devPtr_offset,
 bool sync_default_stream = true);

 std::size_t write(void const* devPtr_base,
 std::size_t size,
 std::size_t file_offset,
 std::size_t devPtr_offset,
 bool sync_default_stream = true);

 std::future<std::size_t> pread(void* buf,
 std::size_t size,
 std::size_t file_offset = 0,
 std::size_t task_size = defaults::task_size(),
 std::size_t gds_threshold = defaults::gds_threshold(),
 bool sync_default_stream = true);

 std::future<std::size_t> pwrite(void const* buf,
 std::size_t size,
 std::size_t file_offset = 0,
 std::size_t task_size = defaults::task_size(),
 std::size_t gds_threshold = defaults::gds_threshold(),
 bool sync_default_stream = true);

 void read_async(void* devPtr_base,
 std::size_t* size_p,
 off_t* file_offset_p,
 off_t* devPtr_offset_p,
 ssize_t* bytes_read_p,
 CUstream stream);

 [[nodiscard]] StreamFuture read_async(void* devPtr_base,
 std::size_t size,
 off_t file_offset = 0,
 off_t devPtr_offset = 0,
 CUstream stream = nullptr);

 void write_async(void* devPtr_base,
 std::size_t* size_p,
 off_t* file_offset_p,
 off_t* devPtr_offset_p,
 ssize_t* bytes_written_p,
 CUstream stream);

 [[nodiscard]] StreamFuture write_async(void* devPtr_base,
 std::size_t size,
 off_t file_offset = 0,
 off_t devPtr_offset = 0,
 CUstream stream = nullptr);

 const CompatModeManager& get_compat_mode_manager() const noexcept;
};

} // namespace kvikio