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

## 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...
LockedContainer & | operator= (const LockedContainer &)
| Prevent assignment. More...

## Private Attributes

T | 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:

- 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/4]

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/4]

template<typename T>

SurgSim::Framework::LockedContainer< T >::LockedContainer | ( | const T & | initialValue | ) |

inline explicit

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/4]

template<typename T>

SurgSim::Framework::LockedContainer< T >::LockedContainer | ( | T && | initialValue | ) |

inline explicit

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.

## ~LockedContainer()

template<typename T>

SurgSim::Framework::LockedContainer< T >::~LockedContainer | ( |  | ) |

inline

Destroy the container and the data it contains.

## LockedContainer() [4/4]

template<typename T>

SurgSim::Framework::LockedContainer< T >::LockedContainer | ( | const LockedContainer< T > & |  | ) |

private

Prevent copying.

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

## operator=()

template<typename T>

LockedContainer& SurgSim::Framework::LockedContainer< T >::operator= | ( | const LockedContainer< T > & |  | ) |

private

Prevent assignment.

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

## Member Data Documentation

## m_buffer

template<typename T>

T SurgSim::Framework::LockedContainer< T >::m_buffer

private

Internal buffer.

## m_haveNewData

template<typename T>

bool SurgSim::Framework::LockedContainer< T >::m_haveNewData

mutable private

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

## m_mutex

template<typename T>

boost::mutex SurgSim::Framework::LockedContainer< T >::m_mutex

mutable private

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

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

- SurgSim/Framework/LockedContainer.h