itsscb/tokio
1
0
Fork 0
mirror of https://github.com/tokio-rs/tokio.git synced 2025-09-28 12:10:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

net: document usage of ready with stream halves (#5515)

Browse Source
This commit is contained in:
Tymoteusz Wiśniewski 2023-03-03 12:21:29 +01:00 committed by GitHub
parent 9931901d5c
commit abd92fb27f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 62 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
tokio/src/net/tcp/split.rs
View File

@ -141,9 +141,9 @@ impl ReadHalf<'_> {
/// Waits for any of the requested ready states. /// Waits for any of the requested ready states.
/// ///
/// This function is usually paired with `try_read()` or `try_write()`. It /// This function is usually paired with [`try_read()`]. It can be used instead
/// can be used to concurrently read / write to the same socket on a single /// of [`readable()`] to check the returned ready set for [`Ready::READABLE`]
/// task without splitting the socket. /// and [`Ready::READ_CLOSED`] events.
/// ///
/// The function may complete without the socket being ready. This is a /// The function may complete without the socket being ready. This is a
/// false-positive and attempting an operation will return with /// false-positive and attempting an operation will return with
@ -153,6 +153,9 @@ impl ReadHalf<'_> {
/// ///
/// This function is equivalent to [`TcpStream::ready`]. /// This function is equivalent to [`TcpStream::ready`].
/// ///
/// [`try_read()`]: Self::try_read
/// [`readable()`]: Self::readable
///
/// # Cancel safety /// # Cancel safety
/// ///
/// This method is cancel safe. Once a readiness event occurs, the method /// This method is cancel safe. Once a readiness event occurs, the method
@ -275,9 +278,9 @@ impl ReadHalf<'_> {
impl WriteHalf<'_> { impl WriteHalf<'_> {
/// Waits for any of the requested ready states. /// Waits for any of the requested ready states.
/// ///
/// This function is usually paired with `try_read()` or `try_write()`. It /// This function is usually paired with [`try_write()`]. It can be used instead
/// can be used to concurrently read / write to the same socket on a single /// of [`writable()`] to check the returned ready set for [`Ready::WRITABLE`]
/// task without splitting the socket. /// and [`Ready::WRITE_CLOSED`] events.
/// ///
/// The function may complete without the socket being ready. This is a /// The function may complete without the socket being ready. This is a
/// false-positive and attempting an operation will return with /// false-positive and attempting an operation will return with
@ -287,6 +290,9 @@ impl WriteHalf<'_> {
/// ///
/// This function is equivalent to [`TcpStream::ready`]. /// This function is equivalent to [`TcpStream::ready`].
/// ///
/// [`try_write()`]: Self::try_write
/// [`writable()`]: Self::writable
///
/// # Cancel safety /// # Cancel safety
/// ///
/// This method is cancel safe. Once a readiness event occurs, the method /// This method is cancel safe. Once a readiness event occurs, the method

18
tokio/src/net/tcp/split_owned.rs
View File

@ -196,9 +196,9 @@ impl OwnedReadHalf {
/// Waits for any of the requested ready states. /// Waits for any of the requested ready states.
/// ///
/// This function is usually paired with `try_read()` or `try_write()`. It /// This function is usually paired with [`try_read()`]. It can be used instead
/// can be used to concurrently read / write to the same socket on a single /// of [`readable()`] to check the returned ready set for [`Ready::READABLE`]
/// task without splitting the socket. /// and [`Ready::READ_CLOSED`] events.
/// ///
/// The function may complete without the socket being ready. This is a /// The function may complete without the socket being ready. This is a
/// false-positive and attempting an operation will return with /// false-positive and attempting an operation will return with
@ -208,6 +208,9 @@ impl OwnedReadHalf {
/// ///
/// This function is equivalent to [`TcpStream::ready`]. /// This function is equivalent to [`TcpStream::ready`].
/// ///
/// [`try_read()`]: Self::try_read
/// [`readable()`]: Self::readable
///
/// # Cancel safety /// # Cancel safety
/// ///
/// This method is cancel safe. Once a readiness event occurs, the method /// This method is cancel safe. Once a readiness event occurs, the method
@ -357,9 +360,9 @@ impl OwnedWriteHalf {
/// Waits for any of the requested ready states. /// Waits for any of the requested ready states.
/// ///
/// This function is usually paired with `try_read()` or `try_write()`. It /// This function is usually paired with [`try_write()`]. It can be used instead
/// can be used to concurrently read / write to the same socket on a single /// of [`writable()`] to check the returned ready set for [`Ready::WRITABLE`]
/// task without splitting the socket. /// and [`Ready::WRITE_CLOSED`] events.
/// ///
/// The function may complete without the socket being ready. This is a /// The function may complete without the socket being ready. This is a
/// false-positive and attempting an operation will return with /// false-positive and attempting an operation will return with
@ -369,6 +372,9 @@ impl OwnedWriteHalf {
/// ///
/// This function is equivalent to [`TcpStream::ready`]. /// This function is equivalent to [`TcpStream::ready`].
/// ///
/// [`try_write()`]: Self::try_write
/// [`writable()`]: Self::writable
///
/// # Cancel safety /// # Cancel safety
/// ///
/// This method is cancel safe. Once a readiness event occurs, the method /// This method is cancel safe. Once a readiness event occurs, the method

28
tokio/src/net/unix/split.rs
View File

@ -55,9 +55,20 @@ pub(crate) fn split(stream: &mut UnixStream) -> (ReadHalf<'_>, WriteHalf<'_>) {
impl ReadHalf<'_> { impl ReadHalf<'_> {
/// Wait for any of the requested ready states. /// Wait for any of the requested ready states.
/// ///
/// This function is usually paired with `try_read()` or `try_write()`. It /// This function is usually paired with [`try_read()`]. It can be used instead
/// can be used to concurrently read / write to the same socket on a single /// of [`readable()`] to check the returned ready set for [`Ready::READABLE`]
/// task without splitting the socket. /// and [`Ready::READ_CLOSED`] events.
///
/// The function may complete without the socket being ready. This is a
/// false-positive and attempting an operation will return with
/// `io::ErrorKind::WouldBlock`. The function can also return with an empty
/// [`Ready`] set, so you should always check the returned value and possibly
/// wait again if the requested states are not set.
///
/// This function is equivalent to [`UnixStream::ready`].
///
/// [`try_read()`]: Self::try_read
/// [`readable()`]: Self::readable
/// ///
/// # Cancel safety /// # Cancel safety
/// ///
@ -178,9 +189,9 @@ impl ReadHalf<'_> {
impl WriteHalf<'_> { impl WriteHalf<'_> {
/// Waits for any of the requested ready states. /// Waits for any of the requested ready states.
/// ///
/// This function is usually paired with `try_read()` or `try_write()`. It /// This function is usually paired with [`try_write()`]. It can be used instead
/// can be used to concurrently read / write to the same socket on a single /// of [`writable()`] to check the returned ready set for [`Ready::WRITABLE`]
/// task without splitting the socket. /// and [`Ready::WRITE_CLOSED`] events.
/// ///
/// The function may complete without the socket being ready. This is a /// The function may complete without the socket being ready. This is a
/// false-positive and attempting an operation will return with /// false-positive and attempting an operation will return with
@ -188,6 +199,11 @@ impl WriteHalf<'_> {
/// [`Ready`] set, so you should always check the returned value and possibly /// [`Ready`] set, so you should always check the returned value and possibly
/// wait again if the requested states are not set. /// wait again if the requested states are not set.
/// ///
/// This function is equivalent to [`UnixStream::ready`].
///
/// [`try_write()`]: Self::try_write
/// [`writable()`]: Self::writable
///
/// # Cancel safety /// # Cancel safety
/// ///
/// This method is cancel safe. Once a readiness event occurs, the method /// This method is cancel safe. Once a readiness event occurs, the method

22
tokio/src/net/unix/split_owned.rs
View File

@ -110,9 +110,9 @@ impl OwnedReadHalf {
/// Waits for any of the requested ready states. /// Waits for any of the requested ready states.
/// ///
/// This function is usually paired with `try_read()` or `try_write()`. It /// This function is usually paired with [`try_read()`]. It can be used instead
/// can be used to concurrently read / write to the same socket on a single /// of [`readable()`] to check the returned ready set for [`Ready::READABLE`]
/// task without splitting the socket. /// and [`Ready::READ_CLOSED`] events.
/// ///
/// The function may complete without the socket being ready. This is a /// The function may complete without the socket being ready. This is a
/// false-positive and attempting an operation will return with /// false-positive and attempting an operation will return with
@ -120,6 +120,11 @@ impl OwnedReadHalf {
/// [`Ready`] set, so you should always check the returned value and possibly /// [`Ready`] set, so you should always check the returned value and possibly
/// wait again if the requested states are not set. /// wait again if the requested states are not set.
/// ///
/// This function is equivalent to [`UnixStream::ready`].
///
/// [`try_read()`]: Self::try_read
/// [`readable()`]: Self::readable
///
/// # Cancel safety /// # Cancel safety
/// ///
/// This method is cancel safe. Once a readiness event occurs, the method /// This method is cancel safe. Once a readiness event occurs, the method
@ -267,9 +272,9 @@ impl OwnedWriteHalf {
/// Waits for any of the requested ready states. /// Waits for any of the requested ready states.
/// ///
/// This function is usually paired with `try_read()` or `try_write()`. It /// This function is usually paired with [`try_write()`]. It can be used instead
/// can be used to concurrently read / write to the same socket on a single /// of [`writable()`] to check the returned ready set for [`Ready::WRITABLE`]
/// task without splitting the socket. /// and [`Ready::WRITE_CLOSED`] events.
/// ///
/// The function may complete without the socket being ready. This is a /// The function may complete without the socket being ready. This is a
/// false-positive and attempting an operation will return with /// false-positive and attempting an operation will return with
@ -277,6 +282,11 @@ impl OwnedWriteHalf {
/// [`Ready`] set, so you should always check the returned value and possibly /// [`Ready`] set, so you should always check the returned value and possibly
/// wait again if the requested states are not set. /// wait again if the requested states are not set.
/// ///
/// This function is equivalent to [`UnixStream::ready`].
///
/// [`try_write()`]: Self::try_write
/// [`writable()`]: Self::writable
///
/// # Cancel safety /// # Cancel safety
/// ///
/// This method is cancel safe. Once a readiness event occurs, the method /// This method is cancel safe. Once a readiness event occurs, the method