|
cppthread 1.1.16
C++ Thread Library
|
Create a thread safe FIFO. More...


Classes | |
| struct | item_has_predicate |
| struct | item_has_predicate< C, R(A...), void_t< decltype(std::declval< C >().valid_workload(std::declval< A >()...))> > |
Public Types | |
| typedef std::vector< mutex > | direct_vector_t |
| A vector of mutexes. | |
| typedef fifo< value_type > | fifo_type |
| The type of the FIFO as a typedef. | |
| typedef std::shared_ptr< fifo_type > | pointer_t |
| A smart pointer to the FIFO. | |
| typedef T | value_type |
| The type of value to push and pop from the FIFO. | |
| typedef std::vector< pointer_t > | vector_t |
| A vector of mutexes. | |
Public Member Functions | |
| void | broadcast () |
| Broadcast a mutex signal. | |
| size_t | byte_size () const |
| Return the total size of the FIFO uses in memory. | |
| void | clear () |
| Clear the current FIFO. | |
| bool | dated_wait (std::uint64_t const date) |
| Wait on a mutex until the specified date. | |
| bool | dated_wait (timespec const &date) |
| Wait on a mutex until the specified date. | |
| void | done (bool clear) |
| Mark the FIFO as done. | |
| bool | empty () const |
| Test whether the FIFO is empty. | |
| bool | is_done () const |
| Check whether the FIFO was marked as done. | |
| void | lock () |
| Lock a mutex. | |
| bool | pop_front (T &v, int64_t const usecs) |
| Retrieve one value from the FIFO. | |
| bool | push_back (T const &v) |
| Push data on this FIFO. | |
| void | safe_broadcast () |
| Broadcast a mutex signal. | |
| void | safe_signal () |
| Signal a mutex. | |
| void | signal () |
| Signal at least one mutex. | |
| size_t | size () const |
| Return the number of items in the FIFO. | |
| bool | timed_wait (std::uint64_t const usec) |
| Wait on a mutex condition with a time limit. | |
| bool | timed_wait (timespec const &nsec) |
| Wait on a mutex condition with a time limit. | |
| bool | try_lock () |
| Try locking the mutex. | |
| void | unlock () |
| Unlock a mutex. | |
| void | wait () |
| Wait on a mutex condition. | |
Private Types | |
| typedef std::deque< T > | items_t |
| The container type of our items. | |
| template<typename ... > | |
| using | void_t = void |
Private Member Functions | |
| template<typename C > | |
| std::enable_if<!snapdev::is_shared_ptr< C >::value &&item_has_predicate< C, bool()>::value, bool >::type | validate_item (C const &item) |
| Validate item. | |
| template<typename C > | |
| std::enable_if<!snapdev::is_shared_ptr< C >::value &&!item_has_predicate< C, bool()>::value, bool >::type | validate_item (C const &item) |
| Validate item. | |
| template<typename C > | |
| std::enable_if< snapdev::is_shared_ptr< C >::value &&item_has_predicate< typenameC::element_type, bool()>::value, bool >::type | validate_item (C const &item) |
| Validate item. | |
| template<typename C > | |
| std::enable_if< snapdev::is_shared_ptr< C >::value &&!item_has_predicate< typenameC::element_type, bool()>::value, bool >::type | validate_item (C const &item) |
| Validate item. | |
Private Attributes | |
| bool | f_broadcast = false |
| Whether the done() function called broadcast(). | |
| bool | f_done = false |
| Whether the FIFO is done. | |
| std::shared_ptr< detail::mutex_impl > | f_impl |
| The pthread mutex implementation. | |
| items_t | f_queue = items_t() |
| The actual FIFO. | |
| std::uint32_t | f_reference_count = 0 |
| The lock reference count. | |
This template defines a thread safe FIFO which is also a mutex. You should use this snap_fifo object to lock your thread and send messages/data across various threads. The FIFO itself is a mutex so you can use it to lock the threads as with a normal mutex:
| T | the type of data that the FIFO will handle. |
|
inherited |
| cppthread::fifo< T >::fifo_type |
|
private |
| cppthread::fifo< T >::pointer_t |
You may want to create FIFOs on the heap in which case we strongly advice that you use this shared pointer type to old those FIFOs.
It is otherwise possible to have the FIFO as a variable member of your thread. One thing to consider, though, if that if thread A owns a FIFO and shares it with thread B, then you must make sure that B is done before destroying A.
| cppthread::fifo< T >::value_type |
|
inherited |
|
inherited |
Our mutexes include a condition that get signaled by calling this function. This function actually signals all the threads that are currently listening to the mutex signal. The order in which the threads get awaken is unspecified.
The function ensures that the mutex is locked before broadcasting the signal so you do not have to lock the mutex yourself.
| cppthread_exception_invalid_error | If one of the pthread system functions return an error, the function raises this exception. |
Definition at line 838 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, cppthread::mutex::lock(), and cppthread::log.
Referenced by cppthread::fifo< T >::done(), and cppthread::fifo< T >::pop_front().


