summaryrefslogtreecommitdiffstats
path: root/mfbt/NotNull.h
diff options
context:
space:
mode:
Diffstat (limited to 'mfbt/NotNull.h')
-rw-r--r--mfbt/NotNull.h449
1 files changed, 449 insertions, 0 deletions
diff --git a/mfbt/NotNull.h b/mfbt/NotNull.h
new file mode 100644
index 0000000000..1a12400e14
--- /dev/null
+++ b/mfbt/NotNull.h
@@ -0,0 +1,449 @@
+/* -*- 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 mozilla_NotNull_h
+#define mozilla_NotNull_h
+
+// It's often unclear if a particular pointer, be it raw (T*) or smart
+// (RefPtr<T>, nsCOMPtr<T>, etc.) can be null. This leads to missing null
+// checks (which can cause crashes) and unnecessary null checks (which clutter
+// the code).
+//
+// C++ has a built-in alternative that avoids these problems: references. This
+// module defines another alternative, NotNull, which can be used in cases
+// where references are not suitable.
+//
+// In the comments below we use the word "handle" to cover all varieties of
+// pointers and references.
+//
+// References
+// ----------
+// References are always non-null. (You can do |T& r = *p;| where |p| is null,
+// but that's undefined behaviour. C++ doesn't provide any built-in, ironclad
+// guarantee of non-nullness.)
+//
+// A reference works well when you need a temporary handle to an existing
+// single object, e.g. for passing a handle to a function, or as a local handle
+// within another object. (In Rust parlance, this is a "borrow".)
+//
+// A reference is less appropriate in the following cases.
+//
+// - As a primary handle to an object. E.g. code such as this is possible but
+// strange: |T& t = *new T(); ...; delete &t;|
+//
+// - As a handle to an array. It's common for |T*| to refer to either a single
+// |T| or an array of |T|, but |T&| cannot refer to an array of |T| because
+// you can't index off a reference (at least, not without first converting it
+// to a pointer).
+//
+// - When the handle identity is meaningful, e.g. if you have a hashtable of
+// handles, because you have to use |&| on the reference to convert it to a
+// pointer.
+//
+// - Some people don't like using non-const references as function parameters,
+// because it is not clear at the call site that the argument might be
+// modified.
+//
+// - When you need "smart" behaviour. E.g. we lack reference equivalents to
+// RefPtr and nsCOMPtr.
+//
+// - When interfacing with code that uses pointers a lot, sometimes using a
+// reference just feels like an odd fit.
+//
+// Furthermore, a reference is impossible in the following cases.
+//
+// - When the handle is rebound to another object. References don't allow this.
+//
+// - When the handle has type |void|. |void&| is not allowed.
+//
+// NotNull is an alternative that can be used in any of the above cases except
+// for the last one, where the handle type is |void|. See below.
+
+#include <stddef.h>
+
+#include <type_traits>
+#include <utility>
+
+#include "mozilla/Assertions.h"
+
+namespace mozilla {
+
+namespace detail {
+template <typename T>
+struct CopyablePtr {
+ T mPtr;
+
+ template <typename U>
+ explicit CopyablePtr(U&& aPtr) : mPtr{std::forward<U>(aPtr)} {}
+
+ template <typename U>
+ explicit CopyablePtr(CopyablePtr<U> aPtr) : mPtr{std::move(aPtr.mPtr)} {}
+};
+} // namespace detail
+
+template <typename T>
+class MovingNotNull;
+
+// NotNull can be used to wrap a "base" pointer (raw or smart) to indicate it
+// is not null. Some examples:
+//
+// - NotNull<char*>
+// - NotNull<RefPtr<Event>>
+// - NotNull<nsCOMPtr<Event>>
+// - NotNull<UniquePtr<Pointee>>
+//
+// NotNull has the following notable properties.
+//
+// - It has zero space overhead.
+//
+// - It must be initialized explicitly. There is no default initialization.
+//
+// - It auto-converts to the base pointer type.
+//
+// - It does not auto-convert from a base pointer. Implicit conversion from a
+// less-constrained type (e.g. T*) to a more-constrained type (e.g.
+// NotNull<T*>) is dangerous. Creation and assignment from a base pointer can
+// only be done with WrapNotNull() or MakeNotNull<>(), which makes them
+// impossible to overlook, both when writing and reading code.
+//
+// - When initialized (or assigned) it is checked, and if it is null we abort.
+// This guarantees that it cannot be null.
+//
+// - |operator bool()| is deleted. This means you cannot check a NotNull in a
+// boolean context, which eliminates the possibility of unnecessary null
+// checks.
+//
+// - It is not movable, but copyable if the base pointer type is copyable. It
+// may be used together with MovingNotNull to avoid unnecessary copies or when
+// the base pointer type is not copyable (such as UniquePtr<T>).
+//
+template <typename T>
+class NotNull {
+ template <typename U>
+ friend constexpr NotNull<U> WrapNotNull(U aBasePtr);
+ template <typename U>
+ friend constexpr NotNull<U> WrapNotNullUnchecked(U aBasePtr);
+ template <typename U, typename... Args>
+ friend constexpr NotNull<U> MakeNotNull(Args&&... aArgs);
+ template <typename U>
+ friend class NotNull;
+
+ detail::CopyablePtr<T> mBasePtr;
+
+ // This constructor is only used by WrapNotNull() and MakeNotNull<U>().
+ template <typename U>
+ constexpr explicit NotNull(U aBasePtr) : mBasePtr(T{std::move(aBasePtr)}) {
+ static_assert(sizeof(T) == sizeof(NotNull<T>),
+ "NotNull must have zero space overhead.");
+ static_assert(offsetof(NotNull<T>, mBasePtr) == 0,
+ "mBasePtr must have zero offset.");
+ }
+
+ public:
+ // Disallow default construction.
+ NotNull() = delete;
+
+ // Construct/assign from another NotNull with a compatible base pointer type.
+ template <typename U,
+ typename = std::enable_if_t<std::is_convertible_v<const U&, T>>>
+ constexpr MOZ_IMPLICIT NotNull(const NotNull<U>& aOther)
+ : mBasePtr(aOther.mBasePtr) {}
+
+ template <typename U,
+ typename = std::enable_if_t<std::is_convertible_v<U&&, T>>>
+ constexpr MOZ_IMPLICIT NotNull(MovingNotNull<U>&& aOther)
+ : mBasePtr(std::move(aOther).unwrapBasePtr()) {}
+
+ // Disallow null checks, which are unnecessary for this type.
+ explicit operator bool() const = delete;
+
+ // Explicit conversion to a base pointer. Use only to resolve ambiguity or to
+ // get a castable pointer.
+ constexpr const T& get() const { return mBasePtr.mPtr; }
+
+ // Implicit conversion to a base pointer. Preferable to get().
+ constexpr operator const T&() const { return get(); }
+
+ // Implicit conversion to a raw pointer from const lvalue-reference if
+ // supported by the base pointer (for RefPtr<T> -> T* compatibility).
+ template <typename U,
+ std::enable_if_t<!std::is_pointer_v<T> &&
+ std::is_convertible_v<const T&, U*>,
+ int> = 0>
+ constexpr operator U*() const& {
+ return get();
+ }
+
+ // Don't allow implicit conversions to raw pointers from rvalue-references.
+ template <typename U,
+ std::enable_if_t<!std::is_pointer_v<T> &&
+ std::is_convertible_v<const T&, U*> &&
+ !std::is_convertible_v<const T&&, U*>,
+ int> = 0>
+ constexpr operator U*() const&& = delete;
+
+ // Dereference operators.
+ constexpr auto* operator->() const MOZ_NONNULL_RETURN {
+ return mBasePtr.mPtr.operator->();
+ }
+ constexpr decltype(*mBasePtr.mPtr) operator*() const {
+ return *mBasePtr.mPtr;
+ }
+
+ // NotNull can be copied, but not moved. Moving a NotNull with a smart base
+ // pointer would leave a nullptr NotNull behind. The move operations must not
+ // be explicitly deleted though, since that would cause overload resolution to
+ // fail in situations where a copy is possible.
+ NotNull(const NotNull&) = default;
+ NotNull& operator=(const NotNull&) = default;
+};
+
+// Specialization for T* to allow adding MOZ_NONNULL_RETURN attributes.
+template <typename T>
+class NotNull<T*> {
+ template <typename U>
+ friend constexpr NotNull<U> WrapNotNull(U aBasePtr);
+ template <typename U>
+ friend constexpr NotNull<U*> WrapNotNullUnchecked(U* aBasePtr);
+ template <typename U, typename... Args>
+ friend constexpr NotNull<U> MakeNotNull(Args&&... aArgs);
+ template <typename U>
+ friend class NotNull;
+
+ T* mBasePtr;
+
+ // This constructor is only used by WrapNotNull() and MakeNotNull<U>().
+ template <typename U>
+ constexpr explicit NotNull(U* aBasePtr) : mBasePtr(aBasePtr) {}
+
+ public:
+ // Disallow default construction.
+ NotNull() = delete;
+
+ // Construct/assign from another NotNull with a compatible base pointer type.
+ template <typename U,
+ typename = std::enable_if_t<std::is_convertible_v<const U&, T*>>>
+ constexpr MOZ_IMPLICIT NotNull(const NotNull<U>& aOther)
+ : mBasePtr(aOther.get()) {
+ static_assert(sizeof(T*) == sizeof(NotNull<T*>),
+ "NotNull must have zero space overhead.");
+ static_assert(offsetof(NotNull<T*>, mBasePtr) == 0,
+ "mBasePtr must have zero offset.");
+ }
+
+ template <typename U,
+ typename = std::enable_if_t<std::is_convertible_v<U&&, T*>>>
+ constexpr MOZ_IMPLICIT NotNull(MovingNotNull<U>&& aOther)
+ : mBasePtr(NotNull{std::move(aOther)}) {}
+
+ // Disallow null checks, which are unnecessary for this type.
+ explicit operator bool() const = delete;
+
+ // Explicit conversion to a base pointer. Use only to resolve ambiguity or to
+ // get a castable pointer.
+ constexpr T* get() const MOZ_NONNULL_RETURN { return mBasePtr; }
+
+ // Implicit conversion to a base pointer. Preferable to get().
+ constexpr operator T*() const MOZ_NONNULL_RETURN { return get(); }
+
+ // Dereference operators.
+ constexpr T* operator->() const MOZ_NONNULL_RETURN { return get(); }
+ constexpr T& operator*() const { return *mBasePtr; }
+};
+
+template <typename T>
+constexpr NotNull<T> WrapNotNull(T aBasePtr) {
+ MOZ_RELEASE_ASSERT(aBasePtr);
+ return NotNull<T>{std::move(aBasePtr)};
+}
+
+// WrapNotNullUnchecked should only be used in situations, where it is
+// statically known that aBasePtr is non-null, and redundant release assertions
+// should be avoided. It is only defined for raw base pointers, since it is only
+// needed for those right now. There is no fundamental reason not to allow
+// arbitrary base pointers here.
+template <typename T>
+constexpr NotNull<T> WrapNotNullUnchecked(T aBasePtr) {
+ return NotNull<T>{std::move(aBasePtr)};
+}
+
+template <typename T>
+MOZ_NONNULL(1)
+constexpr NotNull<T*> WrapNotNullUnchecked(T* const aBasePtr) {
+#if defined(__clang__)
+# pragma clang diagnostic push
+# pragma clang diagnostic ignored "-Wpointer-bool-conversion"
+#elif defined(__GNUC__)
+# pragma GCC diagnostic push
+# pragma GCC diagnostic ignored "-Wnonnull-compare"
+#endif
+ MOZ_ASSERT(aBasePtr);
+#if defined(__clang__)
+# pragma clang diagnostic pop
+#elif defined(__GNUC__)
+# pragma GCC diagnostic pop
+#endif
+ return NotNull<T*>{aBasePtr};
+}
+
+// A variant of NotNull that can be used as a return value or parameter type and
+// moved into both NotNull and non-NotNull targets. This is not possible with
+// NotNull, as it is not movable. MovingNotNull can therefore not guarantee it
+// is always non-nullptr, but it can't be dereferenced, and there are debug
+// assertions that ensure it is only moved once.
+template <typename T>
+class MOZ_NON_AUTOABLE MovingNotNull {
+ template <typename U>
+ friend constexpr MovingNotNull<U> WrapMovingNotNullUnchecked(U aBasePtr);
+
+ T mBasePtr;
+#ifdef DEBUG
+ bool mConsumed = false;
+#endif
+
+ // This constructor is only used by WrapNotNull() and MakeNotNull<U>().
+ template <typename U>
+ constexpr explicit MovingNotNull(U aBasePtr) : mBasePtr{std::move(aBasePtr)} {
+#ifndef DEBUG
+ static_assert(sizeof(T) == sizeof(MovingNotNull<T>),
+ "NotNull must have zero space overhead.");
+#endif
+ static_assert(offsetof(MovingNotNull<T>, mBasePtr) == 0,
+ "mBasePtr must have zero offset.");
+ }
+
+ public:
+ MovingNotNull() = delete;
+
+ MOZ_IMPLICIT MovingNotNull(const NotNull<T>& aSrc) : mBasePtr(aSrc.get()) {}
+
+ template <typename U,
+ typename = std::enable_if_t<std::is_convertible_v<U, T>>>
+ MOZ_IMPLICIT MovingNotNull(const NotNull<U>& aSrc) : mBasePtr(aSrc.get()) {}
+
+ template <typename U,
+ typename = std::enable_if_t<std::is_convertible_v<U, T>>>
+ MOZ_IMPLICIT MovingNotNull(MovingNotNull<U>&& aSrc)
+ : mBasePtr(std::move(aSrc).unwrapBasePtr()) {}
+
+ MOZ_IMPLICIT operator T() && { return std::move(*this).unwrapBasePtr(); }
+
+ MOZ_IMPLICIT operator NotNull<T>() && { return std::move(*this).unwrap(); }
+
+ NotNull<T> unwrap() && {
+ return WrapNotNullUnchecked(std::move(*this).unwrapBasePtr());
+ }
+
+ T unwrapBasePtr() && {
+#ifdef DEBUG
+ MOZ_ASSERT(!mConsumed);
+ mConsumed = true;
+#endif
+ return std::move(mBasePtr);
+ }
+
+ MovingNotNull(MovingNotNull&&) = default;
+ MovingNotNull& operator=(MovingNotNull&&) = default;
+};
+
+template <typename T>
+constexpr MovingNotNull<T> WrapMovingNotNullUnchecked(T aBasePtr) {
+ return MovingNotNull<T>{std::move(aBasePtr)};
+}
+
+template <typename T>
+constexpr MovingNotNull<T> WrapMovingNotNull(T aBasePtr) {
+ MOZ_RELEASE_ASSERT(aBasePtr);
+ return WrapMovingNotNullUnchecked(std::move(aBasePtr));
+}
+
+namespace detail {
+
+// Extract the pointed-to type from a pointer type (be it raw or smart).
+// The default implementation uses the dereferencing operator of the pointer
+// type to find what it's pointing to.
+template <typename Pointer>
+struct PointedTo {
+ // Remove the reference that dereferencing operators may return.
+ using Type = std::remove_reference_t<decltype(*std::declval<Pointer>())>;
+ using NonConstType = std::remove_const_t<Type>;
+};
+
+// Specializations for raw pointers.
+// This is especially required because VS 2017 15.6 (March 2018) started
+// rejecting the above `decltype(*std::declval<Pointer>())` trick for raw
+// pointers.
+// See bug 1443367.
+template <typename T>
+struct PointedTo<T*> {
+ using Type = T;
+ using NonConstType = T;
+};
+
+template <typename T>
+struct PointedTo<const T*> {
+ using Type = const T;
+ using NonConstType = T;
+};
+
+} // namespace detail
+
+// Allocate an object with infallible new, and wrap its pointer in NotNull.
+// |MakeNotNull<Ptr<Ob>>(args...)| will run |new Ob(args...)|
+// and return NotNull<Ptr<Ob>>.
+template <typename T, typename... Args>
+constexpr NotNull<T> MakeNotNull(Args&&... aArgs) {
+ using Pointee = typename detail::PointedTo<T>::NonConstType;
+ static_assert(!std::is_array_v<Pointee>,
+ "MakeNotNull cannot construct an array");
+ return NotNull<T>(new Pointee(std::forward<Args>(aArgs)...));
+}
+
+// Compare two NotNulls.
+template <typename T, typename U>
+constexpr bool operator==(const NotNull<T>& aLhs, const NotNull<U>& aRhs) {
+ return aLhs.get() == aRhs.get();
+}
+template <typename T, typename U>
+constexpr bool operator!=(const NotNull<T>& aLhs, const NotNull<U>& aRhs) {
+ return aLhs.get() != aRhs.get();
+}
+
+// Compare a NotNull to a base pointer.
+template <typename T, typename U>
+constexpr bool operator==(const NotNull<T>& aLhs, const U& aRhs) {
+ return aLhs.get() == aRhs;
+}
+template <typename T, typename U>
+constexpr bool operator!=(const NotNull<T>& aLhs, const U& aRhs) {
+ return aLhs.get() != aRhs;
+}
+
+// Compare a base pointer to a NotNull.
+template <typename T, typename U>
+constexpr bool operator==(const T& aLhs, const NotNull<U>& aRhs) {
+ return aLhs == aRhs.get();
+}
+template <typename T, typename U>
+constexpr bool operator!=(const T& aLhs, const NotNull<U>& aRhs) {
+ return aLhs != aRhs.get();
+}
+
+// Disallow comparing a NotNull to a nullptr.
+template <typename T>
+bool operator==(const NotNull<T>&, decltype(nullptr)) = delete;
+template <typename T>
+bool operator!=(const NotNull<T>&, decltype(nullptr)) = delete;
+
+// Disallow comparing a nullptr to a NotNull.
+template <typename T>
+bool operator==(decltype(nullptr), const NotNull<T>&) = delete;
+template <typename T>
+bool operator!=(decltype(nullptr), const NotNull<T>&) = delete;
+
+} // namespace mozilla
+
+#endif /* mozilla_NotNull_h */