Poco

template < class T >

class BasicFIFOBuffer

Library: Foundation
Package: Core
Header: Poco/FIFOBuffer.h

Description

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 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.

Member Summary

Member Functions: advance, available, begin, buffer, copy, drain, getNotify, isEmpty, isFull, next, operator [], peek, read, resize, setNotify, size, used, write

Types

Type

typedef T Type;

Constructors

BasicFIFOBuffer inline

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

Creates the FIFOBuffer.

BasicFIFOBuffer inline

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

Creates the FIFOBuffer.

BasicFIFOBuffer inline

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

Creates the FIFOBuffer.

Destructor

~BasicFIFOBuffer inline

~BasicFIFOBuffer();

Destroys the FIFOBuffer.

Member Functions

advance inline

void advance(
    std::size_t length
);

Advances buffer by length elements. Should be called AFTER the data was copied into the buffer.

available inline

std::size_t available() const;

Returns the size of the available portion of the buffer.

begin inline

T * begin();

Returns the pointer to the beginning of the buffer.

buffer inline

const Buffer < T > & buffer() const;

Returns const reference to the underlying buffer.

copy inline

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

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

drain inline

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.

getNotify inline

bool getNotify() const;

Returns true if notifications are enabled, false otherwise.

isEmpty inline

bool isEmpty() const;

Returns true is buffer is empty, flase otherwise.

isFull inline

bool isFull() const;

Returns true is buffer is full, false otherwise.

next inline

T * next();

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

operator [] inline

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

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

operator [] inline

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.

peek inline

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.

peek inline

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.

read inline

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

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 reference to the buffer.

read inline

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 reference to the buffer.

resize inline

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.

setNotify inline

void setNotify(
    bool notify = true
);

Enables/disables notifications.

size inline

std::size_t size() const;

Returns the size of the buffer.

used inline

std::size_t used() const;

Returns the size of the used portion of the buffer.

write inline

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.

write inline

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.

Variables

readable

mutable 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

writable

mutable 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