|
inline |
This function returns the sum of each element size() function.
The complexity of this function is O(n).
Definition at line 267 of file fifo.h.
References cppthread::fifo< T >::f_queue, cppthread::mutex::lock(), and cppthread::fifo< T >::validate_item().

|
inline |
This function can be used to clear the FIFO. Right after this call, the FIFO will be empty. All the objects that were pushed in the FIFO will be removed. It is your responsibility to ensure they get cleaned up appropriately.
Definition at line 248 of file fifo.h.
References cppthread::fifo< T >::empty(), cppthread::fifo< T >::f_queue, and cppthread::mutex::lock().
Referenced by cppthread::fifo< T >::done().


|
inherited |
This function waits on the mutex condition to be signaled up until the specified date is passed.
| cppthread_exception_mutex_failed_error | This exception is raised whenever the thread wait function fails. |
| [in] | usec | The date when the mutex times out in microseconds. |
Definition at line 642 of file mutex.cpp.
References cppthread::mutex::dated_wait().
Referenced by cppthread::mutex::dated_wait().


|
inherited |
This function waits on the mutex condition to be signaled up until the specified date is passed.
| cppthread_exception_mutex_failed_error | This exception is raised whenever the thread wait function fails. |
| [in] | date | The date when the mutex times out in nanoseconds. |
Definition at line 668 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, and cppthread::log.

|
inline |
By default the FIFO is not done. Once you are finished with it and will never push any more data to it, call this function. This flag is used by worker threads to know whether they should wait for more data or just exit.
This is rarely used with regular threads. It is more of a feature for worker threads.
| [in] | clear | Whether the function should also call clear() |
Definition at line 280 of file fifo.h.
References cppthread::mutex::broadcast(), cppthread::fifo< T >::clear(), cppthread::fifo< T >::empty(), cppthread::fifo< T >::f_broadcast, cppthread::fifo< T >::f_done, cppthread::fifo< T >::f_queue, and cppthread::mutex::lock().

|
inline |
This function checks whether the FIFO is empty and if so returns true, otherwise it returns false.
The function does not check the semaphore. Instead it checks the size of the FIFO itself.
Definition at line 255 of file fifo.h.
References cppthread::fifo< T >::f_queue, and cppthread::mutex::lock().
Referenced by cppthread::fifo< T >::clear(), and cppthread::fifo< T >::done().


|
inline |
When a child process calls pop_front() and the function returns false, it means the FIFO is empty. On return, the thread may then check whether is_done() is true. If so, then the thread is expected to exit (no more data will even be added to the FIFO so you might as well leave.)
Definition at line 296 of file fifo.h.
References cppthread::fifo< T >::f_done, and cppthread::mutex::lock().

|
inherited |
This function locks the mutex. The function waits until the mutex is available if it is not currently available. To avoid waiting one may want to use the try_lock() function instead.
Although the function cannot fail, the call can lock up a process if two or more mutexes are used and another thread is already waiting on this process.
| cppthread_exception_invalid_error | If the lock fails, this exception is raised. |
Definition at line 369 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, cppthread::mutex::f_reference_count, and cppthread::log.
Referenced by cppthread::guard::guard(), cppthread::mutex::broadcast(), cppthread::fifo< T >::byte_size(), cppthread::fifo< T >::clear(), cppthread::fifo< T >::done(), cppthread::fifo< T >::empty(), cppthread::fifo< T >::is_done(), cppthread::guard::is_locked(), cppthread::guard::lock(), cppthread::fifo< T >::pop_front(), cppthread::fifo< T >::push_back(), cppthread::mutex::safe_broadcast(), cppthread::mutex::safe_signal(), and cppthread::fifo< T >::size().


