Crate cros_async

An Executor and future combinators based on operations that block on file descriptors.

This crate is meant to be used with the futures-rs crate that provides further combinators and utility functions to combine and manage futures. All futures will run until they block on a file descriptor becoming readable or writable. Facilities are provided to register future wakers based on such events.

Running top-level futures.

Use helper functions based the desired behavior of your application.

Completing one of several futures.

If there are several top level tasks that should run until any one completes, use the “select” family of executor constructors. These return an Executor whose run function will return when the first future completes. The uncompleted futures will also be returned so they can be run further or otherwise cleaned up. These functions are inspired by the select_all function from futures-rs, but built to be run inside an FD based executor and to poll only when necessary. See the docs for select2, select3, select4, and select5.

Completing all of several futures.

If there are several top level tasks that all need to be completed, use the “complete” family of executor constructors. These return an Executor whose run function will return only once all the futures passed to it have completed. These functions are inspired by the join_all function from futures-rs, but built to be run inside an FD based executor and to poll only when necessary. See the docs for complete2, complete3, complete4, and complete5.

Implementing new FD-based futures.

For URing implementations should provide an implementation of the IoSource trait. For the FD executor, new futures can use the existing ability to poll a source to build async functionality on top of.

Implementations

Currently there are two paths for using the asynchronous IO. One uses a WaitContext and drives futures based on the FDs signaling they are ready for the opteration. This method will exist so long as kernels < 5.4 are supported. The other method submits operations to io_uring and is signaled when they complete. This is more efficient, but only supported on kernel 5.4+. If IoSource::new is used to interface with async IO, then the correct backend will be chosen automatically.

Examples

See the docs for IoSource if support for kernels <5.4 is required. Focus on UringSource if all systems have support for io_uring.

Re-exports

• pub use mem::BackingMemory;
• pub use mem::MemRegion;
• pub use mem::MemRegionIter;
• pub use mem::VecIoWrapper;
• pub use sys::linux::uring_executor::is_uring_stable;
• pub use crate::sys::async_types::*;

Modules

• async_types 🔒
• audio_streams_async
  Implements the interface required by audio_streams using the cros_async Executor.
• blocking 🔒
• common_executor 🔒
• complete 🔒
• event 🔒
• executor 🔒
• io_ext 🔒
• io_source 🔒
• mem
• queue 🔒
• select 🔒
• sync
• sys
• timer 🔒
• tokio_executor 🔒
• waker 🔒

Structs

• AsyncWrapper
  Simple wrapper struct to implement IntoAsync on foreign types.
• BlockingPool
  A thread pool for running work that may block.
• CancellableBlockingPool
  A thread pool for running work that may block.
• DetachedTasks 🔒
  Heterogeneous collection of async_task:Task that are running in a “detached” state.
• Event
  An inter-process event wait/notify mechanism. Loosely speaking: Writes signal the event. Reads block until the event is signaled and then clear the signal.
• EventAsync
  An async version of base::Event.
• RecvTubeAsync
• SendTubeAsync
• TimerAsync
  An async version of base::Timer.

Enums

• AsyncError
• Error
• Executor
  An executor for scheduling tasks that poll futures to completion.
• ExecutorKind
• IoSource
  Associates an IO object F with cros_async’s runtime and exposes an API to perform async IO on that object’s descriptor.
• SelectResult
• TaskHandle
  Reference to a task managed by the executor.
• TimeoutAction

Traits

• IntoAsync
  Marker trait signifying that the implementor is suitable for use with cros_async. Examples of this include File, and base::net::UnixSeqpacket.

Functions

• block_on
  Run a future to completion on the current thread.
• complete2
  Creates a combinator that runs the two given futures to completion, returning a tuple of the outputs each yields.
• complete3
  Creates a combinator that runs the three given futures to completion, returning a tuple of the outputs each yields.
• complete4
  Creates a combinator that runs the four given futures to completion, returning a tuple of the outputs each yields.
• complete5
  Creates a combinator that runs the five given futures to completion, returning a tuple of the outputs each yields.
• select2
  Creates a combinator that runs the two given futures until one completes, returning a tuple containing the result of the finished future and the still pending future.
• select3
  Creates a combinator that runs the three given futures until one or more completes, returning a tuple containing the result of the finished future(s) and the still pending future(s).
• select4
  Creates a combinator that runs the four given futures until one or more completes, returning a tuple containing the result of the finished future(s) and the still pending future(s).
• select5
  Creates a combinator that runs the five given futures until one or more completes, returning a tuple containing the result of the finished future(s) and the still pending future(s).
• select6
  Creates a combinator that runs the six given futures until one or more completes, returning a tuple containing the result of the finished future(s) and the still pending future(s).
• select7
• select8
• select9
• select10
• select11
• select12
• unblock
  Spawn a task to run in the CancellableBlockingPool static executor.
• unblock_disarm
  Marks all the queued and in-flight tasks as cancelled. Any tasks queued after disarming will be cancelled. Doesn’t not wait for all the tasks to get cancelled.

Type Definitions

• AsyncResult
• Result