All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Private Member Functions | Private Attributes | List of all members
SurgSim::Framework::LockedContainer< T > Class Template Reference

A simple thread-safe data container that can support multiple writers and readers. More...

#include <SurgSim/Framework/LockedContainer.h>

Collaboration diagram for SurgSim::Framework::LockedContainer< T >:
Collaboration graph
[legend]

Public Member Functions

 LockedContainer ()
 Create the container and the data it contains. More...
 
 LockedContainer (const T &initialValue)
 Create the container and the data it contains. More...
 
 LockedContainer (T &&initialValue)
 Create the container and the data it contains. More...
 
 ~LockedContainer ()
 Destroy the container and the data it contains. More...
 
void set (const T &value)
 Write (copy) new data into the container. More...
 
void set (T &&value)
 Write (move) new data into the container. More...
 
void get (T *value) const
 Read (copy) the data from the container. More...
 
void take (T *value)
 Move the data out of the container. More...
 
bool tryGetChanged (T *value) const
 Read (copy) the data from the container if it has been modified since the last access. More...
 
bool tryTakeChanged (T *value)
 Move the data out of the container if it has been modified since the last access. More...
 

Private Member Functions

 LockedContainer (const LockedContainer &)
 Prevent copying. More...
 
LockedContaineroperator= (const LockedContainer &)
 Prevent assignment. More...
 

Private Attributes

m_buffer
 Internal buffer. More...
 
bool m_haveNewData
 True if there data that has been written, but not yet pulled in by get, take, etc. More...
 
boost::mutex m_mutex
 Mutex for synchronization of set() and get() calls. More...
 

Detailed Description

template<typename T>
class SurgSim::Framework::LockedContainer< T >

A simple thread-safe data container that can support multiple writers and readers.

The type of the contained data is determined by the template argument, and should satisfy the following:

Note that STL container types, plain-old-data structs, and most other things you might want to use satisfy those requirements.

The container will create and manage an extra internal instance of the data object.

The interface has been designed to be incredibly simple. The trade-off is that the overhead of reading or writing to the container is significant (Each write incurs either a copy or a move of the data, plus a mutex lock/unlock. Each read incurs a copy, plus a mutex lock/unlock. Applications that write and read heavily may also become mutex-bound.)

Writers write the data by calling the set method, which copies or moves the data into internal storage. Readers read the data by calling the get method, which copies the data from internal storage.

Template Parameters
TType of the data held by the LockedContainer.

Constructor & Destructor Documentation

template<typename T>
SurgSim::Framework::LockedContainer< T >::LockedContainer ( )
inline

Create the container and the data it contains.

The data will be initialized using the default constructor.

template<typename T>
SurgSim::Framework::LockedContainer< T >::LockedContainer ( const T &  initialValue)
inlineexplicit

Create the container and the data it contains.

The data will be initialized using the copy constructor.

Parameters
initialValueThe initial value to be used.
template<typename T>
SurgSim::Framework::LockedContainer< T >::LockedContainer ( T &&  initialValue)
inlineexplicit

Create the container and the data it contains.

The data in the active buffer will be initialized using the move constructor. The data in the second, inactive buffer will be initialized using the default constructor.

Parameters
initialValueThe initial value to be moved into the active buffer.
template<typename T>
SurgSim::Framework::LockedContainer< T >::~LockedContainer ( )
inline

Destroy the container and the data it contains.

template<typename T>
SurgSim::Framework::LockedContainer< T >::LockedContainer ( const LockedContainer< T > &  )
private

Prevent copying.

Member Function Documentation

template<typename T>
void SurgSim::Framework::LockedContainer< T >::get ( T *  value) const
inline

Read (copy) the data from the container.

Parameters
[out]valueThe location to write the data from the container. The pointer must be non-null.
template<typename T>
LockedContainer& SurgSim::Framework::LockedContainer< T >::operator= ( const LockedContainer< T > &  )
private

Prevent assignment.

template<typename T>
void SurgSim::Framework::LockedContainer< T >::set ( const T &  value)
inline

Write (copy) new data into the container.

The data will be copied into internal storage. If set is called again before the next get, the first data will be overwritten and lost.

Parameters
valueThe value to be written.
template<typename T>
void SurgSim::Framework::LockedContainer< T >::set ( T &&  value)
inline

Write (move) new data into the container.

The data will be moved into internal storage. If set is called again before the next get, the first data will be overwritten and lost.

Parameters
valueThe value to be written.
template<typename T>
void SurgSim::Framework::LockedContainer< T >::take ( T *  value)
inline

Move the data out of the container.

For types that support move assignment, the internal state of the container will be invalidated.

Parameters
[out]valueThe location to write the data from the container. The pointer must be non-null.
template<typename T>
bool SurgSim::Framework::LockedContainer< T >::tryGetChanged ( T *  value) const
inline

Read (copy) the data from the container if it has been modified since the last access.

If set has not been called since the last get, take, tryGetChanged or tryTakeChanged, the method returns false and doesn't modify the data.

Parameters
[out]valueThe location to write the data from the container if it has changed. The pointer must be non-null.
Returns
true if there was new data (which may or may not be equal to the old). Note that the initial value created when the object was constructed (if any) is not considered "new" data by this method.
template<typename T>
bool SurgSim::Framework::LockedContainer< T >::tryTakeChanged ( T *  value)
inline

Move the data out of the container if it has been modified since the last access.

If set has not been called since the last get, take, tryGetChanged or tryTakeChanged, the method returns false and doesn't modify the data.

Parameters
[out]valueThe location to write the data from the container if it has changed. The pointer must be non-null.
Returns
true if there was new data (which may or may not be equal to the old). Note that the initial value created when the object was constructed (if any) is not considered "new" data by this method.

Member Data Documentation

template<typename T>
T SurgSim::Framework::LockedContainer< T >::m_buffer
private

Internal buffer.

template<typename T>
bool SurgSim::Framework::LockedContainer< T >::m_haveNewData
mutableprivate

True if there data that has been written, but not yet pulled in by get, take, etc.

template<typename T>
boost::mutex SurgSim::Framework::LockedContainer< T >::m_mutex
mutableprivate

Mutex for synchronization of set() and get() calls.


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