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 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