tokio_fs/
lib.rs

1#![deny(missing_docs, missing_debug_implementations)]
2#![doc(html_root_url = "https://docs.rs/tokio-fs/0.1.7")]
3
4//! Asynchronous file and standard stream adaptation.
5//!
6//! This module contains utility methods and adapter types for input/output to
7//! files or standard streams (`Stdin`, `Stdout`, `Stderr`), and
8//! filesystem manipulation, for use within (and only within) a Tokio runtime.
9//!
10//! Tasks run by *worker* threads should not block, as this could delay
11//! servicing reactor events. Portable filesystem operations are blocking,
12//! however. This module offers adapters which use a [`blocking`] annotation
13//! to inform the runtime that a blocking operation is required. When
14//! necessary, this allows the runtime to convert the current thread from a
15//! *worker* to a *backup* thread, where blocking is acceptable.
16//!
17//! ## Usage
18//!
19//! Where possible, users should prefer the provided asynchronous-specific
20//! traits such as [`AsyncRead`], or methods returning a `Future` or `Poll`
21//! type. Adaptions also extend to traits like `std::io::Read` where methods
22//! return `std::io::Result`.  Be warned that these adapted methods may return
23//! `std::io::ErrorKind::WouldBlock` if a *worker* thread can not be converted
24//! to a *backup* thread immediately. See [tokio-threadpool] for more details
25//! of the threading model and [`blocking`].
26//!
27//! [`blocking`]: https://docs.rs/tokio-threadpool/0.1/tokio_threadpool/fn.blocking.html
28//! [`AsyncRead`]: https://docs.rs/tokio-io/0.1/tokio_io/trait.AsyncRead.html
29//! [tokio-threadpool]: https://docs.rs/tokio-threadpool/0.1/tokio_threadpool
30
31#[macro_use]
32extern crate futures;
33extern crate tokio_io;
34extern crate tokio_threadpool;
35
36mod create_dir;
37mod create_dir_all;
38pub mod file;
39mod hard_link;
40mod metadata;
41pub mod os;
42mod read;
43mod read_dir;
44mod read_link;
45mod remove_dir;
46mod remove_file;
47mod rename;
48mod set_permissions;
49mod stderr;
50mod stdin;
51mod stdout;
52mod symlink_metadata;
53mod write;
54
55pub use create_dir::{create_dir, CreateDirFuture};
56pub use create_dir_all::{create_dir_all, CreateDirAllFuture};
57pub use file::File;
58pub use file::OpenOptions;
59pub use hard_link::{hard_link, HardLinkFuture};
60pub use metadata::{metadata, MetadataFuture};
61pub use read::{read, ReadFile};
62pub use read_dir::{read_dir, DirEntry, ReadDir, ReadDirFuture};
63pub use read_link::{read_link, ReadLinkFuture};
64pub use remove_dir::{remove_dir, RemoveDirFuture};
65pub use remove_file::{remove_file, RemoveFileFuture};
66pub use rename::{rename, RenameFuture};
67pub use set_permissions::{set_permissions, SetPermissionsFuture};
68pub use stderr::{stderr, Stderr};
69pub use stdin::{stdin, Stdin};
70pub use stdout::{stdout, Stdout};
71pub use symlink_metadata::{symlink_metadata, SymlinkMetadataFuture};
72pub use write::{write, WriteFile};
73
74use futures::Async::*;
75use futures::Poll;
76
77use std::io;
78use std::io::ErrorKind::{Other, WouldBlock};
79
80fn blocking_io<F, T>(f: F) -> Poll<T, io::Error>
81where
82    F: FnOnce() -> io::Result<T>,
83{
84    match tokio_threadpool::blocking(f) {
85        Ok(Ready(Ok(v))) => Ok(v.into()),
86        Ok(Ready(Err(err))) => Err(err),
87        Ok(NotReady) => Ok(NotReady),
88        Err(_) => Err(blocking_err()),
89    }
90}
91
92fn would_block<F, T>(f: F) -> io::Result<T>
93where
94    F: FnOnce() -> io::Result<T>,
95{
96    match tokio_threadpool::blocking(f) {
97        Ok(Ready(Ok(v))) => Ok(v),
98        Ok(Ready(Err(err))) => {
99            debug_assert_ne!(err.kind(), WouldBlock);
100            Err(err)
101        }
102        Ok(NotReady) => Err(WouldBlock.into()),
103        Err(_) => Err(blocking_err()),
104    }
105}
106
107fn blocking_err() -> io::Error {
108    io::Error::new(
109        Other,
110        "`blocking` annotated I/O must be called \
111         from the context of the Tokio runtime.",
112    )
113}
tokio_fs/lib.rs

tokio_fs/
lib.rs
