diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 01:47:29 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 01:47:29 +0000 |
commit | 0ebf5bdf043a27fd3dfb7f92e0cb63d88954c44d (patch) | |
tree | a31f07c9bcca9d56ce61e9a1ffd30ef350d513aa /xpcom/base/OwningNonNull.h | |
parent | Initial commit. (diff) | |
download | firefox-esr-0ebf5bdf043a27fd3dfb7f92e0cb63d88954c44d.tar.xz firefox-esr-0ebf5bdf043a27fd3dfb7f92e0cb63d88954c44d.zip |
Adding upstream version 115.8.0esr.upstream/115.8.0esr
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'xpcom/base/OwningNonNull.h')
-rw-r--r-- | xpcom/base/OwningNonNull.h | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/xpcom/base/OwningNonNull.h b/xpcom/base/OwningNonNull.h new file mode 100644 index 0000000000..24c22f8f60 --- /dev/null +++ b/xpcom/base/OwningNonNull.h @@ -0,0 +1,213 @@ +/* -*- 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/. */ + +/* A class for non-null strong pointers to reference-counted objects. */ + +#ifndef mozilla_OwningNonNull_h +#define mozilla_OwningNonNull_h + +#include "nsCOMPtr.h" +#include "nsCycleCollectionNoteChild.h" + +namespace mozilla { + +// OwningNonNull<T> is similar to a RefPtr<T>, which is not null after initial +// initialization. It has a restricted interface compared to RefPtr, with some +// additional operations defined. The main use is in DOM bindings. Use it +// outside DOM bindings only if you can ensure it never escapes without being +// properly initialized, and you don't need to move it. Otherwise, use a +// RefPtr<T> instead. +// +// Compared to a plain RefPtr<T>, in particular +// - it is copyable but not movable +// - it can be constructed and assigned from T& and is convertible to T& +// implicitly +// - it cannot be cleared by the user once initialized, though it can be +// re-assigned a new (non-null) value +// - it is not convertible to bool, but there is an explicit isInitialized +// member function +// +// Beware that there are two cases where an OwningNonNull<T> actually is nullptr +// - it was default-constructed and not yet initialized +// - it was cleared during CC unlinking. +// All attempts to use it in an invalid state will trigger an assertion in debug +// builds. +// +// The original intent of OwningNonNull<T> was to implement a class with the +// same auto-conversion and annotation semantics as mozilla::dom::NonNull<T> +// (i.e. never null once you have properly initialized it, auto-converts to T&), +// but that holds a strong reference to the object involved. This was designed +// for use in DOM bindings and in particular for storing what WebIDL represents +// as InterfaceName (as opposed to `InterfaceName?`) in various containers +// (dictionaries, sequences). DOM bindings never allow a default-constructed +// uninitialized OwningNonNull to escape. RefPtr could have been used for this +// use case, just like we could have used T* instead of NonNull<T>, but it +// seemed desirable to explicitly annotate the non-null nature of the things +// involved to eliminate pointless null-checks, which otherwise tend to +// proliferate. +template <class T> +class MOZ_IS_SMARTPTR_TO_REFCOUNTED OwningNonNull { + public: + using element_type = T; + + OwningNonNull() = default; + + MOZ_IMPLICIT OwningNonNull(T& aValue) { init(&aValue); } + + template <class U> + MOZ_IMPLICIT OwningNonNull(already_AddRefed<U>&& aValue) { + init(aValue); + } + + template <class U> + MOZ_IMPLICIT OwningNonNull(RefPtr<U>&& aValue) { + init(std::move(aValue)); + } + + template <class U> + MOZ_IMPLICIT OwningNonNull(const OwningNonNull<U>& aValue) { + init(aValue); + } + + // This is no worse than get() in terms of const handling. + operator T&() const { return ref(); } + + operator T*() const { return get(); } + + // Conversion to bool is always true, so delete to catch errors + explicit operator bool() const = delete; + + T* operator->() const { return get(); } + + T& operator*() const { return ref(); } + + OwningNonNull<T>& operator=(T* aValue) { + init(aValue); + return *this; + } + + OwningNonNull<T>& operator=(T& aValue) { + init(&aValue); + return *this; + } + + template <class U> + OwningNonNull<T>& operator=(already_AddRefed<U>&& aValue) { + init(aValue); + return *this; + } + + template <class U> + OwningNonNull<T>& operator=(RefPtr<U>&& aValue) { + init(std::move(aValue)); + return *this; + } + + template <class U> + OwningNonNull<T>& operator=(const OwningNonNull<U>& aValue) { + init(aValue); + return *this; + } + + // Don't allow assigning nullptr, it makes no sense + void operator=(decltype(nullptr)) = delete; + + T& ref() const { + MOZ_ASSERT(mInited); + MOZ_ASSERT(mPtr, "OwningNonNull<T> was set to null"); + return *mPtr; + } + + // Make us work with smart pointer helpers that expect a get(). + T* get() const { + MOZ_ASSERT(mInited); + MOZ_ASSERT(mPtr, "OwningNonNull<T> was set to null"); + return mPtr; + } + + template <typename U> + void swap(U& aOther) { + mPtr.swap(aOther); +#ifdef DEBUG + mInited = mPtr; +#endif + } + + // We have some consumers who want to check whether we're inited in non-debug + // builds as well. Luckily, we have the invariant that we're inited precisely + // when mPtr is non-null. + bool isInitialized() const { + MOZ_ASSERT(!!mPtr == mInited, "mInited out of sync with mPtr?"); + return mPtr; + } + + private: + void unlinkForCC() { +#ifdef DEBUG + mInited = false; +#endif + mPtr = nullptr; + } + + // Allow ImplCycleCollectionUnlink to call unlinkForCC(). + template <typename U> + friend void ImplCycleCollectionUnlink(OwningNonNull<U>& aField); + + protected: + template <typename U> + void init(U&& aValue) { + mPtr = std::move(aValue); + MOZ_ASSERT(mPtr); +#ifdef DEBUG + mInited = true; +#endif + } + + RefPtr<T> mPtr; +#ifdef DEBUG + bool mInited = false; +#endif +}; + +template <typename T> +inline void ImplCycleCollectionUnlink(OwningNonNull<T>& aField) { + aField.unlinkForCC(); +} + +template <typename T> +inline void ImplCycleCollectionTraverse( + nsCycleCollectionTraversalCallback& aCallback, OwningNonNull<T>& aField, + const char* aName, uint32_t aFlags = 0) { + CycleCollectionNoteChild(aCallback, aField.get(), aName, aFlags); +} + +} // namespace mozilla + +// Declared in nsCOMPtr.h +template <class T> +template <class U> +nsCOMPtr<T>::nsCOMPtr(const mozilla::OwningNonNull<U>& aOther) + : nsCOMPtr(aOther.get()) {} + +template <class T> +template <class U> +nsCOMPtr<T>& nsCOMPtr<T>::operator=(const mozilla::OwningNonNull<U>& aOther) { + return operator=(aOther.get()); +} + +// Declared in mozilla/RefPtr.h +template <class T> +template <class U> +RefPtr<T>::RefPtr(const mozilla::OwningNonNull<U>& aOther) + : RefPtr(aOther.get()) {} + +template <class T> +template <class U> +RefPtr<T>& RefPtr<T>::operator=(const mozilla::OwningNonNull<U>& aOther) { + return operator=(aOther.get()); +} + +#endif // mozilla_OwningNonNull_h |