tor-browser

ExclusiveData.h (11828B)

---

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* vim: set ts=8 sts=2 et sw=2 tw=80:
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef threading_ExclusiveData_h
#define threading_ExclusiveData_h

#include "mozilla/OperatorNewExtensions.h"

#include <utility>

#include "threading/ConditionVariable.h"
#include "threading/Mutex.h"

namespace js {

/**
* [SMDOC] ExclusiveData API
*
* A mutual exclusion lock class.
*
* `ExclusiveData` provides an RAII guard to automatically lock and unlock when
* accessing the protected inner value.
*
* Unlike the STL's `std::mutex`, the protected value is internal to this
* class. This is a huge win: one no longer has to rely on documentation to
* explain the relationship between a lock and its protected data, and the type
* system can enforce[0] it.
*
* For example, suppose we have a counter class:
*
*     class Counter
*     {
*         int32_t i;
*
*       public:
*         void inc(int32_t n) { i += n; }
*     };
*
* If we share a counter across threads with `std::mutex`, we rely solely on
* comments to document the relationship between the lock and its data, like
* this:
*
*     class SharedCounter
*     {
*         // Remember to acquire `counter_lock` when accessing `counter`,
*         // pretty please!
*         Counter counter;
*         std::mutex counter_lock;
*
*       public:
*         void inc(size_t n) {
*             // Whoops, forgot to acquire the lock! Off to the races!
*             counter.inc(n);
*         }
*     };
*
* In contrast, `ExclusiveData` wraps the protected value, enabling the type
* system to enforce that we acquire the lock before accessing the value:
*
*     class SharedCounter
*     {
*         ExclusiveData<Counter> counter;
*
*       public:
*         void inc(size_t n) {
*             auto guard = counter.lock();
*             guard->inc(n);
*         }
*     };
*
* The API design is based on Rust's `std::sync::Mutex<T>` type.
*
* [0]: Of course, we don't have a borrow checker in C++, so the type system
*      cannot guarantee that you don't stash references received from
*      `ExclusiveData<T>::Guard` somewhere such that the reference outlives the
*      guard's lifetime and therefore becomes invalid. To help avoid this last
*      foot-gun, prefer using the guard directly! Do not store raw references
*      to the protected value in other structures!
*/
template <typename T>
class ExclusiveData {
protected:
 mutable Mutex lock_ MOZ_UNANNOTATED;
 mutable T value_;

 ExclusiveData(const ExclusiveData&) = delete;
 ExclusiveData& operator=(const ExclusiveData&) = delete;

 void acquire() const { lock_.lock(); }
 void release() const { lock_.unlock(); }

public:
 /**
  * Create a new `ExclusiveData`, with perfect forwarding of the protected
  * value.
  */
 template <typename U>
 explicit ExclusiveData(const MutexId& id, U&& u)
     : lock_(id), value_(std::forward<U>(u)) {}

 /**
  * Create a new `ExclusiveData`, constructing the protected value in place.
  */
 template <typename... Args>
 explicit ExclusiveData(const MutexId& id, Args&&... args)
     : lock_(id), value_(std::forward<Args>(args)...) {}

 ExclusiveData& operator=(ExclusiveData&& rhs) {
   this->~ExclusiveData();
   new (mozilla::KnownNotNull, this) ExclusiveData(std::move(rhs));
   return *this;
 }

 /**
  * An RAII class that provides exclusive access to a `ExclusiveData<T>`'s
  * protected inner `T` value.
  *
  * Note that this is intentionally marked MOZ_STACK_CLASS instead of
  * MOZ_RAII_CLASS, as the latter disallows moves and returning by value, but
  * Guard utilizes both.
  */
 class MOZ_STACK_CLASS Guard {
  protected:
   const ExclusiveData* parent_;
   explicit Guard(std::nullptr_t) : parent_(nullptr) {}

  private:
   Guard(const Guard&) = delete;
   Guard& operator=(const Guard&) = delete;

  public:
   explicit Guard(const ExclusiveData& parent) : parent_(&parent) {
     parent_->acquire();
   }

