io::SplitWriter

The SplitWriter is an adapter class implementing io::IWriter. It takes multiple writers and provides one unified interface to them writing a copy of the committed data to each of them. This is useful for connection e.g. one input channel to multiple output channels.

Properties

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

Template Parameters

SplitWriter is a class template with the following parameters:

 * \tparam N Number of IWriter this SplitWriter wraps.

Public API

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

/**
 * Constructs a SplitWriter from an array of IWriter destinations.
 *
 * \assert destinations[0..N-1] != nullptr
 * \assert destinations[0]->maxSize() == destinations[1]->maxSize() ... ==
 * destinations[N-1]->maxSize()
 */
explicit SplitWriter(::estd::slice<IWriter*, N> destinations);

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

/**
 * Allocates a slice of bytes of a given size from the first queue that has free space
 *
 * \param size  Number of bytes to allocate
 * \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 to all destinations. If a destination is not
 * capable of receiving the data, the corresponding drop counter is increased. If the
 * data has been committed successfully, the corresponding sent counter is increased.
 */
void commit() override;

/**
 * Empty function, nothing special to do for flushing to the other end.
 */
void flush() override;

Usage Example

The following example shows a simplified usage of SplitWriter:

/**
 * Forwards all data from an IReader to an IWriter basically connecting them.
 * \param source    IReader acting as source of the connection.
 * \param destination    IWriter acting as destination of the connection.
 *
 * This function will forward one slice of data when being called. If data is available
 * from the source but no space is available in the destination, the source data will be kept
 * and retried when the function is called the next time.
 */
void forwardData(::io::IReader& source, ::io::IWriter& destination)
{
    auto const srcData = source.peek();
    if (srcData.size() > 0)
    {
        auto dstData = destination.allocate(srcData.size());
        if (dstData.size() >= srcData.size())
        {
            ::estd::memory::copy(dstData, srcData);
            destination.commit();
            // Only release data after successful forwarding.
            source.release();
        }
    }
}

/**
 * This usage example demonstrates how to forward data from one reader to two writers. It
 * focuses on the setup and forwarding not on how the actual data is put into the queues or
 * read from it.
 */
TEST(SplitWriter, UsageExample)
{
    using Queue = ::io::MemoryQueue<1024, 16>;
    // Create two output queues.
    Queue q1;
    Queue q2;
    io::MemoryQueueWriter<Queue> w1{q1};
    io::MemoryQueueWriter<Queue> w2{q2};
    ::io::IWriter* writers[2] = {&w1, &w2};
    ::io::SplitWriter<2> w{writers};

    // Create input queue
    Queue q3;
    io::MemoryQueueReader<Queue> r3{q3};

    // ...

    // This function can be called cyclically to forward data from q3 to q1 and q2.
    forwardData(r3, w);
}