1
// Ceres Solver - A fast non-linear least squares minimizer
2
// Copyright 2010, 2011, 2012 Google Inc. All rights reserved.
3
// http://code.google.com/p/ceres-solver/
5
// Redistribution and use in source and binary forms, with or without
6
// modification, are permitted provided that the following conditions are met:
8
// * Redistributions of source code must retain the above copyright notice,
9
// this list of conditions and the following disclaimer.
10
// * Redistributions in binary form must reproduce the above copyright notice,
11
// this list of conditions and the following disclaimer in the documentation
12
// and/or other materials provided with the distribution.
13
// * Neither the name of Google Inc. nor the names of its contributors may be
14
// used to endorse or promote products derived from this software without
15
// specific prior written permission.
17
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
21
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27
// POSSIBILITY OF SUCH DAMAGE.
29
// Author: Craig Silverstein.
31
// A simple mutex wrapper, supporting locks and read-write locks.
32
// You should assume the locks are *not* re-entrant.
34
// This class is meant to be internal-only and should be wrapped by an
35
// internal namespace. Before you use this module, please give the
36
// name of your internal namespace for this module. Or, if you want
37
// to expose it, you'll want to move it to the Google namespace. We
38
// cannot put this class in global namespace because there can be some
39
// problems when we have multiple versions of Mutex in each shared object.
41
// NOTE: by default, we have #ifdef'ed out the TryLock() method.
42
// This is for two reasons:
43
// 1) TryLock() under Windows is a bit annoying (it requires a
44
// #define to be defined very early).
45
// 2) TryLock() is broken for NO_THREADS mode, at least in NDEBUG
47
// If you need TryLock(), and either these two caveats are not a
48
// problem for you, or you're willing to work around them, then
49
// feel free to #define GMUTEX_TRYLOCK, or to remove the #ifdefs
52
// CYGWIN NOTE: Cygwin support for rwlock seems to be buggy:
53
// http://www.cygwin.com/ml/cygwin/2008-12/msg00017.html
54
// Because of that, we might as well use windows locks for
55
// cygwin. They seem to be more reliable than the cygwin pthreads layer.
57
// TRICKY IMPLEMENTATION NOTE:
58
// This class is designed to be safe to use during
59
// dynamic-initialization -- that is, by global constructors that are
60
// run before main() starts. The issue in this case is that
61
// dynamic-initialization happens in an unpredictable order, and it
62
// could be that someone else's dynamic initializer could call a
63
// function that tries to acquire this mutex -- but that all happens
64
// before this mutex's constructor has run. (This can happen even if
65
// the mutex and the function that uses the mutex are in the same .cc
66
// file.) Basically, because Mutex does non-trivial work in its
67
// constructor, it's not, in the naive implementation, safe to use
68
// before dynamic initialization has run on it.
70
// The solution used here is to pair the actual mutex primitive with a
71
// bool that is set to true when the mutex is dynamically initialized.
72
// (Before that it's false.) Then we modify all mutex routines to
73
// look at the bool, and not try to lock/unlock until the bool makes
74
// it to true (which happens after the Mutex constructor has run.)
76
// This works because before main() starts -- particularly, during
77
// dynamic initialization -- there are no threads, so a) it's ok that
78
// the mutex operations are a no-op, since we don't need locking then
79
// anyway; and b) we can be quite confident our bool won't change
80
// state between a call to Lock() and a call to Unlock() (that would
81
// require a global constructor in one translation unit to call Lock()
82
// and another global constructor in another translation unit to call
83
// Unlock() later, which is pretty perverse).
85
// That said, it's tricky, and can conceivably fail; it's safest to
86
// avoid trying to acquire a mutex in a global constructor, if you
87
// can. One way it can fail is that a really smart compiler might
88
// initialize the bool to true at static-initialization time (too
89
// early) rather than at dynamic-initialization time. To discourage
90
// that, we set is_safe_ to true in code (not the constructor
91
// colon-initializer) and set it to true via a function that always
92
// evaluates to true, but that the compiler can't know always
93
// evaluates to true. This should be good enough.
95
#ifndef CERES_INTERNAL_MUTEX_H_
96
#define CERES_INTERNAL_MUTEX_H_
98
#if defined(NO_THREADS)
99
typedef int MutexType; // to keep a lock-count
100
#elif defined(_WIN32) || defined(__CYGWIN32__) || defined(__CYGWIN64__)
101
# define WIN32_LEAN_AND_MEAN // We only need minimal includes
102
# ifdef GMUTEX_TRYLOCK
103
// We need Windows NT or later for TryEnterCriticalSection(). If you
104
// don't need that functionality, you can remove these _WIN32_WINNT
105
// lines, and change TryLock() to assert(0) or something.
106
# ifndef _WIN32_WINNT
107
# define _WIN32_WINNT 0x0400
110
// To avoid macro definition of ERROR.
112
// To avoid macro definition of min/max.
114
# include <windows.h>
115
typedef CRITICAL_SECTION MutexType;
116
#elif defined(CERES_HAVE_PTHREAD) && defined(CERES_HAVE_RWLOCK)
117
// Needed for pthread_rwlock_*. If it causes problems, you could take it
118
// out, but then you'd have to unset CERES_HAVE_RWLOCK (at least on linux --
119
// it *does* cause problems for FreeBSD, or MacOSX, but isn't needed for
121
# if defined(__linux__) && !defined(_XOPEN_SOURCE)
122
# define _XOPEN_SOURCE 500 // may be needed to get the rwlock calls
124
# include <pthread.h>
125
typedef pthread_rwlock_t MutexType;
126
#elif defined(CERES_HAVE_PTHREAD)
127
# include <pthread.h>
128
typedef pthread_mutex_t MutexType;
130
# error Need to implement mutex.h for your architecture, or #define NO_THREADS
133
// We need to include these header files after defining _XOPEN_SOURCE
134
// as they may define the _XOPEN_SOURCE macro.
136
#include <stdlib.h> // for abort()
143
// Create a Mutex that is not held by anybody. This constructor is
144
// typically used for Mutexes allocated on the heap or the stack.
145
// See below for a recommendation for constructing global Mutex
152
inline void Lock(); // Block if needed until free then acquire exclusively
153
inline void Unlock(); // Release a lock acquired via Lock()
154
#ifdef GMUTEX_TRYLOCK
155
inline bool TryLock(); // If free, Lock() and return true, else return false
157
// Note that on systems that don't support read-write locks, these may
158
// be implemented as synonyms to Lock() and Unlock(). So you can use
159
// these for efficiency, but don't use them anyplace where being able
160
// to do shared reads is necessary to avoid deadlock.
161
inline void ReaderLock(); // Block until free or shared then acquire a share
162
inline void ReaderUnlock(); // Release a read share of this Mutex
163
inline void WriterLock() { Lock(); } // Acquire an exclusive lock
164
inline void WriterUnlock() { Unlock(); } // Release a lock from WriterLock()
166
// TODO(hamaji): Do nothing, implement correctly.
167
inline void AssertHeld() {}
171
// We want to make sure that the compiler sets is_safe_ to true only
172
// when we tell it to, and never makes assumptions is_safe_ is
173
// always true. volatile is the most reliable way to do that.
174
volatile bool is_safe_;
176
inline void SetIsSafe() { is_safe_ = true; }
178
// Catch the error of writing Mutex when intending MutexLock.
179
Mutex(Mutex* /*ignored*/) {}
180
// Disallow "evil" constructors
182
void operator=(const Mutex&);
185
// Now the implementation of Mutex for various systems
186
#if defined(NO_THREADS)
188
// When we don't have threads, we can be either reading or writing,
189
// but not both. We can have lots of readers at once (in no-threads
190
// mode, that's most likely to happen in recursive function calls),
191
// but only one writer. We represent this by having mutex_ be -1 when
192
// writing and a number > 0 when reading (and 0 when no lock is held).
194
// In debug mode, we assert these invariants, while in non-debug mode
195
// we do nothing, for efficiency. That's why everything is in an
198
Mutex::Mutex() : mutex_(0) { }
199
Mutex::~Mutex() { assert(mutex_ == 0); }
200
void Mutex::Lock() { assert(--mutex_ == -1); }
201
void Mutex::Unlock() { assert(mutex_++ == -1); }
202
#ifdef GMUTEX_TRYLOCK
203
bool Mutex::TryLock() { if (mutex_) return false; Lock(); return true; }
205
void Mutex::ReaderLock() { assert(++mutex_ > 0); }
206
void Mutex::ReaderUnlock() { assert(mutex_-- > 0); }
208
#elif defined(_WIN32) || defined(__CYGWIN32__) || defined(__CYGWIN64__)
210
Mutex::Mutex() { InitializeCriticalSection(&mutex_); SetIsSafe(); }
211
Mutex::~Mutex() { DeleteCriticalSection(&mutex_); }
212
void Mutex::Lock() { if (is_safe_) EnterCriticalSection(&mutex_); }
213
void Mutex::Unlock() { if (is_safe_) LeaveCriticalSection(&mutex_); }
214
#ifdef GMUTEX_TRYLOCK
215
bool Mutex::TryLock() { return is_safe_ ?
216
TryEnterCriticalSection(&mutex_) != 0 : true; }
218
void Mutex::ReaderLock() { Lock(); } // we don't have read-write locks
219
void Mutex::ReaderUnlock() { Unlock(); }
221
#elif defined(CERES_HAVE_PTHREAD) && defined(CERES_HAVE_RWLOCK)
223
#define SAFE_PTHREAD(fncall) do { /* run fncall if is_safe_ is true */ \
224
if (is_safe_ && fncall(&mutex_) != 0) abort(); \
229
if (is_safe_ && pthread_rwlock_init(&mutex_, NULL) != 0) abort();
231
Mutex::~Mutex() { SAFE_PTHREAD(pthread_rwlock_destroy); }
232
void Mutex::Lock() { SAFE_PTHREAD(pthread_rwlock_wrlock); }
233
void Mutex::Unlock() { SAFE_PTHREAD(pthread_rwlock_unlock); }
234
#ifdef GMUTEX_TRYLOCK
235
bool Mutex::TryLock() { return is_safe_ ?
236
pthread_rwlock_trywrlock(&mutex_) == 0 :
239
void Mutex::ReaderLock() { SAFE_PTHREAD(pthread_rwlock_rdlock); }
240
void Mutex::ReaderUnlock() { SAFE_PTHREAD(pthread_rwlock_unlock); }
243
#elif defined(CERES_HAVE_PTHREAD)
245
#define SAFE_PTHREAD(fncall) do { /* run fncall if is_safe_ is true */ \
246
if (is_safe_ && fncall(&mutex_) != 0) abort(); \
251
if (is_safe_ && pthread_mutex_init(&mutex_, NULL) != 0) abort();
253
Mutex::~Mutex() { SAFE_PTHREAD(pthread_mutex_destroy); }
254
void Mutex::Lock() { SAFE_PTHREAD(pthread_mutex_lock); }
255
void Mutex::Unlock() { SAFE_PTHREAD(pthread_mutex_unlock); }
256
#ifdef GMUTEX_TRYLOCK
257
bool Mutex::TryLock() { return is_safe_ ?
258
pthread_mutex_trylock(&mutex_) == 0 : true; }
260
void Mutex::ReaderLock() { Lock(); }
261
void Mutex::ReaderUnlock() { Unlock(); }
266
// --------------------------------------------------------------------------
267
// Some helper classes
269
// MutexLock(mu) acquires mu when constructed and releases it when destroyed.
272
explicit MutexLock(Mutex *mu) : mu_(mu) { mu_->Lock(); }
273
~MutexLock() { mu_->Unlock(); }
276
// Disallow "evil" constructors
277
MutexLock(const MutexLock&);
278
void operator=(const MutexLock&);
281
// ReaderMutexLock and WriterMutexLock do the same, for rwlocks
282
class ReaderMutexLock {
284
explicit ReaderMutexLock(Mutex *mu) : mu_(mu) { mu_->ReaderLock(); }
285
~ReaderMutexLock() { mu_->ReaderUnlock(); }
288
// Disallow "evil" constructors
289
ReaderMutexLock(const ReaderMutexLock&);
290
void operator=(const ReaderMutexLock&);
293
class WriterMutexLock {
295
explicit WriterMutexLock(Mutex *mu) : mu_(mu) { mu_->WriterLock(); }
296
~WriterMutexLock() { mu_->WriterUnlock(); }
299
// Disallow "evil" constructors
300
WriterMutexLock(const WriterMutexLock&);
301
void operator=(const WriterMutexLock&);
304
// Catch bug where variable name is omitted, e.g. MutexLock (&mu);
305
#define MutexLock(x) COMPILE_ASSERT(0, mutex_lock_decl_missing_var_name)
306
#define ReaderMutexLock(x) COMPILE_ASSERT(0, rmutex_lock_decl_missing_var_name)
307
#define WriterMutexLock(x) COMPILE_ASSERT(0, wmutex_lock_decl_missing_var_name)
309
} // namespace internal
312
#endif // CERES_INTERNAL_MUTEX_H_
added
removed
internal/ceres/mutex.h
