Empowering everyone to build asynchronous software

Related tags

Asynchronous runtime
Overview

Runtime

Empowering everyone to build asynchronous software.

Built with by The Rust Async Ecosystem WG

⚠️ Deprecation notice ⚠️

Runtime is no longer actively developed. The team behind Runtime has moved on to building async-std: an asynchronous version of the Rust stdlib.

If you're looking for an asynchronous runtime please consider using async-std or tokio.

About

Runtime is what we imagine async APIs could look like if they were part of stdlib. We want async Rust to be an experience that mirrors the quality of the standard lib. We believe that in order for Rust to succeed it's not only important to make async Rust possible, it's crucial to make async Rust feel seamless.

And the embodiment of these values is Runtime: a library crafted to empower everyone to build asynchronous software.

  • runtime agnostic: Runtime comes with minimal OS bindings out of the box, but switching to a different runtime is a matter of changing a single line.
  • await anywhere: Runtime allows you to write async main functions, async tests, and async benchmarks. Experience what first-class async support in Rust feels like.
  • built for performance: Runtime is the thinnest layer possible on top of the backing implementations. All of the speed, none of the boilerplate.

Examples

UDP Echo Server

use runtime::net::UdpSocket;

#[runtime::main]
async fn main() -> std::io::Result<()> {
    let mut socket = UdpSocket::bind("127.0.0.1:8080")?;
    let mut buf = vec![0u8; 1024];

    println!("Listening on {}", socket.local_addr()?);

    loop {
        let (recv, peer) = socket.recv_from(&mut buf).await?;
        let sent = socket.send_to(&buf[..recv], &peer).await?;
        println!("Sent {} out of {} bytes to {}", sent, recv, peer);
    }
}

To send messages do:

$ nc -u localhost 8080

More Examples

Attributes

Runtime introduces 3 attributes to enable the use of await anywhere, and swap between different runtimes. Each Runtime is bound locally to the initializing thread. This enables the testing of different runtimes during testing or benchmarking.

#[runtime::main]
async fn main() {}

#[runtime::test]
async fn my_test() {}

#[runtime::bench]
async fn my_bench() {}

Runtimes

Switching runtimes is a one-line change:

/// Use the default Native Runtime
#[runtime::main]
async fn main() {}

/// Use the Tokio Runtime
#[runtime::main(runtime_tokio::Tokio)]
async fn main() {}

The following backing runtimes are available:

  • Runtime Native (default) provides a thread pool, bindings to the OS, and a concurrent scheduler.
  • Runtime Tokio provides a thread pool, bindings to the OS, and a work-stealing scheduler.

Performance

Runtime provides performance that's competitive with most other systems languages, and great ergonomics to match.

Because we don't know what your workload is like, we can't predict which runtime will be able to maximize resource consumption for your use case.

But we can tell from our benchmarks that the difference between using Runtime and not using Runtime doesn't show up for IO-bound applications.

 name          baseline:: ns/iter  native:: ns/iter  diff ns/iter    diff %  speedup
 notify_self   1,350,882           1,237,416             -113,466    -8.40%   x 1.09
 poll_reactor  2,270,428           2,162,264             -108,164    -4.76%   x 1.05

Installation

With cargo-edit do:

$ cargo add runtime --allow-prerelease

To use Futures in the same project, make sure to install futures-preview for std futures.

$ cargo add futures-preview --allow-prerelease

futures-preview provides support for std futures/futures 0.3, while futures provides support for the no longer developed futures 0.1. Once futures land in stdlib, it's expected that the two crates will merge back into futures. With the hopes that eventually most of futures will be part of stdlib.

FAQ

When is it useful to switch Runtimes?

What might be the best solution now, might not stay the best in the future. As Rust grows, so will the ecosystem. By making runtimes pluggable, your code can be forward compatible with any future changes. And as things evolve, you'll be able to test out the benefit new developments in the ecosystem have on your code by just changing a single line.

How is Runtime versioned?

We're currently in the 0.3-alpha range of releases, mirroring the Futures libraries. Once Futures hits 1.0, we'll follow suit and move over to semver proper.

This doesn't mean that Runtime won't release breaking changes. But if we do, we'll release a new major version, and provide instructions on how to upgrade. We view Runtime to be a foundational piece of technology, and that means we have to be serious about our stability guarantees.

Can I use Runtime in production?