   Guard(Guard&& rhs) : parent_(rhs.parent_) {
     MOZ_ASSERT(&rhs != this, "self-move disallowed!");
     rhs.parent_ = nullptr;
   }

   Guard& operator=(Guard&& rhs) {
     this->~Guard();
     new (this) Guard(std::move(rhs));
     return *this;
   }

   T& get() const {
     MOZ_ASSERT(parent_);
     return parent_->value_;
   }

   operator T&() const { return get(); }
   T* operator->() const { return &get(); }

   const ExclusiveData<T>* parent() const {
     MOZ_ASSERT(parent_);
     return parent_;
   }

   ~Guard() {
     if (parent_) {
       parent_->release();
     }
   }
 };

 /**
  * NullableGuard are similar to Guard, except that one the access to the
  * ExclusiveData might not always be granted. This is useful when contextual
  * information is enough to prevent useless use of Mutex.
  *
  * The NullableGuard can be manipulated as follows:
  *
  *     if (NullableGuard guard = data.mightAccess()) {
  *         // NullableGuard is acquired.
  *         guard->...
  *     }
  *     // NullableGuard was either not acquired or released.
  *
  * Where mightAccess returns either a NullableGuard from `noAccess()` or a
  * Guard from `lock()`.
  */
 class MOZ_STACK_CLASS NullableGuard : public Guard {
  public:
   explicit NullableGuard(std::nullptr_t) : Guard((std::nullptr_t) nullptr) {}
   explicit NullableGuard(const ExclusiveData& parent) : Guard(parent) {}
   explicit NullableGuard(Guard&& rhs) : Guard(std::move(rhs)) {}

   NullableGuard& operator=(Guard&& rhs) {
     this->~NullableGuard();
     new (this) NullableGuard(std::move(rhs));
     return *this;
   }

   /**
    * Returns whether this NullableGuard has access to the exclusive data.
    */
   bool hasAccess() const { return this->parent_; }
   explicit operator bool() const { return hasAccess(); }
 };

 /**
  * Access the protected inner `T` value for exclusive reading and writing.
  */
 Guard lock() const { return Guard(*this); }

 /**
  * Provide a no-access guard, which coerces to false when tested. This value
  * can be returned if the guard access is conditioned on external factors.
  *
  * See NullableGuard.
  */
 NullableGuard noAccess() const {
   return NullableGuard((std::nullptr_t) nullptr);
 }
};

template <class T>
class ExclusiveWaitableData : public ExclusiveData<T> {
 using Base = ExclusiveData<T>;

 mutable ConditionVariable condVar_;

public:
 template <typename U>
 explicit ExclusiveWaitableData(const MutexId& id, U&& u)
     : Base(id, std::forward<U>(u)) {}

 template <typename... Args>
 explicit ExclusiveWaitableData(const MutexId& id, Args&&... args)
     : Base(id, std::forward<Args>(args)...) {}

 class MOZ_STACK_CLASS Guard : public ExclusiveData<T>::Guard {
   using Base = typename ExclusiveData<T>::Guard;

  public:
   explicit Guard(const ExclusiveWaitableData& parent) : Base(parent) {}

   Guard(Guard&& guard) : Base(std::move(guard)) {}

   Guard& operator=(Guard&& rhs) { return Base::operator=(std::move(rhs)); }

   void wait() {
     auto* parent = static_cast<const ExclusiveWaitableData*>(this->parent());
     parent->condVar_.wait(parent->lock_);
   }

   void notify_one() {
     auto* parent = static_cast<const ExclusiveWaitableData*>(this->parent());
     parent->condVar_.notify_one();
   }

   void notify_all() {
     auto* parent = static_cast<const ExclusiveWaitableData*>(this->parent());
     parent->condVar_.notify_all();
   }
 };

 Guard lock() const { return Guard(*this); }
};

/**
* Multiple-readers / single-writer variant of ExclusiveData.
*
* Readers call readLock() to obtain a stack-only RAII reader lock, which will
* allow other readers to read concurrently but block writers; the yielded value
* is const.  Writers call writeLock() to obtain a ditto writer lock, which
* yields exclusive access to non-const data.
*
* See ExclusiveData and its implementation for more documentation.
*/
template <typename T>
class RWExclusiveData {
 mutable Mutex lock_ MOZ_UNANNOTATED;
 mutable ConditionVariable cond_;
 mutable T value_;
 mutable int readers_;

