Stroika::Foundation::Execution::BlockingQueue< T > Class Template Reference

#include <BlockingQueue.h>

Public Member Functions
nonvirtual void	AddTail (const T &e, Time::DurationSeconds timeout=Time::kInfinity)
nonvirtual void	SignalEndOfInput ()
nonvirtual bool	EndOfInputHasBeenQueued () const
nonvirtual bool	QAtEOF () const
nonvirtual T	RemoveHead (Time::DurationSeconds timeout=Time::kInfinity)
nonvirtual optional< T >	RemoveHeadIfPossible (Time::DurationSeconds timeout=0s)
nonvirtual optional< T >	PeekHead () const
nonvirtual bool	empty () const
nonvirtual size_t	size () const
nonvirtual size_t	length () const
nonvirtual Containers::Queue< T >	GetQueue () const

Detailed Description

template<typename T>
class Stroika::Foundation::Execution::BlockingQueue< T >

SEE http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/BlockingQueue.html

                Throws exception    Special value       Blocks              Times out

Insert add(e) offer(e) put(e) offer(e, time, unit) Remove remove() poll() take() poll(time, unit) Examine Front() peek() not applicable not applicable

Note

Thread-Safety Internally-Synchronized-Thread-Safety

Example Usage (RegressionTest10_BlockingQueue_)

enum { START = 0, END = 100 };
int expectedValue = (START + END) * (END - START + 1) / 2;
int counter =   0;
BlockingQueue<function<void()>> q;
 
Verify (q.size () == 0);
 
Thread::Ptr  producerThread = Thread::New (
    [&q, &counter] () {
        for (int incBy = START; incBy <= END; ++incBy) {
            q.AddTail ([&counter, incBy] () { counter += incBy; });
        }
        q.SignalEndOfInput ();
    },
    Thread::eAutoStart,
    "Producer"_k
);
Thread::Ptr  consumerThread = Thread::New (
    [&q] () {
        while (true) {
            function<void()>    f   =   q.RemoveHead ();
            f();
        }
    },
    Thread::eAutoStart,
    "Consumer"_k
);
Time::TimePointSeconds killAt = 10.0 + Time::GetTickCount ();
while (counter != expectedValue and Time::GetTickCount () < killAt) {
    Execution::Sleep (500ms);
}
Verify (counter == expectedValue);
producerThread.WaitForDone ();      // producer already set to run off the end...
consumerThread.WaitForDone ();      // consumer will end due to exception reading from end

Note

Aliases This could easily be called EventQueue or MessageQueue, as its well suited to those sorts of uses.

Definition at line 80 of file BlockingQueue.h.

Member Function Documentation

AddTail()

template<typename T >

void Stroika::Foundation::Execution::BlockingQueue< T >::AddTail	(	const T &	e,
		Time::DurationSeconds	timeout = Time::kInfinity
	)

Blocks until item added, and throws if timeout exceeded. About the only way the throw can happen is if the Q is full (or timeout is very small).

Typically this will return almost instantly.

Analogous to the java BlockingQueue<T>::put(e) and similar to the java BlockingQueue<T>::offer() or BlockingQueue<T>::add () method.

Note

this is illegal to call (assertion error) if SignalEndOfInput () has been called on this BlockingQueue.

Definition at line 22 of file BlockingQueue.inl.

SignalEndOfInput()

template<typename T >

void Stroika::Foundation::Execution::BlockingQueue< T >::SignalEndOfInput

(

)

Cause any future calls to AddTail () to be illegal, and any pending (while BlockingQueue empty) calls to RemoveHead to not block but throw a timeout error (no matter the timeout provided).

Note

This doesn't delete the current entries in the blocking queue, so they will still get consumed. This just prevents the Q from blocking while its being emptied out. This is like adding the special value 'EOF' to the end of Q.

Definition at line 33 of file BlockingQueue.inl.

EndOfInputHasBeenQueued()

template<typename T >

bool Stroika::Foundation::Execution::BlockingQueue< T >::EndOfInputHasBeenQueued

(

)

const

This returns true iff SignalEndOfInput () has been called. It does NOT imply the BlockingQueue is empty.

This routine exist because there is no other non-blocking way to check (peek) at see if you are at end of input.

Definition at line 38 of file BlockingQueue.inl.

QAtEOF()

template<typename T >

bool Stroika::Foundation::Execution::BlockingQueue< T >::QAtEOF

(

)

const

This returns true iff SignalEndOfInput () has been called and the BlockingQueue is empty.

Note

Equivalent to EndOfInputHasBeenQueued () and empty ()

Once this is true, it will always remain true.

This function is non-blocking.

See also

also empty ()

Definition at line 45 of file BlockingQueue.inl.

RemoveHead()

template<typename T >

T Stroika::Foundation::Execution::BlockingQueue< T >::RemoveHead

(

Time::DurationSeconds

timeout = Time::kInfinity

)

Blocks until item removed, and throws if timeout exceeded.

If there are currently no items in the Q, this may wait indefinitely (up to timeout provided).

If there are no available entries, and SignalEndOfInput () has been called, this will throw a Streams::EOFException no matter what the timeout value given.

Similar to the java BlockingQueue<T>::take() or BlockingQueue<T>::poll (time) method.

See also

RemoveHeadIfPossible()

Definition at line 51 of file BlockingQueue.inl.

RemoveHeadIfPossible()

template<typename T >

optional< T > Stroika::Foundation::Execution::BlockingQueue< T >::RemoveHeadIfPossible

(

Time::DurationSeconds

timeout = 0s

)

Like RemoveHead() except that on timeout, returns empty optional<T> instead of throwing.

If there is an entry at the head of the Q, return it immediately. Wait up til 'timeout' seconds for an entry to appear. Return 'missing' value if none appears.

If timeout == 0 (the default) this amounts to peeking (but with remove), and never waits.

Analogous to the java BlockingQueue<T>::poll () method.

Definition at line 69 of file BlockingQueue.inl.

PeekHead()

template<typename T >

optional< T > Stroika::Foundation::Execution::BlockingQueue< T >::PeekHead

(

)

const

Returns the front element from the Q, if there is one, and an empty optional<T> if there is none (without blocking).

Analogous to the java BlockingQueue<T>::peek() method.

Definition at line 88 of file BlockingQueue.inl.

empty()

template<typename T >

bool Stroika::Foundation::Execution::BlockingQueue< T >::empty

(

)

const

Returns true if the Q contains no items. Equivalent to PeekHead ().empty ()

See also

also QAtEOF ()

Definition at line 94 of file BlockingQueue.inl.

size()

template<typename T >

size_t Stroika::Foundation::Execution::BlockingQueue< T >::size

(

)

const

Returns the number of elements in the blocking queue (zero if empty).

Definition at line 100 of file BlockingQueue.inl.

length()

template<typename T >

size_t Stroika::Foundation::Execution::BlockingQueue< T >::length

(

)

const

Aliases

size()

Definition at line 106 of file BlockingQueue.inl.

GetQueue()

template<typename T >

Containers::Queue< T > Stroika::Foundation::Execution::BlockingQueue< T >::GetQueue

(

)

const

Get a copy of the entire owned Queue. NOTE - modifications of the returned copy have no effect on Queue associated with the BlockingQueue.

Definition at line 111 of file BlockingQueue.inl.

---

The documentation for this class was generated from the following files:

• BlockingQueue.h
• BlockingQueue.inl