Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/withoutboats/romio

asynchronous networking primitives
https://github.com/withoutboats/romio

Last synced: 7 days ago
JSON representation

asynchronous networking primitives

Awesome Lists containing this project

README 

        
# Romio



[![build status][travis-badge]][travis-url]

[![crates.io version][crates-badge]][crates-url]

[![docs.rs docs][docs-badge]][docs-url]

[![MIT licensed][mit-badge]][mit-url]



Asynchronous network primitives in Rust.



__Note: This library is not actively being developed. If you're looking for an

`async/await` compatible runtime consider using [`tokio`](https://github.com/tokio-rs/tokio/) or

[`async-std`](https://github.com/async-rs/async-std).__



Romio combines the powerful [`futures`][futures] abstractions with the

nonblocking IO primitives of [`mio`][mio] to provide efficient and ergonomic

asynchronous IO primitives for the Rust asynchronous networking ecosystem.

Romio's primitives are:



* **Fast**: The zero-cost `Future` abstractions give you bare metal

  performance, despite the higher level API.

* **Reliable**: Romio leverages Rust's type system to reduce bugs and ensure

  thread safety among concurrently executing asynchronous functions.

* **Scalable**: Romio has a minimal footprint and handles backpressure and

  cancellation naturally.



Romio is based on the [Tokio][tokio] crate, porting components from it to a

newer version of the futures crate.



[travis-badge]: https://img.shields.io/travis/withoutboats/romio/master.svg?style=flat-square

[travis-url]: https://travis-ci.org/withoutboats/romio

[crates-badge]: https://img.shields.io/crates/v/romio.svg?style=flat-square

[crates-url]: https://crates.io/crates/romio

[docs-badge]: https://img.shields.io/badge/docs.rs-latest-blue.svg?style=flat-square

[docs-url]: https://docs.rs/romio

[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square

[mit-url]: LICENSE-MIT



## Examples



Here are two example programs using romio: a TCP server which serves a random

quote of Shakespeare, and a TCP client which connects to that server and prints

the quote it received to standard out.



### Shakespeare Server



```rust

use std::io;



use futures::executor::{self, ThreadPool};

use futures::io::AsyncWriteExt;

use futures::task::SpawnExt;

use futures::StreamExt;



use rand::seq::SliceRandom;



use romio::{TcpListener, TcpStream};



const SHAKESPEARE: &[&[u8]] = &[

    b"Now is the winter of our discontent\nMade glorious summer by this sun of York.\n",

    b"Some are born great, some achieve greatness\nAnd some have greatness thrust upon them.\n",

    b"Friends, Romans, countrymen - lend me your ears!\nI come not to praise Caesar, but to bury him.\n",

    b"The evil that men do lives after them\nThe good is oft interred with their bones.\n",

    b"                  It is a tale\nTold by an idiot, full of sound and fury\nSignifying nothing.\n",

    b"Ay me! For aught that I could ever read,\nCould ever hear by tale or history,\nThe course of true love never did run smooth.\n",

    b"I have full cause of weeping, but this heart\nShall break into a hundred thousand flaws,\nOr ere I'll weep.-O Fool, I shall go mad!\n",

    b"                  Each your doing,\nSo singular in each particular,\nCrowns what you are doing in the present deed,\nThat all your acts are queens.\n",

];



fn main() -> io::Result<()> {

    executor::block_on(async {

        let mut threadpool = ThreadPool::new()?;



        let mut listener = TcpListener::bind(&"127.0.0.1:7878".parse().unwrap())?;

        let mut incoming = listener.incoming();



        println!("Listening on 127.0.0.1:7878");



        while let Some(stream) = incoming.next().await {

            let stream = stream?;

            let addr = stream.peer_addr()?;



            threadpool

                .spawn(async move {

                    println!("Accepting stream from: {}", addr);



                    recite_shakespeare(stream).await.unwrap();



                    println!("Closing stream from: {}", addr);

                })

                .unwrap();

        }



        Ok(())

    })

}



async fn recite_shakespeare(mut stream: TcpStream) -> io::Result<()> {

    //stream.set_keepalive(None);

    let &quote = SHAKESPEARE.choose(&mut rand::thread_rng()).unwrap();

    stream.write_all(quote).await?;

    Ok(())

}

```



### Shakespeare Client



```rust

use std::io;



use futures::executor;

use futures::io::{AllowStdIo, AsyncReadExt};



use romio::TcpStream;



fn main() -> io::Result<()> {

    executor::block_on(async {

        let mut stream = TcpStream::connect(&"127.0.0.1:7878".parse().unwrap()).await?;

        let mut stdout = AllowStdIo::new(io::stdout());

        stream.copy_into(&mut stdout).await?;

        Ok(())

    })

}

```



## Relationship to Tokio



Romio is a fork of another Rust project called [Tokio][tokio]. The Tokio

project uses an older version of the futures API which is not compatible with

the new "async/await" syntax. In order to enable people to experiment with

"async/await," Romio ports parts of the tokio project to the newer futures API

which is compatible with that syntax.



Romio is not a complete port of tokio: it only contains a small part of the

entire tokio code base: the IO primitives necessary for writing asynchronous

networking code. It does not expose low level control of the core "reactor" -

instead, all async IO primitives use the default reactor set up - and it

doesn't contain many other parts of tokio that are not directly related to

asynchronous IO.



You should use romio if you want to experiment with writing networking code

using the new async/await syntax. However, romio is not directly compatible

with other libraries built on top of tokio - like hyper, actix, and tower - so

if you want to use those, romio might not be a good fit for you.



Romio is intended to unblock people trying to experiment with async/await,

which is why it exposes such a minimal API. It's not intended to be a full

fledged "competitor" to tokio, which we expect will eventually move to the

newer futures API and be compatible with async/await syntax.



## License



This project is licensed under the [MIT license](LICENSE).



### Contribution



Unless you explicitly state otherwise, any contribution intentionally submitted

for inclusion in romio by you, shall be licensed as MIT, without any additional

terms or conditions.



[futures]: https://crates.io/crates/futures

[mio]: https://crates.io/crates/mio

[tokio]: https://crates.io/crates/tokio