futures_ringbuf 0.1.0

Mock Type implementing Read/Write/AsyncRead/AsyncWrite for testing and examples.
docs.rs failed to build futures_ringbuf-0.1.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: futures_ringbuf-0.4.0

futures_ringbuf

standard-readme compliant Build Status Docs crates.io

A fake async network stream for testing and examples without having to do tcp.

It acts like both ends of a network connection. You can think of it like the network connection to an echo server. You can frame it with futures_codec, split it to get both halves separately and send and receive messages on it. You can use this in testing and examples to avoid having to make actual TCP connections.

Data in transit is held in an internal RingBuffer from the ringbuf crate.

Table of Contents

Install

With cargo add: cargo add futures_ringbuf

With cargo yaml:

dependencies:

  futures_ringbuf: ^0.1

With raw Cargo.toml

[dependencies]

   futures_ringbuf = "^0.1"

Upgrade

Please check out the changelog when upgrading.

Dependencies

This crate has few dependiencies. Cargo will automatically handle it's dependencies for you.

There are no optional features.

Usage

The crate provides a RingBuffer<T> struct which implements AsyncRead/AsyncWrite from the futures library when T is u8. You can now call split provided by AsyncRead and treat them as both ends of a network connection.

The reader will return Poll::Pending when the buffer is empty, and the writer when the buffer is full. They will wake eachother up when new data/space is available.

If you want to play with std::io::Read/std::io::Write, check out the ringbuf crate directly, as it's Producer and Consumer types implement these traits, so I didn't include them here.

I haven't yet included Stream<T>, Sink<T>, because on u8 that doesn't make much sense, but if there is demand, it can definitely be added.

The requirements on T are T: Sized + Copy.

Basic example

//! Frame a RingBuf with futures_codec. This example shows how the sending task will
//! block when the buffer is full. When a reader consumes the buffer, the sender is woken up.
//!
//! Run with `cargo run --example basic`.
//
#![feature(async_await)]


use
{
   futures_ringbuf :: { *                                            } ,
   futures         :: { SinkExt, StreamExt, executor::block_on, join } ,
   futures_codec   :: { Framed, LinesCodec                           } ,
};


fn main()
{
   let program = async
   {
      let mock = RingBuffer::new( 13 );
      let (mut writer, mut reader) = Framed::new( mock, LinesCodec{} ).split();


      let send_task = async move
      {
         writer.send( "Hello World\n".to_string() ).await.expect( "send" );
         println!( "sent first line" );

         writer.send( "Second line\n".to_string() ).await.expect( "send" );
         println!( "sent second line" );

         writer.close().await.expect( "close sender" );
         println!( "sink closed" );
      };


      let receive_task = async move
      {
         // If we would return here, the second line will never get sent
         // because the buffer is full.
         //
         // return;

         while let Some(msg) = reader.next().await.transpose().expect( "receive message" )
         {
            println!( "Received: {:#?}", msg );
         }
      };


      // Poll them in concurrently
      //
      join!( send_task, receive_task );
   };

   block_on( program );
}

API

Api documentation can be found on docs.rs.

Contributing

This repository accepts contributions. Ideas, questions, feature requests and bug reports can be filed through github issues.

Pull Requests are welcome on github. By commiting pull requests, you accept that your code might be modified and reformatted to fit the project coding style or to improve the implementation. Please discuss what you want to see modified before filing a pull request if you don't want to be doing work that might be rejected.

Please file PR's against the dev branch, don't forget to update the changelog and the documentation.

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.

Testing

cargo test

Code of conduct

Any of the behaviors described in point 4 "Unacceptable Behavior" of the Citizens Code of Conduct are not welcome here and might get you banned. If anyone including maintainers and moderators of the project fail to respect these/your limits, you are entitled to call them out.

License

Unlicence