c++-gtk-utils
Public Types | Public Member Functions
Cgu::AsyncQueueDispatch< T, Container > Class Template Reference

A thread-safe asynchronous queue with a blocking pop() method. More...

#include <c++-gtk-utils/async_queue.h>

List of all members.

Public Types

typedef Container::value_type value_type
typedef Container::size_type size_type
typedef Container container_type

Public Member Functions

void push (const value_type &obj)
void push (value_type &&obj)
template<class... Args>
void emplace (Args &&...args)
void pop (value_type &obj)
void pop_dispatch (value_type &obj)
bool pop_timed_dispatch (value_type &obj, unsigned int millisec)
void pop ()
bool empty () const
 AsyncQueueDispatch ()
 AsyncQueueDispatch (const AsyncQueueDispatch &)
AsyncQueueDispatchoperator= (const AsyncQueueDispatch &)
 ~AsyncQueueDispatch ()

Detailed Description

template<class T, class Container = std::list<T>>
class Cgu::AsyncQueueDispatch< T, Container >

A thread-safe asynchronous queue with a blocking pop() method.

See also:
AsyncQueue

AsyncQueueDispatch is similar to the AsyncQueue class, except that it has a blocking pop_dispatch() method, which allows it to be waited on by a dedicated event/message dispatching thread for incoming work (represented by the data pushed onto the queue). In the same way, it can be used to implement thread pools, by having threads in the pool waiting on the queue.

By default the queue uses a std::list object as its container because in the kind of use mentioned above it is unlikely to hold many objects but it can be changed to, say, a std::deque object by specifying it as the second template parameter.

If the library is installed using the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration options, any AsyncQueueDispatch objects constructed on free store will be constructed in glib memory slices. This does not affect the queue container itself: to change the allocator of the C++ container, a custom allocator type can be provided when the AsyncQueueDispatch object is instantiated offering the standard allocator interface.


Member Typedef Documentation

template<class T , class Container = std::list<T>>
typedef Container Cgu::AsyncQueueDispatch< T, Container >::container_type
template<class T , class Container = std::list<T>>
typedef Container::size_type Cgu::AsyncQueueDispatch< T, Container >::size_type
template<class T , class Container = std::list<T>>
typedef Container::value_type Cgu::AsyncQueueDispatch< T, Container >::value_type

Constructor & Destructor Documentation

template<class T , class Container = std::list<T>>
Cgu::AsyncQueueDispatch< T, Container >::AsyncQueueDispatch ( )
Exceptions:
std::bad_allocThe constructor might throw this exception if memory is exhausted and the system throws in that case.
Thread::MutexErrorThe constructor might throw this exception if initialisation of the contained mutex fails. (It is often not worth checking for this, as it means either memory is exhausted or pthread has run out of other resources to create new mutexes.)
Thread::CondErrorThe constructor might throw this exception if initialisation of the contained condition variable fails. (It is often not worth checking for this, as it means either memory is exhausted or pthread has run out of other resources to create new condition variables.)
template<class T , class Container = std::list<T>>
Cgu::AsyncQueueDispatch< T, Container >::AsyncQueueDispatch ( const AsyncQueueDispatch< T, Container > &  )

This class cannot be copied. The copy constructor is deleted.

template<class T , class Container = std::list<T>>
Cgu::AsyncQueueDispatch< T, Container >::~AsyncQueueDispatch ( ) [inline]

The destructor does not throw unless the destructor of a contained item throws. It is thread safe (any thread may delete the AsyncQueueDispatch object).


Member Function Documentation

template<class T , class Container = std::list<T>>
template<class... Args>
void Cgu::AsyncQueueDispatch< T, Container >::emplace ( Args &&...  args) [inline]

Pushes an item onto the queue by constructing it in place: that is, by passing to this method the item's constructor's arguments, rather than the item itself. This method has strong exception safety if the container is a std::list or std::deque container (the default is std::list). (Technically, for a std::deque container, emplace() only offers the same exception guarantees as does push(), namely only the basic guarantee where a copy or move of the queue item throws during the call, but the purpose of emplace is to construct in place and any reasonable implementation will not copy or move the queue item.) It is thread safe.

Parameters:
argsThe constructor arguments for the item to be pushed onto the queue.
Exceptions:
std::bad_allocThe method might throw std::bad_alloc if memory is exhausted and the system throws in that case. It might also throw if the item's constructor (including any of its constructor arguments) might throw when constructing the item.
Note:
The constructor of the item pushed onto the queue must not access any of the methods of the same queue object, or a deadlock might occur.

Since 2.0.0-rc5

template<class T , class Container = std::list<T>>
bool Cgu::AsyncQueueDispatch< T, Container >::empty ( ) const [inline]
Returns:
Whether the queue is empty. It will not throw assuming that the empty() method of the container type does not throw, as it will not on any sane implementation.
Note:
This method is thread safe, but the return value may not be valid if another thread has pushed to or popped from the queue before the value returned by the method is acted on. It is provided as a utility, but may not be meaningful, depending on the intended usage.
template<class T , class Container = std::list<T>>
AsyncQueueDispatch& Cgu::AsyncQueueDispatch< T, Container >::operator= ( const AsyncQueueDispatch< T, Container > &  )

This class cannot be copied. The assignment operator is deleted.

template<class T , class Container = std::list<T>>
void Cgu::AsyncQueueDispatch< T, Container >::pop ( value_type obj) [inline]

