io::JoinReader

The JoinReader is an adapter class implementing io::IReader. It takes multiple readers and provides one unified interface to them. This is useful for connection e.g. multiple input channels with one output channel.

Properties

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

Template Parameters

JoinReader is a class template with the following parameters:

 * \tparam N Number of IReaders this JoinReader wraps.

Public API

The public API of JoinReader consists of a constructor and the inherited io::IReader API:

/**
 * Constructs a JoinReader from an array of IReader sources.
 *
 * \param sources   Slice of pointers (must not be nullptr) to IReader.
 *
 * \assert sources[0..N-1] != nullptr
 * \assert sources[0]->maxSize() == sources[1]->maxSize() ... == sources[N-1]->maxSize()
 */
explicit JoinReader(::estd::slice<IReader*, N> const& sources);

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

/**
 * Returns a slice to the next piece of available data.
 *
 * The strategy used is a form of round-robin, where one element is returned from each queue
 * in turn.
 * Note that the same element will keep getting returned until release() is called.
 *
 * \return - Slice of bytes if one of the underlying queues was not empty
 *         - Empty slice otherwise
 */
::estd::slice<uint8_t> peek() const override;

/**
 * \see ::io::IReader::release()
 */
void release() override;

Usage Example

The following example shows a simplified usage of JoinReader:

/**
 * 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 two readers to one writer. It
 * focuses on the setup and forwarding not on how the actual data is put into the queues or
 * read from it.
 */
TEST(JoinReader, UsageExample)
{
    using Queue = ::io::MemoryQueue<1024, 16>;
    // Create two input queues.
    Queue q1;
    Queue q2;
    io::MemoryQueueReader<Queue> r1{q1};
    io::MemoryQueueReader<Queue> r2{q2};
    ::io::IReader* readers[2] = {&r1, &r2};
    ::io::JoinReader<2> r{readers};

    // Create output queue
    Queue q3;
    io::MemoryQueueWriter<Queue> w3{q3};

    // ...

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