c++-gtk-utils
Public Types | Public Member Functions | List of all members
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>

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 move_pop (value_type &obj)
 
void move_pop_basic (value_type &obj)
 
void pop_dispatch (value_type &obj)
 
void move_pop_dispatch (value_type &obj)
 
void move_pop_dispatch_basic (value_type &obj)
 
bool pop_timed_dispatch (value_type &obj, unsigned int millisec)
 
bool move_pop_timed_dispatch (value_type &obj, unsigned int millisec)
 
bool move_pop_timed_dispatch_basic (value_type &obj, unsigned int millisec)
 
void pop ()
 
bool empty () const
 
size_type size () const
 
void swap (AsyncQueueDispatch &other)
 
AsyncQueueDispatchoperator= (const AsyncQueueDispatch &rhs)
 
AsyncQueueDispatchoperator= (AsyncQueueDispatch &&rhs)
 
 AsyncQueueDispatch ()=default
 
 AsyncQueueDispatch (AsyncQueueDispatch &&rhs)
 
 AsyncQueueDispatch (const AsyncQueueDispatch &rhs)
 
 ~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 AsyncChannel AsyncResult

AsyncQueueDispatch is a class which has blocking pop_dispatch() and move_pop_dispatch() methods, 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. The AsyncResult class can be useful for passing results between threads in conjunction with AsyncQueueDispatch (the documentation on AsyncResult gives an example).

By default the queue uses a std::list object as its container because when adding an item to the queue all allocation can take place outside the queue object's mutex. However, for types which have low overhead copy or move constructors, this 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. If glib memory slices are not used or no AsyncQueueDispatch objects are constructed on free store, it is not necessary to call g_thread_init() before manipulating or using an AsyncQueueDispatch object in multiple threads, but prior to glib version 2.32 glib itself (and thus glib memory slices) are not thread safe unless that function has been called.

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 ( )
default
Exceptions
std::bad_allocThe default constructor might throw this exception if memory is exhausted and the system throws in that case.
Thread::MutexErrorThe default 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 default 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 ( AsyncQueueDispatch< T, Container > &&  rhs)
inline

As regards thread safety, the move constructor does not synchronize with respect to the initializing rvalue. This is because temporaries are only visible and accessible in the thread carrying out the move operation and synchronization for them would represent pointless overhead. In a case where a user uses std::move to force a move from a named object, and that named object's lifetime is managed by (or the object is otherwise accessed by) a different thread than the one making the move, the user must carry out her own synchronization with respect to that different thread, both to ensure that a consistent view of the the named object is obtained and because that object will be mutated by the move.

Parameters
rhsThe AsyncQueueDispatch object to be moved.
Exceptions
Thread::MutexErrorThe move constructor might throw Thread::MutexError if initialization 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.) It might also throw if the queue's container type's move constructor might throw, but it should not do that unless a custom allocator is in use.
Thread::CondErrorThe move 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.) It might also throw if the queue's container type's move constructor might throw, but it should not do that unless a custom allocator is in use.
Note
If this constructor throws Thread::MutexError or Thread::CondError, and a named object is moved using std::move, this constructor is not strongly exception safe (items in the moved queue will be lost). Fixing this efficiently requires changing the order of construction of data members of this class, which cannot be done without an ABI break for this library as it would alter object layout: this is therefore fixed in the 2.2 series of the library but not in this series. As noted above, in most cases the possibility of Thread::MutexError or Thread::CondError throwing can be ignored, but where that is not the case and strong exception safety is wanted, the user should either not employ std::move with named objects when invoking this class's constructors, or should construct an AsyncQueueDispatch object using the default constructor and then move assign to it.

Since 2.0.8

template<class T, class Container = std::list<T>>
Cgu::AsyncQueueDispatch< T, Container >::AsyncQueueDispatch ( const AsyncQueueDispatch< T, Container > &  rhs)
inline

The copy constructor is thread safe, as it locks the initializing object's mutex to obtain a consistent view of it.

Parameters
rhsThe AsyncQueueDispatch object to be copied.
Exceptions
std::bad_allocThe copy constructor of the queue's container type, and so this constructor, might throw std::bad_alloc if memory is exhausted and the system throws in that case. It will also throw if the copy constructor of the queue's container type throws any other exceptions, including if any copy or move constructor or copy or move assignment operator of a contained item throws.
Thread::MutexErrorThe copy constructor might throw Thread::MutexError if initialization 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 copy 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.)

