#include <dataQueue.h>
Inheritance diagram for dlr::thread::DataQueue< Type >:
Public Types | |
| typedef ClientID< Type > | ClientID |
| Each thread that interacts with a particular BroadcastQueue instance must create a ClientID instance, and then register with the BroadcastQueue by calling the registerClient() member function of that BroadcastQueue instance, passing the clientID instance as an argument. | |
Public Member Functions | |
| DataQueue (size_t maximumLength, size_t numberOfClients=2) | |
| DataQueue (const DataQueue< Type > &source) | |
| virtual | ~DataQueue () |
| void | catchUp (ClientID &clientID) |
| This member function moves the calling thread to the head of the BroadcastQueue. | |
| void | copyBack (const ClientID &clientID, Type &target) |
| This member function copies the tail element of the BroadcastQueue. | |
| bool | copyBack (const ClientID &clientID, Type &target, double timeout) |
| This member function copies the tail element of the BroadcastQueue. | |
| size_t | getMaximumLength () |
| This member function returns the length at which the BroadcastQueue instance will begin dropping elements off the tail. | |
| void | lockBack (const ClientID &clientID) |
| This member function locks the tail element of the BroadcastQueue instance so that it cannot fall off the back of the queue. | |
| bool | lockBack (const ClientID &clientID, double timeout) |
| This member function locks the tail element of the BroadcastQueue instance so that it cannot fall off the back of the queue. | |
| void | popBack (ClientID &clientID) |
| This member function is called by consumer threads to "discard" one element from the tail of the BroadcastQueue so that subsequent calls to copyBack() will copy the next element in the queue. | |
| void | pushFront (const ClientID &clientID, const Type &element) |
| This member function is called by producer threads to add elements to the head of the queue. | |
| void | registerClient (ClientID &clientID, const std::string &clientName="anonymous") |
| This member function introduces a thread to a BroadcastQueue instance. | |
| void | synchronize (ClientID &clientID) |
| This member function blocks until all clients of the BroadcastQueue have called it, then moves the client to the head of the queue. | |
| bool | synchronize (ClientID &clientID, double timeout) |
| This member function blocks until all clients of the BroadcastQueue have called it, then moves the client to the head of the queue. | |
| void | synchronizeQuorum (ClientID &clientID, size_t quorumSize) |
| This member function blocks until the specified number of BroadcastQueue clients have called it, then moves the client to the head of the queue. | |
| bool | synchronizeQuorum (ClientID &clientID, size_t quorumSize, double timeout) |
| This member function blocks until the specified number of BroadcastQueue clients have called it, then moves the client to the head of the queue. | |
| void | unlockBack (const ClientID &clientID) |
| This member function releases a read lock acquired by lockBack(). | |
Definition at line 32 of file dataQueue.h.
typedef ClientID<Type> dlr::thread::BroadcastQueue< Type >::ClientID [inherited] |
Each thread that interacts with a particular BroadcastQueue instance must create a ClientID instance, and then register with the BroadcastQueue by calling the registerClient() member function of that BroadcastQueue instance, passing the clientID instance as an argument.
The same ClientID instance must be passed as an argument in subsequent interactions with that BroadcastQueue instance. The ClientID instance identifies the thread to the BroadcastQueue, and simplifies internal bookkeeping.
Definition at line 69 of file broadcastQueue.h.
| void dlr::thread::BroadcastQueue< Type >::catchUp | ( | ClientID & | clientID | ) | [inline, inherited] |
This member function moves the calling thread to the head of the BroadcastQueue.
Its effect is the same as calling popBack() repeatedly until all elements have been popped from the queue. After calling catchUp(), an immediate call to copyBack() is likely to block waiting for a new element to be pushed onto the queue by a producer thread.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). |
Definition at line 794 of file broadcastQueue.h.
References dlr::thread::ClientID< Type >::m_count, and dlr::thread::ClientID< Type >::m_index.
| void dlr::thread::BroadcastQueue< Type >::copyBack | ( | const ClientID & | clientID, | |
| Type & | target | |||
| ) | [inline, inherited] |
This member function copies the tail element of the BroadcastQueue.
Note that each consumer thread has its own idea of which element is the tail of the BroadcastQueue. Repeated calls to copyBack() will copy the same element unless calls to popBack() are made between them. Each consumer is responsible for calling popBack() frequently so that it doesn't fall too far behind in the queue.
If the client is all caught up in the queue, either because of a recent call to member function catchUp() or because it's been doing a good job of calling popBack(), copyBack() will block, waiting for a new element to be copied onto the queue.
If the client has fallen more than (constructor argument) maximumLength elements behind the head of the queue, then copyBack() will throw an OverflowException. For more information on this, please see the documentation in the comment for the BroadcastQueue class.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). | |
| target | This reference argument is used to return a copy of the tail element in the queue. |
Definition at line 807 of file broadcastQueue.h.
References dlr::thread::BroadcastQueue< Type >::lockBack(), dlr::thread::ClientID< Type >::m_index, and dlr::thread::BroadcastQueue< Type >::unlockBack().
| bool dlr::thread::BroadcastQueue< Type >::copyBack | ( | const ClientID & | clientID, | |
| Type & | target, | |||
| double | timeout | |||
| ) | [inline, inherited] |
This member function copies the tail element of the BroadcastQueue.
It is just like void copyBack(const ClientID&, Type&), with the exception that it will not block for longer than the specified timeout.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). | |
| target | This reference argument is used to return a copy of the tail element in the queue. | |
| timeout | This argument specifies the total amount of time that copyBack is permitted to block while waiting for access to the queue and/or waiting for a new element to become available. If timeout is less than or equal to zero then the call will return immediately. |
Definition at line 827 of file broadcastQueue.h.
References dlr::thread::ClientID< Type >::m_index, and dlr::thread::BroadcastQueue< Type >::unlockBack().
| size_t dlr::thread::BroadcastQueue< Type >::getMaximumLength | ( | ) | [inline, inherited] |
This member function returns the length at which the BroadcastQueue instance will begin dropping elements off the tail.
Definition at line 205 of file broadcastQueue.h.
| void dlr::thread::BroadcastQueue< Type >::lockBack | ( | const ClientID & | clientID | ) | [inline, inherited] |
This member function locks the tail element of the BroadcastQueue instance so that it cannot fall off the back of the queue.
By never using this member function, you will avoid many headaches, so please use copyBack() instead if at all possible. Member function lockBack() is provided to handle a few extreme circumstances.
Member function lockBack() will block until the lock is acquired.
An example of a circumstance in which it makes sense to use lockBack() is when the broadcastQueue elements contain pointers or references to data, so that copyBack() gives you a copy of a pointer, but doesn't actually copy the data. Presumably, the producer threads are smart enough not to de-allocate the data until the element drops of the end of the queue, so you can be confident that you're getting a good pointer at the time of the copyBack() call, but there's nothing to stop the element from falling off the queue (and the associated data from being de-allocated) after the call, when the consumer is still trying to access it. In this case, it makes sense to call lockBack() in the following sequence.
myBroadcastQueue.lockBack(myClientID);
myBroadcastQueue.copyBack(myClientID, myLocalElement);
// Code here does read-only access to the referenced data.
myBroadcastQueue.unlockBack(myClientID);
myBroadcastQueue.popBack(myClientID);
Member function copyBack() is smart enough not to deadlock when copying an already-locked element.
Note that the example above calls for read-only access to the allocated data. This is because changing the values of elements on the queue (or of data that is pointed to by elements that are on the queue) makes the interactions between threads much more difficult to think about and debug.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). |
Definition at line 850 of file broadcastQueue.h.
References DLR_THROW, dlr::thread::ClientID< Type >::m_count, and dlr::thread::ClientID< Type >::m_idNumber.
Referenced by dlr::thread::BroadcastQueue< Type >::copyBack().
| bool dlr::thread::BroadcastQueue< Type >::lockBack | ( | const ClientID & | clientID, | |
| double | timeout | |||
| ) | [inline, inherited] |
This member function locks the tail element of the BroadcastQueue instance so that it cannot fall off the back of the queue.
It is just like void lockBack(const ClientID&), with the exception that it will not block for longer than the specified timeout.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). | |
| timeout | This argument controls how long the call to lockBack() will block waiting for the lock to become available. If timeout is less than or equal to zero, then the call to will return immediately. |
Definition at line 903 of file broadcastQueue.h.
References DLR_THROW, dlr::thread::getXTime(), dlr::thread::ClientID< Type >::m_count, and dlr::thread::ClientID< Type >::m_idNumber.
| void dlr::thread::BroadcastQueue< Type >::popBack | ( | ClientID & | clientID | ) | [inline, inherited] |
This member function is called by consumer threads to "discard" one element from the tail of the BroadcastQueue so that subsequent calls to copyBack() will copy the next element in the queue.
Note that each consumer thread has its own idea of which element is the tail of the BroadcastQueue. Each consumer is responsible for calling popBack() frequently so that it doesn't fall too far behind in the queue.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). |
Definition at line 969 of file broadcastQueue.h.
References DLR_THROW, dlr::thread::ClientID< Type >::m_count, dlr::thread::ClientID< Type >::m_idNumber, and dlr::thread::ClientID< Type >::m_index.
| void dlr::thread::BroadcastQueue< Type >::pushFront | ( | const ClientID & | clientID, | |
| const Type & | element | |||
| ) | [inline, inherited] |
This member function is called by producer threads to add elements to the head of the queue.
When the element is added to the queue, it is copied, not referenced. Note that there is only one head of the queue, where as there are as many tails as there are consumer threads. Calls to pushFront() advance the head for all producer threads. Calls to popBack() advance the tail only for the calling thread.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). | |
| element | This argument is the element to be copied onto the head of the BroadcastQueue instance. |
Definition at line 992 of file broadcastQueue.h.
References DLR_THROW, and dlr::thread::ClientID< Type >::m_idNumber.
| void dlr::thread::BroadcastQueue< Type >::registerClient | ( | ClientID & | clientID, | |
| const std::string & | clientName = "anonymous" | |||
| ) | [inline, inherited] |
This member function introduces a thread to a BroadcastQueue instance.
The thread should create a ClientID instance, and then call registerClient() exactly once, passing the ClientID instance as the first argument. This same ClientID instance should be used by the calling thread in subsequent interactions with the BroadcastQueue instance. Using the same ClientID instance to interact with another BroadcastQueue instance (besides *this) is bad, and will have undefined results.
After a call to registerClient(), calling copyBack() will copy the oldest element of the queue: the very first element to have been pushed onto the queue. If the BroadcastQueue instance has been in use for a while, it is likely that this element has already dropped of the end of the queue as described in the comment for the BroadcastQueue class, leading to an OverflowException when copyBack() is called. To avoid this problem, all consumer threads should register with the BroadcastQueue instance before the producers start filling the queue. Alternatively, a consumer that registers late can call catchUp() to move to the head of the queue.
Note that the ClientID class is currently not copyable. This means the client thread should create the ClientID in an outer scope and then pass it by reference into any inner scopes that need access to the BroadcastQueue.
| clientID | This argument is the clientID that will be used to identify the calling thread to the BroadcastQueue in future interactions. | |
| clientName | This argument specifies a name for the thread. It is useful to specify a unique name for each thread that interacts with a BroadcastQueue instance because this will make it easier to debug any exceptions thrown by the BroadcastQueue member functions. |
Definition at line 1075 of file broadcastQueue.h.
References dlr::thread::ClientID< Type >::m_count, dlr::thread::ClientID< Type >::m_idNumber, and dlr::thread::ClientID< Type >::m_index.
| void dlr::thread::BroadcastQueue< Type >::synchronize | ( | ClientID & | clientID | ) | [inline, inherited] |
This member function blocks until all clients of the BroadcastQueue have called it, then moves the client to the head of the queue.
That is, the first thread to call synchronize will block, as will the second, etc. until each of the registered threads has called synchronize(). When the final thread calls synchronize(), all of the calling threads will be unblocked and execution will continue. Prior to the return from synchronize(), each thread will be moved to the head of the queue as described for member function catchUp().
Once the final call to synchronize() has been completed and all threads have been un-blocked, the internal count of clients that have called synchronize() is reset. Subsequent calls to synchronize() will block again as if they were the first, second, etc. until all of the registered clients have called synchronize() a second time. This cycle will repeat indefinitely.
Calling synchronize() while another thread is blocking in synchronizeQuorum() will throw a StateException.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). |
Definition at line 1125 of file broadcastQueue.h.
References DLR_THROW.
| bool dlr::thread::BroadcastQueue< Type >::synchronize | ( | ClientID & | clientID, | |
| double | timeout | |||
| ) | [inline, inherited] |
This member function blocks until all clients of the BroadcastQueue have called it, then moves the client to the head of the queue.
It is just like synchronize(const ClientID&), with the exception that it will not block for longer than the specified timeout.
Calling synchronize() while another thread is blocking in synchronizeQuorum() will throw a StateException.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). | |
| timeout | This argument controls how long the call to synchronize() will block waiting for other threads. If the timeout expires before all of the other threads have called synchronize(), then the return value will be false, and execution will continue as if the calling thread had not called synchronize(). |
Definition at line 1151 of file broadcastQueue.h.
References DLR_THROW, and dlr::thread::getXTime().
| void dlr::thread::BroadcastQueue< Type >::synchronizeQuorum | ( | ClientID & | clientID, | |
| size_t | quorumSize | |||
| ) | [inline, inherited] |
This member function blocks until the specified number of BroadcastQueue clients have called it, then moves the client to the head of the queue.
That is, the first thread to call synchronize will block, as will the second, etc. until each the specified number of threads have called synchronizeQuorum(), at which time all of the blocking threads will be unblocked. Prior to the return from synchronizeQuorum(), each thread will be moved to the head of the queue as described for member function catchUp().
Calling synchronizeQuorum() while another thread is blocking in synchronize() will throw a StateException. Calling synchronizeQuorum() with a different value for argument quorumSize than a thread which is currently blocking in synchronizeQuorum() will also throw a StateException.
If synchronizeQuorum() is called with a quorumSize of zero, then the quorum size will be set to the number of clients currently registered with the BroadcastQueue instance. Note that this has a different effect than just using the synchronize() methods: synchronize() methods will block waiting for new threads to call synchronize() even if those threads were added after the initial call to synchronize(); synchronizeQuorum() will wait only for the number of threads that were registered at the time of the synchronizeQuorum() call. Be careful, though: if a thread calls synchronizeQuorum() with quorumSize set to zero, a new thread is registered with the BroadcastQueue, and then a second thread calls synchronizeQuorum() with quorumSize set to zero, the second call to synchronizeQuorum() will be trying to set a different quorum size than the first, and will throw a StateException as described in the previous paragraph.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). | |
| quorumSize | If this argument is nonzero, then the function call will block only until the specified number of clients have called synchronizeQuorum(). If quorumSize is zero, it will be as if it were set to the number of clients currently registered with the BroadcastQueue. |
Definition at line 1198 of file broadcastQueue.h.
References DLR_THROW.
| bool dlr::thread::BroadcastQueue< Type >::synchronizeQuorum | ( | ClientID & | clientID, | |
| size_t | quorumSize, | |||
| double | timeout | |||
| ) | [inline, inherited] |
This member function blocks until the specified number of BroadcastQueue clients have called it, then moves the client to the head of the queue.
It is just like synchronizeQuorum(const ClientID&), with the exception that it will not block for longer than the specified timeout.
Calling synchronizeQuorum() while another thread is blocking in synchronize() will throw a StateException. Calling synchronizeQuorum() with a different value for argument quorumSize than a thread which is currently blocking in synchronizeQuorum() will also throw a StateException.
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). | |
| quorumSize | If this argument is nonzero, then the function call will block only until the specified number of clients have called synchronizeQuorum(). If quorumSize is zero, it will be as if it were set to the number of clients currently registered with the BroadcastQueue. | |
| timeout | This argument controls how long the call to synchronizeQuorum() will block waiting for other threads. If the timeout expires before all of the other threads have called synchronizeQuorum(), then the return value will be false, and execution will continue as if the calling thread had not called synchronizeQuorum(). |
Definition at line 1232 of file broadcastQueue.h.
References DLR_THROW, and dlr::thread::getXTime().
| void dlr::thread::BroadcastQueue< Type >::unlockBack | ( | const ClientID & | clientID | ) | [inline, inherited] |
This member function releases a read lock acquired by lockBack().
| clientID | This argument identifies the calling thread to the BroadcastQueue. It should have been previously registered with the BroadcastQueue by calling member function registerClient(). |
Definition at line 1286 of file broadcastQueue.h.
References dlr::thread::ClientID< Type >::m_idNumber, and dlr::thread::ClientID< Type >::m_index.
Referenced by dlr::thread::BroadcastQueue< Type >::copyBack().
1.5.2