template<class T, class Container = std::list<T>>
class Cgu::AsyncQueue< T, Container >
A thread-safe asynchronous queue.
- See also:
- AsyncQueueDispatch AsyncResult
AsyncQueue is a class which provides some of the functionality of a std::queue object (but note that the AsyncQueue::pop(value_type& obj) method provides the pop()ed element by reference - see the comments on that method for the reason), except that it has mutex locking of the data container so as to permit push()ing and pop()ing from different threads. It is therefore useful for passing data between threads, perhaps in response to a signal being emitted from a Notifier object. Passing the data by means of a SharedLockPtr object, or an IntrusivePtr object referencing data derived from IntrusiveLockCounter, would be ideal.
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 AsyncQueue 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 AsyncQueue object is instantiated offering the standard allocator interface. If glib memory slices are not used or no AsyncQueue objects are constructed on free store, it is not necessary to call g_thread_init() before manipulating or using an AsyncQueue 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.
template<class T, class Container = std::list<T>>
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:
-
- Exceptions:
-
Thread::MutexError | The 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. |
- Note:
- If this constructor throws Thread::MutexError, 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 until the next ABI break for this library as it would alter object layout. As noted above, in most cases the possibility of Thread::MutexError 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 AsyncQueue object using the default constructor and then move assign to it.
Since 2.0.8
template<class T, class Container = std::list<T>>
template<class... Args>
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:
-
args | The constructor arguments for the item to be pushed onto the queue. |
- Exceptions:
-
std::bad_alloc | The 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>>
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:
-
- Returns:
- The AsyncQueue object after move assignment.
Since 2.0.8
template<class T, class Container = std::list<T>>
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:
-
obj | The item to be pushed onto the queue. |
- Exceptions:
-
std::bad_alloc | The 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>>
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:
-
obj | The item to be pushed onto the queue. |
- Exceptions:
-
std::bad_alloc | The 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