handy_async/
lib.rs

1//! This library provides miscellaneous functionalities to help asynchronous operations in Rust.
2//!
3//! `handy_async` uses [futures](https://github.com/alexcrichton/futures-rs) to
4//! achieve asynchronous operations (mainly I/O related operations)
5//! and defines a lot of pattern objects to facilitate writing declarative code.
6//!
7//! For example, you can write a function to read a TCP header
8//! defined in [RFC-793](https://www.ietf.org/rfc/rfc793.txt) asynchronously as following.
9//!
10//! ```no_run
11//! extern crate handy_async;
12//! extern crate futures;
13//!
14//! use std::io::{Read, Error};
15//! use futures::{Future, BoxFuture};
16//! use handy_async::io::ReadFrom;
17//! use handy_async::pattern::{Pattern, Endian};
18//! use handy_async::pattern::read::{U16, U32};
19//!
20//! struct TcpHeader {
21//!     source_port: u16,
22//!     destination_port: u16,
23//!     sequence_number: u32,
24//!     acknowledgment_number: u32,
25//!     data_offset: u8, // 4 bits
26//!     reserved: u8, // 6 bits
27//!     flags: u8, // 6 bits
28//!     window: u16,
29//!     checksum: u16,
30//!     urgent_pointer: u16,
31//!     option: Vec<u8>,
32//! }
33//!
34//! fn read_tcp_header<R: Read + Send + 'static>(reader: R) -> BoxFuture<TcpHeader, Error> {
35//!     let pattern = (U16.be(), U16.be(), U32.be(), U32.be(),
36//!                    U16.be(), U16.be(), U16.be(), U16.be())
37//!         .and_then(|(src_port, dst_port, seq_num, ack_num, flags, window, checksum, urgent)| {
38//!             let data_offset = (flags & 0b1111) as u8;
39//!             let header = TcpHeader {
40//!                 source_port: src_port,
41//!                 destination_port: dst_port,
42//!                 sequence_number: seq_num,
43//!                 acknowledgment_number: ack_num,
44//!                 data_offset: data_offset,
45//!                 reserved: ((flags >> 4) & 0b111111) as u8,
46//!                 flags: (flags >> 10) as u8,
47//!                 window: window,
48//!                 checksum: checksum,
49//!                 urgent_pointer: urgent,
50//!                 option: Vec::new(),
51//!             };
52//!
53//!             let option_size = (data_offset as usize - 5) * 4;
54//!             (Ok(header), vec![0; option_size]) // Reads additional option bytes
55//!         })
56//!         .map(|(mut header, option)| {
57//!             header.option = option;
58//!             header
59//!         });
60//!     pattern.read_from(reader).map(|(reader, header)| header).map_err(|e| e.into_error()).boxed()
61//! }
62//!
63//! fn main(){
64//!     let future = read_tcp_header(std::io::stdin());
65//!     let tcp_header = future.wait().expect("Failed to read tcp header");
66//! }
67//! ```
68#![warn(missing_docs)]
69
70extern crate futures;
71extern crate byteorder;
72
73pub mod io;
74pub mod sync_io;
75pub mod pattern;
76pub mod matcher;
77pub mod error;
78pub mod future;