io::BufferedWriter

The BufferedWriter is a helper class implementing io::IWriter allowing a buffered transfer of smaller slices using an io::IWriter which provides these buffers. Using a BufferedWriter only makes sense, if the chunks of data being transferred via this channel are much smaller compared to the maximum allocation size of this channel. A typical use case would be transmission of multiple 8-byte CAN frames via UDP packets of e.g. 1400 bytes.

Properties

• Internally the BufferedWriter manages slices of destination.maxSize() bytes and provides subslices of it to the user.

• Call to flush() required to commit currently buffered data.

• Memory consumption: sizeof(::io::IWriter&) + sizeof(::estd::slice<uint8_t>) + sizeof(size_t)

Public API

The public API of BufferedWriter consists of a constructor and the inherited IWriter API:

/**
 * Constructs a BufferedWriter from a given IWriter destination.
 */
explicit BufferedWriter(IWriter& destination);

/**
 * \see IWriter::maxSize()
 */
size_t maxSize() const override;

/**
 * Allocates a slice of bytes of a given size.
 *
 * If not enough memory is available in the current buffer, it will be flushed and a
 * new allocation of destination.maxSize() bytes will be done.
 *
 * \param size  Number of bytes to allocate from this BufferedWriter.
 * \return  - Empty slice, if requested size was greater as MAX_ELEMENT_SIZE or no memory
 *            is available
 *          - Slice of bytes otherwise.
 */
::estd::slice<uint8_t> allocate(size_t size) override;

/**
 * Commits the previously allocated data. It is not guaranteed that this data is immediately
 * available to the reader as a call to flush() might be required for that.
 */
void commit() override;

/**
 * Commits the data currently written to slice allocated from destination making it available to
 * the reader.
 */
void flush() override;

Usage example

Here is an example:

class CanFrameForwarder
{
    ::io::IReader& _canFrameInput;
    ::io::BufferedWriter _udpOutput;

public:
    CanFrameForwarder(::io::IReader& canFrameInput, ::io::IWriter& udpOutput)
    : _canFrameInput(canFrameInput), _udpOutput(udpOutput)
    {}

    void operator()()
    {
        // Input format is: uint32_t id, payload.
        ::estd::slice<uint8_t const> frame = _canFrameInput.peek();
        while (frame.size() > 0)
        {
            // Output format is uint8_t size, uint32_t id, payload
            ::estd::slice<uint8_t> dst = _udpOutput.allocate(frame.size() + 1);
            if (dst.size() == 0)
            {
                break;
            }
            // Format: uint8_t payload length, uint32_t id, payload
            ::estd::memory::take<uint8_t>(dst) = frame.size();
            ::estd::memory::copy(dst, frame);
            _udpOutput.commit();
            _canFrameInput.release();
            frame = _canFrameInput.peek();
        }
        _udpOutput.flush();
    }
};

/**
 * This usage example demonstrates how to read small input slices of bytes and accumulate them,
 * using a BufferedWriter into a writer that support much larger allocations.
 */
TEST(BufferedWriter, UsageExample)
{
    using CanQueue = ::io::MemoryQueue<1024, 12>;
    using UdpQueue = ::io::MemoryQueue<10240, 1400>;
    // Create output channel.
    UdpQueue outputQueue;
    ::io::MemoryQueueWriter<UdpQueue> output{outputQueue};
    ::io::BufferedWriter udpWriter{output};
    // Create input channel.
    CanQueue inputQueue;
    ::io::MemoryQueueReader<CanQueue> input{inputQueue};

    CanFrameForwarder canFrameForwarder{input, udpWriter};

    // Call this cyclically
    canFrameForwarder();
}