Diff coverage report for

//

//

// Copyright (c) 2026 Michael Vandeberg

// Copyright (c) 2026 Michael Vandeberg

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/corosio

// Official repository: https://github.com/cppalliance/corosio

//

//

#ifndef BOOST_COROSIO_RANDOM_ACCESS_FILE_HPP

#ifndef BOOST_COROSIO_RANDOM_ACCESS_FILE_HPP

#define BOOST_COROSIO_RANDOM_ACCESS_FILE_HPP

#define BOOST_COROSIO_RANDOM_ACCESS_FILE_HPP

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/platform.hpp>

#include <boost/corosio/detail/platform.hpp>

#include <boost/corosio/detail/except.hpp>

#include <boost/corosio/detail/except.hpp>

#include <boost/corosio/detail/native_handle.hpp>

#include <boost/corosio/detail/native_handle.hpp>

#include <boost/corosio/detail/buffer_param.hpp>

#include <boost/corosio/detail/buffer_param.hpp>

#include <boost/corosio/file_base.hpp>

#include <boost/corosio/file_base.hpp>

#include <boost/corosio/io/io_object.hpp>

#include <boost/corosio/io/io_object.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/ex/executor_ref.hpp>

#include <boost/capy/ex/executor_ref.hpp>

#include <boost/capy/ex/execution_context.hpp>

#include <boost/capy/ex/execution_context.hpp>

#include <boost/capy/ex/io_env.hpp>

#include <boost/capy/ex/io_env.hpp>

#include <boost/capy/concept/executor.hpp>

#include <boost/capy/concept/executor.hpp>

#include <boost/capy/buffers.hpp>

#include <boost/capy/buffers.hpp>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <cstddef>

#include <cstddef>

#include <cstdint>

#include <cstdint>

#include <type_traits>

#include <type_traits>

#include <filesystem>

#include <filesystem>

#include <stop_token>

#include <stop_token>

#include <system_error>

#include <system_error>

namespace boost::corosio {

namespace boost::corosio {

/** An asynchronous random-access file for coroutine I/O.

/** An asynchronous random-access file for coroutine I/O.

    Provides asynchronous read and write operations at explicit

    Provides asynchronous read and write operations at explicit

    byte offsets, without maintaining an implicit file position.

    byte offsets, without maintaining an implicit file position.

    On POSIX platforms, file I/O is dispatched to a thread pool

    On POSIX platforms, file I/O is dispatched to a thread pool

    (blocking `preadv`/`pwritev`) with completion posted back to

    (blocking `preadv`/`pwritev`) with completion posted back to

    the scheduler. On Windows, true overlapped I/O is used via IOCP.

    the scheduler. On Windows, true overlapped I/O is used via IOCP.

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.@n

    Distinct objects: Safe.@n

    Shared objects: Unsafe. Multiple concurrent reads and writes

    Shared objects: Unsafe. Multiple concurrent reads and writes

    are supported from coroutines sharing the same file object,

    are supported from coroutines sharing the same file object,

    but external synchronization is required for non-async

    but external synchronization is required for non-async

    operations (open, close, size, resize, etc.).

    operations (open, close, size, resize, etc.).

    @par Example

    @par Example

    @code

    @code

    io_context ioc;

    io_context ioc;

    random_access_file f(ioc);

    random_access_file f(ioc);

    f.open("data.bin", file_base::read_only);

    f.open("data.bin", file_base::read_only);

    char buf[4096];

    char buf[4096];

    auto [ec, n] = co_await f.read_some_at(

    auto [ec, n] = co_await f.read_some_at(

        0, capy::mutable_buffer(buf, sizeof(buf)));

        0, capy::mutable_buffer(buf, sizeof(buf)));

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL random_access_file : public io_object

class BOOST_COROSIO_DECL random_access_file : public io_object

{

{

public:

public:

    /** Platform-specific random-access file implementation interface.

    /** Platform-specific random-access file implementation interface.

        Backends derive from this to provide offset-based file I/O.

        Backends derive from this to provide offset-based file I/O.

    */

    */

    struct implementation : io_object::implementation

    struct implementation : io_object::implementation

    {

