cannam@147: // Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
cannam@147: // Licensed under the MIT License:
cannam@147: //
cannam@147: // Permission is hereby granted, free of charge, to any person obtaining a copy
cannam@147: // of this software and associated documentation files (the "Software"), to deal
cannam@147: // in the Software without restriction, including without limitation the rights
cannam@147: // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
cannam@147: // copies of the Software, and to permit persons to whom the Software is
cannam@147: // furnished to do so, subject to the following conditions:
cannam@147: //
cannam@147: // The above copyright notice and this permission notice shall be included in
cannam@147: // all copies or substantial portions of the Software.
cannam@147: //
cannam@147: // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
cannam@147: // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
cannam@147: // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
cannam@147: // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
cannam@147: // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
cannam@147: // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
cannam@147: // THE SOFTWARE.
cannam@147: 
cannam@147: #ifndef KJ_MUTEX_H_
cannam@147: #define KJ_MUTEX_H_
cannam@147: 
cannam@147: #if defined(__GNUC__) && !KJ_HEADER_WARNINGS
cannam@147: #pragma GCC system_header
cannam@147: #endif
cannam@147: 
cannam@147: #include "memory.h"
cannam@147: #include <inttypes.h>
cannam@147: 
cannam@147: #if __linux__ && !defined(KJ_USE_FUTEX)
cannam@147: #define KJ_USE_FUTEX 1
cannam@147: #endif
cannam@147: 
cannam@147: #if !KJ_USE_FUTEX && !_WIN32
cannam@147: // On Linux we use futex.  On other platforms we wrap pthreads.
cannam@147: // TODO(someday):  Write efficient low-level locking primitives for other platforms.
cannam@147: #include <pthread.h>
cannam@147: #endif
cannam@147: 
cannam@147: namespace kj {
cannam@147: 
cannam@147: // =======================================================================================
cannam@147: // Private details -- public interfaces follow below.
cannam@147: 
cannam@147: namespace _ {  // private
cannam@147: 
cannam@147: class Mutex {
cannam@147:   // Internal implementation details.  See `MutexGuarded<T>`.
cannam@147: 
cannam@147: public:
cannam@147:   Mutex();
cannam@147:   ~Mutex();
cannam@147:   KJ_DISALLOW_COPY(Mutex);
cannam@147: 
cannam@147:   enum Exclusivity {
cannam@147:     EXCLUSIVE,
cannam@147:     SHARED
cannam@147:   };
cannam@147: 
cannam@147:   void lock(Exclusivity exclusivity);
cannam@147:   void unlock(Exclusivity exclusivity);
cannam@147: 
cannam@147:   void assertLockedByCaller(Exclusivity exclusivity);
cannam@147:   // In debug mode, assert that the mutex is locked by the calling thread, or if that is
cannam@147:   // non-trivial, assert that the mutex is locked (which should be good enough to catch problems
cannam@147:   // in unit tests).  In non-debug builds, do nothing.
cannam@147: 
cannam@147: private:
cannam@147: #if KJ_USE_FUTEX
cannam@147:   uint futex;
cannam@147:   // bit 31 (msb) = set if exclusive lock held
cannam@147:   // bit 30 (msb) = set if threads are waiting for exclusive lock
cannam@147:   // bits 0-29 = count of readers; If an exclusive lock is held, this is the count of threads
cannam@147:   //   waiting for a read lock, otherwise it is the count of threads that currently hold a read
cannam@147:   //   lock.
cannam@147: 
cannam@147:   static constexpr uint EXCLUSIVE_HELD = 1u << 31;
cannam@147:   static constexpr uint EXCLUSIVE_REQUESTED = 1u << 30;
cannam@147:   static constexpr uint SHARED_COUNT_MASK = EXCLUSIVE_REQUESTED - 1;
cannam@147: 
cannam@147: #elif _WIN32
cannam@147:   uintptr_t srwLock;  // Actually an SRWLOCK, but don't want to #include <windows.h> in header.
cannam@147: 
cannam@147: #else
cannam@147:   mutable pthread_rwlock_t mutex;
cannam@147: #endif
cannam@147: };
cannam@147: 
cannam@147: class Once {
cannam@147:   // Internal implementation details.  See `Lazy<T>`.
cannam@147: 
cannam@147: public:
cannam@147: #if KJ_USE_FUTEX
cannam@147:   inline Once(bool startInitialized = false)
cannam@147:       : futex(startInitialized ? INITIALIZED : UNINITIALIZED) {}
cannam@147: #else
cannam@147:   Once(bool startInitialized = false);
cannam@147:   ~Once();
cannam@147: #endif
cannam@147:   KJ_DISALLOW_COPY(Once);
cannam@147: 
cannam@147:   class Initializer {
cannam@147:   public:
cannam@147:     virtual void run() = 0;
cannam@147:   };
cannam@147: 
cannam@147:   void runOnce(Initializer& init);
cannam@147: 
cannam@147: #if _WIN32  // TODO(perf): Can we make this inline on win32 somehow?
cannam@147:   bool isInitialized() noexcept;
cannam@147: 
cannam@147: #else
cannam@147:   inline bool isInitialized() noexcept {
cannam@147:     // Fast path check to see if runOnce() would simply return immediately.
cannam@147: #if KJ_USE_FUTEX
cannam@147:     return __atomic_load_n(&futex, __ATOMIC_ACQUIRE) == INITIALIZED;
cannam@147: #else
cannam@147:     return __atomic_load_n(&state, __ATOMIC_ACQUIRE) == INITIALIZED;
cannam@147: #endif
cannam@147:   }
cannam@147: #endif
cannam@147: 
cannam@147:   void reset();
cannam@147:   // Returns the state from initialized to uninitialized.  It is an error to call this when
cannam@147:   // not already initialized, or when runOnce() or isInitialized() might be called concurrently in
cannam@147:   // another thread.
cannam@147: 
cannam@147: private:
cannam@147: #if KJ_USE_FUTEX
cannam@147:   uint futex;
cannam@147: 
cannam@147:   enum State {
cannam@147:     UNINITIALIZED,
cannam@147:     INITIALIZING,
cannam@147:     INITIALIZING_WITH_WAITERS,
cannam@147:     INITIALIZED
cannam@147:   };
cannam@147: 
cannam@147: #elif _WIN32
cannam@147:   uintptr_t initOnce;  // Actually an INIT_ONCE, but don't want to #include <windows.h> in header.
cannam@147: 
cannam@147: #else
cannam@147:   enum State {
cannam@147:     UNINITIALIZED,
cannam@147:     INITIALIZED
cannam@147:   };
cannam@147:   State state;
cannam@147:   pthread_mutex_t mutex;
cannam@147: #endif
cannam@147: };
cannam@147: 
cannam@147: }  // namespace _ (private)
cannam@147: 
cannam@147: // =======================================================================================
cannam@147: // Public interface
cannam@147: 
cannam@147: template <typename T>
cannam@147: class Locked {
cannam@147:   // Return type for `MutexGuarded<T>::lock()`.  `Locked<T>` provides access to the bounded object
cannam@147:   // and unlocks the mutex when it goes out of scope.
cannam@147: 
cannam@147: public:
cannam@147:   KJ_DISALLOW_COPY(Locked);
cannam@147:   inline Locked(): mutex(nullptr), ptr(nullptr) {}
cannam@147:   inline Locked(Locked&& other): mutex(other.mutex), ptr(other.ptr) {
cannam@147:     other.mutex = nullptr;
cannam@147:     other.ptr = nullptr;
cannam@147:   }
cannam@147:   inline ~Locked() {
cannam@147:     if (mutex != nullptr) mutex->unlock(isConst<T>() ? _::Mutex::SHARED : _::Mutex::EXCLUSIVE);
cannam@147:   }
cannam@147: 
cannam@147:   inline Locked& operator=(Locked&& other) {
cannam@147:     if (mutex != nullptr) mutex->unlock(isConst<T>() ? _::Mutex::SHARED : _::Mutex::EXCLUSIVE);
cannam@147:     mutex = other.mutex;
cannam@147:     ptr = other.ptr;
cannam@147:     other.mutex = nullptr;
cannam@147:     other.ptr = nullptr;
cannam@147:     return *this;
cannam@147:   }
cannam@147: 
cannam@147:   inline void release() {
cannam@147:     if (mutex != nullptr) mutex->unlock(isConst<T>() ? _::Mutex::SHARED : _::Mutex::EXCLUSIVE);
cannam@147:     mutex = nullptr;
cannam@147:     ptr = nullptr;
cannam@147:   }
cannam@147: 
cannam@147:   inline T* operator->() { return ptr; }
cannam@147:   inline const T* operator->() const { return ptr; }
cannam@147:   inline T& operator*() { return *ptr; }
cannam@147:   inline const T& operator*() const { return *ptr; }
cannam@147:   inline T* get() { return ptr; }
cannam@147:   inline const T* get() const { return ptr; }
cannam@147:   inline operator T*() { return ptr; }
cannam@147:   inline operator const T*() const { return ptr; }
cannam@147: 
cannam@147: private:
cannam@147:   _::Mutex* mutex;
cannam@147:   T* ptr;
cannam@147: 
cannam@147:   inline Locked(_::Mutex& mutex, T& value): mutex(&mutex), ptr(&value) {}
cannam@147: 
cannam@147:   template <typename U>
cannam@147:   friend class MutexGuarded;
cannam@147: };
cannam@147: 
cannam@147: template <typename T>
cannam@147: class MutexGuarded {
cannam@147:   // An object of type T, bounded by a mutex.  In order to access the object, you must lock it.
cannam@147:   //
cannam@147:   // Write locks are not "recursive" -- trying to lock again in a thread that already holds a lock
cannam@147:   // will deadlock.  Recursive write locks are usually a sign of bad design.
cannam@147:   //
cannam@147:   // Unfortunately, **READ LOCKS ARE NOT RECURSIVE** either.  Common sense says they should be.
cannam@147:   // But on many operating systems (BSD, OSX), recursively read-locking a pthread_rwlock is
cannam@147:   // actually unsafe.  The problem is that writers are "prioritized" over readers, so a read lock
cannam@147:   // request will block if any write lock requests are outstanding.  So, if thread A takes a read
cannam@147:   // lock, thread B requests a write lock (and starts waiting), and then thread A tries to take
cannam@147:   // another read lock recursively, the result is deadlock.
cannam@147: 
cannam@147: public:
cannam@147:   template <typename... Params>
cannam@147:   explicit MutexGuarded(Params&&... params);
cannam@147:   // Initialize the mutex-bounded object by passing the given parameters to its constructor.
cannam@147: 
cannam@147:   Locked<T> lockExclusive() const;
cannam@147:   // Exclusively locks the object and returns it.  The returned `Locked<T>` can be passed by
cannam@147:   // move, similar to `Own<T>`.
cannam@147:   //
cannam@147:   // This method is declared `const` in accordance with KJ style rules which say that constness
cannam@147:   // should be used to indicate thread-safety.  It is safe to share a const pointer between threads,
cannam@147:   // but it is not safe to share a mutable pointer.  Since the whole point of MutexGuarded is to
cannam@147:   // be shared between threads, its methods should be const, even though locking it produces a
cannam@147:   // non-const pointer to the contained object.
cannam@147: 
cannam@147:   Locked<const T> lockShared() const;
cannam@147:   // Lock the value for shared access.  Multiple shared locks can be taken concurrently, but cannot
cannam@147:   // be held at the same time as a non-shared lock.
cannam@147: 
cannam@147:   inline const T& getWithoutLock() const { return value; }
cannam@147:   inline T& getWithoutLock() { return value; }
cannam@147:   // Escape hatch for cases where some external factor guarantees that it's safe to get the
cannam@147:   // value.  You should treat these like const_cast -- be highly suspicious of any use.
cannam@147: 
cannam@147:   inline const T& getAlreadyLockedShared() const;
cannam@147:   inline T& getAlreadyLockedShared();
cannam@147:   inline T& getAlreadyLockedExclusive() const;
cannam@147:   // Like `getWithoutLock()`, but asserts that the lock is already held by the calling thread.
cannam@147: 
cannam@147: private:
cannam@147:   mutable _::Mutex mutex;
cannam@147:   mutable T value;
cannam@147: };
cannam@147: 
cannam@147: template <typename T>
cannam@147: class MutexGuarded<const T> {
cannam@147:   // MutexGuarded cannot guard a const type.  This would be pointless anyway, and would complicate
cannam@147:   // the implementation of Locked<T>, which uses constness to decide what kind of lock it holds.
cannam@147:   static_assert(sizeof(T) < 0, "MutexGuarded's type cannot be const.");
cannam@147: };
cannam@147: 
cannam@147: template <typename T>
cannam@147: class Lazy {
cannam@147:   // A lazily-initialized value.
cannam@147: 
cannam@147: public:
cannam@147:   template <typename Func>
cannam@147:   T& get(Func&& init);
cannam@147:   template <typename Func>
cannam@147:   const T& get(Func&& init) const;
cannam@147:   // The first thread to call get() will invoke the given init function to construct the value.
cannam@147:   // Other threads will block until construction completes, then return the same value.
cannam@147:   //
cannam@147:   // `init` is a functor(typically a lambda) which takes `SpaceFor<T>&` as its parameter and returns
cannam@147:   // `Own<T>`.  If `init` throws an exception, the exception is propagated out of that thread's
cannam@147:   // call to `get()`, and subsequent calls behave as if `get()` hadn't been called at all yet --
cannam@147:   // in other words, subsequent calls retry initialization until it succeeds.
cannam@147: 
cannam@147: private:
cannam@147:   mutable _::Once once;
cannam@147:   mutable SpaceFor<T> space;
cannam@147:   mutable Own<T> value;
cannam@147: 
cannam@147:   template <typename Func>
cannam@147:   class InitImpl;
cannam@147: };
cannam@147: 
cannam@147: // =======================================================================================
cannam@147: // Inline implementation details
cannam@147: 
cannam@147: template <typename T>
cannam@147: template <typename... Params>
cannam@147: inline MutexGuarded<T>::MutexGuarded(Params&&... params)
cannam@147:     : value(kj::fwd<Params>(params)...) {}
cannam@147: 
cannam@147: template <typename T>
cannam@147: inline Locked<T> MutexGuarded<T>::lockExclusive() const {
cannam@147:   mutex.lock(_::Mutex::EXCLUSIVE);
cannam@147:   return Locked<T>(mutex, value);
cannam@147: }
cannam@147: 
cannam@147: template <typename T>
cannam@147: inline Locked<const T> MutexGuarded<T>::lockShared() const {
cannam@147:   mutex.lock(_::Mutex::SHARED);
cannam@147:   return Locked<const T>(mutex, value);
cannam@147: }
cannam@147: 
cannam@147: template <typename T>
cannam@147: inline const T& MutexGuarded<T>::getAlreadyLockedShared() const {
cannam@147: #ifdef KJ_DEBUG
cannam@147:   mutex.assertLockedByCaller(_::Mutex::SHARED);
cannam@147: #endif
cannam@147:   return value;
cannam@147: }
cannam@147: template <typename T>
cannam@147: inline T& MutexGuarded<T>::getAlreadyLockedShared() {
cannam@147: #ifdef KJ_DEBUG
cannam@147:   mutex.assertLockedByCaller(_::Mutex::SHARED);
cannam@147: #endif
cannam@147:   return value;
cannam@147: }
cannam@147: template <typename T>
cannam@147: inline T& MutexGuarded<T>::getAlreadyLockedExclusive() const {
cannam@147: #ifdef KJ_DEBUG
cannam@147:   mutex.assertLockedByCaller(_::Mutex::EXCLUSIVE);
cannam@147: #endif
cannam@147:   return const_cast<T&>(value);
cannam@147: }
cannam@147: 
cannam@147: template <typename T>
cannam@147: template <typename Func>
cannam@147: class Lazy<T>::InitImpl: public _::Once::Initializer {
cannam@147: public:
cannam@147:   inline InitImpl(const Lazy<T>& lazy, Func&& func): lazy(lazy), func(kj::fwd<Func>(func)) {}
cannam@147: 
cannam@147:   void run() override {
cannam@147:     lazy.value = func(lazy.space);
cannam@147:   }
cannam@147: 
cannam@147: private:
cannam@147:   const Lazy<T>& lazy;
cannam@147:   Func func;
cannam@147: };
cannam@147: 
cannam@147: template <typename T>
cannam@147: template <typename Func>
cannam@147: inline T& Lazy<T>::get(Func&& init) {
cannam@147:   if (!once.isInitialized()) {
cannam@147:     InitImpl<Func> initImpl(*this, kj::fwd<Func>(init));
cannam@147:     once.runOnce(initImpl);
cannam@147:   }
cannam@147:   return *value;
cannam@147: }
cannam@147: 
cannam@147: template <typename T>
cannam@147: template <typename Func>
cannam@147: inline const T& Lazy<T>::get(Func&& init) const {
cannam@147:   if (!once.isInitialized()) {
cannam@147:     InitImpl<Func> initImpl(*this, kj::fwd<Func>(init));
cannam@147:     once.runOnce(initImpl);
cannam@147:   }
cannam@147:   return *value;
cannam@147: }
cannam@147: 
cannam@147: }  // namespace kj
cannam@147: 
cannam@147: #endif  // KJ_MUTEX_H_