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

package/third-party/include/executorch/runtime/backend/options.h

@@ -0,0 +1,206 @@
+/*
+ * 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 <array>
+#include <cstddef>
+#include <cstring>
+#include <executorch/runtime/core/error.h>
+#include <executorch/runtime/core/span.h>
+#include <variant>
+
+namespace executorch {
+namespace runtime {
+
+static constexpr size_t kMaxOptionKeyLength = 64;
+static constexpr size_t kMaxOptionValueLength = 256;
+
+// All string keys and values must have static storage duration (string
+// literals, static const char arrays, or global constants). The BackendOptions
+// class does NOT take ownership of strings.
+using OptionValue =
+    std::variant<bool, int, std::array<char, kMaxOptionValueLength>>;
+
+struct BackendOption {
+  // key is the name of the backend option, like num_threads, enable_profiling,
+  // etc
+  char key[kMaxOptionKeyLength]{};
+  // value is the value of the backend option, like 4, true, etc
+  OptionValue value;
+};
+
+/**
+ * A template class for storing and managing backend-specific configuration
+ * options.
+ *
+ * This class provides a type-safe way to store key-value pairs for backend
+ * configuration, with compile-time capacity limits and runtime type checking.
+ * It supports bool, int, and const char* value types.
+ *
+ * @tparam MaxCapacity The maximum number of options that can be stored
+ */
+template <size_t MaxCapacity> class BackendOptions {
+public:
+  /**
+   * Copy constructor
+   */
+  BackendOptions(const BackendOptions &other) : size_(other.size_) {
+    for (size_t i = 0; i < size_; ++i) {
+      options_[i] = other.options_[i];
+    }
+  }
+
+  /**
+   * Copy assignment operator
+   */
+  BackendOptions &operator=(const BackendOptions &other) {
+    if (this != &other) {
+      size_ = other.size_;
+      for (size_t i = 0; i < size_; ++i) {
+        options_[i] = other.options_[i];
+      }
+    }
+    return *this;
+  }
+
+  /**
+   * Default constructor - initializes with zero options.
+   */
+  BackendOptions() : size_(0) {}
+
+  /**
+   * Returns a mutable view of all stored options as a Span.
+   *
+   * @return A mutable Span containing all BackendOption entries
+   */
+  executorch::runtime::Span<BackendOption> view() {
+    return executorch::runtime::Span<BackendOption>(options_, size_);
+  }
+
+  /**
+   * Sets a boolean option value for the given key.
+   * If the key already exists, updates its value. Otherwise, adds a new option.
+   *
+   * @tparam N The length of the key string (automatically deduced)
+   * @param key The option key (must be a string literal or array)
+   * @param value The boolean value to set
+   * @return Error::Ok on success, Error::InvalidArgument if storage is full
+   */
+  template <size_t N>
+  Error set_option(const char (&key)[N], bool value) noexcept {
+    static_assert(N <= kMaxOptionKeyLength, "Option key is too long");
+    return set_option_impl(key, value);
+  }
+
+  /**
+   * Sets an integer option value for the given key.
+   * If the key already exists, updates its value. Otherwise, adds a new option.
+   *
+   * @tparam N The length of the key string (automatically deduced)
+   * @param key The option key (must be a string literal or array)
+   * @param value The integer value to set
+   * @return Error::Ok on success, Error::InvalidArgument if storage is full
+   */
+  template <size_t N>
+  Error set_option(const char (&key)[N], int value) noexcept {
+    static_assert(N <= kMaxOptionKeyLength, "Option key is too long");
+    return set_option_impl(key, value);
+  }
+
+  /**
+   * Sets a string option value for the given key.
+   * If the key already exists, updates its value. Otherwise, adds a new option.
+   *
+   * Note: The string value must have static storage duration. This class does
+   * NOT take ownership of the string - it only stores the pointer.
+   *
+   * @tparam N The length of the key string (automatically deduced)
+   * @param key The option key (must be a string literal or array)
+   * @param value The string value to set (must have static storage duration)
+   * @return Error::Ok on success, Error::InvalidArgument if storage is full
+   */
+  template <size_t N>
+  Error set_option(const char (&key)[N], const char *value) noexcept {
+    static_assert(N <= kMaxOptionKeyLength, "Option key is too long");
+    // Create a fixed-size array and copy the string
+    std::array<char, kMaxOptionValueLength> arr{};
+    strncpy(arr.data(), value, kMaxOptionValueLength - 1);
+    arr[kMaxOptionValueLength - 1] = '\0'; // Ensure null termination
+    return set_option_impl(key, arr);
+  }
+  /**
+   * Retrieves an option value by key and type.
+   *
+   * @tparam T The expected type of the option value (bool, int, or const char*)
+   * @tparam KeyLen The length of the key string (automatically deduced)
+   * @param key The option key to look up
+   * @param out Reference to store the retrieved value
+   * @return Error::Ok if found and type matches, Error::NotFound if key doesn't
+   * exist, Error::InvalidArgument if type doesn't match
+   */
+  template <typename T, size_t KeyLen>
+  Error get_option(const char (&key)[KeyLen], T &out) const {
+    static_assert(KeyLen <= kMaxOptionKeyLength, "Option key is too long");
+    for (size_t i = 0; i < size_; ++i) {
+      if (std::strcmp(options_[i].key, key) == 0) {
+        // Special handling for string (convert array to const char*)
+        if constexpr (std::is_same_v<T, const char *>) {
+          if (auto *arr = std::get_if<std::array<char, kMaxOptionValueLength>>(
+                  &options_[i].value)) {
+            out = arr->data(); // Return pointer to stored array
+            return Error::Ok;
+          }
+        }
+        // Default handling for bool/int
+        else if (auto *val = std::get_if<T>(&options_[i].value)) {
+          out = *val;
+          return Error::Ok;
+        }
+        return Error::InvalidArgument;
+      }
+    }
+    return Error::NotFound;
+  }
+
+private:
+  BackendOption options_[MaxCapacity]{}; // Storage for backend options
+  size_t size_;                          // Current number of options
+
+  /**
+   * Internal implementation for setting option values.
+   * Handles both updating existing options and adding new ones.
+   *
+   * @tparam T The type of the value (bool, int, or const char*)
+   * @param key The option key
+   * @param value The value to set
+   * @return Error::Ok on success, Error::InvalidArgument if storage is full
+   */
+  template <typename T> Error set_option_impl(const char *key, T value) {
+    // Update existing if found
+    for (size_t i = 0; i < size_; ++i) {
+      if (strcmp(options_[i].key, key) == 0) {
+        options_[i].value = value;
+        return Error::Ok;
+      }
+    }
+    if (size_ < MaxCapacity) {
+      BackendOption new_option;
+      const size_t key_len = std::strlen(key);
+      const size_t copy_len = std::min(key_len, kMaxOptionKeyLength - 1);
+      std::memcpy(new_option.key, key, copy_len);
+      new_option.key[copy_len] = '\0';
+      new_option.value = value;       // Restored value assignment
+      options_[size_++] = new_option; // Store option and increment size
+      return Error::Ok;
+    }
+    return Error::InvalidArgument;
+  }
+};
+
+} // namespace runtime
+} // namespace executorch

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

