@@ -635,8 +635,8 @@ impl<T: AsFd> Async<T> {
635
635
/// This method will put the handle in non-blocking mode and register it in
636
636
/// [epoll]/[kqueue]/[event ports]/[IOCP].
637
637
///
638
- /// On Unix systems, the handle must implement `AsRawFd `, while on Windows it must implement
639
- /// `AsRawSocket `.
638
+ /// On Unix systems, the handle must implement `AsFd `, while on Windows it must implement
639
+ /// `AsSocket `.
640
640
///
641
641
/// [epoll]: https://en.wikipedia.org/wiki/Epoll
642
642
/// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
@@ -661,7 +661,24 @@ impl<T: AsFd> Async<T> {
661
661
Self :: new_nonblocking ( io)
662
662
}
663
663
664
- fn new_nonblocking ( io : T ) -> io:: Result < Async < T > > {
664
+ /// Creates an async I/O handle without setting it to non-blocking mode.
665
+ ///
666
+ /// This method will register the handle in [epoll]/[kqueue]/[event ports]/[IOCP].
667
+ ///
668
+ /// On Unix systems, the handle must implement `AsFd`, while on Windows it must implement
669
+ /// `AsSocket`.
670
+ ///
671
+ /// [epoll]: https://en.wikipedia.org/wiki/Epoll
672
+ /// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
673
+ /// [event ports]: https://illumos.org/man/port_create
674
+ /// [IOCP]: https://learn.microsoft.com/en-us/windows/win32/fileio/i-o-completion-ports
675
+ ///
676
+ /// # Caveats
677
+ ///
678
+ /// The caller should ensure that the handle is set to non-blocking mode or that it is okay if
679
+ /// it is not set. If not set to non-blocking mode, I/O operations may block the current thread
680
+ /// and cause a deadlock in an asynchronous context.
681
+ pub fn new_nonblocking ( io : T ) -> io:: Result < Async < T > > {
665
682
// SAFETY: It is impossible to drop the I/O source while it is registered through
666
683
// this type.
667
684
let registration = unsafe { Registration :: new ( io. as_fd ( ) ) } ;
@@ -712,8 +729,8 @@ impl<T: AsSocket> Async<T> {
712
729
/// This method will put the handle in non-blocking mode and register it in
713
730
/// [epoll]/[kqueue]/[event ports]/[IOCP].
714
731
///
715
- /// On Unix systems, the handle must implement `AsRawFd `, while on Windows it must implement
716
- /// `AsRawSocket `.
732
+ /// On Unix systems, the handle must implement `AsFd `, while on Windows it must implement
733
+ /// `AsSocket `.
717
734
///
718
735
/// [epoll]: https://en.wikipedia.org/wiki/Epoll
719
736
/// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
@@ -738,7 +755,24 @@ impl<T: AsSocket> Async<T> {
738
755
Self :: new_nonblocking ( io)
739
756
}
740
757
741
- fn new_nonblocking ( io : T ) -> io:: Result < Async < T > > {
758
+ /// Creates an async I/O handle without setting it to non-blocking mode.
759
+ ///
760
+ /// This method will register the handle in [epoll]/[kqueue]/[event ports]/[IOCP].
761
+ ///
762
+ /// On Unix systems, the handle must implement `AsFd`, while on Windows it must implement
763
+ /// `AsSocket`.
764
+ ///
765
+ /// [epoll]: https://en.wikipedia.org/wiki/Epoll
766
+ /// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
767
+ /// [event ports]: https://illumos.org/man/port_create
768
+ /// [IOCP]: https://learn.microsoft.com/en-us/windows/win32/fileio/i-o-completion-ports
769
+ ///
770
+ /// # Caveats
771
+ ///
772
+ /// The caller should ensure that the handle is set to non-blocking mode or that it is okay if
773
+ /// it is not set. If not set to non-blocking mode, I/O operations may block the current thread
774
+ /// and cause a deadlock in an asynchronous context.
775
+ pub fn new_nonblocking ( io : T ) -> io:: Result < Async < T > > {
742
776
// Create the registration.
743
777
//
744
778
// SAFETY: It is impossible to drop the I/O source while it is registered through
0 commit comments