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`]: trait@crate::io::AsyncRead
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 mod read;
52 pub use self::read::read;
53
54 mod read_dir;
55 pub use self::read_dir::{read_dir, DirEntry, ReadDir};
56
57 mod read_link;
58 pub use self::read_link::read_link;
59
60 mod read_to_string;
61 pub use self::read_to_string::read_to_string;
62
63 mod remove_dir;
64 pub use self::remove_dir::remove_dir;
65
66 mod remove_dir_all;
67 pub use self::remove_dir_all::remove_dir_all;
68
69 mod remove_file;
70 pub use self::remove_file::remove_file;
71
72 mod rename;
73 pub use self::rename::rename;
74
75 mod set_permissions;
76 pub use self::set_permissions::set_permissions;
77
78 mod symlink_metadata;
79 pub use self::symlink_metadata::symlink_metadata;
80
81 mod write;
82 pub use self::write::write;
83
84 mod copy;
85 pub use self::copy::copy;
86
87 #[cfg(test)]
88 mod mocks;
89
90 feature! {
91 #![unix]
92
93 mod symlink;
94 pub use self::symlink::symlink;
95 }
96
97 feature! {
98 #![windows]
99
100 mod symlink_dir;
101 pub use self::symlink_dir::symlink_dir;
102
103 mod symlink_file;
104 pub use self::symlink_file::symlink_file;
105 }
106
107 use std::io;
108
109 #[cfg(not(test))]
110 use crate::blocking::spawn_blocking;
111 #[cfg(test)]
112 use mocks::spawn_blocking;
113
asyncify<F, T>(f: F) -> io::Result<T> where F: FnOnce() -> io::Result<T> + Send + 'static, T: Send + 'static,114 pub(crate) async fn asyncify<F, T>(f: F) -> io::Result<T>
115 where
116 F: FnOnce() -> io::Result<T> + Send + 'static,
117 T: Send + 'static,
118 {
119 match spawn_blocking(f).await {
120 Ok(res) => res,
121 Err(_) => Err(io::Error::new(
122 io::ErrorKind::Other,
123 "background task failed",
124 )),
125 }
126 }
127