1 #![cfg(not(loom))]
2
3 //! Asynchronous file and standard stream adaptation.
4 //!
5 //! This module contains utility methods and adapter types for input/output to
6 //! files or standard streams (`Stdin`, `Stdout`, `Stderr`), and
7 //! filesystem manipulation, for use within (and only within) a Tokio runtime.
8 //!
9 //! Tasks run by *worker* threads should not block, as this could delay
10 //! servicing reactor events. Portable filesystem operations are blocking,
11 //! however. This module offers adapters which use a `blocking` annotation
12 //! to inform the runtime that a blocking operation is required. When
13 //! necessary, this allows the runtime to convert the current thread from a
14 //! *worker* to a *backup* thread, where blocking is acceptable.
15 //!
16 //! ## Usage
17 //!
18 //! Where possible, users should prefer the provided asynchronous-specific
19 //! traits such as [`AsyncRead`], or methods returning a `Future` or `Poll`
20 //! type. Adaptions also extend to traits like `std::io::Read` where methods
21 //! return `std::io::Result`. Be warned that these adapted methods may return
22 //! `std::io::ErrorKind::WouldBlock` if a *worker* thread can not be converted
23 //! to a *backup* thread immediately.
24 //!
25 //! [`AsyncRead`]: https://docs.rs/tokio-io/0.1/tokio_io/trait.AsyncRead.html
26
27 mod canonicalize;
28 pub use self::canonicalize::canonicalize;
29
30 mod create_dir;
31 pub use self::create_dir::create_dir;
32
33 mod create_dir_all;
34 pub use self::create_dir_all::create_dir_all;
35
36 mod dir_builder;
37 pub use self::dir_builder::DirBuilder;
38
39 mod file;
40 pub use self::file::File;
41
42 mod hard_link;
43 pub use self::hard_link::hard_link;
44
45 mod metadata;
46 pub use self::metadata::metadata;
47
48 mod open_options;
49 pub use self::open_options::OpenOptions;
50
51 pub mod os;
52
53 mod read;
54 pub use self::read::read;
55
56 mod read_dir;
57 pub use self::read_dir::{read_dir, DirEntry, ReadDir};
58
59 mod read_link;
60 pub use self::read_link::read_link;
61
62 mod read_to_string;
63 pub use self::read_to_string::read_to_string;
64
65 mod remove_dir;
66 pub use self::remove_dir::remove_dir;
67
68 mod remove_dir_all;
69 pub use self::remove_dir_all::remove_dir_all;
70
71 mod remove_file;
72 pub use self::remove_file::remove_file;
73
74 mod rename;
75 pub use self::rename::rename;
76
77 mod set_permissions;
78 pub use self::set_permissions::set_permissions;
79
80 mod symlink_metadata;
81 pub use self::symlink_metadata::symlink_metadata;
82
83 mod write;
84 pub use self::write::write;
85
86 mod copy;
87 pub use self::copy::copy;
88
89 use std::io;
90
asyncify<F, T>(f: F) -> io::Result<T> where F: FnOnce() -> io::Result<T> + Send + 'static, T: Send + 'static,91 pub(crate) async fn asyncify<F, T>(f: F) -> io::Result<T>
92 where
93 F: FnOnce() -> io::Result<T> + Send + 'static,
94 T: Send + 'static,
95 {
96 match sys::run(f).await {
97 Ok(res) => res,
98 Err(_) => Err(io::Error::new(
99 io::ErrorKind::Other,
100 "background task failed",
101 )),
102 }
103 }
104
105 /// Types in this module can be mocked out in tests.
106 mod sys {
107 pub(crate) use std::fs::File;
108
109 // TODO: don't rename
110 pub(crate) use crate::runtime::spawn_blocking as run;
111 pub(crate) use crate::task::JoinHandle as Blocking;
112 }
113