Crate main_loop_async 

main-loop-async

This crate is an extraction of the generic parts of the functionality from reqwest-cross and aims to make it ergonomic to spawn async (or blocking sync tasks on native) and do not want to block in the calling task/thread, for example in main loop in a UI task/thread or game loop. This is achieved by using callbacks (Note: Unable to spawn tasks on WASM that directly return a value). This crate provides a few options to choose from and the one that fits best for you depends on what you need. A good way to get an idea what level of abstraction would work for you is by looking at the [examples][#examples]. I would say if you’re writing a larger application then DataState can abstract away a lot of the boiler plate. If automated retires are desired see DataStateRetry which exposes similar methods but with retry built in.

NOTE: At least 1 feature flag for native MUST be set to choose which runtime to use. Currently only Tokio is supported but if you want to use another runtime please open an issue on github and we’d be happy to add it. To communicate between the callback and the caller you can use various approaches such as:

• The helper type in this crate DataState see examples folder
• channels (used in examples)
• Arc<Mutex<_>>
• promises and so on.

Feature Flags

• default — Enables the tokio runtime and reqwest’s default features. If default-features gets disabled do ensure you at least enable tls, unless you explicitly do not want tls support.
• native-tokio (enabled by default) — Sets [tokio][tokio-url] as the runtime to use for native
• yield_now — Add a function that can be called to yield to the executor. This is only needed if you only have one thread and need to release it to prevent a deadlock because you are waiting on another future (as can be the case in WASM). If you are using a framework such as egui this may not be necessary as they already allow for other futures to make progress. But one test will quickly let you know either way. If the program freezes after you spawn a task then this can help.
• egui — Add helper functions to [‘DataState’] to do egui boiler plate

Exactly 1 of the “native-*” flags MUST be enabled to select which runtime to use for native. If one of the other options needs to be used instead of tokio then defaults must be disabled.

Sync vs Async

This crate supports async on both native and WASM. It also provides support for using threads sync tasks if using native. The sync version was added to support applications that are native only but still need to call out from the main loop with possibly sync tasks.

How to run tokio on “secondary” thread

If you want to use the main thread for your UI and need to run [tokio][tokio-url] on a “secondary” thread see the egui example. I also found this example helpful. I found it in this discussion, which had other suggested examples as well.

Modules

oneshot

A channel for sending a single message between asynchronous tasks.

Structs

Awaiting

Used to represent data that is pending being available

DataStateRetry

Automatically retries with a delay on failure until attempts are exhausted

Enums

CanMakeProgress

Provides a way to ensure the calling code knows if it is calling a function that cannot do anything useful anymore

DataState

Used to store a type that is not always available and we need to keep polling it to get it ready

DataStateError

Represents the types of errors that can occur while using DataState

Traits

ErrorBounds

Provides a common way to specify the bounds errors are expected to meet

Spawnable

An async function that is able to be spawned (Not directly able to be spawned on WASM because of the return type)

SpawnableNoReturn

An async function that is able to be spawned, lowest common denominator as we cannot have a return type on WASM

SpawnableWithReturn

An async func that accepts a generic argument and returns a generic value

Functions

spawn

Spawns a future on the underlying runtime in a cross platform way (NB: the Send bound is removed in WASM)

spawn_thread_with_return

Spawns a thead to run a sync job returns a futures::channel::oneshot::Receiver which can be used to get the return value from f.

spawn_with_return

Spawns a async job to run f (the future passed) and returns a futures::channel::oneshot::Receiver which can be used to get the return value from f.

yield_now

Attempts to provide a yield for executor currently in use.