Since 2.0.8

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). Destroying an AsyncQueueDispatch object on which another thread is currently blocked results in undefined behavior.

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>>
void Cgu::AsyncQueueDispatch< T, Container >::move_pop ( value_type obj)
inline

Pops an item from the queue using the contained type's move assignment operator, if it has one. This method is identical to the pop() method if that type has no move assignment operator. 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 and the move assignment operator of a contained item has strong exception safety. It is thread safe. Use this method in preference to the pop() method if it is known that the contained items' move assignment operator does not throw or is strongly exception safe, or if the use case does not require strong exception safety. This method (or the move_pop_basic() method) must be used in place of the pop() method if the contained type has a move assignment operator but no copy assignment operator (such as a std::unique_ptr object).

Parameters
objA value type reference to which the item at the front of the queue will be move assigned.
Exceptions
AsyncQueuePopErrorIf the queue is empty when a pop is attempted, this method will throw AsyncQueuePopError. It might also throw if the move assignment operator of the queue item might throw, or if it has no move assignment operator and its copy assignment operator throws. In order to complete pop operations atomically under a single lock and to retain strong exception safety, the object into which the popped data is to be placed is passed as an argument by reference (this avoids a move 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).

Since 2.0.11

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

Pops an item from the queue using the contained type's move assignment operator, if it has one, or if not using its copy assignment operator. This method is only available where the queue's container is a std::list object (which is the default), and does the same as the move_pop() method except that when popping the only thing which is done to the queue's container's internal state within the queue object's mutex is to swap some pointers: in particular, deallocation of the list node at the front of the queue occurs outside that mutex, as does assignment to this method's argument. Given that, if the queue's container is a list, any new node is also constructed outside the mutex when pushing or emplacing an item onto the queue, this minimizes contention between threads: it gets as close to lock-free performance as it is possible to get with the standard containers.

However this minimizing of contention comes at a cost, which is that if the contained item's move assignment operator (or if it has none, its copy assignment operator) throws, then only the basic exception guarantee is offered (hence the name of this method). This means that although the AsyncQueueDispatch object would be left in a valid state in the event of such throwing, the item at the front of the queue would be lost. As in the case of the pop() and move_pop() methods, in addition only the basic exception guarantee is offered if the destructor of the contained item throws. Only use this method if the queue's container is a std::list object, and if either it is known that the contained item's move assignment operator (or if it has none, its copy assignment operator) does not throw, or the use case does not require strong exception safety. This method is thread safe.

If this method is called for an AsyncQueueDispatch object whose container is not a std::list object, it will hand off to the move_pop() method, which is separately documented.

Parameters
objA value type reference to which the item at the front of the queue will be move assigned.
Exceptions
AsyncQueuePopErrorIf the queue is empty when a pop is attempted, this method will throw AsyncQueuePopError. It might also throw if the move assignment operator of the queue item might throw or it has no move assignment operator and its copy assignment operator throws (in which case only the basic exception guarantee is offered). It might also throw if the destructor of the queue item might throw (but that should never happen), if the empty() method of the container type throws (which would not happen on any sane implementation) or if the constructor of the implementation's list allocator throws (which would be highly unusual). In the event of any of the last two throwing, the strong exception guarantee is offered.

Since 2.0.26

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

Pops an item from the queue using the contained type's move assignment operator, if it has one (this method is identical to the pop_dispatch() method if that type has no move assignment operator). 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 and the move assignment operator of a contained item has strong exception safety. It is thread safe. Use this method in preference to the pop_dispatch() method if it is known that the contained items' move assignment operator does not throw or is strongly exception safe, or if the use case does not require strong exception safety. This method (or the move_pop_dispatch_basic() method) must be used in place of the pop_dispatch() method if the contained type has a move assignment operator but no copy assignment operator (such as a std::unique_ptr object).

Parameters
objA value type reference to which the item at the front of the queue will be move assigned. This method might throw if the move assignment operator of the queue item might throw, or if it has no move assignment operator and its copy assignment operator throws. In order to complete pop operations atomically under a single lock and to retain strong exception safety, the object into which the popped data is to be placed is passed as an argument by reference (this avoids a move 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).

Since 2.0.11

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

Pops an item from the queue using the contained type's move assignment operator, if it has one, or if not using its copy assignment operator. This method is only available where the queue's container is a std::list object (which is the default), and does the same as the move_pop_dispatch() method except that when popping the only thing which is done to the queue's container's internal state within the queue object's mutex is to swap some pointers: in particular, deallocation of the list node at the front of the queue occurs outside that mutex, as does assignment to this method's argument. Given that, if the queue's container is a list, any new node is also constructed outside the mutex when pushing or emplacing an item onto the queue, this minimizes contention between threads: it gets as close to lock-free performance as it is possible to get with the standard containers.

