1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
// 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_
|