    {

        /** Initiate a read at the given offset.

        /** Initiate a read at the given offset.

            @param offset Byte offset into the file.

            @param offset Byte offset into the file.

            @param h Coroutine handle to resume on completion.

            @param h Coroutine handle to resume on completion.

            @param ex Executor for dispatching the completion.

            @param ex Executor for dispatching the completion.

            @param buf The buffer to read into.

            @param buf The buffer to read into.

            @param token Stop token for cancellation.

            @param token Stop token for cancellation.

            @param ec Output error code.

            @param ec Output error code.

            @param bytes_out Output bytes transferred.

            @param bytes_out Output bytes transferred.

            @return Coroutine handle to resume immediately.

            @return Coroutine handle to resume immediately.

        */

        */

        virtual std::coroutine_handle<> read_some_at(

        virtual std::coroutine_handle<> read_some_at(

            std::uint64_t offset,

            std::uint64_t offset,

            std::coroutine_handle<> h,

            std::coroutine_handle<> h,

            capy::executor_ref ex,

            capy::executor_ref ex,

            buffer_param buf,

            buffer_param buf,

            std::stop_token token,

            std::stop_token token,

            std::error_code* ec,

            std::error_code* ec,

            std::size_t* bytes_out) = 0;

            std::size_t* bytes_out) = 0;

        /** Initiate a write at the given offset.

        /** Initiate a write at the given offset.

            @param offset Byte offset into the file.

            @param offset Byte offset into the file.

            @param h Coroutine handle to resume on completion.

            @param h Coroutine handle to resume on completion.

            @param ex Executor for dispatching the completion.

            @param ex Executor for dispatching the completion.

            @param buf The buffer to write from.

            @param buf The buffer to write from.

            @param token Stop token for cancellation.

            @param token Stop token for cancellation.

            @param ec Output error code.

            @param ec Output error code.

            @param bytes_out Output bytes transferred.

            @param bytes_out Output bytes transferred.

            @return Coroutine handle to resume immediately.

            @return Coroutine handle to resume immediately.

        */

        */

        virtual std::coroutine_handle<> write_some_at(

        virtual std::coroutine_handle<> write_some_at(

            std::uint64_t offset,

            std::uint64_t offset,

            std::coroutine_handle<> h,

            std::coroutine_handle<> h,

            capy::executor_ref ex,

            capy::executor_ref ex,

            buffer_param buf,

            buffer_param buf,

            std::stop_token token,

            std::stop_token token,

            std::error_code* ec,

            std::error_code* ec,

            std::size_t* bytes_out) = 0;

            std::size_t* bytes_out) = 0;

        /// Return the platform file descriptor or handle.

        /// Return the platform file descriptor or handle.

        virtual native_handle_type native_handle() const noexcept = 0;

        virtual native_handle_type native_handle() const noexcept = 0;

        /// Cancel pending asynchronous operations.

        /// Cancel pending asynchronous operations.

        virtual void cancel() noexcept = 0;

        virtual void cancel() noexcept = 0;

        /// Return the file size in bytes.

        /// Return the file size in bytes.

        virtual std::uint64_t size() const = 0;

        virtual std::uint64_t size() const = 0;

        /// Resize the file to @p new_size bytes.

        /// Resize the file to @p new_size bytes.

        virtual void resize(std::uint64_t new_size) = 0;

        virtual void resize(std::uint64_t new_size) = 0;

        /// Synchronize file data to stable storage.

        /// Synchronize file data to stable storage.

        virtual void sync_data() = 0;

        virtual void sync_data() = 0;

        /// Synchronize file data and metadata to stable storage.

        /// Synchronize file data and metadata to stable storage.

        virtual void sync_all() = 0;

        virtual void sync_all() = 0;

        /// Release ownership of the native handle.

        /// Release ownership of the native handle.

        virtual native_handle_type release() = 0;

        virtual native_handle_type release() = 0;

        /// Adopt an existing native handle.

        /// Adopt an existing native handle.

        virtual void assign(native_handle_type handle) = 0;

        virtual void assign(native_handle_type handle) = 0;

    };

    };

    /** Awaitable for async read-at operations. */

