/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* 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/. */ /** * CopyOnWrite<T> allows code to safely read from a data structure without * worrying that reentrant code will modify it. */ #ifndef mozilla_image_CopyOnWrite_h #define mozilla_image_CopyOnWrite_h #include "mozilla/RefPtr.h" #include "MainThreadUtils.h" #include "nsISupportsImpl.h" namespace mozilla { namespace image { /////////////////////////////////////////////////////////////////////////////// // Implementation Details /////////////////////////////////////////////////////////////////////////////// namespace detail { template <typename T> class CopyOnWriteValue final { public: NS_INLINE_DECL_REFCOUNTING(CopyOnWriteValue) explicit CopyOnWriteValue(T* aValue) : mValue(aValue) { } explicit CopyOnWriteValue(already_AddRefed<T>& aValue) : mValue(aValue) { } explicit CopyOnWriteValue(already_AddRefed<T>&& aValue) : mValue(aValue) { } explicit CopyOnWriteValue(const RefPtr<T>& aValue) : mValue(aValue) { } explicit CopyOnWriteValue(RefPtr<T>&& aValue) : mValue(aValue) { } T* get() { return mValue.get(); } const T* get() const { return mValue.get(); } bool HasReaders() const { return mReaders > 0; } bool HasWriter() const { return mWriter; } bool HasUsers() const { return HasReaders() || HasWriter(); } void LockForReading() { MOZ_ASSERT(!HasWriter()); mReaders++; } void UnlockForReading() { MOZ_ASSERT(HasReaders()); mReaders--; } struct MOZ_STACK_CLASS AutoReadLock { explicit AutoReadLock(CopyOnWriteValue* aValue) : mValue(aValue) { mValue->LockForReading(); } ~AutoReadLock() { mValue->UnlockForReading(); } CopyOnWriteValue<T>* mValue; }; void LockForWriting() { MOZ_ASSERT(!HasUsers()); mWriter = true; } void UnlockForWriting() { MOZ_ASSERT(HasWriter()); mWriter = false; } struct MOZ_STACK_CLASS AutoWriteLock { explicit AutoWriteLock(CopyOnWriteValue* aValue) : mValue(aValue) { mValue->LockForWriting(); } ~AutoWriteLock() { mValue->UnlockForWriting(); } CopyOnWriteValue<T>* mValue; }; private: CopyOnWriteValue(const CopyOnWriteValue&) = delete; CopyOnWriteValue(CopyOnWriteValue&&) = delete; ~CopyOnWriteValue() { } RefPtr<T> mValue; uint64_t mReaders = 0; bool mWriter = false; }; } // namespace detail /////////////////////////////////////////////////////////////////////////////// // Public API /////////////////////////////////////////////////////////////////////////////// /** * CopyOnWrite<T> allows code to safely read from a data structure without * worrying that reentrant code will modify it. If reentrant code would modify * the data structure while other code is reading from it, a copy is made so * that readers can continue to use the old version. * * Note that it's legal to nest a writer inside any number of readers, but * nothing can be nested inside a writer. This is because it's assumed that the * state of the contained data structure may not be consistent during the write. * * This is a main-thread-only data structure. * * To work with CopyOnWrite<T>, a type T needs to be reference counted and to * support copy construction. */ template <typename T> class CopyOnWrite final { typedef detail::CopyOnWriteValue<T> CopyOnWriteValue; public: explicit CopyOnWrite(T* aValue) : mValue(new CopyOnWriteValue(aValue)) { } explicit CopyOnWrite(already_AddRefed<T>& aValue) : mValue(new CopyOnWriteValue(aValue)) { } explicit CopyOnWrite(already_AddRefed<T>&& aValue) : mValue(new CopyOnWriteValue(aValue)) { } explicit CopyOnWrite(const RefPtr<T>& aValue) : mValue(new CopyOnWriteValue(aValue)) { } explicit CopyOnWrite(RefPtr<T>&& aValue) : mValue(new CopyOnWriteValue(aValue)) { } /// @return true if it's safe to read at this time. bool CanRead() const { return !mValue->HasWriter(); } /** * Read from the contained data structure using the function @aReader. * @aReader will be passed a pointer of type |const T*|. It's not legal to * call this while a writer is active. * * @return whatever value @aReader returns, or nothing if @aReader is a void * function. */ template <typename ReadFunc> auto Read(ReadFunc aReader) const -> decltype(aReader(static_cast<const T*>(nullptr))) { MOZ_ASSERT(NS_IsMainThread()); MOZ_ASSERT(CanRead()); // Run the provided function while holding a read lock. RefPtr<CopyOnWriteValue> cowValue = mValue; typename CopyOnWriteValue::AutoReadLock lock(cowValue); return aReader(cowValue->get()); } /** * Read from the contained data structure using the function @aReader. * @aReader will be passed a pointer of type |const T*|. If it's currently not * possible to read because a writer is currently active, @aOnError will be * called instead. * * @return whatever value @aReader or @aOnError returns (their return types * must be consistent), or nothing if the provided functions are void. */ template <typename ReadFunc, typename ErrorFunc> auto Read(ReadFunc aReader, ErrorFunc aOnError) const -> decltype(aReader(static_cast<const T*>(nullptr))) { MOZ_ASSERT(NS_IsMainThread()); if (!CanRead()) { return aOnError(); } return Read(aReader); } /// @return true if it's safe to write at this time. bool CanWrite() const { return !mValue->HasWriter(); } /** * Write to the contained data structure using the function @aWriter. * @aWriter will be passed a pointer of type |T*|. It's not legal to call this * while another writer is active. * * If readers are currently active, they will be able to continue reading from * a copy of the old version of the data structure. The copy will be destroyed * when all its readers finish. Later readers and writers will see the * version of the data structure produced by the most recent call to Write(). * * @return whatever value @aWriter returns, or nothing if @aWriter is a void * function. */ template <typename WriteFunc> auto Write(WriteFunc aWriter) -> decltype(aWriter(static_cast<T*>(nullptr))) { MOZ_ASSERT(NS_IsMainThread()); MOZ_ASSERT(CanWrite()); // If there are readers, we need to copy first. if (mValue->HasReaders()) { mValue = new CopyOnWriteValue(new T(*mValue->get())); } // Run the provided function while holding a write lock. RefPtr<CopyOnWriteValue> cowValue = mValue; typename CopyOnWriteValue::AutoWriteLock lock(cowValue); return aWriter(cowValue->get()); } /** * Write to the contained data structure using the function @aWriter. * @aWriter will be passed a pointer of type |T*|. If it's currently not * possible to write because a writer is currently active, @aOnError will be * called instead. * * If readers are currently active, they will be able to continue reading from * a copy of the old version of the data structure. The copy will be destroyed * when all its readers finish. Later readers and writers will see the * version of the data structure produced by the most recent call to Write(). * * @return whatever value @aWriter or @aOnError returns (their return types * must be consistent), or nothing if the provided functions are void. */ template <typename WriteFunc, typename ErrorFunc> auto Write(WriteFunc aWriter, ErrorFunc aOnError) -> decltype(aWriter(static_cast<T*>(nullptr))) { MOZ_ASSERT(NS_IsMainThread()); if (!CanWrite()) { return aOnError(); } return Write(aWriter); } private: CopyOnWrite(const CopyOnWrite&) = delete; CopyOnWrite(CopyOnWrite&&) = delete; RefPtr<CopyOnWriteValue> mValue; }; } // namespace image } // namespace mozilla #endif // mozilla_image_CopyOnWrite_h