SurgSim::Framework::LockedContainer< T > Class Template Reference

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

#include <LockedContainer.h>

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.
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...

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:

• It must be either default-constructable or copy-constructable or move-constructable. In other words, construction must be possible using either T() or T(const T&) or T(T&&), or compiler-generated equivalents.
• It must be either copy-assignable or move-assignable. In other words, assignment must be possible using either operator=(const T&) or operator=(T&&), or compiler-generated equivalents. (If it is only move-assignable, then you can't get the value in the container without erasing it.)

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

T	Type of the data held by the LockedContainer.

Constructor & Destructor Documentation

LockedContainer() [1/3]

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.

LockedContainer() [2/3]

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

initialValue

The initial value to be used.

LockedContainer() [3/3]

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

initialValue

The initial value to be moved into the active buffer.

Member Function Documentation

get()

template<typename T>

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

inline

Read (copy) the data from the container.

Parameters

[out]

value

The location to write the data from the container. The pointer must be non-null.

set() [1/2]

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

value

The value to be written.

set() [2/2]

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

value

The value to be written.

take()

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]

value

The location to write the data from the container. The pointer must be non-null.

tryGetChanged()

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]

value

The 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.

tryTakeChanged()

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]

value

The 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.

---

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

• SurgSim/Framework/LockedContainer.h