/* -*- 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 */