Transfer Algorithms

This section explains the composed read/write operations and transfer algorithms.

Prerequisites

Composed Read/Write

The partial operations (read_some, write_some) often require looping. Capy provides composed operations that handle the loops for you.

read

Fills a buffer completely by looping read_some:

#include <boost/capy/read.hpp>

template<ReadStream Stream, MutableBufferSequence Buffers>
task<std::pair<error_code, std::size_t>>
read(Stream& stream, Buffers const& buffers);

Keeps reading until:

  • Buffer is full (n == buffer_size(buffers))

  • EOF is reached (returns cond::eof with partial count)

  • Error occurs (returns error with partial count)

Example:

char buf[1024];
auto [ec, n] = co_await read(stream, mutable_buffer(buf));
// n == 1024, or ec indicates why not

read with DynamicBuffer

Reads until EOF into a growable buffer:

template<ReadStream Stream, DynamicBuffer Buffer>
task<std::pair<error_code, std::size_t>>
read(Stream& stream, Buffer&& buffer);

Example:

flat_dynamic_buffer buf;
auto [ec, n] = co_await read(stream, buf);
// buf now contains all data until EOF

write

Writes all data by looping write_some:

#include <boost/capy/write.hpp>

template<WriteStream Stream, ConstBufferSequence Buffers>
task<std::pair<error_code, std::size_t>>
write(Stream& stream, Buffers const& buffers);

Keeps writing until:

  • All data is written (n == buffer_size(buffers))

  • Error occurs (returns error with partial count)

Example:

co_await write(stream, make_buffer("Hello, World!"));

Transfer Algorithms

Transfer algorithms move data between sources/sinks and streams.

push_to

Transfers data from a BufferSource to a destination:

#include <boost/capy/io/push_to.hpp>

// To WriteSink (with EOF propagation)
template<BufferSource Source, WriteSink Sink>
task<std::pair<error_code, std::size_t>>
push_to(Source& source, Sink& sink);

// To WriteStream (streaming, no EOF)
template<BufferSource Source, WriteStream Stream>
task<std::pair<error_code, std::size_t>>
push_to(Source& source, Stream& stream);

The source provides buffers via pull(). Data is pushed to the destination. Buffer ownership stays with the source—no intermediate copying when possible.

Example:

// Transfer file to network
mmap_source file("large_file.bin");
co_await push_to(file, socket);

pull_from

Transfers data from a source to a BufferSink:

#include <boost/capy/io/pull_from.hpp>

// From ReadSource
template<ReadSource Source, BufferSink Sink>
task<std::pair<error_code, std::size_t>>
pull_from(Source& source, Sink& sink);

// From ReadStream (streaming)
template<ReadStream Stream, BufferSink Sink>
task<std::pair<error_code, std::size_t>>
pull_from(Stream& stream, Sink& sink);

The sink provides writable buffers via prepare(). Data is pulled from the source directly into the sink’s buffers.

Example:

// Receive network data into compression buffer
compression_sink compressor;
co_await pull_from(socket, compressor);

Why No buffer-to-buffer?

There is no push_to(BufferSource, BufferSink) because it would require redundant copying. The source owns read-only buffers; the sink owns writable buffers. Transferring between them would need an intermediate copy, defeating the zero-copy purpose.

Instead, compose with an intermediate stage:

// Transform: BufferSource → processing → BufferSink
task<> process_pipeline(any_buffer_source& source, any_buffer_sink& sink)
{
    const_buffer src_bufs[8];

    while (true)
    {
        auto [ec, count] = co_await source.pull(src_bufs, 8);
        if (count == 0)
            break;

        for (std::size_t i = 0; i < count; ++i)
        {
            auto processed = transform(src_bufs[i]);

            // Write processed data to sink
            mutable_buffer dst_bufs[8];
            std::size_t dst_count = sink.prepare(dst_bufs, 8);

            std::size_t copied = buffer_copy(
                std::span(dst_bufs, dst_count),
                make_buffer(processed));

            co_await sink.commit(copied);
        }
    }

    co_await sink.commit_eof();
}

Naming Convention

The algorithm names reflect buffer ownership:

Name Meaning

push_to

Source provides buffers → push data to destination

pull_from

Sink provides buffers → pull data from source

The preposition indicates the direction of buffer provision, not data flow.

Error Handling

All transfer algorithms return (error_code, std::size_t):

  • error_code — Success, EOF, or error condition

  • std::size_t — Total bytes transferred before return

On error, partial transfer may have occurred. The returned count indicates how much was transferred.

Example:

auto [ec, total] = co_await push_to(source, sink);

if (ec == cond::eof)
{
    // Normal completion
    std::cout << "Transferred " << total << " bytes\n";
}
else if (ec.failed())
{
    // Error occurred
    std::cerr << "Error after " << total << " bytes: " << ec.message() << "\n";
}

Reference

Header Description

<boost/capy/read.hpp>

Composed read operations

<boost/capy/write.hpp>

Composed write operations

<boost/capy/io/push_to.hpp>

BufferSource → WriteSink/WriteStream transfer

<boost/capy/io/pull_from.hpp>

ReadSource/ReadStream → BufferSink transfer

You have now learned about transfer algorithms. Continue to Physical Isolation to learn how type erasure enables compilation firewalls.

Edit this Page