Function fuchsia_async::unblock

source ·
pub fn unblock<T: 'static + Send>(
    f: impl 'static + Send + FnOnce() -> T
) -> impl 'static + Send + Future<Output = T>
Expand description

Offload a blocking function call onto a different thread.

This function can be called from an asynchronous function without blocking it, returning a future that can be .awaited normally. The provided function should contain at least one blocking operation, such as:

  • A synchronous syscall that does not yet have an async counterpart.
  • A compute operation which risks blocking the executor for an unacceptable amount of time.

If neither of these conditions are satisfied, just call the function normally, as synchronous functions themselves are allowed within an async context, as long as they are not blocking.

If you have an async function that may block, refactor the function such that the blocking operations are offloaded onto the function passed to unblock.

NOTE:

  • The input function should not interact with the executor. Attempting to do so can cause runtime errors. This includes spawning, creating new executors, passing futures between the input function and the calling context, and in some cases constructing async-aware types (such as IO-, IPC- and timer objects).
  • Synchronous functions cannot be cancelled and may keep running after the returned future is dropped. As a result, resources held by the function should be assumed to be held until the returned future completes.
  • This function assumes panic=abort semantics, so if the input function panics, the process aborts. Behavior for panic=unwind is not defined.