Add ET_EXPERIMENTAL

Differential Revision: D61368408

Pull Request resolved: #4802

docs/source/api-life-cycle.md

@@ -91,19 +91,21 @@ communicate state to developers.
    <td>
 
 Use the
-<a href="https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.deprecated">typing_extensions.deprecated</a>
-decorator
+<a href="https://github.com/pytorch/executorch/blob/main/exir/_warnings.py">executorch.exir._warnings.deprecated</a>
+decorator.
 
 <p>
-Use ExecuTorch's native experimental decorator (TODO not yet implemented)
+Use the
+<a href="https://github.com/pytorch/executorch/blob/main/exir/_warnings.py">executorch.exir._warnings.experimental</a>
+decorator.
 
    </td>
    <td>
 
 Use <code>.. warning::</code> in the docstrings of deprecated and experimental
 APIs. See
 <a href="https://github.com/pytorch/pytorch/blob/cd8bbdc71a0258292381a7d54c8b353988d02ff4/torch/nn/utils/stateless.py#L170">example
-usage</a>
+usage</a>.
 
 </ul>
    </td>
@@ -113,35 +115,35 @@ usage</a>
    </td>
    <td>
 
-Use <code>ET_DEPRECATED</code> macros. See <a href="https://github.com/pytorch/executorch/blob/8e0f856ee269b319ac4195509cf31e3f548aa0e8/runtime/executor/program.h#L81">example usage</a>
+Use the <code>ET_DEPRECATED</code> annotation macro. See <a href="https://github.com/pytorch/executorch/blob/8e0f856ee269b319ac4195509cf31e3f548aa0e8/runtime/executor/program.h#L81">example usage</a>.
 
 <p>
 <p>
-Use <code>ET_EXPERIMENTAL</code> macros (TODO not yet implemented)
+Use the <code>ET_EXPERIMENTAL</code> annotation macro.
 </ul>
    </td>
    <td>
 
 Start Doxygen comments with <code>DEPRECATED:</code> See
 <a href="https://github.com/pytorch/executorch/blob/9d859653ae916d0a72f6b2b5c5925bed38832140/runtime/executor/program.h#L139">example
-usage</a>
+usage</a>.
 
 <p>
 <p>
-Start Doxygen comments with <code>EXPERIMENTAL:</code>
+Start Doxygen comments with <code>EXPERIMENTAL:</code>.
    </td>
   </tr>
   <tr>
    <td>Java
    </td>
    <td>
 
-Use <a href="https://docs.oracle.com/javase/9/docs/api/java/lang/Deprecated.html">java.lang.Deprecated</a>
+Use <a href="https://docs.oracle.com/javase/9/docs/api/java/lang/Deprecated.html">java.lang.Deprecated</a>.
 
 <p>
 <p>
 
-Use <a href="https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:docs/api_guidelines/annotations.md">androidx.annotation.RequiresOptIn</a>
+Use <a href="https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:docs/api_guidelines/annotations.md">androidx.annotation.RequiresOptIn</a>.
 
    </td>
    <td>
@@ -164,7 +166,7 @@ Use <a href="https://cs.android.com/androidx/platform/frameworks/support/+/andro
 <code>__attribute__((deprecated("Use newMethod instead")));</code>
 <p>
 <p>
-<code>__attribute__((experimental("Use newMethod instead")));</code> (TODO not yet implemented)
+<code>__attribute__((deprecated("This API is experimental and may change without notice.")));</code>
    </td>
    <td>
 <p>

runtime/executor/method.cpp

@@ -1176,7 +1176,7 @@ Error Method::execute_instruction() {
   return err;
 }
 
