dlib C++ Library - auto_mutex_extension_abstract.h

// Copyright (C) 2005 Davis E. King (davis@dlib.net)
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_AUTO_MUTEX_EXTENSIOn_ABSTRACT_
#ifdef DLIB_AUTO_MUTEX_EXTENSIOn_ABSTRACT_
#include "threads_kernel_abstract.h"
#include "rmutex_extension_abstract.h"
#include "read_write_mutex_extension_abstract.h"
namespace dlib
{
// ----------------------------------------------------------------------------------------
 class auto_mutex
 {
 /*!
 INITIAL VALUE
 The mutex given in the constructor is locked and associated with this 
 object.
 WHAT THIS OBJECT REPRESENTS
 This object represents a mechanism for automatically locking and unlocking
 a mutex object.
 !*/
 public:
 explicit auto_mutex (
 const mutex& m
 );
 /*!
 ensures
 - #*this is properly initialized
 - m will be locked
 !*/
 explicit auto_mutex (
 const rmutex& m
 );
 /*!
 ensures
 - #*this is properly initialized
 - m will be locked
 !*/
 explicit auto_mutex (
 const read_write_mutex& m
 );
 /*!
 ensures
 - #*this is properly initialized
 - m will be locked via m.lock() (i.e. a write lock will be obtained)
 !*/
 void unlock(
 );
 /*!
 ensures
 - if (unlock() has not already been called) then
 - The mutex associated with *this has been unlocked. This is useful if
 you want to unlock a mutex before the auto_mutex destructor executes.
 !*/
 ~auto_mutex (
 );
 /*!
 ensures
 - all resources allocated by *this have been freed
 - calls unlock()
 !*/
 private:
 // restricted functions
 auto_mutex(auto_mutex&); // copy constructor
 auto_mutex& operator=(auto_mutex&); // assignment operator
 };
// ----------------------------------------------------------------------------------------
 class auto_mutex_readonly
 {
 /*!
 INITIAL VALUE
 The mutex given in the constructor is locked using a read-only lock and
 associated with this object.
 WHAT THIS OBJECT REPRESENTS
 This object represents a mechanism for automatically locking and unlocking
 a read_write_mutex object. In particular, a readonly lock is used.
 !*/
 public:
 explicit auto_mutex_readonly (
 const read_write_mutex& m
 );
 /*!
 ensures
 - #*this is properly initialized
 - a readonly lock will be obtained on m using m.lock_readonly()
 - #has_read_lock() == true
 !*/
 ~auto_mutex_readonly (
 );
 /*!
 ensures
 - all resources allocated by *this have been freed
 - the mutex associated with *this has been unlocked
 !*/
 bool has_read_lock (
 );
 /*!
 ensures
 - returns true if this object has called read_write_mutex::lock_readonly()
 on its associated mutex and has yet to release that lock.
 !*/
 bool has_write_lock (
 ); 
 /*!
 ensures
 - returns true if this object has called read_write_mutex::lock() on its
 associated mutex and has yet to release that lock.
 !*/
 void lock_readonly (
 );
 /*!
 ensures
 - This function converts the lock on the associated mutex into a readonly lock.
 Specifically:
 if (!has_read_lock()) then
 - if (has_write_lock()) then
 - unlocks the associated mutex and then relocks it by calling
 read_write_mutex::lock_readonly()
 - else
 - locks the associated mutex by calling read_write_mutex::lock_readonly()
 - #has_read_lock() == true
 - Note that the lock switch is not atomic. This means that whatever
 resource is protected by the mutex might have been modified during the
 call to lock_readonly().
 !*/
 void lock_write (
 );
 /*!
 ensures
 - This function converts the lock on the associated mutex into a write lock.
 Specifically:
 if (!has_write_lock()) then
 - if (has_read_lock()) then
 - unlocks the associated mutex and then relocks it by calling
 read_write_mutex::lock()
 - else
 - locks the associated mutex by calling read_write_mutex::lock()
 - #has_write_lock() == true
 - Note that the lock switch is not atomic. This means that whatever
 resource is protected by the mutex might have been modified during the
 call to lock_write().
 !*/
 void unlock (
 );
 /*!
 ensures
 - if (has_read_lock() || has_write_lock()) then
 - unlocks the associated mutex. This is useful if you want to unlock a
 mutex before the auto_mutex_readonly destructor executes.
 - #has_read_lock() == false
 - #has_write_lock() == false
 !*/
 private:
 // restricted functions
 auto_mutex_readonly(auto_mutex_readonly&); // copy constructor
 auto_mutex_readonly& operator=(auto_mutex_readonly&); // assignment operator
 };
// ----------------------------------------------------------------------------------------
}
#endif // DLIB_AUTO_MUTEX_EXTENSIOn_ABSTRACT_