timeout_readwrite/
lib.rs

1// Copyright 2017 Jonathan Creekmore
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9#![cfg(unix)]
10
11//! Provides `TimeoutReader` and `TimeoutWriter` structs to time out reads and
12//! writes, respectively. `TimeoutReader` implements `Read` and `TimeoutWriter`
13//! implements `Write`. If any operation times out, the method called will return
14//! an `io::ErrorKind::TimedOut` variant as the value of `io::Error`. All other
15//! error values that would normally be produced by the underlying implementation
16//! of the `Read` or `Write` trait could also be produced by the `TimeoutReader` and
17//! `TimeoutWriter` structs.
18//!
19//! # Example: read from a process with a 5-second timeout
20//!
21//! Given a process that writes to standard out, read from the output once it is there,
22//! but fail if you have to wait longer than 5-seconds for data to be present on standard
23//! out.
24//!
25//! ```rust
26//! use std::io::{ErrorKind, Read, Result};
27//! use std::process;
28//! use std::time::Duration;
29//! use timeout_readwrite::TimeoutReader;
30//!
31//! fn read_command(mut cmd: process::Command) -> Result<String> {
32//!     let child = cmd.stdout(process::Stdio::piped())
33//!        .stderr(process::Stdio::null())
34//!        .spawn()
35//!        .expect("spawing did not succeed");
36//!     let stdout = child.stdout.expect("stdout must be there");
37//!
38//!     let mut data = String::new();
39//!     let mut rdr = TimeoutReader::new(stdout, Duration::new(5, 0));
40//!     rdr.read_to_string(&mut data)?;
41//!     Ok(data)
42//! }
43//!
44//! match read_command(process::Command::new("ls")) {
45//!   Ok(value) => { print!("{}", value); },
46//!   Err(ref e) if e.kind() == ErrorKind::TimedOut => { println!("timed out!"); },
47//!   Err(ref e) => { println!("failed reading with {}", e); },
48//! }
49//! ```
50//!
51//! # Example: use the TimeoutReadExt trait
52//!
53//! Use the TimeoutReadExt trait to provide a simple helper method to creating a TimeoutReader.
54//!
55//! ```rust
56//! use std::io::{ErrorKind, Read, Result};
57//! use std::process;
58//! use std::time::Duration;
59//! use timeout_readwrite::TimeoutReadExt;
60//!
61//! fn read_command(mut cmd: process::Command) -> Result<String> {
62//!     let child = cmd.stdout(process::Stdio::piped())
63//!        .stderr(process::Stdio::null())
64//!        .spawn()
65//!        .expect("spawing did not succeed");
66//!     let stdout = child.stdout.expect("stdout must be there");
67//!
68//!     let mut data = String::new();
69//!     stdout.with_timeout(Duration::new(5, 0)).read_to_string(&mut data)?;
70//!     Ok(data)
71//! }
72//!
73//! match read_command(process::Command::new("ls")) {
74//!   Ok(value) => { print!("{}", value); },
75//!   Err(ref e) if e.kind() == ErrorKind::TimedOut => { println!("timed out!"); },
76//!   Err(ref e) => { println!("failed reading with {}", e); },
77//! }
78//! ```
79
80#[cfg(test)]
81#[macro_use]
82extern crate lazy_static;
83extern crate nix;
84
85mod utils;
86
87pub mod reader;
88pub use reader::{TimeoutReadExt, TimeoutReader};
89
90pub mod writer;
91pub use writer::{TimeoutWriteExt, TimeoutWriter};
timeout_readwrite/lib.rs

timeout_readwrite/
lib.rs
