Class template monitor

poet::monitor — A wrapper which provides automatically locked access to an object.

Synopsis

template<typename T, typename Mutex = boost::mutex> 
class monitor {
public:
  // types
  typedef T     element_type;
  typedef Mutex mutex_type;  

  // construct/copy/destruct
  monitor();
  monitor(const T &);
  monitor(const monitor &);
  template<typename U, typename M> monitor(const monitor<U, M> &);
  template<typename U1, typename U2, typename ..., typename UN> 
    monitor(U1, U2, ..., UN);
  template<typename U, typename M> 
    monitor<T, Mutex> & operator=(const monitor<U, M> &);
  monitor& operator=(const monitor &);
  virtual ~monitor();

  // public member functions
  const monitor_ptr<T, Mutex> & get_monitor_ptr();
  monitor_ptr<const T, Mutex> get_monitor_ptr() const;
  monitor_unique_lock<monitor> operator->();
  monitor_unique_lock<const monitor> operator->() const;
  template<typename M> void swap(monitor<T, M> &);

  // Boost.Thread Lockable concept support
  void lock() const;
  bool try_lock() const;
  void unlock() const;

  // Boost.Thread TimedLockable concept support
  template<typename Timeout> bool timed_lock(const Timeout &) const;

  // Boost.Thread SharedLockable concept support
  void lock_shared() const;
  bool try_lock_shared() const;
  template<typename Timeout> bool timed_lock_shared(const Timeout &) const;
  void unlock_shared() const;
  void unlock_and_lock_shared() const;

  // Boost.Thread UpgradeLockable concept support
  void lock_upgrade() const;
  void unlock_upgrade() const;
  void unlock_upgrade_and_lock() const;
  void unlock_upgrade_and_lock_shared() const;
  void unlock_and_lock_upgrade() const;
};

// free function: swap
template<typename T, typename Mutex> 
  void swap(monitor<T, Mutex> &, monitor<T, Mutex> &);

Description

monitor allows for the easy creation of monitor objects. A monitor provides automatically locked access to its contained object's members when they are accessed through the overloaded operator->, or alternatively through one of the lock classes from poet/monitor_locks.hpp. It is similar to a monitor_ptr, except it behaves like a value instead of a smart pointer when copied. Copies of a monitor object are deep copies with independent values, and do not share the same mutex/condition.

Although any object may be wrapped in a monitor, special support is provided for classes derived from monitor_base. This allows classes derived from monitor_base to wait on conditions inside member function calls, releasing the monitor's mutex until the condition is satisfied.

The Mutex template type parameter must model the Lockable concept from the Boost.Thread library. The monitor itself models the Lockable concept, and will also model any of the TimedLockable, SharedLockable, or UpgradeLockable concepts if the underlying Mutex template type supports them.

The interfaces defined by the Boost.Thread mutex concepts should generally not be used directly by the user. They are intended to be used by scoped lock classes such as monitor_unique_lock, which provide a safer means to perform locking. See the "Mutex Concepts" documentation in the Boost.Thread library for more information about the Lockable, etc. concepts.

It is possible to obtain monitor_ptrs from a monitor which shares ownership/mutex/condition and points at the value wrapped in a monitor object, via the get_monitor_ptr method. The value wrapped in a monitor object will not be destructed until the last such monitor_ptr is destroyed, along with the monitor object containing it, and any locks from poet/monitor_locks.hpp which reference it.

Example Code

monitor_demo.cpp

See also

monitor_ptr: a pointer-like alternative to the monitor class.

`monitor` public construct/copy/destruct

