cuddl::detail::file_writer Class Reference

Writes a file from a thread of its own, so the caller produces the next bytes while earlier ones reach storage. More...

#include <file_writer.hpp>

Public Member Functions
	file_writer (std::filesystem::path const &path, bool durable, size_t queued_limit=size_t{1}<< 30)
	file_writer (file_writer const &)=delete
file_writer &	operator= (file_writer const &)=delete
	~file_writer ()
	Stops writing without flushing; finish reports whether every byte arrived.
std::span< char >	reserve (size_t bytes)
	Space for the next bytes of the file, for the caller to fill and then hand back with commit, sparing append's copy.
void	commit ()
	Queues the bytes of the last reserve.
void	append (std::initializer_list< std::span< char const > > chunks)
	Copies chunks, which reach the file together and in order; waits while the queued bytes reach the limit.
void	append (std::span< char const > bytes)
void	finish ()
	Writes everything appended and closes the file, flushing it to storage first if durable.
bool	direct () const noexcept
	Whether writes bypass the page cache.
bool	asynchronous () const noexcept
	Whether writes go through io_uring.

Static Public Attributes
static constexpr size_t	block_bytes = size_t{8} << 20
static constexpr unsigned	depth = 4
	Writes in flight with io_uring.
static constexpr size_t	probe_window = size_t{64} << 20
	Bytes timed per route before a writer that need not be durable picks one; it leaves the page cache only after 16 such windows through it ran too slow.

Detailed Description

Writes a file from a thread of its own, so the caller produces the next bytes while earlier ones reach storage.

Bytes are copied into page-aligned memory by append, or produced there in place through reserve, and written with O_DIRECT in requests of up to 8 MiB, bypassing the page cache. Buffered writes stall in page-cache copies and writeback: on a Samsung 9100 PRO, one buffered stream plus fsync wrote 2.4-3.1 GB/s and O_DIRECT 8 MiB writes 12.9-13.6 GB/s, the drive's rated 13.4 GB/s; 1 MiB writes reached only 9.1-9.7 GB/s. There the copy itself, 11 GB/s on one core, held a 159 GB all-to-all output below the drive. Where io_uring is available, four requests are in flight at once: on a btrfs file system that wrote 2.9-4.4 GB/s against 1.9-2.6 GB/s for synchronous writes. Elsewhere one request is written at a time, which on ext4 already reached the drive's rate.

File systems without O_DIRECT (tmpfs) and network file systems get buffered writes: direct writes to Lustre wait for the server on every request (8 streams reached 28 MB/s).

Definition at line 49 of file file_writer.hpp.

Constructor & Destructor Documentation

file_writer() [1/2]

cuddl::detail::file_writer::file_writer ( std::filesystem::path const &  path, bool  durable, size_t  queued_limit = size_t{1} << 30  )

inline

Parameters

durable	Whether finish flushes the file to storage before returning.
queued_limit	Bytes reserved or appended but not yet written before reserve and append wait; a larger reservation waits only for all but one other.

Definition at line 61 of file file_writer.hpp.

                                    {1} << 30
    )
        : path_(path), queued_limit_(queued_limit), durable_(durable) {
        int const flags = O_WRONLY | O_CREAT | O_TRUNC | O_CLOEXEC;
        fd_ = ablated("direct-io") ? -1 : ::open(path.c_str(), flags | O_DIRECT, 0644);
        direct_ = fd_ != -1;
        if (fd_ == -1) fd_ = ::open(path.c_str(), flags, 0644);
        if (fd_ == -1) fail("cannot write");
        struct statfs status{};
        // shortcut: NFS and Lustre only, the network file systems we run on; add others as met.
        if (direct_ && ::fstatfs(fd_, &status) == 0 &&
            (status.f_type == 0x6969 || status.f_type == 0x0BD00BD0)) {
            if (::fcntl(fd_, F_SETFL, ::fcntl(fd_, F_GETFL) & ~O_DIRECT) == -1) {
                ::close(fd_);
                fail("cannot write");
            }
            direct_ = false;
        }
        // Buffered writes through io_uring would run concurrently on kernel workers, and several
        // writers into one Lustre file were far slower than one.
        if (direct_ && !ablated("io-uring")) ring_ = io_ring::make(depth);
        // A drive slower than the page cache leaves a run that need not be durable waiting on
        // direct writes the cache could absorb: 159 GB to a PM9A3 took 108-158 s direct and
        // 60-97 s buffered. Such writers time both routes and keep the faster; see work().
        if (direct_ && !durable_ && !ablated("write-probe")) {
            buffered_fd_ = ::open(path.c_str(), O_WRONLY | O_CLOEXEC);
            if (buffered_fd_ == -1) fail("cannot write");
            // btrfs compresses page-cache writes during writeback, never direct ones; with zstd
            // a buffered 120 GB run took 58.5 s compressed and 45.8 s not. Other file systems
            // refuse or ignore the flag.
            int attributes = 0;
            if (::ioctl(fd_, FS_IOC_GETFLAGS, &attributes) == 0) {
                attributes |= FS_NOCOMP_FL;
                static_cast<void>(::ioctl(fd_, FS_IOC_SETFLAGS, &attributes));
            }
        }
        thread_ = std::thread([this] { work(); });
    }

