You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
147 lines
5.3 KiB
C++
147 lines
5.3 KiB
C++
// Copyright (C) 2010 Davis E. King (davis@dlib.net)
|
|
// License: Boost Software License See LICENSE.txt for the full license.
|
|
#undef DLIB_READWRITE_MUTEX_EXTENSIOn_ABSTRACT_
|
|
#ifdef DLIB_READWRITE_MUTEX_EXTENSIOn_ABSTRACT_
|
|
|
|
#include "threads_kernel_abstract.h"
|
|
|
|
namespace dlib
|
|
{
|
|
|
|
// ----------------------------------------------------------------------------------------
|
|
|
|
class read_write_mutex
|
|
{
|
|
/*!
|
|
INITIAL VALUE
|
|
read_write_mutex is in the fully unlocked state
|
|
|
|
WHAT THIS OBJECT REPRESENTS
|
|
This object represents a mutex intended to be used for synchronous
|
|
thread control of shared data. When a thread wants to access some
|
|
shared data it locks out other threads by calling lock() and calls
|
|
unlock() when it is finished.
|
|
|
|
This mutex also has the additional ability to distinguish between
|
|
a lock for the purposes of modifying some shared data, a write lock,
|
|
and a lock for the purposes of only reading shared data, a readonly
|
|
lock. The lock() and unlock() functions are used for write locks while
|
|
the lock_readonly() and unlock_readonly() are for readonly locks.
|
|
|
|
The difference between a readonly and write lock can be understood as
|
|
follows. The read_write_mutex will allow many threads to obtain simultaneous
|
|
readonly locks but will only allow a single thread to obtain a write lock.
|
|
Moreover, while the write lock is obtained no other threads are allowed
|
|
to have readonly locks.
|
|
!*/
|
|
public:
|
|
|
|
read_write_mutex (
|
|
);
|
|
/*!
|
|
ensures
|
|
- #*this is properly initialized
|
|
- max_readonly_locks() == 0xFFFFFFFF
|
|
(i.e. about 4 billion)
|
|
throws
|
|
- dlib::thread_error
|
|
the constructor may throw this exception if there is a problem
|
|
gathering resources to create the read_write_mutex.
|
|
!*/
|
|
|
|
explicit read_write_mutex (
|
|
unsigned long max_locks
|
|
);
|
|
/*!
|
|
requires
|
|
- max_locks > 0
|
|
ensures
|
|
- #*this is properly initialized
|
|
- max_readonly_locks() == max_locks
|
|
throws
|
|
- dlib::thread_error
|
|
the constructor may throw this exception if there is a problem
|
|
gathering resources to create the read_write_mutex.
|
|
!*/
|
|
|
|
~read_write_mutex (
|
|
);
|
|
/*!
|
|
requires
|
|
- *this is not locked
|
|
ensures
|
|
- all resources allocated by *this have been freed
|
|
!*/
|
|
|
|
void lock (
|
|
) const;
|
|
/*!
|
|
requires
|
|
- The thread calling this function does not have any kind of lock on this
|
|
object
|
|
ensures
|
|
- if (there is any kind of lock on *this) then
|
|
- the calling thread is put to sleep until a write lock becomes available.
|
|
Once available, a write lock is obtained on this mutex and this function
|
|
terminates.
|
|
- else
|
|
- a write lock is obtained on this mutex and the calling thread is not put to sleep
|
|
!*/
|
|
|
|
void unlock (
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- if (there is a write lock on *this) then
|
|
- #*this is unlocked (i.e. other threads may now lock this object)
|
|
- else
|
|
- the call to unlock() has no effect
|
|
!*/
|
|
|
|
unsigned long max_readonly_locks (
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- returns the maximum number of concurrent readonly locks this object will allow.
|
|
!*/
|
|
|
|
void lock_readonly (
|
|
) const;
|
|
/*!
|
|
requires
|
|
- The thread calling this function does not already have a write
|
|
lock on this object
|
|
ensures
|
|
- if (there is a write lock on *this or there are no free readonly locks) then
|
|
- the calling thread is put to sleep until there is no longer a write lock
|
|
and a free readonly lock is available. Once this is the case, a readonly
|
|
lock is obtained and this function terminates.
|
|
- else
|
|
- a readonly lock is obtained on *this and the calling thread is not put
|
|
to sleep. Note that multiple readonly locks can be obtained at once.
|
|
!*/
|
|
|
|
void unlock_readonly (
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- if (there is a readonly lock on *this) then
|
|
- one readonly lock is removed from *this.
|
|
- else
|
|
- the call to unlock_readonly() has no effect.
|
|
!*/
|
|
|
|
private:
|
|
// restricted functions
|
|
read_write_mutex(read_write_mutex&); // copy constructor
|
|
read_write_mutex& operator=(read_write_mutex&); // assignment operator
|
|
};
|
|
|
|
// ----------------------------------------------------------------------------------------
|
|
|
|
}
|
|
|
|
#endif // DLIB_READWRITE_MUTEX_EXTENSIOn_ABSTRACT_
|
|
|
|
|