-Error Method::experimental_reset_execution() {
+Error Method::reset_execution() {
   ET_CHECK_OR_RETURN_ERROR(
       step_state_.chain_idx == n_chains_,
       InvalidState,
@@ -1185,6 +1185,10 @@ Error Method::experimental_reset_execution() {
   return Error::Ok;
 }
 
+Error Method::experimental_reset_execution() {
+  return reset_execution(); // @lint-ignore CLANGTIDY facebook-hte-Deprecated
+}
+
 // Log all the outputs of this method to the event tracer.
 void Method::log_outputs() {
 #ifdef ET_EVENT_TRACER_ENABLED
@@ -1199,7 +1203,7 @@ void Method::log_outputs() {
 #endif
 }
 
-Error Method::experimental_step() {
+Error Method::step() {
   EXECUTORCH_PROFILE_INSTRUCTION_SCOPE(
       static_cast<int32_t>(step_state_.chain_idx),
       static_cast<uint32_t>(step_state_.instr_idx));
@@ -1245,6 +1249,10 @@ Error Method::experimental_step() {
   return Error::Ok;
 }
 
+Error Method::experimental_step() {
+  return step();
+}
+
 Error Method::execute() {
   internal::event_tracer_create_event_block(event_tracer_, "Execute");
   internal::EventTracerProfileScope event_tracer_profile_scope =
@@ -1289,7 +1297,7 @@ Error Method::execute() {
 
   // TODO(jakeszwe, dbort): Decide on calling execute back to back without
   // going through the reset api first.
-  return experimental_reset_execution();
+  return reset_execution(); // @lint-ignore CLANGTIDY facebook-hte-Deprecated
 }
 
 MethodMeta Method::method_meta() const {

runtime/executor/method.h

@@ -181,35 +181,37 @@ class Method final {
    * Execute the method.
    *
    * NOTE: Will fail if the method has been partially executed using the
-   * `experimental_step()` api.
+   * `step()` api.
    *
    * @returns Error::Ok on success, non-Ok on failure.
    */
   ET_NODISCARD Error execute();
 
   /**
-   * Advances/executes a single instruction in the method.
-   *
-   * NOTE: Prototype API; subject to change.
+   * EXPERIMENTAL: Advances/executes a single instruction in the method.
    *
    * @retval Error::Ok step succeeded
    * @retval non-Ok step failed
    * @retval Error::EndOfMethod method finished executing successfully
    */
-  ET_NODISCARD Error experimental_step();
+  ET_EXPERIMENTAL ET_NODISCARD Error step();
+
+  /// DEPRECATED: Use `step()` instead.
+  ET_DEPRECATED ET_NODISCARD Error experimental_step();
 
   /**
-   * Resets execution state to the start of the Method. For use with the
-   * `experimental_step()` API.
-   *
-   * NOTE: Prototype API; subject to change.
+   * EXPERIMENTAL: Resets execution state to the start of the Method. For use
+   * with the `step()` API.
    *
    * @retval Error:Ok on success
    * @retval Error::InvalidState if called before step-based execution reached
    *     the end of the Method. This means it is not possible to recover a
    *     Method that failed mid-execution.
    */
-  ET_NODISCARD Error experimental_reset_execution();
+  ET_EXPERIMENTAL ET_NODISCARD Error reset_execution();
+
+  /// DEPRECATED: Use `reset_execution()` instead.
+  ET_DEPRECATED ET_NODISCARD Error experimental_reset_execution();
 
   /**
    * Returns the MethodMeta that corresponds to the calling Method.

runtime/platform/compiler.h

@@ -62,13 +62,18 @@
 #if (__cplusplus) >= 201703L
 
 #define ET_DEPRECATED [[deprecated]]
+#define ET_EXPERIMENTAL \
+  [[deprecated("This API is experimental and may change without notice.")]]
 #define ET_FALLTHROUGH [[fallthrough]]
 #define ET_NODISCARD [[nodiscard]]
 #define ET_UNUSED [[maybe_unused]]
 
 #else
 
 #define ET_DEPRECATED __attribute__((deprecated))
+#define ET_EXPERIMENTAL \
+  __attribute__((       \
+      deprecated("This API is experimental and may change without notice.")))
 #define ET_FALLTHROUGH __attribute__((fallthrough))
 #define ET_NODISCARD __attribute__((warn_unused_result))
 #define ET_UNUSED __attribute__((unused))