react-native-executorch 0.4.9 → 0.5.0-nightly-6f4dd53-20251211

package/third-party/include/executorch/runtime/core/portable_type/tensor_impl.h

@@ -0,0 +1,281 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <executorch/runtime/core/array_ref.h>
+#include <executorch/runtime/core/error.h>
+#include <executorch/runtime/core/portable_type/scalar_type.h>
+#include <executorch/runtime/core/tensor_shape_dynamism.h>
+
+// Forward declaration of a helper that provides access to internal resizing
+// methods of TensorImpl. Real definition is in
+// executorch/runtime/core/exec_aten/tensor_util.h.
+namespace executorch {
+namespace runtime {
+namespace internal {
+class TensorResizerFriend;
+} // namespace internal
+} // namespace runtime
+} // namespace executorch
+
+namespace executorch {
+namespace runtime {
+namespace etensor {
+
+/**
+ * Manages the storage behind an ETensor (torch::executor::Tensor).
+ *
+ * Note that instances of this class do not own the arrays given to it
+ * (sizes/strides/data), which means that the caller must guarantee that they
+ * live longer than a given instance of this class.
+ *
+ * Note on types:
+ *
+ * Code that uses ETensor should also be able to build against at::Tensor. So,
+ * although the overlapping APIs don't need to be exactly the same, their types
+ * should be semantically similar.
+ *
+ * Many of the methods in at::Tensor use int64_t for parameter and return types.
+ * This can be a waste when building for 32-bit environments. So, TensorImpl and
+ * ETensor use ssize_t instead: like int64_t it is signed, but it will match the
+ * native word size of the target architecture. This will avoid unnecessarily
+ * expensive uses of 64-bit integers on 32-bit machines.
+ *
+ * But, since the types are not identical, code that uses ETensor needs to be
+ * generic about the local types it uses when working with these methods. In
+ * most cases, `auto` will do the trick. In the worst case, code can be guarded
+ * with `#ifdef USE_ATEN_LIB`.
+ */
+class TensorImpl {
+public:
+  /**
+   * The type used for elements of `sizes()`.
+   *
+   * This must match the size/signedness of the type used for `Tensor.sizes` in
+   * //executorch/schema/program.fbs.
+   *
+   * Note that at::TensorImpl uses `int64_t` for this type. ExecuTorch uses
+   * `int32_t` to save memory, since no single size value will ever be larger
+   * than 2 billion.
+   */
+  using SizesType = int32_t;
+
+  /**
+   * The type used for elements of `dim_order()`.
+   *
+   * This must match the size/signedness of the type used for `Tensor.dim_order`
+   * in //executorch/schema/program.fbs.
+   */
+  using DimOrderType = uint8_t;
+
+  /**
+   * The type used for elements of `strides()`.
+   *
+   * This must match the size/signedness of the type used for `Tensor.strides`
+   * in //executorch/schema/program.fbs.
+   *
+   * Note that at::TensorImpl uses `int64_t` for this type. ExecuTorch uses
+   * `int32_t` to save memory, since no single stride value will ever be larger
+   * than 2 billion.
+   */
+  using StridesType = int32_t;
+
+  TensorImpl() = delete;
+
+  /**
+   * @param type The type of the data (int, float, bool).
+   * @param dim Number of dimensions, and the length of the `sizes` array.
+   * @param sizes Sizes of the tensor at each dimension. Must contain `dim`
+   *     entries.
+   * @param data Pointer to the data, whose size is determined by `type`,
+   *     `dim`, and `sizes`. The tensor will not own this memory.
+   * @param dim_order Order in which dimensions are laid out in memory.
+   * @param strides Strides of the tensor at each dimension. Must contain `dim`
+   *     entries.
+   * @param dynamism The mutability of the shape of the tensor.
+   */
+  TensorImpl(ScalarType type, ssize_t dim, SizesType *sizes,
+             void *data = nullptr, DimOrderType *dim_order = nullptr,
+             StridesType *strides = nullptr,
+             TensorShapeDynamism dynamism = TensorShapeDynamism::STATIC);
+
+  /**
+   * Returns the size of the tensor in bytes.
+   *
+   * NOTE: This returns the size of the data used by the tensor's current shape,
+   * not the capacity of the underlying buffer.
+   */
+  size_t nbytes() const;
+
+  /**
+   * Returns the size of the tensor at the given dimension.
+   *
+   * NOTE: size() intentionally does not return SizeType even though it
+   * returns an element of an array of SizeType. This is to help make calls of
+   * this method more compatible with at::Tensor, and more consistent with the
+   * rest of the methods on this class and in ETensor.
+   */
+  ssize_t size(ssize_t dim) const {
+    ET_CHECK_MSG(dim < dim_ && dim >= 0,
+                 "Dimension out of range (expected to be in range of [0, %zd], "
+                 "but got %zd",
+                 dim_ - 1, dim);
+    return sizes_[dim];
+  }
+
+  /// Returns the tensor's number of dimensions.
+  ssize_t dim() const { return dim_; }
+
+  /// Returns the number of elements in the tensor.
+  ssize_t numel() const { return numel_; }
+
+  /// Returns the type of the elements in the tensor (int32, float, bool, etc).
+  ScalarType scalar_type() const { return type_; }
+
+  inline ScalarType dtype() const { return scalar_type(); }
+
+  /// Returns the size in bytes of one element of the tensor.
+  ssize_t element_size() const;
+
+  /// Returns the sizes of the tensor at each dimension.
+  const ArrayRef<SizesType> sizes() const {
+    return ArrayRef<SizesType>{sizes_, static_cast<size_t>(dim_)};
+  }
+
+  /// Returns the order the dimensions are laid out in memory.
+  const ArrayRef<DimOrderType> dim_order() const {
+    return ArrayRef<DimOrderType>{dim_order_, static_cast<size_t>(dim_)};
+  }
+
+  /// Returns the strides of the tensor at each dimension.
+  const ArrayRef<StridesType> strides() const {
+    return ArrayRef<StridesType>{strides_, static_cast<size_t>(dim_)};
+  }
+
+  /// Returns the mutability of the shape of the tensor.
+  TensorShapeDynamism shape_dynamism() const { return shape_dynamism_; }
+
+  /// Returns a pointer of type T to the constant underlying data blob.
+  template <typename T> inline const T *data() const {
+    return static_cast<const T *>(data());
+  }
+
+  /// Returns a pointer to the constant underlying data blob.
+  const void *data() const { return data_; }
+
+  /// Returns a pointer of type T to the mutable underlying data blob.
+  template <typename T> inline T *mutable_data() const {
+    return static_cast<T *>(mutable_data());
+  }
+
+  /// Returns a pointer to the mutable underlying data blob.
+  void *mutable_data() const { return data_; }
+
+  /// Sets the underlying data blob to the passed in pointer.
+  void set_data(void *ptr) { data_ = ptr; }
+
+  /*
+   * DEPRECATED: Use torch::executor::resize_tensor() or
+   * torch::executor::resize_tensor_impl().
+   */
+  ET_DEPRECATED
+  void set_sizes_contiguous(ArrayRef<SizesType> new_sizes) {
+    Error err = internal_resize_contiguous(new_sizes);
+    ET_CHECK_MSG(err == Error::Ok,
+                 "Could not resize Tensor; see logs for details");
+  }
+
+private:
+  // For access to internal_resize_contiguous().
+  friend class ::executorch::runtime::internal::TensorResizerFriend;
+
+  /**
+   * Set the sizes and strides of a tensor assuming contiguous strides.
+   * Requires that `new_sizes.size() == this.dim()`.
+   *
+   * Callers must use torch::executor::resize_tensor() or
+   * torch::executor::resize_tensor_impl() instead, defined in TensorUtil.h.
+   *
+   * Same semantics as at::TensorImpl::set_sizes_contiguous(), but returns an
+   * error instead of panicking on failure. This is not part of the at::Tensor
+   * API, and can only be used in lean mode.
+   */
+  ET_NODISCARD Error internal_resize_contiguous(ArrayRef<SizesType> new_sizes);
+
+private:
+  // Keep fields arranged to avoid unnecessary alignment holes.
+
+  /// List of sizes of each dimension in the tensor.
+  SizesType *sizes_;
+
+  /// List of the order that dimensions are laid out in memory.
+  DimOrderType *dim_order_;
+
+  // TODO(T148356881): Get rid of strides from ETensor
+  StridesType *strides_;
+
+  /// Pointer to underlying data blob. NOTE: Can be null.
+  void *data_;
+
+  /// Tensor's number of dimensions.
+  const ssize_t dim_;
+
+  /// Number of elements in the tensor.
+  ssize_t numel_;
+
+  /// Maximum number of elements in the bounded tensor. Used when resizing up
+  /// and down.
+  size_t numel_bound_;
+
+  /// Scalar type (int, float, bool, etc) of the tensor data.
+  const ScalarType type_;
+
+  /// Specifies the mutability of the shape of the tensor.
+  const TensorShapeDynamism shape_dynamism_;
+};
+
+/**
+ * Compute the number of elements based on the sizes of a tensor.
+ */
+ssize_t compute_numel(
+    const ::executorch::runtime::etensor::TensorImpl::SizesType *sizes,
+    ssize_t dim);
+
+/// Appropriate format specifier for the result of calling
+/// size(). Must be used instead of using zd directly to support ATen
+/// mode.
+#define ET_PRI_TENSOR_SIZE "zd"
+
+/// Appropriate format specifier for the result of calling
+/// dim(). Must be used instead of using zd directly to support ATen
+/// mode.
+#define ET_PRI_TENSOR_DIM "zd"
+
+/// Appropriate format specifier for the result of calling
+/// numel(). Must be used instead of using zd directly to support ATen
+/// mode.
+#define ET_PRI_TENSOR_NUMEL "zd"
+
+// Appropriate format specifier for elements of sizes() and
+// strides(). Must be used instead of using d directly to support ATen
+// mode.
+#define ET_PRI_SIZES_AND_STRIDES "d"
+
+} // namespace etensor
+} // namespace runtime
+} // namespace executorch
+
+namespace torch {
+namespace executor {
+// TODO(T197294990): Remove these deprecated aliases once all users have moved
+// to the new `::executorch` namespaces.
+using ::executorch::runtime::etensor::compute_numel;
+using ::executorch::runtime::etensor::TensorImpl;
+} // namespace executor
+} // namespace torch