@@ -0,0 +1,235 @@
+/*
+ * 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.
+ */
+
+//===--- ArrayRef.h - Array Reference Wrapper -------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// removed llvm-specific functionality
+// removed some implicit const -> non-const conversions that rely on
+// complicated std::enable_if meta-programming
+// removed a bunch of slice variants for simplicity...
+// remove constructors and operators for std::vector
+// removed some prevention of accidental assignments from temporary that
+// required std::enable_if meta-programming
+// removed reverse iterator
+
+#pragma once
+
+#include <array>
+#include <cstdint>
+
+#include <c10/util/irange.h>
+#include <executorch/runtime/platform/assert.h>
+
+namespace executorch {
+namespace runtime {
+
+/**
+ * Represents a constant 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 ArrayRef. For this reason, it is not in general
+ * safe to store an ArrayRef.
+ *
+ * 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 ArrayRef final {
+public:
+  using iterator = const T *;
+  using const_iterator = const T *;
+  using size_type = size_t;
+  using value_type = T;
+
+private:
+  /// The start of the array, in an external buffer.
+  const T *Data;
+
+  /// The number of elements.
+  size_type Length;
+
+public:
+  /// @name Constructors
+  /// @{
+
+  /// Construct an empty ArrayRef.
+  /* implicit */ constexpr ArrayRef() : Data(nullptr), Length(0) {}
+
+  /// Construct a ArrayRef from a single element. Implicitly convert element
+  /// type. It is aligned with PyTorch's c10::ArrayRef.
+  /* implicit */ constexpr ArrayRef(const T &OneElt)
+      : Data(&OneElt), Length(1) {}
+
+  /// Construct a ArrayRef from a pointer and length.
+  ArrayRef(const T *data, size_t length) : Data(data), Length(length) {
+    ET_DCHECK(Data != nullptr || Length == 0);
+  }
+
+  /// Construct a ArrayRef from a range.
+  ArrayRef(const T *begin, const T *end) : Data(begin), Length(end - begin) {}
+
+  /// Construct an ArrayRef from a std::array
+  template <size_t N>
+  /* implicit */ constexpr ArrayRef(const std::array<T, N> &Arr)
+      : Data(Arr.data()), Length(N) {}
+
+  /// Construct a ArrayRef from a C array.
+  template <size_t N>
+  /* implicit */ constexpr ArrayRef(const T (&Arr)[N]) : Data(Arr), Length(N) {}
+
+  /// @}
+  /// @name Simple Operations
+  /// @{
+
+  constexpr iterator begin() const { return Data; }
+  constexpr iterator end() const { return Data + Length; }
+
+  // These are actually the same as iterator, since ArrayRef only
+  // gives you const iterators.
+  constexpr const_iterator cbegin() const { return Data; }
+  constexpr const_iterator cend() const { return Data + Length; }
+
+  /// empty - Check if the array is empty.
+  constexpr bool empty() const { return Length == 0; }
+
+  constexpr const T *data() const { return Data; }
+
+  /// size - Get the array size.
+  constexpr size_t size() const { return Length; }
+
+  /// front - Get the first element.
+  const T &front() const {
+    // ArrayRef: attempted to access front() of empty list
+    ET_CHECK(!empty());
+    return Data[0];
+  }
+
+  /// back - Get the last element.
+  const T &back() const {
+    // ArrayRef: attempted to access back() of empty list
+    ET_CHECK(!empty());
+    return Data[Length - 1];
+  }
+
+  /// equals - Check for element-wise equality.
+  bool equals(ArrayRef RHS) const {
+    if (Length != RHS.Length) {
+      return false;
+    }
+    for (const auto i : c10::irange(this->Length)) {
+      if (Data[i] != RHS.Data[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /// slice(n, m) - Take M elements of the array starting at element N
+  ArrayRef<T> slice(size_t N, size_t M) const {
+    // cant slice longer then the array
+    ET_CHECK(N + M <= size());
+    return ArrayRef<T>(data() + N, M);
+  }
+
+  /// slice(n) - Chop off the first N elements of the array.
+  constexpr ArrayRef<T> slice(size_t N) const { return slice(N, size() - N); }
+
+  /// @}
+  /// @name Operator Overloads
+  /// @{
+  constexpr const T &operator[](size_t Index) const { return Data[Index]; }
+
+  /// Vector compatibility
+  const T &at(size_t Index) const {
+    // invalid index
+    ET_CHECK(Index < Length);
+    return Data[Index];
+  }
+
+  /// @}
+};
+
+/// @name ArrayRef Convenience constructors
+/// @{
+
+/// Construct an ArrayRef from a single element.
+template <typename T> ArrayRef<T> makeArrayRef(const T &OneElt) {
+  return OneElt;
+}
+
+/// Construct an ArrayRef from a pointer and length.
+template <typename T> ArrayRef<T> makeArrayRef(const T *data, size_t length) {
+  return ArrayRef<T>(data, length);
+}
+
+/// Construct an ArrayRef from a range.
+template <typename T> ArrayRef<T> makeArrayRef(const T *begin, const T *end) {
+  return ArrayRef<T>(begin, end);
+}
+
+/// Construct an ArrayRef from a std::array.
+template <typename T, std::size_t N>
+ArrayRef<T> makeArrayRef(const std::array<T, N> &Arr) {
+  return Arr;
+}
+
+/// Construct an ArrayRef from an ArrayRef (no-op) (const)
+template <typename T> ArrayRef<T> makeArrayRef(const ArrayRef<T> &Vec) {
+  return Vec;
+}
+
+/// Construct an ArrayRef from an ArrayRef (no-op)
+template <typename T> ArrayRef<T> &makeArrayRef(ArrayRef<T> &Vec) {
+  return Vec;
+}
+
+/// Construct an ArrayRef from a C array.
+template <typename T, size_t N> ArrayRef<T> makeArrayRef(const T (&Arr)[N]) {
+  return ArrayRef<T>(Arr);
+}
+
+// WARNING: Template instantiation will NOT be willing to do an implicit
+// conversions to get you to an ArrayRef, which is why we need so
+// many overloads.
+
+template <typename T> bool operator==(ArrayRef<T> a1, ArrayRef<T> a2) {
+  return a1.equals(a2);
+}
+
+template <typename T> bool operator!=(ArrayRef<T> a1, ArrayRef<T> a2) {
+  return !a1.equals(a2);
+}
+
+using IntArrayRef = ArrayRef<int64_t>;
+
+} // 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::ArrayRef;
+using ::executorch::runtime::IntArrayRef;
+using ::executorch::runtime::makeArrayRef;
+} // namespace executor
+} // namespace torch

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

@@ -0,0 +1,136 @@
+/*
+ * 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 <cstddef>
+
+#include <executorch/runtime/core/freeable_buffer.h>
+#include <executorch/runtime/core/result.h>
+#include <executorch/runtime/platform/compiler.h>
+
+namespace executorch {
+namespace runtime {
+
+/**
+ * Loads from a data source.
+ *
+ * See //executorch/extension/data_loader for common implementations.
+ */
+class DataLoader {
+public:
+  /**
+   * Describes the content of the segment.
+   */
+  struct SegmentInfo {
+    /**
+     * Represents the purpose of the segment.
+     */
+    enum class Type {
+      /**
+       * Data for the actual program.
+       */
+      Program,
+      /**
+       * Holds constant tensor data.
+       */
+      Constant,
+      /**
+       * Data used for initializing a backend.
+       */
+      Backend,
+      /**
+       * Data used for initializing mutable tensors.
+       */
+      Mutable,
+      /**
+       * Data used for initializing external tensors.
+       */
+      External,
+    };
+
+    /// Type of the segment.
+    Type segment_type;
+
+    /// Index of the segment within the segment list. Undefined for program
+    /// segments.
+    size_t segment_index;
+
+    /// An optional, null-terminated string describing the segment. For
+    /// `Backend` segments, this is the backend ID. Null for other segment
+    /// types.
+    const char *descriptor;
+
+    SegmentInfo() = default;
+
+    explicit SegmentInfo(Type segment_type_, size_t segment_index_ = 0,
+                         const char *descriptor_ = nullptr)
+        : segment_type(segment_type_), segment_index(segment_index_),
+          descriptor(descriptor_) {}
+  };
+
+  virtual ~DataLoader() = default;
+
+  /**
+   * Loads data from the underlying data source.
+   *
+   * NOTE: This must be thread-safe. If this call modifies common state, the
+   * implementation must do its own locking.
+   *
+   * @param offset The byte offset in the data source to start loading from.
+   * @param size The number of bytes to load.
+   * @param segment_info Information about the segment being loaded.
+   *
+   * @returns a `FreeableBuffer` that owns the loaded data.
+   */
+  ET_NODISCARD virtual Result<FreeableBuffer>
+  load(size_t offset, size_t size, const SegmentInfo &segment_info) const = 0;
+
+  /**
+   * Loads data from the underlying data source into the provided buffer.
+   *
+   * NOTE: This must be thread-safe. If this call modifies common state, the
+   * implementation must do its own locking.
+   *
+   * @param offset The byte offset in the data source to start loading from.
+   * @param size The number of bytes to load.
+   * @param segment_info Information about the segment being loaded.
+   * @param buffer The buffer to load data into. Must point to at least `size`
+   * bytes of memory.
+   *
+   * @returns an Error indicating if the load was successful.
+   */
+  ET_NODISCARD virtual Error load_into(size_t offset, size_t size,
+                                       const SegmentInfo &segment_info,
+                                       void *buffer) const {
+    // Using a stub implementation here instead of pure virtual to expand the
+    // data_loader interface in a backwards compatible way.
+    (void)buffer;
+    (void)offset;
+    (void)size;
+    (void)segment_info;
+    ET_LOG(Error, "load_into() not implemented for this data loader.");
+    return Error::NotImplemented;
+  }
+
+  /**
+   * Returns the length of the underlying data source, typically the file size.
+   */
+  ET_NODISCARD virtual Result<size_t> size() const = 0;
+};
+
+} // 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::DataLoader;
+} // namespace executor
+} // namespace torch

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

@@ -0,0 +1,20 @@
+/*
+ * 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
+ * Contains preprocessor definitions used by ExecuTorch core.
+ */
+
+#pragma once
+
+// Enable ET_ENABLE_ENUM_STRINGS by default. This option gates inclusion of
+// enum string names and can be disabled by explicitly setting it to 0.
+#ifndef ET_ENABLE_ENUM_STRINGS
+#define ET_ENABLE_ENUM_STRINGS 1
+#endif