    /** Awaitable for async read-at operations. */

    template<class MutableBufferSequence>

    template<class MutableBufferSequence>

    struct read_some_at_awaitable

    struct read_some_at_awaitable

    {

    {

        random_access_file& f_;

        random_access_file& f_;

        std::uint64_t offset_;

        std::uint64_t offset_;

        MutableBufferSequence buffers_;

        MutableBufferSequence buffers_;

        std::stop_token token_;

        std::stop_token token_;

        mutable std::error_code ec_;

        mutable std::error_code ec_;

        mutable std::size_t bytes_ = 0;

        mutable std::size_t bytes_ = 0;

            random_access_file& f,

            random_access_file& f,

            std::uint64_t offset,

            std::uint64_t offset,

            MutableBufferSequence buffers)

            MutableBufferSequence buffers)

            noexcept(std::is_nothrow_move_constructible_v<MutableBufferSequence>)

            noexcept(std::is_nothrow_move_constructible_v<MutableBufferSequence>)

        {

        {

        {

        {

        }

        }

        {

        {

        }

        }

            -> std::coroutine_handle<>

            -> std::coroutine_handle<>

        {

        {

        }

        }

    };

    };

    /** Awaitable for async write-at operations. */

    /** Awaitable for async write-at operations. */

    template<class ConstBufferSequence>

    template<class ConstBufferSequence>

    struct write_some_at_awaitable

    struct write_some_at_awaitable

    {

    {

        random_access_file& f_;

        random_access_file& f_;

        std::uint64_t offset_;

        std::uint64_t offset_;

        ConstBufferSequence buffers_;

        ConstBufferSequence buffers_;

        std::stop_token token_;

        std::stop_token token_;

        mutable std::error_code ec_;

        mutable std::error_code ec_;

        mutable std::size_t bytes_ = 0;

        mutable std::size_t bytes_ = 0;

            random_access_file& f,

            random_access_file& f,

            std::uint64_t offset,

            std::uint64_t offset,

            ConstBufferSequence buffers)

            ConstBufferSequence buffers)

            noexcept(std::is_nothrow_move_constructible_v<ConstBufferSequence>)

            noexcept(std::is_nothrow_move_constructible_v<ConstBufferSequence>)

        {

        {

        {

        {

        }

        }

        {

        {

        }

        }

            -> std::coroutine_handle<>

            -> std::coroutine_handle<>

        {

        {

        }

        }

    };

    };

public:

public:

    /** Destructor.

    /** Destructor.

        Closes the file if open, cancelling any pending operations.

        Closes the file if open, cancelling any pending operations.

    */

    */

    ~random_access_file() override;

    ~random_access_file() override;

    /** Construct from an execution context.

    /** Construct from an execution context.

        @param ctx The execution context that will own this file.

        @param ctx The execution context that will own this file.

    */

    */

    explicit random_access_file(capy::execution_context& ctx);

    explicit random_access_file(capy::execution_context& ctx);

    /** Construct from an executor.

    /** Construct from an executor.

        @param ex The executor whose context will own this file.

        @param ex The executor whose context will own this file.

    */

    */

    template<class Ex>

    template<class Ex>

        requires(!std::same_as<std::remove_cvref_t<Ex>, random_access_file>) &&

        requires(!std::same_as<std::remove_cvref_t<Ex>, random_access_file>) &&

        capy::Executor<Ex>

        capy::Executor<Ex>