package/third-party/include/executorch/runtime/core/portable_type/tensor_options.h

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <cstdint>
+
+namespace executorch {
+namespace runtime {
+namespace etensor {
+
+/**
+ * Tensor data memory formats supported by ExecuTorch. This concept only exists
+ * for compatibility with ATen; use dim_order to describe non-contiguous
+ * layouts.
+ */
+enum class MemoryFormat : int8_t {
+  /**
+   * Row-major contiguous data.
+   */
+  Contiguous = 0,
+  /**
+   * Output tensor format should remain the same as the input tensor format.
+   * E.g. if the input tensor is in channels_last format, operator output
+   * should be in channels_last format.
+   */
+  Preserve = 1,
+};
+
+/**
+ * Tensor data memory layout. This concept only exists for compatibility
+ * with ATen.
+ */
+enum class Layout : int8_t {
+  /**
+   * The tensor occupies memory densely and indexing is managed through strides.
+   * Contrasted with a sparse tensor layout where the memory structure of the
+   * data blob will be more complicated and indexing requires larger structures.
+   *
+   * This is the only layout supported by ExecuTorch.
+   */
+  Strided = 0,
+};
+} // namespace etensor
+} // namespace runtime
+} // namespace executorch
+
+namespace torch {
+namespace executor {
+// TODO(T197294990): Remove these deprecated aliases once all users have moved
+// to the new `::executorch` namespaces.
+using ::executorch::runtime::etensor::Layout;
+using ::executorch::runtime::etensor::MemoryFormat;
+} // namespace executor
+} // namespace torch