file_writer() [2/2]

cuddl::detail::file_writer::file_writer ( file_writer const &  )

delete

~file_writer()

cuddl::detail::file_writer::~file_writer ( )

inline

Stops writing without flushing; finish reports whether every byte arrived.

Definition at line 105 of file file_writer.hpp.

                   {
        stop();
        if (fd_ != -1) ::close(fd_);
        if (buffered_fd_ != -1) ::close(buffered_fd_);
    }

Member Function Documentation

append() [1/2]

void cuddl::detail::file_writer::append ( std::initializer_list< std::span< char const > >  chunks )

inline

Copies chunks, which reach the file together and in order; waits while the queued bytes reach the limit.

Throws if an earlier write failed.

Definition at line 133 of file file_writer.hpp.

                                                                 {
        size_t bytes = 0;
        for (auto const& chunk : chunks) bytes += chunk.size();
        auto* out = reserve(bytes).data();
        for (auto const& chunk : chunks) {
            if (!chunk.empty()) std::memcpy(out, chunk.data(), chunk.size());
            out += chunk.size();
        }
        commit();
    }

Here is the call graph for this function:

Here is the caller graph for this function:

append() [2/2]

void cuddl::detail::file_writer::append ( std::span< char const >  bytes )

inline

Definition at line 144 of file file_writer.hpp.

                                           {
        append({bytes});
    }

Here is the call graph for this function:

asynchronous()

bool cuddl::detail::file_writer::asynchronous ( ) const

inlinenoexcept

Whether writes go through io_uring.

Definition at line 180 of file file_writer.hpp.

                                                     {
        return ring_ != nullptr;
    }

commit()

void cuddl::detail::file_writer::commit ( )

inline

Queues the bytes of the last reserve.

A direct write covers whole sectors, so the last partial sector waits for the next bytes.

Definition at line 126 of file file_writer.hpp.

                  {
        queue_current(false);
        reservation_.unlock();
    }

Here is the caller graph for this function:

direct()

bool cuddl::detail::file_writer::direct ( ) const

inlinenoexcept

Whether writes bypass the page cache.

Definition at line 175 of file file_writer.hpp.

                                               {
        return direct_;
    }

finish()

void cuddl::detail::file_writer::finish ( )

inline

Writes everything appended and closes the file, flushing it to storage first if durable.

Bytes left in the page cache otherwise reach storage after the caller moves on, as with any buffered write.

Definition at line 151 of file file_writer.hpp.

                  {
        uint64_t size = 0;
        {
            reserve(0);
            size = offset_ + carry_bytes_;
            queue_current(true);
            reservation_.unlock();
        }
        {
            std::unique_lock lock(mutex_);
            space_.wait(lock, [&] { return failed_ != 0 || (queue_.empty() && in_flight_ == 0); });
        }
        stop();
        int error = failed_;
        if (error == 0 && direct_ && ::ftruncate(fd_, static_cast<off_t>(size)) != 0) error = errno;
        if (error == 0 && durable_ && ::fsync(fd_) != 0) error = errno;
        if (::close(fd_) != 0 && error == 0) error = errno;
        fd_ = -1;
        if (buffered_fd_ != -1 && ::close(buffered_fd_) != 0 && error == 0) error = errno;
        buffered_fd_ = -1;
        if (error != 0) fail("cannot write", error);
    }

Here is the call graph for this function:

operator=()

file_writer & cuddl::detail::file_writer::operator= ( file_writer const &  )

delete

reserve()

std::span< char > cuddl::detail::file_writer::reserve ( size_t  bytes )

inline

Space for the next bytes of the file, for the caller to fill and then hand back with commit, sparing append's copy.

Waits while the queued bytes reach the limit; throws if an earlier write failed. One reservation at a time.

Definition at line 114 of file file_writer.hpp.

                                        {
        std::unique_lock lock(append_mutex_);
        auto const total = carry_bytes_ + bytes;
        current_ = take_extent((total + 4095) / 4096 * 4096);
        std::memcpy(current_->data.get(), carry_.data(), carry_bytes_);
        reserved_ = bytes;
        reservation_ = std::move(lock);
        return {current_->data.get() + carry_bytes_, bytes};
    }

Here is the caller graph for this function:

Member Data Documentation

block_bytes

constexpr size_t cuddl::detail::file_writer::block_bytes = size_t{8} << 20

staticconstexpr

Definition at line 51 of file file_writer.hpp.

{8} << 20;

depth

constexpr unsigned cuddl::detail::file_writer::depth = 4

staticconstexpr

Writes in flight with io_uring.

Definition at line 53 of file file_writer.hpp.

probe_window

constexpr size_t cuddl::detail::file_writer::probe_window = size_t{64} << 20

staticconstexpr

Bytes timed per route before a writer that need not be durable picks one; it leaves the page cache only after 16 such windows through it ran too slow.

Definition at line 56 of file file_writer.hpp.

{64} << 20;

---

The documentation for this class was generated from the following file:

• file_writer.hpp