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