fs: add support for DirBuilder and DirBuilderExt

The initial idea was to implement  a thin wrapper  around an internally
held `std::fs::DirBuilder` instance.  This, however, didn't work due to
`std::fs::DirBuilder` not having a Copy/Clone traits implemented, which
are necessary  for constructing an instance to move-capture it  into  a
closure.

Instead,  we mirror `std::fs::DirBuilder` configuration by  storing the
`recursive` and (unix-only) `mode`  parameters locally,  which are then
used to construct an `std::fs::DirBuilder` instance on-the-fly.

The (unix-only) `DirBuilderExt` trait  has  been  implemented  in-place
within the `dir_builder` create. Despite it might have looked better to
have it separated somewhere in `../fs/os/unix`, I haven't found a clean
and idiomatic way to do so (due to Rust's "orphan rules").  I'd be glad
to hear  the propositions  in case someone  sees  a  way for this to be
further simplified.

Fixes: #2369

tokio/src/fs/dir_builder.rs

@@ -0,0 +1,137 @@
+use crate::fs::asyncify;
+
+use std::io;
+use std::path::Path;
+
+/// A builder for creating directories in various manners.
+///
+/// Additional Unix-specific options are available via importing the
+/// [os::unix::fs::DirBuilderExt] trait.
+///
+/// This is a specialized version of [`std::fs::DirBuilder`] for usage from
+/// the Tokio runtime.
+///
+/// [os::unix::fs::DirBuilderExt]: ../os/unix/fs/trait.DirBuilderExt.html
+/// [std::fs::DirBuilder]: https://doc.rust-lang.org/std/fs/struct.DirBuilder.html
+#[derive(Debug, Default)]
+pub struct DirBuilder {
+    /// Indicates whether to create parent directories if they are missing.
+    recursive: bool,
+
+    /// Set the Unix mode for newly created directories.
+    #[cfg(unix)]
+    mode: Option<u32>,
+}
+
+impl DirBuilder {
+    /// Creates a new set of options with default mode/security settings for all
+    /// platforms and also non-recursive.
+    ///
+    /// This is an async version of [`std::fs::DirBuilder::new`][std]
+    ///
+    /// [std]: std::fs::DirBuilder::new
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::DirBuilder;
+    ///
+    /// let builder = DirBuilder::new();
+    /// ```
+    pub fn new() -> DirBuilder {
+        #[cfg(not(unix))]
+        let builder = DirBuilder { recursive: false };
+
+        #[cfg(unix)]
+        let builder = DirBuilder {
+            recursive: false,
+            mode: None,
+        };
+
+        builder
+    }
+
+    /// Indicates whether to create directories recursively (including all parent directories).
+    /// Parents that do not exist are created with the same security and permissions settings.
+    ///
+    /// This option defaults to `false`.
+    ///
+    /// This is an async version of [`std::fs::DirBuilder::recursive`][std]
+    ///
+    /// [std]: std::fs::DirBuilder::recursive
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::DirBuilder;
+    ///
+    /// let mut builder = DirBuilder::new();
+    /// builder.recursive(true);
+    /// ```
+    pub fn recursive(&mut self, recursive: bool) -> &mut Self {
+        self.recursive = recursive;
+        self
+    }
+
+    /// Creates the specified directory with the configured options.
+    ///
+    /// It is considered an error if the directory already exists unless
+    /// recursive mode is enabled.
+    ///
+    /// This is an async version of [`std::fs::DirBuilder::create`][std]
+    ///
+    /// [std]: std::fs::DirBuilder::create
+    ///
+    /// # Errors
+    ///
+    /// An error will be returned under the following circumstances:
+    ///
+    /// * Path already points to an existing file.
+    /// * Path already points to an existing directory and the mode is
+    ///   non-recursive.
+    /// * The calling process doesn't have permissions to create the directory
+    ///   or its missing parents.
+    /// * Other I/O error occurred.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::DirBuilder;
+    /// use std::io;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     DirBuilder::new()
+    ///         .recursive(true)
+    ///         .create("/tmp/foo/bar/baz")
+    ///         .await?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    pub async fn create<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
+        let path = path.as_ref().to_owned();
+        let mut builder = std::fs::DirBuilder::new();
+        builder.recursive(self.recursive);
+
+        #[cfg(unix)]
+        {
+            if let Some(mode) = self.mode {
+                std::os::unix::fs::DirBuilderExt::mode(&mut builder, mode);
+            }
+        }
+
+        asyncify(move || builder.create(path)).await
+    }
+}
+
+cfg_unix! {
+    use std::os::unix::fs::DirBuilderExt;
+
+    impl DirBuilderExt for DirBuilder {
+        fn mode(&mut self, mode: u32) -> &mut Self {
+            self.mode = Some(mode);
+            self
+        }
+    }
+}