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