 // We maintain a count of active readers.  Writers may enter the critical
 // section only when the reader count is zero, so the reader that decrements
 // the count to zero must wake up any waiting writers.
 //
 // There can be multiple writers waiting, so a writer leaving the critical
 // section must also wake up any other waiting writers.

 void acquireReaderLock() const {
   lock_.lock();
   readers_++;
   lock_.unlock();
 }

 void releaseReaderLock() const {
   lock_.lock();
   MOZ_ASSERT(readers_ > 0);
   if (--readers_ == 0) {
     cond_.notify_all();
   }
   lock_.unlock();
 }

 void acquireWriterLock() const {
   lock_.lock();
   while (readers_ > 0) {
     cond_.wait(lock_);
   }
 }

 void releaseWriterLock() const {
   cond_.notify_all();
   lock_.unlock();
 }

public:
 RWExclusiveData(const RWExclusiveData&) = delete;
 RWExclusiveData& operator=(const RWExclusiveData&) = delete;

 /**
  * Create a new `RWExclusiveData`, constructing the protected value in place.
  */
 template <typename... Args>
 explicit RWExclusiveData(const MutexId& id, Args&&... args)
     : lock_(id), value_(std::forward<Args>(args)...), readers_(0) {}

 class MOZ_STACK_CLASS ReadGuard {
   const RWExclusiveData* parent_;
   explicit ReadGuard(std::nullptr_t) : parent_(nullptr) {}

  public:
   ReadGuard(const ReadGuard&) = delete;
   ReadGuard& operator=(const ReadGuard&) = delete;

   explicit ReadGuard(const RWExclusiveData& parent) : parent_(&parent) {
     parent_->acquireReaderLock();
   }

   ReadGuard(ReadGuard&& rhs) : parent_(rhs.parent_) {
     MOZ_ASSERT(&rhs != this, "self-move disallowed!");
     rhs.parent_ = nullptr;
   }

   ReadGuard& operator=(ReadGuard&& rhs) {
     this->~ReadGuard();
     new (this) ReadGuard(std::move(rhs));
     return *this;
   }

   const T& get() const {
     MOZ_ASSERT(parent_);
     return parent_->value_;
   }

   operator const T&() const { return get(); }
   const T* operator->() const { return &get(); }

   const RWExclusiveData<T>* parent() const {
     MOZ_ASSERT(parent_);
     return parent_;
   }

   ~ReadGuard() {
     if (parent_) {
       parent_->releaseReaderLock();
     }
   }
 };

 class MOZ_STACK_CLASS WriteGuard {
   const RWExclusiveData* parent_;
   explicit WriteGuard(std::nullptr_t) : parent_(nullptr) {}

  public:
   WriteGuard(const WriteGuard&) = delete;
   WriteGuard& operator=(const WriteGuard&) = delete;

   explicit WriteGuard(const RWExclusiveData& parent) : parent_(&parent) {
     parent_->acquireWriterLock();
   }

   WriteGuard(WriteGuard&& rhs) : parent_(rhs.parent_) {
     MOZ_ASSERT(&rhs != this, "self-move disallowed!");
     rhs.parent_ = nullptr;
   }

   WriteGuard& operator=(WriteGuard&& rhs) {
     this->~WriteGuard();
     new (this) WriteGuard(std::move(rhs));
     return *this;
   }

   T& get() const {
     MOZ_ASSERT(parent_);
     return parent_->value_;
   }

   operator T&() const { return get(); }
   T* operator->() const { return &get(); }

   const RWExclusiveData<T>* parent() const {
     MOZ_ASSERT(parent_);
     return parent_;
   }

   ~WriteGuard() {
     if (parent_) {
       parent_->releaseWriterLock();
     }
   }
 };

 ReadGuard readLock() const { return ReadGuard(*this); }
 WriteGuard writeLock() const { return WriteGuard(*this); }
};

}  // namespace js

#endif  // threading_ExclusiveData_h