```
monitor();
```
Creates a monitor with a default-constructed value.
```
monitor(const T & value);
```
Creates a monitor which contains a value copy-constructed from the constructor's argument.
```
monitor(const monitor & other);
```
The copy constructor creates a monitor whose contained value is copy-constructed from the value contained in the other parameter. other is locked while its value is copied out.
```
template<typename U, typename M> monitor(const monitor<U, M> & other);
```
Creates a monitor whose contained value is copy-constructed from the value contained in the other parameter. The type U must be implicitly convertible to type T. other is locked while its value is copied out.
```
template<typename U1, typename U2, typename ..., typename UN> 
  monitor(U1 arg1, U2 arg2, ..., UN argN);
```
Creates a monitor by forwarding the constructor's arguments to the constructor for the contained value. If you need to pass a reference to the contained value's constructor, you should wrap it in a boost::reference_wrapper to prevent it from being automatically converted to a value.

If you wish to change the maximum number of arguments this family of constructors can take from its default value of 10, you may define the macro POET_MONITOR_MAX_CONSTRUCTOR_ARGS to your desired value prior to including monitor.hpp.

template<typename U, typename M> 
  monitor<T, Mutex> & operator=(const monitor<U, M> & rhs);

Copies the contained value of type U from rhs into *this.

The mutexes of both *this and rhs are locked before the assignment is performed. The mutexes are locked by trying each of the two possible locking orders until both mutexes are successfully locked. This avoids any possibility of deadlock due to locking order violation, but may produce false positives when using debugging tools such as acyclic_mutex.

Copies of a monitor object are deep copies, which do not share the same mutex or condition.

Requires:

The template type U of rhs must be implicitly convertible into the template type T of *this.

```
monitor& operator=(const monitor & rhs);
```
Same as the templated assignment operator. This overload is provided to prevent a default assignment operator from being generated.
```
virtual ~monitor();
```

`monitor` public member functions

```
const monitor_ptr<T, Mutex> & get_monitor_ptr();
monitor_ptr<const T, Mutex> get_monitor_ptr() const;
```
The get_monitor_ptr method can be used to obtain a monitor_ptr which shares ownership/mutex/condition with *this.
```
monitor_unique_lock<monitor> operator->();
monitor_unique_lock<const monitor> operator->() const;
```
Returns a temporary monitor_unique_lock which locks the monitor's mutex. The operator->() of the returned monitor_unique_lock object will be automatically called in turn (overloading operator->() is special in that way), which will utimately result in a call of operator->() on a pointer to the monitor's contained object. The mutex is automatically unlocked after the member access completes by the monitor_unique_lock destructor.

If more flexibility is desired, the lock types from poet/monitor_locks.hpp provide alternatives to monitor::operator->.
```
template<typename M> void swap(monitor<T, M> & other);
```
Swaps the wrapped values of *this and other. Only the wrapped values of the two monitors are swapped, not their mutexes or condition variables.

The mutexes of both monitors are locked before their values are swapped. The mutexes are locked by trying each of the two possible locking orders until both mutexes are successfully locked. This avoids any possibility of deadlock due to locking order violation, but may produce false positives when using debugging tools such as acyclic_mutex.

`monitor` Boost.Thread Lockable concept support

```
void lock() const;
```
```
bool try_lock() const;
```
```
void unlock() const;
```

`monitor` Boost.Thread TimedLockable concept support

template<typename Timeout> bool timed_lock(const Timeout & t) const;

`monitor` Boost.Thread SharedLockable concept support

```
void lock_shared() const;
```
```
bool try_lock_shared() const;
```

template<typename Timeout> bool timed_lock_shared(const Timeout & t) const;

```
void unlock_shared() const;
```
```
void unlock_and_lock_shared() const;
```

`monitor` Boost.Thread UpgradeLockable concept support

```
void lock_upgrade() const;
```
```
void unlock_upgrade() const;
```
```
void unlock_upgrade_and_lock() const;
```

void unlock_upgrade_and_lock_shared() const;

```
void unlock_and_lock_upgrade() const;
```

`monitor` free function: swap

template<typename T, typename Mutex> 
  void swap(monitor<T, Mutex> & monitor0, monitor<T, Mutex> & monitor1);

Swaps the values of monitor0 and monitor1. This function is provided to enhance efficiency with generic algorithms.

Effects:

monitor0.swap(monitor1);