Runtime is a thin layer that sits between your code and the backing runtimes. If you trust the backing runtime in production, then you can probably trust Runtime too.

Why is Runtime Native the default?

We believe Runtime Native provides a balanced implementation that works well for most scenarios. The codebase is small and comprehensive, and the algorithms simple yet performant.

Specific runtimes might introduce different trade-offs, and with Runtime you're able to compare, and pick the best fit for your requirements.

Can Runtime be used on embedded devices?

Runtime is designed to be compatible with micro processors, but not with micro controllers. Out of the box Runtime works on embedded devices such as Raspberry Pis, and with the appropriate backends it should also work on phones.

Micro controllers are very specific in what they provide, and while a Runtime-like library might be possible in the future, it's still early for the ecosystem and APIs would likely also need to be different. We don't know what the future holds, but for now we've chosen not to target micro controllers.

When will Timers and File System support land?

Timers are next up on the list of things we want to target, together with Unix Domain Sockets. Filesystem is a bit further behind because currently the implementations in the backing runtimes are changing, and we're not sure yet how to best abstract that.

Getting things right takes time. But if you'd like to move the state of async forward, we'd love for you to get involved!

Safety

This crate uses #![deny(unsafe_code)] to ensure everything is implemented in 100% Safe Rust.

Contributing

Want to join us? Check out our The "Contributing" section of the guide and take a look at some of these issues:

Conduct