package/third-party/include/executorch/runtime/core/result.h

@@ -0,0 +1,258 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @file
+ * Result type to be used in conjunction with ExecuTorch Error type.
+ */
+
+#pragma once
+
+#include <new>
+#include <utility>
+
+#include "executorch/runtime/core/error.h"
+#include "executorch/runtime/platform/assert.h"
+
+namespace executorch {
+namespace runtime {
+
+/**
+ * Result type wrapping either a value of type T or an error.
+ *
+ * Example use case:
+ * @code
+ *   Result<OpFn> getOp(int opcode) {
+ *     if (isValidOpCode(opcode)) {
+ *       return opFns[opcode];
+ *     }
+ *     return Error::NotFound;
+ *   }
+ *
+ *   Error useOp(int opcode) {
+ *     Result<OpFn> op = getOp(opcode);
+ *     if (!op.ok()) {
+ *       return op.error();
+ *     }
+ *     print(op->toString());
+ *     execute(*op);
+ *     return Error::Ok;
+ *   }
+ * @endcode
+ */
+template <typename T> class Result final {
+public:
+  /// `value_type` member for generic programming.
+  typedef T value_type;
+
+  /**
+   * Creates a Result object from an Error.
+   *
+   * To preserve the invariant that `(result.error() == Error::Ok) ==
+   * result.ok()`, an `error` parameter value of `Error:Ok` will be converted to
+   * a non-Ok value.
+   */
+  /* implicit */ Result(Error error)
+      : error_(error == Error::Ok ? Error::Internal : error), hasValue_(false) {
+    if ET_UNLIKELY (error == Error::Ok) {
+      ET_LOG(Debug, "Attempted to create Result from Error::Ok, this has been "
+                    "converted to Error::Internal.");
+    }
+  }
+
+  /// Value copy constructor.
+  /* implicit */ Result(const T &val) : value_(val), hasValue_(true) {}
+
+  /// Value move constructor.
+  /* implicit */ Result(T &&val) : value_(std::move(val)), hasValue_(true) {}
+
+  /// Result move constructor.
+  /* implicit */ Result(Result &&rhs) noexcept : hasValue_(rhs.hasValue_) {
+    if (hasValue_) {
+      // Use the value type's move constructor.
+      new (&value_) T(std::move(rhs.value_));
+    } else {
+      error_ = rhs.error_;
+    }
+  }
+
+  ~Result() {
+    if (hasValue_) {
+      // Manual value destruction.
+      // Result "owns" the memory, so `delete` would segfault.
+      value_.~T();
+    }
+  }
+
+  /**
+   * Returns true if this Result has a value.
+   *
+   * If true, it is guaranteed that `error()` will return `Error::Ok`.
+   * If false, it is guaranteed that `error()` will not return `Error::Ok`.
+   */
+  ET_NODISCARD bool ok() const { return hasValue_; }
+
+  /**
+   * Returns the error code of this Result.
+   *
+   * If this returns `Error::Ok`, it is guaranteed that `ok()` will return true.
+   * If this does not return `Error:Ok`, it is guaranteed that `ok()` will
+   * return false.
+   */
+  ET_NODISCARD Error error() const {
+    if (hasValue_) {
+      return Error::Ok;
+    } else {
+      return error_;
+    }
+  }
+
+  /**
+   * Returns a reference to the Result's value; longhand for operator*().
+   *
+   * Only legal to call if `ok()` returns true.
+   */
+  T &get() {
+    CheckOk();
+    return value_;
+  }
+
+  /**
+   * Returns a reference to the Result's value; longhand for operator*().
+   *
+   * Only legal to call if `ok()` returns true.
+   */
+  const T &get() const {
+    CheckOk();
+    return value_;
+  }
+
+  /*
+   * Returns a reference to the Result's value; shorthand for get().
+   *
+   * Only legal to call if `ok()` returns true.
+   */
+  const T &operator*() const &;
+  T &operator*() &;
+
+  /*
+   * Returns a pointer to the Result's value.
+   *
+   * Only legal to call if `ok()` returns true.
+   */
+  const T *operator->() const;
+  T *operator->();
+
+private:
+  /**
+   * Delete default constructor since all Results should contain a value or
+   * error.
+   */
+  Result() = delete;
+  /// Delete copy constructor since T may not be copyable.
+  Result(const Result &) = delete;
+  /// Delete copy assignment since T may not be copyable.
+  Result &operator=(const Result &) = delete;
+  /// Delete move assignment since it's not a supported pattern to reuse Result.
+  Result &operator=(Result &&rhs) = delete;
+
+  // Panics if ok() would return false;
+  void CheckOk() const { ET_CHECK(hasValue_); }
+
+  union {
+    T value_;     // Used if hasValue_ is true.
+    Error error_; // Used if hasValue_ is false.
+  };
+
+  /// True if the Result contains a value.
+  const bool hasValue_;
+};
+
+template <typename T> const T &Result<T>::operator*() const & {
+  CheckOk();
+  return value_;
+}
+
+template <typename T> T &Result<T>::operator*() & {
+  CheckOk();
+  return value_;
+}
+
+template <typename T> const T *Result<T>::operator->() const {
+  CheckOk();
+  return &value_;
+}
+
+template <typename T> T *Result<T>::operator->() {
+  CheckOk();
+  return &value_;
+}
+
+} // namespace runtime
+} // namespace executorch
+
+namespace torch {
+namespace executor {
+// TODO(T197294990): Remove these deprecated aliases once all users have moved
+// to the new `::executorch` namespaces.
+using ::executorch::runtime::Result;
+} // namespace executor
+} // namespace torch
+
+/**
+ * Unwrap a Result to obtain its value. If the Result contains an error,
+ * propogate the error via trivial function return.
+ *
+ * Note: A function using ET_UNWRAP should itself return a Result or Error.
+ *
+ * @param[in] result__ Expression yielding the result to unwrap.
+ * @param[in] ... Optional format string for the log error message and its
+ * arguments.
+ */
+#define ET_UNWRAP(result__, ...) ET_INTERNAL_UNWRAP(result__, ##__VA_ARGS__)
+
+// Internal only: Use ET_UNWRAP() instead.
+#define ET_INTERNAL_UNWRAP(...)                                                \
+  ET_INTERNAL_UNWRAP_SELECT(__VA_ARGS__, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1)        \
+  (__VA_ARGS__)
+
+// Internal only: Use ET_UNWRAP() instead.
+#define ET_INTERNAL_UNWRAP_SELECT(_1, _2, _3, _4, _5, _6, _7, _8, _9, _10, N,  \
+                                  ...)                                         \
+  ET_INTERNAL_UNWRAP_##N
+
+// Internal only: Use ET_UNWRAP() instead.
+#define ET_INTERNAL_UNWRAP_1(result__)                                         \
+  ({                                                                           \
+    auto et_result__ = (result__);                                             \
+    if (!et_result__.ok()) {                                                   \
+      return et_result__.error();                                              \
+    }                                                                          \
+    std::move(*et_result__);                                                   \
+  })
+
+// Internal only: Use ET_UNWRAP() instead.
+#define ET_INTERNAL_UNWRAP_2(result__, message__, ...)                         \
+  ({                                                                           \
+    auto et_result__ = (result__);                                             \
+    if (!et_result__.ok()) {                                                   \
+      ET_LOG(Error, message__, ##__VA_ARGS__);                                 \
+      return et_result__.error();                                              \
+    }                                                                          \
+    std::move(*et_result__);                                                   \
+  })
+
+// Internal only: Use ET_UNWRAP() instead.
+#define ET_INTERNAL_UNWRAP_3 ET_INTERNAL_UNWRAP_2
+#define ET_INTERNAL_UNWRAP_4 ET_INTERNAL_UNWRAP_2
+#define ET_INTERNAL_UNWRAP_5 ET_INTERNAL_UNWRAP_2
+#define ET_INTERNAL_UNWRAP_6 ET_INTERNAL_UNWRAP_2
+#define ET_INTERNAL_UNWRAP_7 ET_INTERNAL_UNWRAP_2
+#define ET_INTERNAL_UNWRAP_8 ET_INTERNAL_UNWRAP_2
+#define ET_INTERNAL_UNWRAP_9 ET_INTERNAL_UNWRAP_2
+#define ET_INTERNAL_UNWRAP_10 ET_INTERNAL_UNWRAP_2

package/third-party/include/executorch/runtime/core/span.h

@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <cstdint>
+
+#include <executorch/runtime/platform/assert.h>
+
+namespace executorch {
+namespace runtime {
+
+/**
+ * Represent a reference to an array (0 or more elements
+ * consecutively in memory), i.e. a start pointer and a length.  It allows
+ * various APIs to take consecutive elements easily and conveniently.
+ *
+ * This class does not own the underlying data, it is expected to be used in
+ * situations where the data resides in some other buffer, whose lifetime
+ * extends past that of the Span.
+ *
+ * Span and ArrayRef are extrememly similar with the difference being ArrayRef
+ * views a list of constant elements and Span views a list of mutable elements.
+ * Clients should decide between the two based on if the list elements for their
+ * use case should be mutable.
+ *
+ * This is intended to be trivially copyable, so it should be passed by
+ * value.
+ */
+template <typename T> class Span final {
+public:
+  using value_type = T;
+  using iterator = T *;
+  using size_type = size_t;
+
+public:
+  /// Construct an empty Span.
+  /* implicit */ constexpr Span() noexcept : data_(nullptr), length_(0) {}
+
+  /// Construct a Span from a pointer and length.
+  Span(T *data, size_t length) : data_(data), length_(length) {
+    ET_DCHECK(data_ != nullptr || length_ == 0);
+  }
+
+  /// Construct a Span from a range.
+  Span(T *begin, T *end) : data_(begin), length_(end - begin) {}
+
+  /// Construct a Span from a C array.
+  template <size_t N>
+  /* implicit */ constexpr Span(T (&Arr)[N]) : data_(Arr), length_(N) {}
+
+  /// Construct a Span from a single element reference.
+  /* implicit */ constexpr Span(T &single_element)
+      : data_(&single_element), length_(1) {}
+
+  /// @returns a pointer to the start of the underlying element buffer.
+  iterator begin() const noexcept { return data_; }
+
+  /// @returns a pointer to the end of the underlying element buffer.
+  iterator end() const noexcept { return data_ + length_; }
+
+  /// @retval a boolean indicating if the Span is empty.
+  constexpr bool empty() const noexcept { return length_ == 0; }
+
+  /// @returns a pointer to the start of the underlying element buffer.
+  constexpr T *data() const noexcept { return data_; }
+
+  /// @returns the number of elements in the Span.
+  constexpr size_t size() const noexcept { return length_; }
+
+  /// Unchecked index into the array according to the argument index.
+  /// @returns a reference to the element at the specified index.
+  T &operator[](size_t index) const { return data_[index]; }
+
+private:
+  /// The start of the array, in an external buffer.
+  T *data_;
+
+  /// The number of elements.
+  size_type length_;
+};
+
+} // namespace runtime
+} // namespace executorch
+
+namespace torch {
+namespace executor {
+// TODO(T197294990): Remove these deprecated aliases once all users have moved
+// to the new `::executorch` namespaces.
+using ::executorch::runtime::Span;
+} // namespace executor
+} // namespace torch