This function retrieves one value from the thread FIFO. If necessary, the function can wait for a value to be received. The wait works as defined in the semaphore wait() function:
If the function works (returns true,) then v is set to the value being popped. Otherwise v is not modified and the function returns false.
v is not set to anything so it still has the value it had when calling the function.| [out] | v | The value read. |
| [in] | usecs | The number of microseconds to wait. |
Definition at line 184 of file fifo.h.
References cppthread::mutex::broadcast(), cppthread::fifo< T >::f_broadcast, cppthread::fifo< T >::f_done, cppthread::fifo< T >::f_queue, cppthread::mutex::lock(), cppthread::mutex::timed_wait(), cppthread::fifo< T >::validate_item(), and cppthread::mutex::wait().

This function appends data on the FIFO queue. The function has the side effect to wake up another thread if such is currently waiting for data on the same FIFO.
| cppthread_exception_invalid_error | Do not call this function after calling done(), it will raise this exception if you do so. |
| [in] | v | The value to be pushed on the FIFO queue. |
Definition at line 172 of file fifo.h.
References cppthread::fifo< T >::f_done, cppthread::fifo< T >::f_queue, cppthread::mutex::lock(), and cppthread::mutex::signal().

|
inherited |
Our mutexes include a condition that get signaled by calling this function. This function actually signals all the threads that are currently listening to the mutex signal. The order in which the threads get awaken is unspecified.
The function ensures that the mutex is locked before broadcasting the signal so you do not have to lock the mutex yourself. Note that is not required to lock a mutex before broadcasting a signal. The effects are similar.
| cppthread_exception_invalid_error | If one of the pthread system functions return an error, the function raises this exception. |
Definition at line 799 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, cppthread::mutex::lock(), and cppthread::log.

|
inherited |
Our mutexes include a condition that get signaled by calling this function. This function wakes up one listening thread.
The function ensures that the mutex is locked before sending the signal so you do not have to lock the mutex yourself.
| cppthread_exception_invalid_error | If one of the pthread system functions return an error, the function raises this exception. |
Definition at line 765 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, cppthread::mutex::lock(), and cppthread::log.

|
inherited |
Our mutexes include a condition that get signaled by calling this function. This function wakes up one or more listening threads.
The function does not lock the mutext before sending the signal. This is useful if you already are in a guarded block or you do not mind waking up more than one thread as a result of the call.
| cppthread_exception_invalid_error | If one of the pthread system functions return an error, the function raises this exception. |
Definition at line 737 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, and cppthread::log.
Referenced by cppthread::thread::internal_thread(), and cppthread::fifo< T >::push_back().


|
inline |
This function returns the number of items currently added to the FIFO. This can be used by the caller to avoid flooding the FIFO, if at all possible.
The complexity of this function is O(1).
Definition at line 261 of file fifo.h.
References cppthread::fifo< T >::f_queue, and cppthread::mutex::lock().

|
inherited |
At times it is useful to wait on a mutex to become available without polling the mutex, but only for some time. This function waits for the number of specified micro seconds. The function returns early if the condition was triggered. Otherwise it waits until the specified number of micro seconds elapsed and then returns.
| cppthread_exception_system_error | This exception is raised if a function returns an unexpected error. |
| cppthread_exception_mutex_failed_error | This exception is raised when the mutex wait function fails. |
| [in] | usecs | The maximum number of micro seconds to wait until you receive the signal. |
Definition at line 549 of file mutex.cpp.
References cppthread::mutex::timed_wait().
Referenced by cppthread::fifo< T >::pop_front(), and cppthread::mutex::timed_wait().


|
inherited |
At times it is useful to wait on a mutex to become available without polling the mutex, but only for some time. This function waits for the number of specified nano seconds. The function returns early if the condition was triggered. Otherwise it waits until the specified number of nano seconds elapsed and then returns.
| cppthread_exception_system_error | This exception is raised if a function returns an unexpected error. |
| cppthread_exception_mutex_failed_error | This exception is raised when the mutex wait function fails. |
| [in] | nsecs | The maximum number of nano seconds to wait until you receive the signal. |
Definition at line 583 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, and cppthread::log.

