ci: run doc tests with miri (#7060)

.github/workflows/ci.yml

@@ -403,6 +403,25 @@ jobs:
         env:
           MIRIFLAGS: -Zmiri-disable-isolation -Zmiri-strict-provenance -Zmiri-retag-fields
 
+  miri-doc-test:
+    name: miri-doc-test
+    needs: basics
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust ${{ env.rust_miri_nightly }}
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.rust_miri_nightly }}
+          components: miri
+      - uses: Swatinem/rust-cache@v2
+      - name: miri-doc-test
+        run: |
+          cargo miri test --doc --all-features --no-fail-fast
+        working-directory: tokio
+        env:
+          MIRIFLAGS: -Zmiri-disable-isolation -Zmiri-strict-provenance -Zmiri-retag-fields
+
   asan:
     name: asan
     needs: basics

tokio/src/net/tcp/listener.rs

@@ -83,6 +83,7 @@ impl TcpListener {
         /// # Examples
         ///
         /// ```no_run
+        /// # if cfg!(miri) { return } // No `socket` in miri.
         /// use tokio::net::TcpListener;
         ///
         /// use std::io;

tokio/src/net/tcp/socket.rs

@@ -743,6 +743,7 @@ impl TcpSocket {
     /// # Examples
     ///
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// use tokio::net::TcpSocket;
     /// use socket2::{Domain, Socket, Type};
     ///

tokio/src/net/tcp/stream.rs

@@ -213,6 +213,7 @@ impl TcpStream {
     /// # Examples
     ///
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// use std::error::Error;
     /// use std::io::Read;
     /// use tokio::net::TcpListener;

tokio/src/net/udp.rs

@@ -134,6 +134,7 @@ impl UdpSocket {
     /// # Example
     ///
     /// ```no_run
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// use tokio::net::UdpSocket;
     /// use std::io;
     ///
@@ -295,6 +296,7 @@ impl UdpSocket {
     /// # Example
     ///
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// use tokio::net::UdpSocket;
     ///
     /// # use std::{io, net::SocketAddr};
@@ -1979,6 +1981,7 @@ impl UdpSocket {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// use tokio::net::UdpSocket;
     /// use std::io;
     ///

tokio/src/net/unix/datagram/socket.rs

@@ -35,6 +35,7 @@ cfg_net_unix! {
     /// # Examples
     /// Using named sockets, associated with a filesystem path:
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -67,6 +68,7 @@ cfg_net_unix! {
     ///
     /// Using unnamed sockets, created as a pair
     /// ```
+    /// # if cfg!(miri) { return } // No `socketpair` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -371,6 +373,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -403,6 +406,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No SOCK_DGRAM for socketpair in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -457,6 +461,7 @@ impl UnixDatagram {
     /// explicitly with [`Runtime::enter`](crate::runtime::Runtime::enter) function.
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -521,6 +526,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -560,6 +566,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -604,6 +611,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socketpair` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -734,6 +742,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socketpair` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -884,6 +893,7 @@ impl UnixDatagram {
         ///
         /// # Examples
         /// ```
+        /// # if cfg!(miri) { return } // No `socket` in miri.
         /// # use std::error::Error;
         /// # #[tokio::main]
         /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1000,6 +1010,7 @@ impl UnixDatagram {
         ///
         /// # Examples
         /// ```
+        /// # if cfg!(miri) { return } // No `socketpair` in miri.
         /// # use std::error::Error;
         /// # #[tokio::main]
         /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1050,6 +1061,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1100,6 +1112,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1416,6 +1429,7 @@ impl UnixDatagram {
     /// # Examples
     /// For a socket bound to a local path
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1438,6 +1452,7 @@ impl UnixDatagram {
     ///
     /// For an unbound socket
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1462,6 +1477,7 @@ impl UnixDatagram {
     /// # Examples
     /// For a peer with a local path
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1487,6 +1503,7 @@ impl UnixDatagram {
     ///
     /// For an unbound peer
     /// ```
+    /// # if cfg!(miri) { return } // No `socketpair` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1508,6 +1525,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {
@@ -1535,6 +1553,7 @@ impl UnixDatagram {
     ///
     /// # Examples
     /// ```
+    /// # if cfg!(miri) { return } // No `socketpair` in miri.
     /// # use std::error::Error;
     /// # #[tokio::main]
     /// # async fn main() -> Result<(), Box<dyn Error>> {

tokio/src/net/unix/stream.rs

@@ -833,6 +833,7 @@ impl UnixStream {
     /// # Examples
     ///
     /// ```
+    /// # if cfg!(miri) { return } // No `socket` in miri.
     /// use std::error::Error;
     /// use std::io::Read;
     /// use tokio::net::UnixListener;

tokio/src/process/mod.rs

@@ -810,6 +810,7 @@ impl Command {
     /// Basic usage:
     ///
     /// ```no_run
+    /// # if cfg!(miri) { return } // No `pidfd_spawnp` in miri.
     /// use tokio::process::Command;
     ///
     /// async fn run_ls() -> std::process::ExitStatus {
@@ -1192,6 +1193,7 @@ impl Child {
     /// This function is cancel safe.
     ///
     /// ```
+    /// # if cfg!(miri) { return } // No `pidfd_spawnp` in miri.
     /// # #[cfg(not(unix))]fn main(){}
     /// # #[cfg(unix)]
     /// use tokio::io::AsyncWriteExt;

tokio/src/runtime/runtime.rs

@@ -421,6 +421,7 @@ impl Runtime {
     /// # Examples
     ///
     /// ```
+    /// # if cfg!(miri) { return } // Miri reports error when main thread terminated without waiting all remaining threads.
     /// use tokio::runtime::Runtime;
     /// use tokio::task;
     ///