However this minimizing of contention comes at a cost, which is that if the contained item's move assignment operator (or if it has none, its copy assignment operator) throws, then only the basic exception guarantee is offered (hence the name of this method). This means that although the AsyncQueueDispatch object would be left in a valid state in the event of such throwing, the item at the front of the queue would be lost. As in the case of the pop_dispatch() and move_pop_dispatch() methods, in addition only the basic exception guarantee is offered if the destructor of the contained item throws. Only use this method if the queue's container is a std::list object, and if either it is known that the contained item's move assignment operator (or if it has none, its copy assignment operator) does not throw, or the use case does not require strong exception safety. This method is thread safe.

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.

If this method is called for an AsyncQueueDispatch object whose container is not a std::list object, it will hand off to the move_pop_dispatch() method, which is separately documented.

Parameters
objA value type reference to which the item at the front of the queue will be move assigned. This method might throw if the move assignment operator of the queue item might throw or it has no move assignment operator and its copy assignment operator throws (in which case only the basic exception guarantee is offered). It might also throw if the destructor of the queue item might throw (but that should never happen), if the empty() method of the container type throws (which would not happen on any sane implementation) or if the constructor of the implementation's list allocator throws (which would be highly unusual). In the event of any of the last two throwing, the strong exception guarantee is offered.

Since 2.0.26

template<class T, class Container = std::list<T>>
bool Cgu::AsyncQueueDispatch< T, Container >::move_pop_timed_dispatch ( value_type obj,
unsigned int  millisec 
)
inline

Pops an item from the queue using the contained type's move assignment operator, if it has one (this method is identical to the pop_timed_dispatch() method if that type has no move assignment operator). 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 and the move assignment operator of a contained item has strong exception safety. It is thread safe. Use this method in preference to the pop_timed_dispatch() method if it is known that the contained items' move assignment operator does not throw or is strongly exception safe, or if the use case does not require strong exception safety. This method (or the move_pop_timed_dispatch_basic() method) must be used in place of the pop_timed_dispatch() method if the contained type has a move assignment operator but no copy assignment operator (such as a std::unique_ptr object).

Parameters
objA value type reference to which the item at the front of the queue will be move assigned. This method might throw if the move assignment operator of the queue item might throw, or if it has no move assignment operator and its copy assignment operator throws. In order to complete pop operations atomically under a single lock and to retain strong exception safety, the object into which the popped data is to be placed is passed as an argument by reference (this avoids a move 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.

Since 2.0.11

template<class T, class Container = std::list<T>>
bool Cgu::AsyncQueueDispatch< T, Container >::move_pop_timed_dispatch_basic ( value_type obj,
unsigned int  millisec 
)
inline

Pops an item from the queue using the contained type's move assignment operator, if it has one, or if not using its copy assignment operator. This method is only available where the queue's container is a std::list object (which is the default), and does the same as the move_pop_timed_dispatch() method except that when popping the only thing which is done to the queue's container's internal state within the queue object's mutex is to swap some pointers: in particular, deallocation of the list node at the front of the queue occurs outside that mutex, as does assignment to this method's argument. Given that, if the queue's container is a list, any new node is also constructed outside the mutex when pushing or emplacing an item onto the queue, this minimizes contention between threads: it gets as close to lock-free performance as it is possible to get with the standard containers.

However this minimizing of contention comes at a cost, which is that if the contained item's move assignment operator (or if it has none, its copy assignment operator) throws, then only the basic exception guarantee is offered (hence the name of this method). This means that although the AsyncQueueDispatch object would be left in a valid state in the event of such throwing, the item at the front of the queue would be lost. As in the case of the pop_timed_dispatch() and move_pop_timed_dispatch() methods, in addition only the basic exception guarantee is offered if the destructor of the contained item throws. Only use this method if the queue's container is a std::list object, and if either it is known that the contained item's move assignment operator (or if it has none, its copy assignment operator) does not throw, or the use case does not require strong exception safety. This method is thread safe.

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.

If this method is called for an AsyncQueueDispatch object whose container is not a std::list object, it will hand off to the move_pop_timed_dispatch() method, which is separately documented.

Parameters
objA value type reference to which the item at the front of the queue will be move assigned. This method might throw if the move assignment operator of the queue item might throw or it has no move assignment operator and its copy assignment operator throws (in which case only the basic exception guarantee is offered). It might also throw if the destructor of the queue item might throw (but that should never happen), if the empty() method of the container type throws (which would not happen on any sane implementation) or if the constructor of the implementation's list allocator throws (which would be highly unusual). In the event of any of the last two throwing, the strong exception guarantee is offered.
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.

Since 2.0.26

template<class T, class Container = std::list<T>>
AsyncQueueDispatch& Cgu::AsyncQueueDispatch< T, Container >::operator= ( const AsyncQueueDispatch< T, Container > &  rhs)
inline

The copy assignment operator is strongly exception safe with the standard sequence containers (it uses copy and swap). It is also thread safe, as it safely locks both the assignor's and assignee's mutex to provide a thread-wise atomic assignment.

Parameters
rhsThe assignor.
Returns
The AsyncQueueDispatch object after assignment.
Exceptions
std::bad_allocThe copy constructor of the queue's container type, and so this assignment operator, might throw std::bad_alloc if memory is exhausted and the system throws in that case. This assignment operator will also throw if the copy constructor of the queue's container type throws any other exceptions, including if any copy or move constructor or copy or move assignment operator of a contained item throws.
Thread::MutexErrorThis assignment operator might throw Thread::MutexError if initialization of a transitional object's 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::CondErrorThis assignment operator might throw Thread::CondError if initialisation of a transitional object's 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.)
Note
The assignee does not, by virtue of the assignment, inherit any threads waiting on the assignor. However, if prior to the assignment threads were waiting on the assignee and the assignee acquires items from the assignor as a result of the assignment, the waiting threads will unblock and extract those items.

