react-native-windows 0.83.2 → 0.83.3

package/external/folly/folly/memory/not_null.h

@@ -0,0 +1,449 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+/**
+ * C++ Core Guideline's not_null PtrT>.
+ *
+ * not_null<PtrT> holds a pointer-like type PtrT which is not nullptr.
+ *
+ * not_null<T*> is a drop-in replacement for T* (as long as it's never null).
+ * Specializations not_null_unique_ptr<T> and not_null_shared_ptr<T> are
+ * drop-in replacements for unique_ptr<T> and shared_ptr<T>, respecitively.
+ *
+ * Example:
+ *    void foo(not_null<int*> nnpi) {
+ *      *nnpi = 7; // Safe, since `nnpi` is not null.
+ *    }
+ *
+ *    void bar(not_null_shared_ptr<int> nnspi) {
+ *      foo(nnsp.get());
+ *    }
+ *
+ * Notes:
+ *    - Constructing a not_null<PtrT> from a nullptr-equivalent argument throws
+ *      a std::invalid_argument exception.
+ *    - Cannot be used after move.
+ *    - In debug mode, not_null checks that it is not null on all accesses,
+ *      since use-after-move can cause the underlying PtrT to be null.
+ */
+
+#include <cstddef>
+#include <functional>
+#include <iosfwd>
+#include <memory>
+#include <type_traits>
+
+namespace folly {
+
+namespace detail {
+template <typename T>
+struct is_not_null;
+template <typename FromT, typename ToT>
+struct is_not_null_convertible;
+template <typename FromT, typename ToPtrT>
+struct is_not_null_nothrow_constructible;
+template <typename FromPtrT, typename ToT>
+struct is_not_null_castable;
+template <typename FromPtrT, typename ToT>
+struct is_not_null_move_castable;
+} // namespace detail
+
+class guaranteed_not_null_provider {
+ protected:
+  struct guaranteed_not_null {};
+};
+
+/**
+ * not_null_base, the common interface for all not_null subclasses.
+ *  - Implicitly constructs and casts just like a PtrT.
+ *  - Has unwrap() function to access the underlying PtrT.
+ */
+template <typename PtrT>
+class not_null_base : protected guaranteed_not_null_provider {
+  template <bool>
+  struct implicit_tag {};
+
+ public:
+  using pointer = PtrT;
+  using element_type = typename std::pointer_traits<PtrT>::element_type;
+
+  /**
+   * Construction:
+   *  - Throws std::invalid_argument if null.
+   *  - Cannot default construct.
+   *  - Cannot construct from nullptr.
+   *  - Allows implicit construction iff PtrT allows implicit construction.
+   *  - Construction from another not_null skips null check (in opt builds).
+   */
+  not_null_base() = delete;
+  /* implicit */ not_null_base(std::nullptr_t) = delete;
+
+  not_null_base(const not_null_base& nn) = default;
+  not_null_base(not_null_base&& nn) = default;
+
+  template <
+      typename U,
+      typename =
+          std::enable_if_t<detail::is_not_null_convertible<U&&, PtrT>::value>>
+  /* implicit */ not_null_base(U&& u, implicit_tag<true> = {}) noexcept(
+      detail::is_not_null_nothrow_constructible<U&&, PtrT>::value);
+
+  template <
+      typename U,
+      typename =
+          std::enable_if_t<!detail::is_not_null_convertible<U&&, PtrT>::value>>
+  explicit not_null_base(U&& u, implicit_tag<false> = {}) noexcept(
+      detail::is_not_null_nothrow_constructible<U&&, PtrT>::value);
+
+  // Allow construction without a null check for trusted callsites.
+  explicit not_null_base(
+      PtrT&& ptr, guaranteed_not_null_provider::guaranteed_not_null) noexcept;
+
+  /**
+   * Assignment:
+   *  - Due to implicit construction, just need to assign from self.
+   *  - Cannot assign from nullptr.
+   */
+  not_null_base& operator=(std::nullptr_t) = delete;
+  not_null_base& operator=(const not_null_base& nn) = default;
+  not_null_base& operator=(not_null_base&& nn) = default;
+
+  /**
+   * Dereferencing:
+   *  - Does not return mutable references, since that would allow the
+   *    underlying pointer to be assigned to nullptr.
+   */
+  element_type& operator*() const noexcept;
+  const PtrT& operator->() const noexcept;
+
+  /**
+   * Casting:
+   *  - Implicit casting to PtrT allowed, so that not_null<PtrT> can be used
+   *    wherever a PtrT is expected.
+   *  - Does not return mutable references, since that would allow the
+   *    underlying pointer to be assigned to nullptr.
+   *  - Boolean cast is always true.
+   */
+  operator const PtrT&() const& noexcept;
+  operator PtrT&&() && noexcept;
+
+  template <
+      typename U,
+      typename = std::enable_if_t<detail::is_not_null_castable<PtrT, U>::value>>
+  operator U() const& noexcept(std::is_nothrow_constructible_v<U, const PtrT&>);
+
+  template <
+      typename U,
+      typename =
+          std::enable_if_t<detail::is_not_null_move_castable<PtrT, U>::value>>
+  operator U() && noexcept(std::is_nothrow_constructible_v<U, PtrT&&>);
+
+  explicit inline operator bool() const noexcept { return true; }
+
+  /**
+   * Swap
+   */
+  void swap(not_null_base& other) noexcept;
+
+  /**
+   * Accessor:
+   *  - Can explicitly access the underlying type via `unwrap`.
+   *  - Does not return mutable references, since that would allow the
+   *    underlying pointer to be assigned to nullptr.
+   */
+  const PtrT& unwrap() const& noexcept;
+  PtrT&& unwrap() && noexcept;
+
+ protected:
+  void throw_if_null() const;
+  template <typename T>
+  static void throw_if_null(const T& ptr);
+  template <typename T>
+  static void terminate_if_null(const T& ptr);
+  template <typename Deleter>
+  static Deleter&& forward_or_throw_if_null(Deleter&& deleter);
+
+  // Non-const accessor.
+  PtrT& mutable_unwrap() noexcept;
+
+ private:
+  struct private_tag {};
+  template <typename U>
+  not_null_base(U&& u, private_tag);
+
+  PtrT ptr_;
+};
+
+/**
+ * not_null specializable class.
+ *
+ * Default implementation is not_null_base.
+ */
+template <typename PtrT>
+class not_null : public not_null_base<PtrT> {
+ public:
+  using pointer = typename not_null_base<PtrT>::pointer;
+  using element_type = typename not_null_base<PtrT>::element_type;
+  using not_null_base<PtrT>::not_null_base;
+};
+
+/**
+ * not_null<std::unique_ptr<>> specialization.
+ *
+ * alias: not_null_unique_ptr
+ *
+ * Provides API compatibility with unique_ptr, except:
+ *  - Pointer arguments must be non-null.
+ *  - Cannot reset().
+ *  - Functions are not noexcept, since debug-mode checks can throw exceptions.
+ *  - Promotes returned pointers to be not_null pointers. Implicit casting
+ *    allows these to be used in place of regular pointers.
+ *
+ * Notes:
+ *  - Has make_not_null_unique, equivalent to std::make_unique
+ */
+template <typename T, typename Deleter>
+class not_null<std::unique_ptr<T, Deleter>>
+    : public not_null_base<std::unique_ptr<T, Deleter>> {
+ public:
+  using pointer = not_null<typename std::unique_ptr<T, Deleter>::pointer>;
+  using element_type = typename std::unique_ptr<T, Deleter>::element_type;
+  using deleter_type = typename std::unique_ptr<T, Deleter>::deleter_type;
+
+  /**
+   * Constructors. Most are inherited from not_null_base.
+   */
+  using not_null_base<std::unique_ptr<T, Deleter>>::not_null_base;
+
+  not_null(pointer p, const Deleter& d);
+  not_null(pointer p, Deleter&& d);
+
+  /**
+   * not_null_unique_ptr cannot be released - that would cause it to be null.
+   */
+  pointer release() = delete;
+
+  /**
+   * not_null_unique_ptr can only be reset to a non-null pointer.
+   */
+  void reset(std::nullptr_t) = delete;
+  void reset(pointer ptr) noexcept;
+
+  /**
+   * get() returns a not_null (pointer type is not_null<T*>).
+   *
+   * Due to implicit casting, can still capture the result of get() as a regular
+   * pointer type:
+   *
+   *   int* ptr = not_null_unique_ptr<int>(...).get(); // valid
+   */
+  pointer get() const noexcept;
+
+  /**
+   * get_deleter(): same as for unique_ptr.
+   */
+  Deleter& get_deleter() noexcept;
+  const Deleter& get_deleter() const noexcept;
+};
+
+template <typename T, typename Deleter = std::default_delete<T>>
+using not_null_unique_ptr = not_null<std::unique_ptr<T, Deleter>>;
+
+template <typename T, typename... Args>
+not_null_unique_ptr<T> make_not_null_unique(Args&&... args);
+
+/**
+ * not_null<std::shared_ptr<>> specialization.
+ *
+ * alias: not_null_shared_ptr
+ *
+ * Provides API compatibility with shared_ptr, except:
+ *  - Pointer arguments must be non-null.
+ *  - Cannot reset().
+ *  - Functions are not noexcept, since debug-mode checks can throw exceptions.
+ *  - Promotes returned pointers to be not_null pointers. Implicit casting
+ *    allows these to be used in place of regular pointers.
+ *
+ * Notes:
+ *  - Has make_not_null_shared, equivalent to std::make_shared.
+ */
+template <typename T>
+class not_null<std::shared_ptr<T>> : public not_null_base<std::shared_ptr<T>> {
+ public:
+  using element_type = typename std::shared_ptr<T>::element_type;
+  using pointer = not_null<element_type*>;
+  using weak_type = typename std::shared_ptr<T>::weak_type;
+
+  /**
+   * Constructors. Most are inherited from not_null_base.
+   */
+  using not_null_base<std::shared_ptr<T>>::not_null_base;
+
+  template <typename U, typename Deleter>
+  not_null(U* ptr, Deleter d);
+  template <typename U, typename Deleter>
+  not_null(not_null<U*> ptr, Deleter d);
+
+  /**
+   * Aliasing constructors.
+   *
+   * Note:
+   *  - The aliased shared_ptr argument, @r, is allowed to be null. The
+   *    constructed object is not null iff @ptr is.
+   */
+  template <typename U>
+  not_null(const std::shared_ptr<U>& r, not_null<element_type*> ptr) noexcept;
+  template <typename U>
+  not_null(
+      const not_null<std::shared_ptr<U>>& r,
+      not_null<element_type*> ptr) noexcept;
+  template <typename U>
+  not_null(std::shared_ptr<U>&& r, not_null<element_type*> ptr) noexcept;
+  template <typename U>
+  not_null(
+      not_null<std::shared_ptr<U>>&& r, not_null<element_type*> ptr) noexcept;
+
+  /**
+   * not_null_shared_ptr can only be reset to a non-null pointer.
+   */
+  void reset() = delete;
+  template <typename U>
+  void reset(U* ptr);
+  template <typename U>
+  void reset(not_null<U*> ptr) noexcept;
+  template <typename U, typename Deleter>
+  void reset(U* ptr, Deleter d);
+  template <typename U, typename Deleter>
+  void reset(not_null<U*> ptr, Deleter d);
+
+  /**
+   * get() returns a not_null.
+   *
+   * Due to implicit casting, can still capture the result of get() as a regular
+   * pointer type:
+   *
+   *   int* ptr = not_null_shared_ptr<int>(...).get(); // valid
+   */
+  pointer get() const noexcept;
+
+  /**
+   * use_count()
+   * owner_before()
+   *
+   * Same as shared_ptr.
+   *
+   * Notes:
+   *  - unique() is deprecated in c++17, so is not implemented here. Can call
+   *    not_null_shared_ptr.unwrap().unique() as a workaround, until unique()
+   *    is removed in C++20.
+   */
+  long use_count() const noexcept;
+  template <typename U>
+  bool owner_before(const std::shared_ptr<U>& other) const noexcept;
+  template <typename U>
+  bool owner_before(const not_null<std::shared_ptr<U>>& other) const noexcept;
+};
+
+template <typename T>
+using not_null_shared_ptr = not_null<std::shared_ptr<T>>;
+
+template <typename T, typename... Args>
+not_null_shared_ptr<T> make_not_null_shared(Args&&... args);
+
+template <typename T, typename Alloc, typename... Args>
+not_null_shared_ptr<T> allocate_not_null_shared(
+    const Alloc& alloc, Args&&... args);
+
+/**
+ * Comparison:
+ *  - Forwards to underlying PtrT.
+ *  - Works when one of the operands is not not_null.
+ *  - Works when one of the operands is nullptr.
+ */
+#define FB_NOT_NULL_MK_OP(op)                                      \
+  template <typename PtrT, typename T>                             \
+  bool operator op(const not_null<PtrT>& lhs, const T& rhs);       \
+  template <                                                       \
+      typename PtrT,                                               \
+      typename T,                                                  \
+      typename = std::enable_if_t<!detail::is_not_null<T>::value>> \
+  bool operator op(const T& lhs, const not_null<PtrT>& rhs);
+FB_NOT_NULL_MK_OP(==)
+FB_NOT_NULL_MK_OP(!=)
+FB_NOT_NULL_MK_OP(<)
+FB_NOT_NULL_MK_OP(<=)
+FB_NOT_NULL_MK_OP(>)
+FB_NOT_NULL_MK_OP(>=)
+#undef FB_NOT_NULL_MK_OP
+
+/**
+ * Output:
+ *  - Forwards to underlying PtrT.
+ */
+template <typename U, typename V, typename PtrT>
+std::basic_ostream<U, V>& operator<<(
+    std::basic_ostream<U, V>& os, const not_null<PtrT>& ptr);
+
+/**
+ * Swap
+ */
+template <typename PtrT>
+void swap(not_null<PtrT>& lhs, not_null<PtrT>& rhs) noexcept;
+
+/**
+ * Getters
+ */
+template <typename Deleter, typename T>
+Deleter* get_deleter(const not_null_shared_ptr<T>& ptr);
+
+/**
+ * Casting
+ */
+template <typename T, typename U>
+not_null_shared_ptr<T> static_pointer_cast(const not_null_shared_ptr<U>& r);
+template <typename T, typename U>
+not_null_shared_ptr<T> static_pointer_cast(not_null_shared_ptr<U>&& r);
+template <typename T, typename U>
+std::shared_ptr<T> dynamic_pointer_cast(const not_null_shared_ptr<U>& r);
+template <typename T, typename U>
+std::shared_ptr<T> dynamic_pointer_cast(not_null_shared_ptr<U>&& r);
+template <typename T, typename U>
+not_null_shared_ptr<T> const_pointer_cast(const not_null_shared_ptr<U>& r);
+template <typename T, typename U>
+not_null_shared_ptr<T> const_pointer_cast(not_null_shared_ptr<U>&& r);
+template <typename T, typename U>
+not_null_shared_ptr<T> reinterpret_pointer_cast(
+    const not_null_shared_ptr<U>& r);
+template <typename T, typename U>
+not_null_shared_ptr<T> reinterpret_pointer_cast(not_null_shared_ptr<U>&& r);
+
+template <typename PtrT>
+not_null(PtrT&&) -> not_null<std::remove_cv_t<std::remove_reference_t<PtrT>>>;
+
+} // namespace folly
+
+namespace std {
+/**
+ * Hashing:
+ *  - Forwards to underlying PtrT.
+ */
+template <typename PtrT>
+struct hash<::folly::not_null<PtrT>> : hash<PtrT> {};
+} // namespace std
+
+#include <folly/memory/not_null-inl.h>