Expand description
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§
Structs§
- Deferred
Future - A future that runs a function in a new thread without blocking.
- Joined
Future - A future cosisting of multiple other futures. Ready once all of the inner futures are ready.
- Owned
Runtime - Owned wrapper for anything that implements InternalRuntime, used to add a Runtime impl.
- Runtime
Wrapper - Wrapper for anything that implements InternalRuntime, used to add a Runtime impl.
- Spawned
Future - Future equivalent of a join handle
- Stop
- A never-completing future, used in stopping the runtime. Returns stable equivalent of
! - Yield
Future - 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§
- Internal
Runtime - Trait to be implemented by async runtimes
- Runtime
- Auto-trait with the methods that will actually be called by the users of the runtime.
- Startable
Runtime - 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