Since 2.0.8

template<class T, class Container = std::list<T>>
AsyncQueueDispatch& Cgu::AsyncQueueDispatch< T, Container >::operator= ( AsyncQueueDispatch< T, Container > &&  rhs)
inline

This move assignment operator is thread safe as regards the assignee (the object moved to), but no synchronization is carried out with respect to the rvalue assignor/movant. This is because temporaries are only visible and accessible in the thread carrying out the move operation and synchronization for them would represent pointless overhead. In a case where the user uses std::move to force a move from a named object, and that named object's lifetime is managed by (or the object is otherwise accessed by) a different thread than the one making the move, the user must carry out her own synchronization with respect to that different thread, both to ensure that a consistent view of the the named object is obtained and because that object will be mutated by the move. This method invokes std::queue's move assignment operator, and therefore has the same exception safety as the standard library's implementation of that operator. It will not normally throw unless a custom allocator is used which throws on move assignment, or the destructor of a contained item throws.

Parameters
rhsThe assignor/movant.
Returns
The AsyncQueueDispatch object after move assignment.
Note
The assignee does not, by virtue of the move, inherit any threads waiting on the assignor/movant. However, if prior to the move threads were waiting on the assignee and the assignee acquires items from the assignor/movant as a result of the move, from version 2.0.9 the waiting threads will unblock and extract those items (such unblocking on move assignment did not happen with version 2.0.8, which was a bug).

Since 2.0.8

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

Pops an item from the queue using the contained type's copy assignment operator. 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 copy 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 popped 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 using the contained type's copy assignment operator. 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 copy 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 popped 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 using the contained type's copy assignment operator. 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 copy 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 popped 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, copy 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, copy 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

template<class T, class Container = std::list<T>>
size_type Cgu::AsyncQueueDispatch< T, Container >::size ( ) const
inline
Returns
The number of items currently in the queue. It will not throw assuming that the size() 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.

Since 2.0.8

template<class T, class Container = std::list<T>>
void Cgu::AsyncQueueDispatch< T, Container >::swap ( AsyncQueueDispatch< T, Container > &  other)
inline

Swaps the contents of 'this' and 'other'. It will not throw assuming that the swap method of the container type does not throw (which the C++11/14 standard requires not to happen with the standard sequence containers). It is thread safe and the swap is thread-wise atomic. A non-class function Cgu::swap(Cgu::AsyncQueueDispatch&, Cgu::AsyncQueueDispatch&) method is also provided which will call this method.

Parameters
otherThe object to be swapped with this one.
Note
An object swapped does not, by virtue of the swap, inherit any threads waiting on the other one. However if threads were waiting on a swapped object prior to the swap, and it acquires items by virtue of the swap, the waiting threads will unblock and extract those items.

Since 2.0.8


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