Skip to content

Commit 6ae6575

Browse files
committed
Expose Async::new_nonblocking
1 parent b7617e6 commit 6ae6575

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
@@ -636,8 +636,8 @@ impl<T: AsFd> Async<T> {
636636
/// This method will put the handle in non-blocking mode and register it in
637637
/// [epoll]/[kqueue]/[event ports]/[IOCP].
638638
///
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`.
641641
///
642642
/// [epoll]: https://en.wikipedia.org/wiki/Epoll
643643
/// [kqueue]: https://en.wikipedia.org/wiki/Kqueue
@@ -662,7 +662,24 @@ impl<T: AsFd> Async<T> {
662662
Self::new_nonblocking(io)
663663
}
664664

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

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

0 commit comments

Comments
 (0)