Class template monitor_shared

Class template monitor_shared_lock

poet::monitor_shared_lock — shared_lock with monitor object access

Synopsis

template<typename MonitorType> 
class monitor_shared_lock {
public:
  // types
  typedef MonitorType               monitor_type;
  typedef MonitorType::element_type element_type;  // will additionally be const-qualified if MonitorType is "const monitor<T>"

  // construct/copy/destruct
  explicit monitor_shared_lock(MonitorType &);
  template<typename T> monitor_shared_lock(MonitorType &, const T &);
  monitor_shared_lock(boost::detail::thread_move_t<monitor_shared_lock>);
  monitor_shared_lock(boost::detail::thread_move_t<monitor_upgrade_lock<MonitorType> >);
  monitor_shared_lock(boost::detail::thread_move_t<monitor_unique_lock<MonitorType> >);
  monitor_shared_lock();
  ~monitor_shared_lock();

  // public boost::shared_lock interface
  void lock();
  boost::detail::thread_move_t<monitor_shared_lock> move();
  MonitorType * mutex() const;
  monitor_shared_lock & 
  operator=(boost::detail::thread_move_t<monitor_shared_lock>);
  monitor_shared_lock & 
  operator=(boost::detail::thread_move_t<monitor_upgrade_lock>);
  monitor_shared_lock & 
  operator=(boost::detail::thread_move_t<monitor_unique_lock>);
  bool operator!() const;
   operator boost::detail::thread_move_t<monitor_shared_lock>();
   operator unspecified_bool_type() const;
  bool owns_lock() const;
  MonitorType * release();
  void swap(monitor_shared_lock &);
  template<typename Timeout> bool timed_lock(const Timeout &);
  bool try_lock();
  void unlock();

  // public member functions
  const element_type * operator->() const;
  const element_type & operator*() const;
private:
  // construct/copy/destruct
  monitor_shared_lock(monitor_shared_lock &);
  monitor_shared_lock& operator=(monitor_shared_lock &);
};

// free functions
template<typename Monitor> 
  boost::detail::thread_move_t<monitor_shared_lock<Monitor> > 
  move(monitor_shared_lock<Monitor> &);
template<typename Monitor> 
  void swap(monitor_shared_lock<Monitor> &, monitor_shared_lock<Monitor> &);

Description

monitor_shared_lock is an extension of boost::shared_lock from the Boost.Thread library. It extends the interface of boost::shared_lock by adding operator-> and operator* methods, which permit access to the object protected by the lock's associated monitor. This tight coupling of locking with access helps insure the monitor's mutex is always locked when the object it is protecting is accessed.

Unlike monitor_unique_lock, the operator-> and operator* of monitor_shared_lock only permit const access to the associated object. This helps prevent unintended modification of the object while only holding a shared_lock.

The MonitorType template type parameter may be one of the monitor or monitor_ptr types.

See the documentation of boost::shared_lock in the Boost.Thread library for more information about the shared_lock interface.

`monitor_shared_lock` public construct/copy/destruct

```
explicit monitor_shared_lock(MonitorType & mon);
```
Calls lock(), acquiring shared ownership of mon (in the sense of a lock having ownership of a mutex).

Internally, the monitor_shared_lock stores a monitor_ptr to use as a reference to the object protected by the mon argument. Thus the monitor_shared_lock shares ownership (in the shared_ptr sense) and may safely outlive the mon object.
```
template<typename T> monitor_shared_lock(MonitorType & mon, const T & arg);
```
This constructor corresponds to all the 2 argument constructors of boost::shared_lock. The second argument may thus be of type boost::adopt_lock_t, boost::defer_lock_t, boost::try_to_lock_t, or boost::system_time.

monitor_shared_lock(boost::detail::thread_move_t<monitor_shared_lock> other);

Move constructor.

monitor_shared_lock(boost::detail::thread_move_t<monitor_upgrade_lock<MonitorType> > other);

Move constructor.

monitor_shared_lock(boost::detail::thread_move_t<monitor_unique_lock<MonitorType> > other);

Move constructor. The unique_lock is downgraded to a shared_lock as it is moved into *this.

```
monitor_shared_lock();
```
The default constructor creates an empty lock that is not associated with any monitor object. The empty lock can only be made useful by moving another another lock into it.
```
~monitor_shared_lock();
```
If owns_lock(), calls unlock().

`monitor_shared_lock` public boost::shared_lock interface

```
void lock();
```

boost::detail::thread_move_t<monitor_shared_lock> move();

```
MonitorType * mutex() const;
```

monitor_shared_lock & 
operator=(boost::detail::thread_move_t<monitor_shared_lock>);

monitor_shared_lock & 
operator=(boost::detail::thread_move_t<monitor_upgrade_lock>);

monitor_shared_lock & 
operator=(boost::detail::thread_move_t<monitor_unique_lock>);

```
bool operator!() const;
```

 operator boost::detail::thread_move_t<monitor_shared_lock>();

 operator unspecified_bool_type() const;

```
bool owns_lock() const;
```
```
MonitorType * release();
```
```
void swap(monitor_shared_lock & other);
```

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

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

`monitor_shared_lock` public member functions

const element_type * operator->() const;

Provides const access to the members of the object protected by the lock's associated monitor.

Throws:

boost::lock_error if owns_lock() != true.

const element_type & operator*() const;

Provides const access to the object protected by the lock's associated monitor.

Throws:

boost::lock_error if owns_lock() != true.

`monitor_shared_lock` private construct/copy/destruct

monitor_shared_lock(monitor_shared_lock & other);

Locks are moveable but not copyable.

monitor_shared_lock& operator=(monitor_shared_lock & other);

Locks are moveable but not copyable.

`monitor_shared_lock` free functions

template<typename Monitor> 
  boost::detail::thread_move_t<monitor_shared_lock<Monitor> > 
  move(monitor_shared_lock<Monitor> & lock);

Returns:

lock.move()

template<typename Monitor> 
  void swap(monitor_shared_lock<Monitor> & lock_a, 
            monitor_shared_lock<Monitor> & lock_b);

Effects:

lock_a.swap(lock_b)