Expose Async::new_nonblocking

src/lib.rs

@@ -662,7 +662,24 @@ impl<T: AsFd> Async<T> {
         Self::new_nonblocking(io)
     }
 
-    fn new_nonblocking(io: T) -> io::Result<Async<T>> {
+    /// Creates an async I/O handle without setting it to non-blocking mode.
+    ///
+    /// This method will register the handle in [epoll]/[kqueue]/[event ports]/[IOCP].
+    ///
+    /// On Unix systems, the handle must implement `AsRawFd`, while on Windows it must implement
+    /// `AsRawSocket`.
+    ///
+    /// [epoll]: https://en.wikipedia.org/wiki/Epoll
+    /// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
+    /// [event ports]: https://illumos.org/man/port_create
+    /// [IOCP]: https://learn.microsoft.com/en-us/windows/win32/fileio/i-o-completion-ports
+    ///
+    /// # Caveats
+    ///
+    /// The caller should ensure that the handle is set to non-blocking mode or that it is okay if
+    /// it is not set. If not set to non-blocking mode, I/O operations may block the current thread
+    /// and cause a deadlock in an asynchronous context.
+    pub fn new_nonblocking(io: T) -> io::Result<Async<T>> {
         // SAFETY: It is impossible to drop the I/O source while it is registered through
         // this type.
         let registration = unsafe { Registration::new(io.as_fd()) };
@@ -739,7 +756,24 @@ impl<T: AsSocket> Async<T> {
         Self::new_nonblocking(io)
     }
 
-    fn new_nonblocking(io: T) -> io::Result<Async<T>> {
+    /// Creates an async I/O handle without setting it to non-blocking mode.
+    ///
+    /// This method will register the handle in [epoll]/[kqueue]/[event ports]/[IOCP].
+    ///
+    /// On Unix systems, the handle must implement `AsRawFd`, while on Windows it must implement
+    /// `AsRawSocket`.
+    ///
+    /// [epoll]: https://en.wikipedia.org/wiki/Epoll
+    /// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
+    /// [event ports]: https://illumos.org/man/port_create
+    /// [IOCP]: https://learn.microsoft.com/en-us/windows/win32/fileio/i-o-completion-ports
+    ///
+    /// # Caveats
+    ///
+    /// The caller should ensure that the handle is set to non-blocking mode or that it is okay if
+    /// it is not set. If not set to non-blocking mode, I/O operations may block the current thread
+    /// and cause a deadlock in an asynchronous context.
+    pub fn new_nonblocking(io: T) -> io::Result<Async<T>> {
         // Create the registration.
         //
         // SAFETY: It is impossible to drop the I/O source while it is registered through