Cgu::Thread::RWLock::WriterTrackLock Class Reference

A scoped locking class for exception safe RWLock write locking which tracks the status of its read-write lock.. More...

`#include <c++-gtk-utils/rw_lock.h>`

## Public Member Functions

| WriterTrackLock (const RWLock::WriterTrackLock &)=delete
RWLock::WriterTrackLock & | operator= (const RWLock::WriterTrackLock &)=delete
int | lock () noexcept
int | trylock () noexcept
int | unlock () noexcept
bool | is_owner () const noexcept
| WriterTrackLock (RWLock &rw_lock_) noexcept
| WriterTrackLock (RWLock &rw_lock_, Locked tag) noexcept
| WriterTrackLock (RWLock &rw_lock_, DeferLock tag) noexcept
| WriterTrackLock ()=delete
| ~WriterTrackLock ()

## Detailed Description

A scoped locking class for exception safe RWLock write locking which tracks the status of its read-write lock..

See also
  Thread::RWLock Thread::RWLock::WriterLock Thread::RWLock::ReaderLock Thread::RWLock::ReaderTrackLock Thread::Thread

This class is similar to a RWLock::WriterLock object, except that it tracks whether the read-write lock it manages is locked for writing by the thread creating the RWLock::WriterTrackLock object (provided that, while the RWLock::WriterTrackLock object exists, the thread creating it only accesses the managed read-write lock for write-locking through that object). This enables RWLock::WriterTrackLock::unlock() to be used without it being followed later by a call to RWLock::WriterTrackLock::lock() or a successful call to RWLock::WriterTrackLock::trylock(), and also permits locking to be deferred until after construction of the RWLock::WriterTrackLock object. Note that only one thread may call the methods of any one RWLock::WriterTrackLock object, including causing its destructor to be invoked.

## Constructor & Destructor Documentation

## WriterTrackLock() [1/5]

Cgu::Thread::RWLock::WriterTrackLock::WriterTrackLock | ( | const RWLock::WriterTrackLock & |  | ) |

delete

This class cannot be copied. The copy constructor is deleted.

## WriterTrackLock() [2/5]

Cgu::Thread::RWLock::WriterTrackLock::WriterTrackLock | ( | RWLock & | rw_lock_ | ) |

inline noexcept

This constructor locks for writing the read-write lock passed to it. It is not a cancellation point. It does not throw.

Parameters

  rw_lock_ | The read-write lock to be locked for writing.

## WriterTrackLock() [3/5]

Cgu::Thread::RWLock::WriterTrackLock::WriterTrackLock | ( | RWLock & | rw_lock_,
|  | Locked | tag
| ) |  |

inline noexcept

This constructor takes a read-write lock already locked for writing (say as a result of RWLock::writer_trylock()), and takes ownership of it. It is not a cancellation point. It does not throw.

Parameters

  rw_lock_ | The read-write lock to be managed for writing by this object.
  tag | Pass the Cgu::Thread::locked enum tag to this parameter.

## WriterTrackLock() [4/5]

Cgu::Thread::RWLock::WriterTrackLock::WriterTrackLock | ( | RWLock & | rw_lock_,
|  | DeferLock | tag
| ) |  |

inline noexcept

This constructor defers locking of the read-write lock for writing until an explicit call to lock() or trylock() is made. It is not a cancellation point. It does not throw.

Parameters

  rw_lock_ | The read-write lock to be managed for writing by this object.
  tag | Pass the Cgu::Thread::defer enum tag to this parameter.

## WriterTrackLock() [5/5]

Cgu::Thread::RWLock::WriterTrackLock::WriterTrackLock | ( |  | ) |

delete

This class requires initialisation with a RWLock. The default constructor is deleted.

## ~WriterTrackLock()

Cgu::Thread::RWLock::WriterTrackLock::~WriterTrackLock | ( |  | ) |

inline

The destructor unlocks the read-write lock which is managed for writing if it is owned by this RWLock::WriterTrackLock object. It is not a cancellation point. It does not throw.

## Member Function Documentation

## is_owner()

bool Cgu::Thread::RWLock::WriterTrackLock::is_owner | ( |  | ) | const

inline noexcept

Indicates whether the read-write lock managed by this RWLock::ReaderTrackLock object is locked for writing by it and so owned by it. It does not throw.

Returns
  true if the read-write lock is owned by this object, otherwise false.

## lock()

int Cgu::Thread::RWLock::WriterTrackLock::lock | ( |  | ) |

inline noexcept

Calls RWLock::writer_lock(), and so locks the read-write lock for writing and acquires ownership. It blocks if the read-write lock is already locked for reading or writing until it becomes free. This method should normally only be called if a previous call has been made to RWLock::WriterTrackLock::unlock() or this RWLock::WriterTrackLock object has been constructed with the Thread::defer enum tag. It is not a cancellation point. It does not throw.

Returns
  0 if successful, otherwise the pthread read-write lock error number.

Note
  With this library implementation, the only pthread error number which could be returned by this method is EDEADLK, which it would do if the default pthread reader lock behaviour happens to return that error rather than deadlock where the thread calling this method already holds a read lock or write lock on the particular read-write lock in question. Most default implementations do not do this (they just deadlock) and hence the return value is usually not worth checking for except during debugging.

## operator=()

RWLock::WriterTrackLock& Cgu::Thread::RWLock::WriterTrackLock::operator= | ( | const RWLock::WriterTrackLock & |  | ) |

delete

This class cannot be copied. The assignment operator is deleted.

## trylock()

int Cgu::Thread::RWLock::WriterTrackLock::trylock | ( |  | ) |

inline noexcept

Calls RWLock::writer_trylock(), and so tries to lock the read-write lock for writing and acquire ownership, but returns immediately with value EBUSY if it is already locked for reading or writing. This method should normally only be called if a previous call has been made to RWLock::WriterTrackLock::unlock() or this RWLock::WriterTrackLock object has been constructed with the Thread::defer enum tag. It is not a cancellation point. It does not throw.

Returns
  0 if successful, otherwise EBUSY.

Note
  With this library implementation, the only pthread error number which could be returned by this method is EBUSY.

## unlock()

int Cgu::Thread::RWLock::WriterTrackLock::unlock | ( |  | ) |

inline noexcept

Calls RWLock::unlock(), and so unlocks a locked read-write lock owned by the calling thread for writing and relinquishes ownership. It will cause is_owner() to return false unless a subsequent call is made to lock() or a subsequent successful call is made to trylock(). It is not a cancellation point. It does not throw.

Returns
  0 if successful, otherwise the pthread read-write lock error number.

Note
  With this library implementation, the only pthread error number which could be returned by this method is EPERM because the calling thread does hold a lock on the particular read-write lock in question (however POSIX does not require that return value in that case and hence the return value is usually not worth checking for except during debugging).

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

- rw_lock.h