|
inherited |
This function tries locking the mutex. If the mutex cannot be locked because another process already locked it, then the function returns immediately with false.
| cppthread_exception_invalid_error | If the lock fails, this exception is raised. |
Definition at line 400 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, cppthread::mutex::f_reference_count, and cppthread::log.

|
inherited |
This function unlock the specified mutex. The function must be called exactly once per call to the lock() function, or successful call to the try_lock() function.
The unlock never waits.
| cppthread_exception_invalid_error | If the unlock fails, this exception is raised. |
| cppthread_exception_not_locked_error | If the function is called too many times, then the lock count is going to be zero and this exception will be raised. |
Definition at line 443 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, cppthread::mutex::f_reference_count, and cppthread::log.
Referenced by cppthread::guard::is_locked(), cppthread::guard::lock(), and cppthread::guard::unlock().


|
inlineprivate |
Validate a fifo item.
This function checks whether the T::valid_workload() function says the item can be processed now or not.
In this case, the class C is not a shared pointer.
| C | The type of the item. |
| [in] | item | The item to verify. |
The validate_item() checks whether the item can be returned by the pop_front() function or not.
Definition at line 101 of file fifo.h.
Referenced by cppthread::fifo< T >::byte_size(), and cppthread::fifo< T >::pop_front().

|
inlineprivate |
|
inlineprivate |
This function checks whether the T::valid_workload() function says the item can be processed now or not.
In this case, the class C is a shared pointer to an item T.
| C | The type of the item. |
| [in] | item | The item to verify. |
|
inlineprivate |
|
inherited |
At times it is useful to wait on a mutex to become available without polling the mutex (which uselessly wastes precious processing time.) This function can be used to wait on a mutex condition.
This version of the wait() blocks until a signal is received.
| cppthread_exception_not_locked_once_error | This exception is raised if the reference count is not exactly 1. In other words, the mutex must be locked by the caller but only one time. |
| cppthread_exception_mutex_failed_error | This exception is raised in the event the conditional wait fails. |
Definition at line 494 of file mutex.cpp.
References cppthread::end(), cppthread::mutex::f_impl, and cppthread::log.
Referenced by cppthread::fifo< T >::pop_front(), and cppthread::thread::start().


|
private |
This variable is set to true once the done() function called the broadcast() function of the mutex. This way we avoid calling it more than once even if you call the done() function multiple times.
Definition at line 305 of file fifo.h.
Referenced by cppthread::fifo< T >::done(), and cppthread::fifo< T >::pop_front().
|
private |
This flag tells us whether the FIFO is done or not.
Definition at line 304 of file fifo.h.
Referenced by cppthread::fifo< T >::done(), cppthread::fifo< T >::is_done(), cppthread::fifo< T >::pop_front(), and cppthread::fifo< T >::push_back().
|
privateinherited |
This variable member holds the actual pthread mutex. The mutex implementation manages this field as required.
Definition at line 82 of file mutex.h.
Referenced by cppthread::mutex::mutex(), cppthread::mutex::~mutex(), cppthread::mutex::broadcast(), cppthread::mutex::dated_wait(), cppthread::mutex::lock(), cppthread::mutex::safe_broadcast(), cppthread::mutex::safe_signal(), cppthread::mutex::signal(), cppthread::mutex::timed_wait(), cppthread::mutex::try_lock(), cppthread::mutex::unlock(), and cppthread::mutex::wait().
|
private |
This variable member holds the actual data in this FIFO object.
Definition at line 303 of file fifo.h.
Referenced by cppthread::fifo< T >::byte_size(), cppthread::fifo< T >::clear(), cppthread::fifo< T >::done(), cppthread::fifo< T >::empty(), cppthread::fifo< T >::pop_front(), cppthread::fifo< T >::push_back(), and cppthread::fifo< T >::size().
|
privateinherited |
The mutex tracks the number of times the mutex gets locked. In the end, the lock reference must be zero for the mutex to be properly destroyed.
Definition at line 84 of file mutex.h.
Referenced by cppthread::mutex::~mutex(), cppthread::mutex::lock(), cppthread::mutex::try_lock(), and cppthread::mutex::unlock().
This document is part of the Snap! Websites Project.
Copyright by Made to Order Software Corp.