The Runtime project adheres to the Contributor Covenant Code of Conduct. This describes the minimum behavior expected from all contributors.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Comments
  • Proper runtime

    Proper runtime "enter" instead of spawn + local blocking

    Remove the necessity to spawn threads by using an explicit enter method in the Runtime trait which blocks on the passed future.

    Description, Motivation and Context

    Currently all runtimes need to run in background threads / worker pools.

    With this PR this is changed: there is an explicit enter which is supposed to block on the passed future, so a current_thread runtime doesn't need to spawn new threads (which makes strace way easier to read, and is simply cleaner imho).

    This also removes various (lazy_statics) globals: if a runtime is entered again, it will simply have to recreate the runtime environment, and it should shutdown cleanly on leaving enter. (One might argue whether it should only block on the passed future or on a more generic "runtime shutdown".)

    The second commit avoids double-boxing with a more generic JoinHandle and its type-erased CompletionHandle part.

    This also makes it more explicit that enter can't work on wasm; I went for a simple panic though instead of going #[cfg(...)]-crazy over the API (especially as the existing wasm cfg handling is broken and looks wrong).

    Types of changes

    • [x] New feature (non-breaking change which adds functionality)
    • [x] Breaking change (fix or feature that would cause existing functionality to change)

    (Although the breaking change should only be visible for runtime_raw users.)

    opened by stbuehler 12
  • Update examples

    Update examples

    This project looks promising. I like the simplicity. However, can you kindly update your examples with every release to prevent errors. I have tried a few and some of them result in errors, for example, the UDP and TCP echo server examples result in error error[E0599]: no method namednextfound for typeruntime::net::tcp::Incoming<'_>in the current scope --> src/main.rs:18:46

    question 
    opened by charleschege 11
  • Is it possible to read and write from one socket simultaneously?

    Is it possible to read and write from one socket simultaneously?

    I found the both read and write functions of TcpStream and UdpSocket take &mut self and make it impossible.

    Is it able to achieve this by providing a method that "split" the read and write part of a socket?

    opened by oxalica 10
  • Ability to have custom initialization for each worker thread

    Ability to have custom initialization for each worker thread

    tokio::runtime provides a builder which let users run initialization code for each worker thread. Could this be also possible in runtime, say, having an attribute proc macro runtime::initializer which can let us designate the function to be ran for worker thread initialization?

    enhancement 
    opened by dovahcrow 9
  • Design: separate networking from spawning futures

    Design: separate networking from spawning futures

    I have been considering using runtime, but there are some issues with it's design. I wonder how you feel about them. It's common to spawn futures without using networking (TCP/UDP), especially in libraries which might have to spawn futures, but would leave the choice of executor to client code.

    I am surprised by how tightly runtime is coupled to romio and networking. I don't really want to bloat library dependencies like this.

    Have you considered separating the two concerns?

    opened by najamelan 8
  • Move from StreamObj to Pin<Box<dyn Future>>

    Move from StreamObj to Pin>

    As per https://github.com/rust-lang-nursery/futures-rs/issues/1352 and https://github.com/rust-lang-nursery/futures-rs/pull/1494 FutureObj is going to be deprecated. We should update our usage to use BoxFuture instead.

    enhancement 
    opened by yoshuawuyts 8
  • fix false must_use warning on JoinHandle

    fix false must_use warning on JoinHandle

    Removes the must_use requirement on the JoinHandle

    Motivation and Context

    The must_use requirement is a bit misleading, since the JoinHandle is the result of a future being spawned, and thus the originating future will be polled to completion, whether or not the JoinHandle is polled.

    This seems like it may overlap with some of the changes in #73, where it may be desirable to instead use a RemoteHandle - but since there is some open discussion, this seems like a worthy (and simple) change.

    Another option might be to add a .forget() method which consumes the JoinHandle directly, and is thus a bit more explicit.

    Types of changes

    • [x] Bug fix (non-breaking change which fixes an issue)
    • [ ] New feature (non-breaking change which adds functionality)
    • [ ] Breaking change (fix or feature that would cause existing functionality to change)
    opened by rschmukler 6
  • improved error message for unused futures

    improved error message for unused futures

    Follows https://github.com/rustasync/runtime/pull/31#issuecomment-492593832 I guess this variant was merged in rust-lang/rust. What about message for streams?

    opened by ibaryshnikov 6
  • Replace `JoinHandle` with `RemoteHandle`

    Replace `JoinHandle` with `RemoteHandle`

    Replace JoinHandle with RemoteHandle from futures.

    This is a counter proposal to #78.

    It changes the semantic a little (RemoteHandle must actually be used; if dropped without calling forget it will cancel the future) - basically the opposite direction of #78.

    Types of changes

    • [ ] Bug fix (non-breaking change which fixes an issue)
    • [ ] New feature (non-breaking change which adds functionality)
    • [x] Breaking change (fix or feature that would cause existing functionality to change)
    opened by stbuehler 5
  • default cross-platform runtime

    default cross-platform runtime

    This is a neat project! Over in Fuchsia we'd like to use this to abstract over unix/fuchsia async primitives. In particular, we would like to be able to run third party tests on fuchsia to validate that things work as expected in the presence of the (substantially) different underlying system.

    As a motivating example, consider Trust-DNS, which has tests which need an executor because they deal in futures. In order for that code to compile on fuchsia, we need some executor implementation that is cross-platform.

    Has any thought been given to how such a thing would be provided? Fuchsia is still substantially unstable, so adding a dependency from runtime to some Fuchsia crate wouldn't work (since we're not yet publishing our crates to avoid stability guarantees).

    Thanks!

    opened by tamird 5
  • How to use runtime with a framed + codec style transformation

    How to use runtime with a framed + codec style transformation

    I am trying out runtime, but having a hard time figuring out how to translate an existing tokio codec, to use runtime, without having to fallback onto a Futures01 compat layer.

    Before I had a TLS Stream wrapped into a framed tokio codec in my Connection struct, which was a line based codec, meaning I have a parser that transforms each line of the incoming data into a parsed struct, and vice versa when writing.

    Most solutions I found so far are effectively reimplementing the Framed construction (https://github.com/tokio-rs/tokio/blob/master/tokio-io/src/framed_read.rs) which I was hoping could be avoided. Would love to hear any ideas.

    question 
    opened by dignifiedquire 5
Owner
Rust Async (archived)
Formerly the @rust-lang async ecosystem domain working group, now archived
Rust Async (archived)
Rust - Empowering everyone to build reliable and efficient software.

The Rust Programming Language This is the main source code repository for Rust. It contains the compiler, standard library, and documentation. Note: t

The Rust Programming Language 75.9k Dec 28, 2022
Build fast, reward everyone, and scale without friction.

Scrypto Language for building DeFi apps on Radix. Terminology Package: A collection of blueprints, compiled and published as a single unit. Blueprint:

Radix DLT 330 Dec 25, 2022
A comprehensive collection of resources and learning materials for Rust programming, empowering developers to explore and master the modern, safe, and blazingly fast language.

?? Awesome Rust Lang ⛰️ Project Description : Welcome to the Awesome Rust Lang repository! This is a comprehensive collection of resources for Rust, a

Shubham Raj 16 May 29, 2023
Revolutionize handheld gaming with adaptive game settings. Optimize graphics and gameplay experience based on real-time system metrics. Open-source project empowering developers to enhance games on portable devices

Welcome to the server-side application for the HarmonyLink project. This innovative software is developed with the Rust programming language and is ai

Jordon Brooks 5 Jun 28, 2023
A simple programming language for everyone.

Slang A simple programming language for everyone, made with Rust. State In very early stages. Plan is to create a byte-code compiler and make that exe

Slang, Inc. 11 Jul 1, 2022
HyperCube is a free and open source blockchain project for everyone to use.

XPZ Public Chain HyperCube is a free and open source blockchain project for everyone to use. 日本語 简体中文 正體中文 HyperCube Wiki Wha is HyperCube HyperCube i

null 949 Dec 31, 2022
Hi I'm Sophy, a discord bot in devlopment, soon I'll be available to help everyone (❁´◡`❁)

Sophy Bot Hi I'm Sophy, a discord bot in devlopment, soon I'll be available to help everyone (❁´◡`❁) Contribution Do you like me and want to help me?

Far Dragi 0 May 30, 2022
Santa Claus has to optimize the space for everyone present on the sled.

How to generate all sets of P packages into N bags Santa Claus has to optimize the space for everyone present on the sled Description Santa Claus got

João Nuno Carvalho 2 Apr 26, 2022
This is the Rust course used by the Android team at Google. It provides you the material to quickly teach Rust to everyone.

Comprehensive Rust ?? This repository has the source code for Comprehensive Rust ?? , a four day Rust course developed by the Android team. The course

Google 5.2k Jan 3, 2023
Open to everyone 👪 - The Polkadot Blockchain Academy's Rust Qualifier Exam.

Rust Qualifier Exam An open source learning resource, available to all. This exam is maintained by the Polkadot Blockchain Academy, for the benefit of

Polkadot Blockchain Academy 8 Apr 18, 2023
dark-std an Implementation of asynchronous containers build on tokio

dark-std dark-std is an Implementation of asynchronous containers build on tokio. It uses a read-write separation design borrowed from Golang SyncHash

darkrpc 4 Dec 13, 2022
Habitat is open source software that creates platform-independent build artifacts and provides built-in deployment and management capabilities.

Habitat is open source software that creates platform-independent build artifacts and provides built-in deployment and management capabilities. The go

Habitat 2.4k Dec 27, 2022
UniSBOM is a tool to build a software bill of materials on any platform with a unified data format.

UniSBOM is a tool to build a software bill of materials on any platform with a unified data format. Work in progress Support MacOS Uses system_profile

Simone Margaritelli 32 Nov 2, 2022
Build Java applications without fighting your build tool. Drink some espresso.

Espresso Build Java applications without fighting your build tool. Drink some espresso. Features Modern Look & Feel Command line interface inspired by

Hunter LaFaille 5 Apr 2, 2024
Zero-cost asynchronous programming in Rust

Zero-cost asynchronous programming in Rust Documentation | Website futures-rs is a library providing the foundations for asynchronous programming in R

The Rust Programming Language 4.7k Jan 1, 2023
Asynchronous Linux SocketCAN sockets with tokio

tokio-socketcan SocketCAN support for tokio based on the socketcan crate. Example echo server use futures_util::stream::StreamExt; use tokio_socketcan

Terry 29 Nov 8, 2022
A fully asynchronous, futures-based Kafka client library for Rust based on librdkafka

rust-rdkafka A fully asynchronous, futures-enabled Apache Kafka client library for Rust based on librdkafka. The library rust-rdkafka provides a safe

Federico Giraud 1.1k Jan 8, 2023
A runtime for writing reliable asynchronous applications with Rust. Provides I/O, networking, scheduling, timers, ...

Tokio A runtime for writing reliable, asynchronous, and slim applications with the Rust programming language. It is: Fast: Tokio's zero-cost abstracti

Tokio 18.7k Dec 30, 2022
Time-manager of delayed tasks. Like crontab, but synchronous asynchronous tasks are possible, and dynamic add/cancel/remove is supported.

delay-timer Time-manager of delayed tasks. Like crontab, but synchronous asynchronous tasks are possible, and dynamic add/cancel/remove is supported.

BinCheng 255 Dec 30, 2022
Hitbox is an asynchronous caching framework supporting multiple backends and suitable for distributed and for single-machine applications.

Hitbox is an asynchronous caching framework supporting multiple backends and suitable for distributed and for single-machine applications.

null 62 Dec 27, 2022