File IO

The async_file provides simple asynchronous read/write operations to the user. An async_file is essentially just a wrapper for file io family of requests providied by liburing.

async_file usage in an engine_enabled class:

Example

async_function<>
your_class::file_io_example()
{

    async_file<char> file(engine_);

    /* Open with read, write, and truncate */
    bool success = co_await file.open("test_file.txt", file::Options::kRWTruncate);

    if (success)
    {
        std::vector<char> buffer(42, 42);

        /* Write data to file */
        success = co_await file.write_to_file(buffer);

        if (success)
        {
            /* Re position the file ptr */
            success = file.position(0);

            if (success)
            {
                /* Read the data */
                std::optional<std::vector<char>> data = co_await file.read_file();

                if (data && *data == buffer) { std::cout << "File io was successful.": }
            }
        }

        /* Close the file */
        success = co_await file.close();
    }
}

template<MemoryType ReadType = std::byte> class zab::async_file

This class allows for asynchronous file i/o.

async_file does not provide any synchronisation for file ops. async_file must be used within an engine thread.

The file descriptor associated with async_file is opened as if by call to fopen() or open(2) with the following flags:

┌───────────────┬───────────────┬───────────────────────────────┐ │ Options │ fopen() mode │ open() flags │ ├───────────────┼───────────────┼───────────────────────────────┤ │ kRead │ r │ O_RDONLY │ ├───────────────┼───────────────┼───────────────────────────────┤ │ kTrunc │ w │ O_WRONLY | O_CREAT | O_TRUNC │ ├───────────────┼───────────────┼───────────────────────────────┤ │ kAppend │ a │ O_WRONLY | O_CREAT | O_APPEND │ ├───────────────┼───────────────┼───────────────────────────────┤ │ kReadWrite │ r+ │ O_RDWR │ ├───────────────┼───────────────┼───────────────────────────────┤ │ kRWTruncate │ w+ │ O_RDWR | O_CREAT | O_TRUNC │ ├───────────────├───────────────┼───────────────────────────────┤ │ kRWAppend │ a+ │ O_RDWR | O_CREAT | O_APPEND │ └───────────────┴───────────────┴───────────────────────────────┘

Public Functions

inline async_file(engine *_engine)

Create a async file.

Parameters: _engine – The engine to use.

async_file(const async_file&) = delete: Files are not copyable.

inline async_file(async_file &&_move)

Construct a new async_file object taking the file descriptor from another async_file.

Parameters: _move – The async_file to move.

inline async_file &operator=(async_file &&_move_op)

Move assignment for an async_file.

Parameters: _move_op –
Returns: async_file&

inline ~async_file()

Closes the file.

The actual closing of the file will be flushed to a background process. co_awaiting on close() is reconmended before deconstruction.

inline auto open(std::string_view _path, file::Option _options, mode_t _mode = kDefaultMode) noexcept

Opens a file relative to this proccess cwd.

Parameters

_path – The relative path of the file.
_options – The zab options to apply.
_mode – The open mode.

Returns

suspension_point The awaitable instance for opening the file. Async returns the success.

inline auto open(std::string_view _path, int _flags, mode_t _mode) noexcept

Opens a file relative to this proccess cwd.

Parameters

_path – The relative path of the file.
_flags – The flags to apply.
_mode – The open mode.

Returns

suspension_point The awaitable instance for opening the file. Async returns the success.

inline auto open(const directory &_dir, std::string_view _path, file::Option _options, mode_t _mode = kDefaultMode) noexcept

Opens a file relative to the directory given.

Parameters

directory – The directory.
_path – The relative path of the file.
_options – The zab options to apply.
_mode – The open mode.

Returns

suspension_point The awaitable instance for opening the file. Async returns the success.

inline auto open(const directory &_dir, std::string_view _path, int _flags, mode_t _mode = kDefaultMode) noexcept

Opens a file relative to the directory given.

Parameters

directory – The directory.
_path – The relative path of the file.
_flags – The flags to apply.
_mode – The open mode.

Returns

suspension_point The awaitable instance for opening the file. Async returns the success.

inline auto close() noexcept

Attempts to close the file.

Returns: suspension_point The awaitable instance for closing the file. Async returns the success.

inline simple_future<std::vector<ReadType>> read_file() noexcept

Reads the entire files contents into a vector.

Returns: simple_future<std::vector<ReadType>>

inline auto read_some(std::int32_t _amount) noexcept

Reads up to _amount bytes of data from the file.

May read less then _amount bytes.

Parameters: _amount – The maximum amount to read.
Returns: suspension_point The awaitable instance for reading some data. Async returns the amount of bytes read.

inline auto read_some(std::span<ReadType> _data, std::int32_t _off_set = 0) noexcept

Reads up to _data - _off_set bytes of data from the file.

May read less then _data - _off_set bytes.

Parameters

_data – The buffer to read data into.
_off_set – The offset for where to read data into the buffer.

Returns

suspension_point The awaitable instance for reading some data. Async returns the amount of bytes read.

inline guaranteed_future<std::size_t> write_to_file(std::span<const ReadType> _data) noexcept

Write the content of _data to the file.

Only writes less then _data.size bytes if the write operation fails.

Parameters: _data – The buffer to write from.
Returns: guaranteed_future<std::size_t>

inline auto write_some(std::span<const ReadType> _data, std::int32_t _off_set = 0) noexcept

Writes up to _data.size() - _off_set bytes of data to the file.

May write less then _data - _off_set bytes without an error occuring.

Parameters

_data – The buffer to write data from.
_off_set – The offset for where to write data from the buffer.

Returns

suspension_point The awaitable instance for writing some data. Async returns the amount of bytes written.

inline bool position(std::size_t _pos, file::Offset _whence = file::Offset::kBegin) noexcept

Reset the poistion of the file cursor.

Parameters

_pos – [in] The amount to move.
_whence – [in] Where to move from.

Returns

true if successful, false otherwise.

inline std::size_t size()

Computes the size of the file.

Returns: std::size_t The size of the file.

inline bool good() const noexcept

Checks if there is an error pending on the file.

Returns: true if no error, false otherwise.

Public Static Functions

static inline auto relative_dir()

Dummy directory to specify the path is relative.

Returns: directory

static inline auto open(engine *_engine, const directory &_dir, std::string_view _path, int _flags, mode_t _mode = kDefaultMode)

Opens a file relative to the directory given.

Parameters

_engine – The engine to use.
directory – The directory.
_path – The relative path of the file.
_flags – The flags to apply.
_mode – The open mode.

Returns

suspension_point The awaitable instance for opening the file. Async returns the success.

static inline auto close(engine *_engine, int _fd) noexcept

Attempts to close the file.

Parameters

_engine – The engine to operate within.
_fd – The file descriptor to close.

Returns

suspension_point The awaitable instance for closing the file. Async returns the success.

static inline async_function close_in_background(engine *_engine, int _fd)

Attempts to close the file in the background.

Cannot report failures to the user.

Parameters

_engine – The engine to operate within.
_fd – The file descriptor to close.

Returns

async_function<> The async function that is running.

Public Static Attributes

static constexpr mode_t kDefaultMode = S_IRUSR | S_IWUSR: The default mode for opening files is user read/write.