Skip to content

Commit a5da16f

Browse files
committed
Expose Async::new_nonblocking
1 parent 0f2af63 commit a5da16f

File tree

1 file changed

+40
-6
lines changed

1 file changed

+40
-6
lines changed

src/lib.rs

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -635,8 +635,8 @@ impl<T: AsFd> Async<T> {
635635
/// This method will put the handle in non-blocking mode and register it in
636636
/// [epoll]/[kqueue]/[event ports]/[IOCP].
637637
///
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`.
640640
///
641641
/// [epoll]: https://en.wikipedia.org/wiki/Epoll
642642
/// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
@@ -661,7 +661,24 @@ impl<T: AsFd> Async<T> {
661661
Self::new_nonblocking(io)
662662
}
663663

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>> {
665682
// SAFETY: It is impossible to drop the I/O source while it is registered through
666683
// this type.
667684
let registration = unsafe { Registration::new(io.as_fd()) };
@@ -712,8 +729,8 @@ impl<T: AsSocket> Async<T> {
712729
/// This method will put the handle in non-blocking mode and register it in
713730
/// [epoll]/[kqueue]/[event ports]/[IOCP].
714731
///
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`.
717734
///
718735
/// [epoll]: https://en.wikipedia.org/wiki/Epoll
719736
/// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
@@ -738,7 +755,24 @@ impl<T: AsSocket> Async<T> {
738755
Self::new_nonblocking(io)
739756
}
740757

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>> {
742776
// Create the registration.
743777
//
744778
// SAFETY: It is impossible to drop the I/O source while it is registered through

0 commit comments

Comments
 (0)