Pops an item from the queue. This method has strong exception safety if the container is a std::deque or std::list container (the default is std::list), provided the destructor of a contained item does not throw. It is thread safe.

Parameters:
objA value type reference to which the item at the front of the queue will be assigned.
Exceptions:
AsyncQueuePopErrorIf the queue is empty when a pop is attempted, this method will throw AsyncQueuePopError. It might also throw if the assignment operator of the queue item might throw. In order to complete pop() operations atomically under a single lock and to retain strong exception safety, the object into which the pop()ed data is to be placed is passed as an argument by reference (this avoids a copy from a temporary object after the data has been extracted from the queue, which would occur if the item extracted were returned by value). It might also throw if the destructor of the queue item might throw (but that should never happen), or if the empty() method of the container type throws (which would not happen on any sane implementation).
template<class T , class Container = std::list<T>>
void Cgu::AsyncQueueDispatch< T, Container >::pop ( ) [inline]

Discards the item at the front of the queue. This method has strong exception safety if the container is a std::deque or std::list container (the default is std::list), provided the destructor of a contained item does not throw. It is thread safe.

Exceptions:
AsyncQueuePopErrorIf the queue is empty when a pop is attempted, this method will throw AsyncQueuePopError. It might also throw if the destructor of the queue item might throw (but that should never happen), or if the empty() method of the container type throws (which would not happen on any sane implementation).
template<class T , class Container = std::list<T>>
void Cgu::AsyncQueueDispatch< T, Container >::pop_dispatch ( value_type obj) [inline]

Pops an item from the queue. If the queue is empty, it will block until an item becomes available. If it blocks, the wait comprises a cancellation point. This method is cancellation safe if the stack unwinds on cancellation, as cancellation is blocked while the queue is being operated on after coming out of a wait. This method has strong exception safety if the container is a std::deque or std::list container (the default is std::list), provided the destructor of a contained item does not throw. It is thread safe.

Parameters:
objA value type reference to which the item at the front of the queue will be assigned. This method might throw if the assignment operator of the queue item might throw. In order to complete pop() operations atomically under a single lock and to retain strong exception safety, the object into which the pop()ed data is to be placed is passed as an argument by reference (this avoids a copy from a temporary object after the data has been extracted from the queue, which would occur if the item extracted were returned by value). It might also throw if the destructor of the queue item might throw (but that should never happen), or if the empty() method of the container type throws (which would not happen on any sane implementation).
template<class T , class Container = std::list<T>>
bool Cgu::AsyncQueueDispatch< T, Container >::pop_timed_dispatch ( value_type obj,
unsigned int  millisec 
) [inline]

Pops an item from the queue. If the queue is empty, it will block until an item becomes available or until the timeout expires. If it blocks, the wait comprises a cancellation point. This method is cancellation safe if the stack unwinds on cancellation, as cancellation is blocked while the queue is being operated on after coming out of a wait. This method has strong exception safety if the container is a std::deque or std::list container (the default is std::list), provided the destructor of a contained item does not throw. It is thread safe.

Parameters:
objA value type reference to which the item at the front of the queue will be assigned. This method might throw if the assignment operator of the queue item might throw. In order to complete pop() operations atomically under a single lock and to retain strong exception safety, the object into which the pop()ed data is to be placed is passed as an argument by reference (this avoids a copy from a temporary object after the data has been extracted from the queue, which would occur if the item extracted were returned by value). It might also throw if the destructor of the queue item might throw (but that should never happen), or if the empty() method of the container type throws (which would not happen on any sane implementation).
millisecThe timeout interval, in milliseconds.
Returns:
If the timeout expires without an item becoming available, the method will return true. If an item from the queue is extracted, it returns false.
template<class T , class Container = std::list<T>>
void Cgu::AsyncQueueDispatch< T, Container >::push ( const value_type obj) [inline]

Pushes an item onto the queue. This method has strong exception safety if the container is a std::list or std::deque container (the default is std::list), except that if std::deque is used as the container and the copy constructor, move constructor, assignment operator or move assignment operator of the queue item throws, it only gives the basic exception guarantee (and the basic guarantee is not given by std::deque if the queue item's move constructor throws and it uses a non-default allocator which does not provide for it to be CopyInsertable). It is thread safe.

Parameters:
objThe item to be pushed onto the queue.
Exceptions:
std::bad_allocThe method might throw std::bad_alloc if memory is exhausted and the system throws in that case. It might also throw if the copy constructor, move constructor, assignment operator or move assignment operator of the queue item might throw.
template<class T , class Container = std::list<T>>
void Cgu::AsyncQueueDispatch< T, Container >::push ( value_type &&  obj) [inline]

Pushes an item onto the queue. This method has strong exception safety if the container is a std::list or std::deque container (the default is std::list), except that if std::deque is used as the container and the copy constructor, move constructor, assignment operator or move assignment operator of the queue item throws, it only gives the basic exception guarantee (and the basic guarantee is not given by std::deque if the queue item's move constructor throws and it uses a non-default allocator which does not provide for it to be CopyInsertable). It is thread safe.

Parameters:
objThe item to be pushed onto the queue.
Exceptions:
std::bad_allocThe method might throw std::bad_alloc if memory is exhausted and the system throws in that case. It might also throw if the copy constructor, move constructor, assignment operator or move assignment operator of the queue item might throw.

Since 2.0.0-rc5


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