Skip to content

Add ET_EXPERIMENTAL #4802

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 21, 2024
Merged

Add ET_EXPERIMENTAL #4802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions docs/source/api-life-cycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down
14 changes: 11 additions & 3 deletions runtime/executor/method.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
Expand All @@ -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));
Expand Down Expand Up @@ -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 =
Expand Down Expand Up @@ -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 {
Expand Down
22 changes: 12 additions & 10 deletions runtime/executor/method.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 5 additions & 0 deletions runtime/platform/compiler.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
Loading