Update the documentation for Caller::get_export. (#5556)

Update the documentation for `Caller::get_export` to clarify that it's
not expected to be removed in the future. Components do offer an
alternative to `Caller::get_export`, so add a brief note mentioning
that.

Also, as of #4431 `get_export` now works for all exports, not just
memories and functions.
This commit is contained in:
Dan Gohman
2023-01-10 17:46:23 -08:00
committed by GitHub
parent 9556cb190f
commit 4f0445b9e8

View File

@@ -1726,24 +1726,23 @@ impl<T> Caller<'_, T> {
/// Looks up an export from the caller's module by the `name` given. /// Looks up an export from the caller's module by the `name` given.
/// ///
/// Note that when accessing and calling exported functions, one should /// This is a low-level function that's typically used to implement passing
/// adhere to the guidelines of the interface types proposal. This method /// of pointers or indices between core Wasm instances, where the callee
/// is a temporary mechanism for accessing the caller's information until /// needs to consult the caller's exports to perform memory management and
/// interface types has been fully standardized and implemented. The /// resolve the references.
/// interface types proposal will obsolete this type and this will be ///
/// removed in the future at some point after interface types is /// For comparison, in components, the component model handles translating
/// implemented. If you're relying on this method type it's recommended to /// arguments from one component instance to another and managing memory, so
/// become familiar with interface types to ensure that your use case is /// that callees don't need to be aware of their callers, which promotes
/// covered by the proposal. /// virtualizability of APIs.
/// ///
/// # Return /// # Return
/// ///
/// If a memory or function export with the `name` provided was found, then it is /// If an export with the `name` provided was found, then it is returned as an
/// returned as a `Memory`. There are a number of situations, however, where /// `Extern`. There are a number of situations, however, where the export may not
/// the memory or function may not be available: /// be available:
/// ///
/// * The caller instance may not have an export named `name` /// * The caller instance may not have an export named `name`
/// * The export named `name` may not be an exported memory
/// * There may not be a caller available, for example if `Func` was called /// * There may not be a caller available, for example if `Func` was called
/// directly from host code. /// directly from host code.
/// ///