From 6bf0a5cb5034a7e684dcc3500e841785237ce2dd Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 19:32:43 +0200 Subject: Adding upstream version 1:115.7.0. Signed-off-by: Daniel Baumann --- xpcom/base/OwningNonNull.h | 213 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 xpcom/base/OwningNonNull.h (limited to 'xpcom/base/OwningNonNull.h') 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 is similar to a RefPtr, 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 instead. +// +// Compared to a plain RefPtr, 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 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 was to implement a class with the +// same auto-conversion and annotation semantics as mozilla::dom::NonNull +// (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, 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 MOZ_IS_SMARTPTR_TO_REFCOUNTED OwningNonNull { + public: + using element_type = T; + + OwningNonNull() = default; + + MOZ_IMPLICIT OwningNonNull(T& aValue) { init(&aValue); } + + template + MOZ_IMPLICIT OwningNonNull(already_AddRefed&& aValue) { + init(aValue); + } + + template + MOZ_IMPLICIT OwningNonNull(RefPtr&& aValue) { + init(std::move(aValue)); + } + + template + MOZ_IMPLICIT OwningNonNull(const OwningNonNull& 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& operator=(T* aValue) { + init(aValue); + return *this; + } + + OwningNonNull& operator=(T& aValue) { + init(&aValue); + return *this; + } + + template + OwningNonNull& operator=(already_AddRefed&& aValue) { + init(aValue); + return *this; + } + + template + OwningNonNull& operator=(RefPtr&& aValue) { + init(std::move(aValue)); + return *this; + } + + template + OwningNonNull& operator=(const OwningNonNull& 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 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 was set to null"); + return mPtr; + } + + template + 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 + friend void ImplCycleCollectionUnlink(OwningNonNull& aField); + + protected: + template + void init(U&& aValue) { + mPtr = std::move(aValue); + MOZ_ASSERT(mPtr); +#ifdef DEBUG + mInited = true; +#endif + } + + RefPtr mPtr; +#ifdef DEBUG + bool mInited = false; +#endif +}; + +template +inline void ImplCycleCollectionUnlink(OwningNonNull& aField) { + aField.unlinkForCC(); +} + +template +inline void ImplCycleCollectionTraverse( + nsCycleCollectionTraversalCallback& aCallback, OwningNonNull& aField, + const char* aName, uint32_t aFlags = 0) { + CycleCollectionNoteChild(aCallback, aField.get(), aName, aFlags); +} + +} // namespace mozilla + +// Declared in nsCOMPtr.h +template +template +nsCOMPtr::nsCOMPtr(const mozilla::OwningNonNull& aOther) + : nsCOMPtr(aOther.get()) {} + +template +template +nsCOMPtr& nsCOMPtr::operator=(const mozilla::OwningNonNull& aOther) { + return operator=(aOther.get()); +} + +// Declared in mozilla/RefPtr.h +template +template +RefPtr::RefPtr(const mozilla::OwningNonNull& aOther) + : RefPtr(aOther.get()) {} + +template +template +RefPtr& RefPtr::operator=(const mozilla::OwningNonNull& aOther) { + return operator=(aOther.get()); +} + +#endif // mozilla_OwningNonNull_h -- cgit v1.2.3