Crate async_core

This crate provides wrappers for async operations in order to help standardize rust async runtimes.

SAFETY: The current runtime must be cleaned up after each tick of a runtime, and must therefore live shorter than the runtime itself as the runtime can not be dropped while it is running. Without this, async-core causes undefined behavior.

SAFETY: In a no_std environment, creating multiple threads is inherently unsafe as there is no safe API wrapping threads. I assume you know what you are doing if you are using this with multiple threads in a no_std environment. Please do not share runtimes between threads this way.

How to use a runtime:

• Import the re-exported Runtime and get_current_runtime.
• (Skip this if you are a library developer and want your users to control the runtime) Create a runtime like you normally would
• Don’t use that runtime’s specifics if you can somehow avoid it. Use get_current_runtime and the functions provided in the returned RuntimeWrapper

How to implement a runtime:

• Re-export everything so your users can use async_core without needing to add it as a dependency.
• In the runtime, call set_current_runtime and clear_current_runtime:

set_current_runtime(self);
let result = execute_futures(); // Do your cool runtime things here
clear_current_runtime();
result

• If your crate has a no_std feature, link that with this crate’s no_std feature.
• Make absolutely sure you call set_current_runtime and clear_current_runtime.

Macros

join

join_boxed

Structs

DeferredFuture

A future that runs a function in a new thread without blocking.

JoinedFuture

A future cosisting of multiple other futures. Ready once all of the inner futures are ready.

OwnedRuntime

Owned wrapper for anything that implements InternalRuntime, used to add a Runtime impl.

RuntimeWrapper

Wrapper for anything that implements InternalRuntime, used to add a Runtime impl.

SpawnedFuture

Future equivalent of a join handle

Stop

A never-completing future, used in stopping the runtime. Returns stable equivalent of !

YieldFuture

A future which returns Pending once, and returns Ready the next time it is polled. Used to interrupt a running task to make space for others to run.

Enums

Never

Stable wrapper of ! type for the Stop struct.

Traits

InternalRuntime

Trait to be implemented by async runtimes

Runtime

Auto-trait with the methods that will actually be called by the users of the runtime.

StartableRuntime

Trait to construct a runtime

Functions

clear_current_runtime

This clears the currently running runtime. MUST ONLY BE CALLED BY A RUNTIME WHEN IT WILL (temporarily of permanently) STOP EXECUTING FUTURES. MUST FOLLOW A set_current_runtime CALL. IF THE RUNTIME STARTS TO BE USED AGAIN, set_current_runtime MUST BE CALLED AGAIN.

defer

Defers execution of a blocking function to another thread returning a DeferredFuture, which does nothing until it is awaited.

get_current_runtime

This gets the currently running runtime. PANICS IF IT IS CALLED FROM OUTSIDE THE RUNTIME.

join

Joins multiple futures into one, which will be ready once all of the inner ones are. This is effectively a small one-time-use runtime without the ability to add any tasks.

prep

set_current_runtime

This sets the currently running runtime. MUST ONLY BE CALLED BY A RUNTIME WHEN IT IS ABOUT TO START EXECUTING, AND MUST BE CLEARED AFTERWARDS.

yield_now

Interrupts the current task and yields for the ohers. This uses a YieldFuture

Type Definitions

BoxFuture