Cgu::Thread::Mutex::TrackLock Class Reference

A scoped locking class for exception safe Mutex locking which tracks the status of its mutex. More...

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

## Public Member Functions

| TrackLock (const Mutex::TrackLock &)=delete
Mutex::TrackLock & | operator= (const Mutex::TrackLock &)=delete
int | lock () noexcept
int | trylock () noexcept
int | unlock () noexcept
bool | is_owner () const noexcept
| TrackLock (Mutex &mutex_) noexcept
| TrackLock (Mutex &mutex_, Locked tag) noexcept
| TrackLock (Mutex &mutex_, DeferLock tag) noexcept
| TrackLock ()=delete
| ~TrackLock ()

## Friends

class | Cond

## Detailed Description

A scoped locking class for exception safe Mutex locking which tracks the status of its mutex.

See also
  Thread::Mutex Thread::Mutex::Lock Thread::Thread Thread::Cond

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

## Constructor & Destructor Documentation

## TrackLock() [1/5]

Cgu::Thread::Mutex::TrackLock::TrackLock | ( | const Mutex::TrackLock & |  | ) |

delete

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

## TrackLock() [2/5]

Cgu::Thread::Mutex::TrackLock::TrackLock | ( | Mutex & | mutex_ | ) |

inline noexcept

This constructor locks the mutex passed to it. It is not a cancellation point. It does not throw.

Parameters

  mutex_ | The mutex to be locked.

## TrackLock() [3/5]

Cgu::Thread::Mutex::TrackLock::TrackLock | ( | Mutex & | mutex_,
|  | Locked | tag
| ) |  |

inline noexcept

This constructor takes an already locked mutex (say as a result of Mutex::trylock()), and takes ownership of it. It is not a cancellation point. It does not throw.

Parameters

  mutex_ | The mutex to be managed by this object.
  tag | Pass the Cgu::Thread::locked enum tag to this parameter.

## TrackLock() [4/5]

Cgu::Thread::Mutex::TrackLock::TrackLock | ( | Mutex & | mutex_,
|  | DeferLock | tag
| ) |  |

inline noexcept

This constructor defers locking of the mutex (and so taking ownership of it) until an explicit call to lock() or trylock() is made. It is not a cancellation point. It does not throw.

Parameters

  mutex_ | The mutex to be managed by this object.
  tag | Pass the Cgu::Thread::defer enum tag to this parameter.

## TrackLock() [5/5]

Cgu::Thread::Mutex::TrackLock::TrackLock | ( |  | ) |

delete

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

## ~TrackLock()

Cgu::Thread::Mutex::TrackLock::~TrackLock | ( |  | ) |

inline

The destructor unlocks the managed mutex if it is locked. It is not a cancellation point. It does not throw.

## Member Function Documentation

## is_owner()

bool Cgu::Thread::Mutex::TrackLock::is_owner | ( |  | ) | const

inline noexcept

Indicates whether the mutex managed by this Mutex::TrackLock object is locked, and so owned, by it. It does not throw.

Returns
  true if the mutex is locked by this object, otherwise false.

## lock()

int Cgu::Thread::Mutex::TrackLock::lock | ( |  | ) |

inline noexcept

Calls Mutex::lock(), and so locks the mutex and acquires ownership. It blocks if the mutex is already locked until the mutex becomes free. This method should normally only be called if a previous call has been made to Mutex::TrackLock::unlock() or this Mutex::TrackLock 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 mutex 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 mutex behaviour happens to return that error rather than deadlock in the case of recursive locking. Most default implementations do not do this and hence the return value is usually not worth checking for except during debugging.

## operator=()

Mutex::TrackLock& Cgu::Thread::Mutex::TrackLock::operator= | ( | const Mutex::TrackLock & |  | ) |

delete

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

## trylock()

int Cgu::Thread::Mutex::TrackLock::trylock | ( |  | ) |

inline noexcept

Calls Mutex::trylock(), and so tries to lock the mutex and acquire ownership, but returns immediately if it is already locked with value EBUSY. This method should normally only be called if a previous call has been made to Mutex::TrackLock::unlock() or this Mutex::TrackLock 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::Mutex::TrackLock::unlock | ( |  | ) |

inline noexcept

Calls Mutex::unlock(), and so unlocks a locked mutex owned by the calling thread. 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 mutex 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 not own the mutex (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).

## Friends And Related Function Documentation

## Cond

friend class Cond

friend

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

- mutex.h