    {

    {

    /** Move constructor. */

    /** Move constructor. */

    {

    {

    /** Move assignment operator. */

    /** Move assignment operator. */

    random_access_file& operator=(random_access_file&& other) noexcept

    random_access_file& operator=(random_access_file&& other) noexcept

    {

    {

        if (this != &other)

        if (this != &other)

        {

        {

            close();

            close();

            h_ = std::move(other.h_);

            h_ = std::move(other.h_);

        }

        }

        return *this;

        return *this;

    }

    }

    random_access_file(random_access_file const&)            = delete;

    random_access_file(random_access_file const&)            = delete;

    random_access_file& operator=(random_access_file const&) = delete;

    random_access_file& operator=(random_access_file const&) = delete;

    /** Open a file.

    /** Open a file.

        @param path The filesystem path to open.

        @param path The filesystem path to open.

        @param mode Bitmask of @ref file_base::flags specifying

        @param mode Bitmask of @ref file_base::flags specifying

            access mode and creation behavior.

            access mode and creation behavior.

        @throws std::system_error on failure.

        @throws std::system_error on failure.

    */

    */

    void open(

    void open(

        std::filesystem::path const& path,

        std::filesystem::path const& path,

        file_base::flags mode = file_base::read_only);

        file_base::flags mode = file_base::read_only);

    /** Close the file.

    /** Close the file.

        Releases file resources. Any pending operations complete

        Releases file resources. Any pending operations complete

        with `errc::operation_canceled`.

        with `errc::operation_canceled`.

    */

    */

    void close();

    void close();

    /** Check if the file is open. */

    /** Check if the file is open. */

    {

    {

#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)

#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)

        return h_ && get().native_handle() != ~native_handle_type(0);

        return h_ && get().native_handle() != ~native_handle_type(0);

#else

#else

#endif

#endif

    }

    }

    /** Read data at the given offset.

    /** Read data at the given offset.

        @param offset Byte offset into the file.

        @param offset Byte offset into the file.

        @param buffers The buffer sequence to read into.

        @param buffers The buffer sequence to read into.

        @return An awaitable yielding `(error_code, std::size_t)`.

        @return An awaitable yielding `(error_code, std::size_t)`.

        @throws std::logic_error if the file is not open.

        @throws std::logic_error if the file is not open.

    */

    */

    template<capy::MutableBufferSequence MB>

    template<capy::MutableBufferSequence MB>

    {

    {

    }

    }

    /** Write data at the given offset.

    /** Write data at the given offset.

        @param offset Byte offset into the file.

        @param offset Byte offset into the file.

        @param buffers The buffer sequence to write from.

        @param buffers The buffer sequence to write from.

        @return An awaitable yielding `(error_code, std::size_t)`.

        @return An awaitable yielding `(error_code, std::size_t)`.

        @throws std::logic_error if the file is not open.

        @throws std::logic_error if the file is not open.

    */

    */

    template<capy::ConstBufferSequence CB>

    template<capy::ConstBufferSequence CB>

    {

    {

    }

    }

    /** Cancel pending asynchronous operations. */

    /** Cancel pending asynchronous operations. */

    void cancel();

    void cancel();

    /** Get the native file descriptor or handle. */

    /** Get the native file descriptor or handle. */

    native_handle_type native_handle() const noexcept;

    native_handle_type native_handle() const noexcept;

    /** Return the file size in bytes. */

    /** Return the file size in bytes. */

    std::uint64_t size() const;

    std::uint64_t size() const;

    /** Resize the file. */

    /** Resize the file. */

    void resize(std::uint64_t new_size);

    void resize(std::uint64_t new_size);

    /** Synchronize file data to stable storage. */

    /** Synchronize file data to stable storage. */

    void sync_data();

    void sync_data();

    /** Synchronize file data and metadata to stable storage. */

    /** Synchronize file data and metadata to stable storage. */

    void sync_all();

    void sync_all();

    /** Release ownership of the native handle.

    /** Release ownership of the native handle.

        The file object becomes not-open. The caller is

        The file object becomes not-open. The caller is

        responsible for closing the returned handle.

        responsible for closing the returned handle.

        @return The native file descriptor or handle.

        @return The native file descriptor or handle.

    */

    */

    native_handle_type release();

    native_handle_type release();

    /** Adopt an existing native handle.

    /** Adopt an existing native handle.

        Closes any currently open file before adopting.

        Closes any currently open file before adopting.

        The file object takes ownership of the handle.

        The file object takes ownership of the handle.

        @param handle The native file descriptor or handle.

        @param handle The native file descriptor or handle.

    */

    */

    void assign(native_handle_type handle);

    void assign(native_handle_type handle);

private:

private:

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif // BOOST_COROSIO_RANDOM_ACCESS_FILE_HPP

#endif // BOOST_COROSIO_RANDOM_ACCESS_FILE_HPP