template class Poco::BasicFIFOBuffer

Overview

A simple buffer class with support for re-entrant, FIFO-style read/write operations, as well as (optional) empty/non-empty/full (i.e. More…

#include <FIFOBuffer.h>

template <class T>
class BasicFIFOBuffer
{
public:
    // typedefs

    typedef T Type;

    // fields

    Poco::BasicEvent<bool> writable;
    Poco::BasicEvent<bool> readable;

    // construction

    BasicFIFOBuffer(
        std::size_t size,
        bool notify = false
        );

    BasicFIFOBuffer(
        T* pBuffer,
        std::size_t size,
        bool notify = false
        );

    BasicFIFOBuffer(
        const T* pBuffer,
        std::size_t size,
        bool notify = false
        );

    // methods

    void
    resize(
        std::size_t newSize,
        bool preserveContent = true
        );

    std::size_t
    peek(
        T* pBuffer,
        std::size_t length
        ) const;

    std::size_t
    peek(
        Poco::Buffer<T>& buffer,
        std::size_t length = 0
        ) const;

    std::size_t
    read(
        T* pBuffer,
        std::size_t length
        );

    std::size_t
    read(
        Poco::Buffer<T>& buffer,
        std::size_t length = 0
        );

    std::size_t
    write(
        const T* pBuffer,
        std::size_t length
        );

    std::size_t
    write(
        const Buffer<T>& buffer,
        std::size_t length = 0
        );

    std::size_t
    size() const;

    std::size_t
    used() const;

    std::size_t
    available() const;

    void
    drain(std::size_t length = 0);

    void
    copy(
        const T* ptr,
        std::size_t length
        );

    void
    advance(std::size_t length);

    T*
    begin();

    T*
    next();

    T&
    operator[](std::size_t index);

    const T&
    operator[](std::size_t index) const;

    const Buffer<T>&
    buffer() const;

    void
    setError(bool error = true);

    bool
    isValid() const;

    void
    setEOF(bool eof = true);

    bool
    hasEOF() const;

    bool
    isEOF() const;

    bool
    isEmpty() const;

    bool
    isFull() const;

    bool
    isReadable() const;

    bool
    isWritable() const;

    void
    setNotify(bool notify = true);

    bool
    getNotify() const;

    Mutex&
    mutex();
};

Detailed Documentation

A simple buffer class with support for re-entrant, FIFO-style read/write operations, as well as (optional) empty/non-empty/full (i.e.

writable/readable) transition notifications. Buffer can be flagged with end-of-file and error flags, which renders it un-readable/writable.

Critical portions of code are protected by a recursive mutex. However, to achieve thread-safety in cases where multiple member function calls are involved and have to be atomic, the mutex must be locked externally.

Buffer size, as well as amount of unread data and available space introspections are supported as well.

This class is useful anywhere where a FIFO functionality is needed.

Fields

Poco::BasicEvent<bool> writable

Event indicating “writability” of the buffer, triggered as follows:

when buffer transitions from non-full to full,

Writable event observers are notified, with
false value as the argument

when buffer transitions from full to non-full,

Writable event observers are notified, with
true value as the argument

Poco::BasicEvent<bool> readable

Event indicating “readability” of the buffer, triggered as follows:

when buffer transitions from non-empty to empty,

Readable event observers are notified, with false
value as the argument

when FIFOBuffer transitions from empty to non-empty,

Readable event observers are notified, with true value
as the argument

Construction

~BasicFIFOBuffer()

Destroys the FIFOBuffer.

Methods

void
resize(
    std::size_t newSize,
    bool preserveContent = true
    )

Resizes the buffer.

If preserveContent is true, the content of the old buffer is preserved. New size can be larger or smaller than the current size, but it must not be 0. Additionally, if the new length is smaller than currently used length and preserveContent is true, InvalidAccessException is thrown.

std::size_t
peek(
    T* pBuffer,
    std::size_t length
    ) const

Peeks into the data currently in the FIFO without actually extracting it.

If length is zero, the return is immediate. If length is greater than used length, it is substituted with the the current FIFO used length.

Returns the number of elements copied in the supplied buffer.

std::size_t
peek(
    Poco::Buffer<T>& buffer,
    std::size_t length = 0
    ) const

Peeks into the data currently in the FIFO without actually extracting it.

Resizes the supplied buffer to the size of data written to it. If length is not supplied by the caller or is greater than length of currently used data, the current FIFO used data length is substituted for it.

Returns the number of elements copied in the supplied buffer.

std::size_t
read(
    T* pBuffer,
    std::size_t length
    )

Copies the data currently in the FIFO into the supplied buffer, which must be preallocated to at least the length size before calling this function.

Returns the size of the copied data.

std::size_t
read(
    Poco::Buffer<T>& buffer,
    std::size_t length = 0
    )

Copies the data currently in the FIFO into the supplied buffer.

Resizes the supplied buffer to the size of data written to it.

Returns the size of the copied data.

std::size_t
write(
    const T* pBuffer,
    std::size_t length
    )

Writes data from supplied buffer to the FIFO buffer.

If there is no sufficient space for the whole buffer to be written, data up to available length is written. The length of data to be written is determined from the length argument. Function does nothing and returns zero if length argument is equal to zero.

Returns the length of data written.

std::size_t
write(
    const Buffer<T>& buffer,
    std::size_t length = 0
    )

Writes data from supplied buffer to the FIFO buffer.

If there is no sufficient space for the whole buffer to be written, data up to available length is written. The length of data to be written is determined from the length argument or buffer size (when length argument is default zero or greater than buffer size).

Returns the length of data written.

std::size_t
size() const

Returns the size of the buffer.

std::size_t
used() const

Returns the size of the used portion of the buffer.

std::size_t
available() const

Returns the size of the available portion of the buffer.

void
drain(std::size_t length = 0)

Drains length number of elements from the buffer.

If length is zero or greater than buffer current content length, buffer is emptied.

void
copy(
    const T* ptr,
    std::size_t length
    )

Copies the supplied data to the buffer and adjusts the used buffer size.

void
advance(std::size_t length)

Advances buffer by length elements.

Should be called AFTER the data was copied into the buffer.

T*
begin()

Returns the pointer to the beginning of the buffer.

T*
next()

Returns the pointer to the next available position in the buffer.

T&
operator[](std::size_t index)

Returns value at index position.

Throws InvalidAccessException if index is larger than the last valid (used) buffer position.

const T&
operator[](std::size_t index) const

Returns value at index position.

Throws InvalidAccessException if index is larger than the last valid (used) buffer position.

const Buffer<T>&
buffer() const

Returns const reference to the underlying buffer.

void
setError(bool error = true)

Sets the error flag on the buffer and empties it.

If notifications are enabled, they will be triggered if appropriate.

Setting error flag to true prevents reading and writing to the buffer; to re-enable FIFOBuffer for reading/writing, the error flag must be set to false.

bool
isValid() const

Returns true if error flag is not set on the buffer, otherwise returns false.

void
setEOF(bool eof = true)

Sets end-of-file flag on the buffer.

Setting EOF flag to true prevents writing to the buffer; reading from the buffer will still be allowed until all data present in the buffer at the EOF set time is drained. After that, to re-enable FIFOBuffer for reading/writing, EOF must be set to false.

Setting EOF flag to false clears EOF state if it was previously set. If EOF was not set, it has no effect.

bool
hasEOF() const

Returns true if EOF flag has been set.

bool
isEOF() const

Returns true if EOF flag has been set and buffer is empty.

bool
isEmpty() const

Returns true is buffer is empty, false otherwise.

bool
isFull() const

Returns true is buffer is full, false otherwise.

bool
isReadable() const

Returns true if buffer contains data and is not in error state.

bool
isWritable() const

Returns true if buffer is not full and is not in error state.

void
setNotify(bool notify = true)

Enables/disables notifications.

bool
getNotify() const

Returns true if notifications are enabled, false otherwise.

Mutex&
mutex()

Returns reference to mutex.

Table of Contents

Previous topic

Next topic