diff options
Diffstat (limited to 'mfbt/NotNull.h')
| -rw-r--r-- | mfbt/NotNull.h | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/mfbt/NotNull.h b/mfbt/NotNull.h new file mode 100644 index 000000000..0c3c333e4 --- /dev/null +++ b/mfbt/NotNull.h @@ -0,0 +1,209 @@ +/* -*- 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 "mozilla/Assertions.h" + +namespace mozilla { + +// 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 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(), 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. +// +// NotNull currently doesn't work with UniquePtr. See +// https://github.com/Microsoft/GSL/issues/89 for some discussion. +// +template <typename T> +class NotNull +{ + template <typename U> friend NotNull<U> WrapNotNull(U aBasePtr); + + T mBasePtr; + + // This constructor is only used by WrapNotNull(). + template <typename U> + 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> + MOZ_IMPLICIT NotNull(const NotNull<U>& aOther) : mBasePtr(aOther.get()) {} + + // Default copy/move construction and assignment. + NotNull(const NotNull<T>&) = default; + NotNull<T>& operator=(const NotNull<T>&) = default; + NotNull(NotNull<T>&&) = default; + NotNull<T>& operator=(NotNull<T>&&) = default; + + // 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. + const T& get() const { return mBasePtr; } + + // Implicit conversion to a base pointer. Preferable to get(). + operator const T&() const { return get(); } + + // Dereference operators. + const T& operator->() const { return get(); } + decltype(*mBasePtr) operator*() const { return *mBasePtr; } +}; + +template <typename T> +NotNull<T> +WrapNotNull(const T aBasePtr) +{ + NotNull<T> notNull(aBasePtr); + MOZ_RELEASE_ASSERT(aBasePtr); + return notNull; +} + +// Compare two NotNulls. +template <typename T, typename U> +inline bool +operator==(const NotNull<T>& aLhs, const NotNull<U>& aRhs) +{ + return aLhs.get() == aRhs.get(); +} +template <typename T, typename U> +inline 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> +inline bool +operator==(const NotNull<T>& aLhs, const U& aRhs) +{ + return aLhs.get() == aRhs; +} +template <typename T, typename U> +inline 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> +inline bool +operator==(const T& aLhs, const NotNull<U>& aRhs) +{ + return aLhs == aRhs.get(); +} +template <typename T, typename U> +inline 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 */ |