queue_spsc_locked

See Locked Queues

This class is designed to be a more generally useful version of etl::queue_spsc_isr and can replace it.

A fixed capacity single-producer, single-consumer queue, generally used to transfer data to or from an ISR.

Calls from the 'unlocked' thread of execution (ISR) must use the _from_unlocked versions.

Helper functions must be supplied at construction that lock (disable) and unlock (enable) the relevant ISR.

They are passed as const references to etl::ifunction<void>.

They must perform the requisite memory barriers to preserve the order of execution.

Many functions have two versions. One locks and unlocks access and is used from the foreground task (non-ISR). The

other, with a _from_unlocked suffix, are called from the ISR.

etl::queue_spsc_locked<typename T,

const size_t SIZE,

const size_t MEMORY_MODEL = etl::memory_model::MEMORY_MODEL_LARGE>

Inherits from etl::iqueue_spsc_locked<T, const size_t MEMORY_MODEL>

etl::iqueue_spsc_locked may be used as a size independent pointer or reference type for any

etl::queue_spsc_locked instance of the same implementation.

The memory model determines the type used internally for indexes and size, to allow for the most efficient

implementation for the application.

Maximum queue sizes:

MEMORY_MODEL_SMALL 255

MEMORY_MODEL_MEDIUM 65535

MEMORY_MODEL_LARGE 2147483647

MEMORY_MODEL_HUGE 9223372036854775807

See memory_model.h

____________________________________________________________________________________________________

Member types

value_type T

size_type <based on memory model>

pointer value_type*

const_pointer const value_type*

reference value_type&

const_reference const value_type&

____________________________________________________________________________________________________

Constructor

queue_spsc_locked(const etl::ifunction<void>& lock, const etl::ifunction<void>& unlock);

____________________________________________________________________________________________________

Capacity

bool empty() const

bool empty_from_unlocked() const

Returns true if the size of the queue is zero, otherwise false.

____________________________________________________________________________________________________

bool full() const

bool full_from_unlocked() const

Returns true if the size of the queue is SIZE, otherwise false.

____________________________________________________________________________________________________

size_type size() const

size_type size_from_unlocked() const

Returns the size of the queue.

____________________________________________________________________________________________________

size_type available() const

size_type available_from_unlocked() const

Returns the remaining available capacity in the queue.

____________________________________________________________________________________________________

size_type max_size() const

Returns the maximum possible size of the queue.

____________________________________________________________________________________________________

size_type capacity() const

Returns the maximum possible size of the queue.

____________________________________________________________________________________________________

Modifiers

bool push(const T& value);

bool push(T&& value);

bool push_from_locked(const T& value);

bool push_from_locked(T&& value);

Pushes a value to the back of the queue.

Returns true if successful, otherwise false.

____________________________________________________________________________________________________

bool pop();

bool pop_from_unlocked();

Pop a value from the front of the list.

Returns true if successful, otherwise false.

____________________________________________________________________________________________________

bool pop(T& value);

bool pop_from_locked(T& value);

bool pop(T&& value);

bool pop_from_locked(T&& value);

Pop a value from the front of the list and place it in value.

Returns true if successful, otherwise false.

____________________________________________________________________________________________________

void clear();

void clear_from_unlocked();

Clears the queue to a size of zero.

____________________________________________________________________________________________________

C++03

bool emplace(const T1& value1);

bool emplace(const T1& value1, const T2& value2);

bool emplace(const T1& value1, const T2& value2, const T3& value3);

bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4);

C++11

bool emplace(Args&&… args);

Constructs an item in the the queue 'in place'.

C++03: Supports up to four constructor parameters.

____________________________________________________________________________________________________

Notes

Remember that interrupts may occur between calls to the access protected functions. For example, a call to empty()

may return true, but a subsequent call to pop() may succeed if an interrupt occurred between the two and pushed a

new value.

Example

class InterruptControl

{

public:

void lock()

{

// Store current interrupt control register and disable the relevant interrupt.

}

void unlock()

{

// Restore the interrupt control register.

}

};

InterruptControl interruptControl;

// Create function wrappers with direct calls to the instance's member functions.

etl::function_imv<InterruptControl, interruptControl, &InterruptControl::lock> lock;

etl::function_imv<InterruptControl, interruptControl, &InterruptControl::unlock> unlock;

etl::queue_spsc_locked<char, 10> queue(lock, unlock);

int main()

{

while (true)

{

char c;

if (queue.pop(c))

{

Print(c);

}

void ISR(char c)

{

queue.push_from_unlocked(c);

}

queue_spsc_locked.h