diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 60a962f8b25..c0e728e63b0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -71,6 +71,7 @@ jobs: - check-external-types - check-fuzzing - check-unstable-mt-counters + - check-spelling steps: - run: exit 0 @@ -994,3 +995,22 @@ jobs: - name: Check /tokio-stream/ run: cargo fuzz check --all-features working-directory: tokio-stream + + check-spelling: + name: check-spelling + needs: basics + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install Rust ${{ env.rust_stable }} + uses: dtolnay/rust-toolchain@stable + with: + toolchain: ${{ env.rust_stable }} + - name: Install cargo-spellcheck + uses: taiki-e/install-action@v2 + with: + tool: cargo-spellcheck + - uses: actions/checkout@v4 + - name: Run cargo-spellcheck + run: cargo spellcheck --code 1 + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1fd3bf0d28..cd6f651a2ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -194,6 +194,24 @@ MIRIFLAGS="-Zmiri-disable-isolation -Zmiri-tag-raw-pointers" \ cargo +nightly miri test --features full --lib ``` +### Performing spellcheck on tokio codebase + +You can perform spell-check on tokio codebase. For details of how to use the spellcheck tool, feel free to visit +https://github.com/drahnr/cargo-spellcheck +``` +# First install the spell-check plugin +cargo install --locked cargo-spellcheck + +# Then run the cargo spell check command +cargo spellcheck check +``` + +if the command rejects a word, you should backtick the rejected word if it's code related. If not, the +rejected word should be put into `spellcheck.dic` file. + +Note that when you add a word into the file, you should also update the first line which tells the spellcheck tool +the total number of words included in the file + ### Tests If the change being proposed alters code (as opposed to only documentation for diff --git a/Cargo.toml b/Cargo.toml index f3e19312e8b..d8ac248189d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,3 +14,7 @@ members = [ "tests-build", "tests-integration", ] + +[workspace.metadata.spellcheck] +config = "spellcheck.toml" + diff --git a/spellcheck.dic b/spellcheck.dic new file mode 100644 index 00000000000..ddedb90730d --- /dev/null +++ b/spellcheck.dic @@ -0,0 +1,279 @@ +279 +\ +~ +~4 +~12 +±1m +±1ms +— +& ++ +0o777 +0s +0xA +0xD +100ms +10ms +1ms +1s +250ms +2x +443 +450ms +50ms +8MB +< += +> +adaptor +adaptors +Adaptors +AIO +ambiant +amongst +api +APIs +async +awaitable +backend +backpressure +backtrace +backtraces +backtracing +binded +bitfield +bitfields +Blockingly +boolean +broadcasted +cancelled +cancelling +Cancelling +CLI +cloneable +codebase +codec +codecs +combinator +combinators +Config +config +connectionless +cpu +cpus +Customizable +Datagram +datagram +datagrams +deallocate +deallocated +Deallocates +decrementing +dequeued +deregister +deregistered +deregistering +Deregisters +deregisters +deregistration +descriptor's +destructor +destructors +destructure +Destructures +Dev +dns +DNS +DoS +dwOpenMode +endian +enqueue +enqueued +EntryInner +enum +eof +errored +EWMA +expirations +fcntl +fd's +FIFOs +filename +filesystem +filesystems +fn +fns +FreeBSD +frontend +fs +functionalities +getters +GID +Growable +gzip +hashmaps +HashMaps +hashsets +ie +Illumos +impl +implementers +implementor +implementors +incrementing +interoperate +Invariants +invariants +io +IOCP +iOS +IOs +IP +IPv4 +IPv6 +iteratively +latencies +Lauck +libc +lifecycle +lifo +lookups +macOS +MacOS +Marsaglia's +metadata +mio +Mio +mio's +misconfigured +mock's +mpmc +mpsc +Multi +multi +multicast +Multithreaded +mut +mutex +Mutex +Nagle +nonblocking +nondecreasing +noop +ntasks +ok +oneshot +ORed +os +overweighing +parker +parsers +peekable +PGID +PID +plaintext +poller +POSIX +proxied +qos +RAII +reallocations +recv's +refactors +refcount +refcounting +repo +repr +representable +reqwest +reregistering +resize +resized +RMW +runtime +runtimes +runtime's +rwlock +rx +scalability +scheduler's +semver +setpgid +sharded +signalled +signalling +SmallCrush +Solaris +spawner +Splitter +spmc +spsc +src +stabilised +startup +stateful +stderr +stdin +stdout +stealable +stealer +stealers +struct +structs +subfield +suboptimal +subprocess +superset +symlink +symlinks +sys +syscall +syscalls +TCP +tcp +TestU01 +threadpool +timestamp +timestamps +TLS +TOCTOU +TODO +Tokio +tokio +tokio's +Tokio's +Tuple +tuple +tx +UDP +udp +UID +unhandled +unix +unlink +unpark +Unpark +unparked +unparking +Unparks +unparks +unreceived +unsafety +Unsets +unsynchronized +untrusted +usecases +Valgrind +Varghese +vec +versa +versioned +versioning +vtable +waker +wakers +Wakers +wakeup +wakeups +workstealing + diff --git a/spellcheck.toml b/spellcheck.toml new file mode 100644 index 00000000000..fb14364be0c --- /dev/null +++ b/spellcheck.toml @@ -0,0 +1,13 @@ +dev_comments = false +skip_readme = false + +[Hunspell] +lang = "en_US" +search_dirs = ["."] +extra_dictionaries = ["spellcheck.dic"] +skip_os_lookups = true +use_builtin = true + +[Hunspell.quirks] +allow_concatenation = true + diff --git a/tokio-stream/src/lib.rs b/tokio-stream/src/lib.rs index 28ca9963ce1..b6e651c7b8b 100644 --- a/tokio-stream/src/lib.rs +++ b/tokio-stream/src/lib.rs @@ -54,7 +54,7 @@ //! //! [async-stream]: https://docs.rs/async-stream //! -//! # Conversion to and from AsyncRead/AsyncWrite +//! # Conversion to and from `AsyncRead`/`AsyncWrite` //! //! It is often desirable to convert a `Stream` into an [`AsyncRead`], //! especially when dealing with plaintext formats streamed over the network. diff --git a/tokio-stream/src/stream_map.rs b/tokio-stream/src/stream_map.rs index 041e477aa51..3f424eca221 100644 --- a/tokio-stream/src/stream_map.rs +++ b/tokio-stream/src/stream_map.rs @@ -658,9 +658,9 @@ mod rand { /// Fast random number generate /// - /// Implement xorshift64+: 2 32-bit xorshift sequences added together. + /// Implement `xorshift64+`: 2 32-bit `xorshift` sequences added together. /// Shift triplet `[17,7,16]` was calculated as indicated in Marsaglia's - /// Xorshift paper: + /// `Xorshift` paper: /// This generator passes the SmallCrush suite, part of TestU01 framework: /// #[derive(Debug)] diff --git a/tokio-stream/src/wrappers/watch.rs b/tokio-stream/src/wrappers/watch.rs index ec8ead06da0..a1ea646035a 100644 --- a/tokio-stream/src/wrappers/watch.rs +++ b/tokio-stream/src/wrappers/watch.rs @@ -10,7 +10,7 @@ use tokio::sync::watch::error::RecvError; /// A wrapper around [`tokio::sync::watch::Receiver`] that implements [`Stream`]. /// -/// This stream will start by yielding the current value when the WatchStream is polled, +/// This stream will start by yielding the current value when the `WatchStream` is polled, /// regardless of whether it was the initial value or sent afterwards, /// unless you use [`WatchStream::from_changes`]. /// diff --git a/tokio-util/src/codec/framed.rs b/tokio-util/src/codec/framed.rs index 8a344f90db2..e988da0a734 100644 --- a/tokio-util/src/codec/framed.rs +++ b/tokio-util/src/codec/framed.rs @@ -130,7 +130,7 @@ impl Framed { /// things like gzip or TLS, which require both read and write access to the /// underlying object. /// - /// This objects takes a stream and a readbuffer and a writebuffer. These field + /// This objects takes a stream and a `readbuffer` and a `writebuffer`. These field /// can be obtained from an existing `Framed` with the [`into_parts`] method. /// /// If you want to work more directly with the streams and sink, consider diff --git a/tokio-util/src/codec/mod.rs b/tokio-util/src/codec/mod.rs index 2295176bdce..98a2f724425 100644 --- a/tokio-util/src/codec/mod.rs +++ b/tokio-util/src/codec/mod.rs @@ -1,4 +1,4 @@ -//! Adaptors from AsyncRead/AsyncWrite to Stream/Sink +//! Adaptors from `AsyncRead`/`AsyncWrite` to Stream/Sink //! //! Raw I/O objects work with byte sequences, but higher-level code usually //! wants to batch these into meaningful chunks, called "frames". diff --git a/tokio-util/src/io/inspect.rs b/tokio-util/src/io/inspect.rs index c860b803571..7604d9a3de1 100644 --- a/tokio-util/src/io/inspect.rs +++ b/tokio-util/src/io/inspect.rs @@ -18,7 +18,7 @@ pin_project! { } impl InspectReader { - /// Create a new InspectReader, wrapping `reader` and calling `f` for the + /// Create a new `InspectReader`, wrapping `reader` and calling `f` for the /// new data supplied by each read call. /// /// The closure will only be called with an empty slice if the inner reader @@ -100,7 +100,7 @@ pin_project! { } impl InspectWriter { - /// Create a new InspectWriter, wrapping `write` and calling `f` for the + /// Create a new `InspectWriter`, wrapping `write` and calling `f` for the /// data successfully written by each write call. /// /// The closure `f` will never be called with an empty slice. A vectored diff --git a/tokio-util/src/sync/cancellation_token/tree_node.rs b/tokio-util/src/sync/cancellation_token/tree_node.rs index 0263f311164..f042e4e79e1 100644 --- a/tokio-util/src/sync/cancellation_token/tree_node.rs +++ b/tokio-util/src/sync/cancellation_token/tree_node.rs @@ -1,16 +1,16 @@ -//! This mod provides the logic for the inner tree structure of the CancellationToken. +//! This mod provides the logic for the inner tree structure of the `CancellationToken`. //! -//! CancellationTokens are only light handles with references to [`TreeNode`]. +//! `CancellationTokens` are only light handles with references to [`TreeNode`]. //! All the logic is actually implemented in the [`TreeNode`]. //! //! A [`TreeNode`] is part of the cancellation tree and may have one parent and an arbitrary number of //! children. //! -//! A [`TreeNode`] can receive the request to perform a cancellation through a CancellationToken. +//! A [`TreeNode`] can receive the request to perform a cancellation through a `CancellationToken`. //! This cancellation request will cancel the node and all of its descendants. //! //! As soon as a node cannot get cancelled any more (because it was already cancelled or it has no -//! more CancellationTokens pointing to it any more), it gets removed from the tree, to keep the +//! more `CancellationTokens` pointing to it any more), it gets removed from the tree, to keep the //! tree as small as possible. //! //! # Invariants @@ -66,7 +66,7 @@ impl TreeNode { } } -/// The data contained inside a TreeNode. +/// The data contained inside a `TreeNode`. /// /// This struct exists so that the data of the node can be wrapped /// in a Mutex. @@ -198,7 +198,7 @@ where /// `parent` MUST have been a parent of the node when they both got locked, /// otherwise there is a potential for a deadlock as invariant #2 would be violated. /// -/// To acquire the locks for node and parent, use [with_locked_node_and_parent]. +/// To acquire the locks for node and parent, use [`with_locked_node_and_parent`]. fn move_children_to_parent(node: &mut Inner, parent: &mut Inner) { // Pre-allocate in the parent, for performance parent.children.reserve(node.children.len()); @@ -216,7 +216,7 @@ fn move_children_to_parent(node: &mut Inner, parent: &mut Inner) { /// Removes a child from the parent. /// /// `parent` MUST be the parent of `node`. -/// To acquire the locks for node and parent, use [with_locked_node_and_parent]. +/// To acquire the locks for node and parent, use [`with_locked_node_and_parent`]. fn remove_child(parent: &mut Inner, mut node: MutexGuard<'_, Inner>) { // Query the position from where to remove a node let pos = node.parent_idx; diff --git a/tokio-util/src/task/join_map.rs b/tokio-util/src/task/join_map.rs index 412aa96c10b..13e27bb670b 100644 --- a/tokio-util/src/task/join_map.rs +++ b/tokio-util/src/task/join_map.rs @@ -878,7 +878,7 @@ impl Eq for Key {} #[derive(Debug, Clone)] pub struct JoinMapKeys<'a, K, V> { iter: hashbrown::hash_map::Keys<'a, Key, AbortHandle>, - /// To make it easier to change JoinMap in the future, keep V as a generic + /// To make it easier to change `JoinMap` in the future, keep V as a generic /// parameter. _value: PhantomData<&'a V>, } diff --git a/tokio/src/doc/os.rs b/tokio/src/doc/os.rs index cded8b97cc0..337f8969afa 100644 --- a/tokio/src/doc/os.rs +++ b/tokio/src/doc/os.rs @@ -1,67 +1,67 @@ -//! See [std::os](https://doc.rust-lang.org/std/os/index.html). +//! See [`std::os`](https://doc.rust-lang.org/std/os/index.html). /// Platform-specific extensions to `std` for Windows. /// -/// See [std::os::windows](https://doc.rust-lang.org/std/os/windows/index.html). +/// See [`std::os::windows`](https://doc.rust-lang.org/std/os/windows/index.html). pub mod windows { /// Windows-specific extensions to general I/O primitives. /// - /// See [std::os::windows::io](https://doc.rust-lang.org/std/os/windows/io/index.html). + /// See [`std::os::windows::io`](https://doc.rust-lang.org/std/os/windows/io/index.html). pub mod io { - /// See [std::os::windows::io::RawHandle](https://doc.rust-lang.org/std/os/windows/io/type.RawHandle.html) + /// See [`std::os::windows::io::RawHandle`](https://doc.rust-lang.org/std/os/windows/io/type.RawHandle.html) pub type RawHandle = crate::doc::NotDefinedHere; - /// See [std::os::windows::io::OwnedHandle](https://doc.rust-lang.org/std/os/windows/io/struct.OwnedHandle.html) + /// See [`std::os::windows::io::OwnedHandle`](https://doc.rust-lang.org/std/os/windows/io/struct.OwnedHandle.html) pub type OwnedHandle = crate::doc::NotDefinedHere; - /// See [std::os::windows::io::AsRawHandle](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html) + /// See [`std::os::windows::io::AsRawHandle`](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html) pub trait AsRawHandle { - /// See [std::os::windows::io::AsRawHandle::as_raw_handle](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html#tymethod.as_raw_handle) + /// See [`std::os::windows::io::AsRawHandle::as_raw_handle`](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html#tymethod.as_raw_handle) fn as_raw_handle(&self) -> RawHandle; } - /// See [std::os::windows::io::FromRawHandle](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html) + /// See [`std::os::windows::io::FromRawHandle`](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html) pub trait FromRawHandle { - /// See [std::os::windows::io::FromRawHandle::from_raw_handle](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html#tymethod.from_raw_handle) + /// See [`std::os::windows::io::FromRawHandle::from_raw_handle`](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html#tymethod.from_raw_handle) unsafe fn from_raw_handle(handle: RawHandle) -> Self; } - /// See [std::os::windows::io::RawSocket](https://doc.rust-lang.org/std/os/windows/io/type.RawSocket.html) + /// See [`std::os::windows::io::RawSocket`](https://doc.rust-lang.org/std/os/windows/io/type.RawSocket.html) pub type RawSocket = crate::doc::NotDefinedHere; - /// See [std::os::windows::io::AsRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html) + /// See [`std::os::windows::io::AsRawSocket`](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html) pub trait AsRawSocket { - /// See [std::os::windows::io::AsRawSocket::as_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html#tymethod.as_raw_socket) + /// See [`std::os::windows::io::AsRawSocket::as_raw_socket`](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html#tymethod.as_raw_socket) fn as_raw_socket(&self) -> RawSocket; } - /// See [std::os::windows::io::FromRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html) + /// See [`std::os::windows::io::FromRawSocket`](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html) pub trait FromRawSocket { - /// See [std::os::windows::io::FromRawSocket::from_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html#tymethod.from_raw_socket) + /// See [`std::os::windows::io::FromRawSocket::from_raw_socket`](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html#tymethod.from_raw_socket) unsafe fn from_raw_socket(sock: RawSocket) -> Self; } - /// See [std::os::windows::io::IntoRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html) + /// See [`std::os::windows::io::IntoRawSocket`](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html) pub trait IntoRawSocket { - /// See [std::os::windows::io::IntoRawSocket::into_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html#tymethod.into_raw_socket) + /// See [`std::os::windows::io::IntoRawSocket::into_raw_socket`](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html#tymethod.into_raw_socket) fn into_raw_socket(self) -> RawSocket; } - /// See [std::os::windows::io::BorrowedHandle](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedHandle.html) + /// See [`std::os::windows::io::BorrowedHandle`](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedHandle.html) pub type BorrowedHandle<'handle> = crate::doc::NotDefinedHere; - /// See [std::os::windows::io::AsHandle](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html) + /// See [`std::os::windows::io::AsHandle`](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html) pub trait AsHandle { - /// See [std::os::windows::io::AsHandle::as_handle](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html#tymethod.as_handle) + /// See [`std::os::windows::io::AsHandle::as_handle`](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html#tymethod.as_handle) fn as_handle(&self) -> BorrowedHandle<'_>; } - /// See [std::os::windows::io::BorrowedSocket](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedSocket.html) + /// See [`std::os::windows::io::BorrowedSocket`](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedSocket.html) pub type BorrowedSocket<'socket> = crate::doc::NotDefinedHere; - /// See [std::os::windows::io::AsSocket](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html) + /// See [`std::os::windows::io::AsSocket`](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html) pub trait AsSocket { - /// See [std::os::windows::io::AsSocket::as_socket](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html#tymethod.as_socket) + /// See [`std::os::windows::io::AsSocket::as_socket`](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html#tymethod.as_socket) fn as_socket(&self) -> BorrowedSocket<'_>; } } diff --git a/tokio/src/fs/open_options/mock_open_options.rs b/tokio/src/fs/open_options/mock_open_options.rs index 17b4a48640a..2fbdd282a3a 100644 --- a/tokio/src/fs/open_options/mock_open_options.rs +++ b/tokio/src/fs/open_options/mock_open_options.rs @@ -1,5 +1,5 @@ #![allow(unreachable_pub)] -//! Mock version of std::fs::OpenOptions; +//! Mock version of `std::fs::OpenOptions`; use mockall::mock; use crate::fs::mocks::MockFile; diff --git a/tokio/src/io/interest.rs b/tokio/src/io/interest.rs index e8cc0c42d84..a15b28cf79a 100644 --- a/tokio/src/io/interest.rs +++ b/tokio/src/io/interest.rs @@ -40,11 +40,11 @@ impl Interest { #[cfg(not(target_os = "freebsd"))] pub const AIO: Interest = Interest(READABLE); - /// Interest for POSIX AIO lio_listio events. + /// Interest for POSIX AIO `lio_listio` events. #[cfg(target_os = "freebsd")] pub const LIO: Interest = Interest(LIO); - /// Interest for POSIX AIO lio_listio events. + /// Interest for POSIX AIO `lio_listio` events. #[cfg(not(target_os = "freebsd"))] pub const LIO: Interest = Interest(READABLE); } diff --git a/tokio/src/io/mod.rs b/tokio/src/io/mod.rs index ff35a0e0f7e..5e903c04842 100644 --- a/tokio/src/io/mod.rs +++ b/tokio/src/io/mod.rs @@ -4,7 +4,7 @@ //! defines two traits, [`AsyncRead`] and [`AsyncWrite`], which are asynchronous //! versions of the [`Read`] and [`Write`] traits in the standard library. //! -//! # AsyncRead and AsyncWrite +//! # `AsyncRead` and `AsyncWrite` //! //! Like the standard library's [`Read`] and [`Write`] traits, [`AsyncRead`] and //! [`AsyncWrite`] provide the most general interface for reading and writing @@ -122,7 +122,7 @@ //! [`BufReader`]: crate::io::BufReader //! [`BufWriter`]: crate::io::BufWriter //! -//! ## Implementing AsyncRead and AsyncWrite +//! ## Implementing `AsyncRead` and `AsyncWrite` //! //! Because they are traits, we can implement [`AsyncRead`] and [`AsyncWrite`] for //! our own types, as well. Note that these traits must only be implemented for diff --git a/tokio/src/io/poll_evented.rs b/tokio/src/io/poll_evented.rs index 67beb5b1551..3952a31e783 100644 --- a/tokio/src/io/poll_evented.rs +++ b/tokio/src/io/poll_evented.rs @@ -47,7 +47,7 @@ cfg_io_driver! { /// This clears the readiness state until a new readiness event is received. /// /// This allows the caller to implement additional functions. For example, - /// [`TcpListener`] implements poll_accept by using [`poll_read_ready`] and + /// [`TcpListener`] implements `poll_accept` by using [`poll_read_ready`] and /// [`clear_readiness`]. /// /// ## Platform-specific events diff --git a/tokio/src/io/stdio_common.rs b/tokio/src/io/stdio_common.rs index 792b3a40002..c32b889e582 100644 --- a/tokio/src/io/stdio_common.rs +++ b/tokio/src/io/stdio_common.rs @@ -4,7 +4,7 @@ use std::pin::Pin; use std::task::{Context, Poll}; /// # Windows /// [`AsyncWrite`] adapter that finds last char boundary in given buffer and does not write the rest, -/// if buffer contents seems to be utf8. Otherwise it only trims buffer down to `MAX_BUF`. +/// if buffer contents seems to be `utf8`. Otherwise it only trims buffer down to `MAX_BUF`. /// That's why, wrapped writer will always receive well-formed utf-8 bytes. /// # Other platforms /// Passes data to `inner` as is. diff --git a/tokio/src/io/util/async_buf_read_ext.rs b/tokio/src/io/util/async_buf_read_ext.rs index 2aee3925843..92500f7f869 100644 --- a/tokio/src/io/util/async_buf_read_ext.rs +++ b/tokio/src/io/util/async_buf_read_ext.rs @@ -302,7 +302,7 @@ cfg_io_util! { /// /// The stream returned from this function will yield instances of /// [`io::Result`]`<`[`Option`]`<`[`String`]`>>`. Each string returned will *not* have a newline - /// byte (the 0xA byte) or CRLF (0xD, 0xA bytes) at the end. + /// byte (the 0xA byte) or `CRLF` (0xD, 0xA bytes) at the end. /// /// [`io::Result`]: std::io::Result /// [`Option`]: core::option::Option diff --git a/tokio/src/io/util/buf_reader.rs b/tokio/src/io/util/buf_reader.rs index 60879c0fdc2..d9307202c13 100644 --- a/tokio/src/io/util/buf_reader.rs +++ b/tokio/src/io/util/buf_reader.rs @@ -145,13 +145,13 @@ impl AsyncBufRead for BufReader { #[derive(Debug, Clone, Copy)] pub(super) enum SeekState { - /// start_seek has not been called. + /// `start_seek` has not been called. Init, - /// start_seek has been called, but poll_complete has not yet been called. + /// `start_seek` has been called, but `poll_complete` has not yet been called. Start(SeekFrom), - /// Waiting for completion of the first poll_complete in the `n.checked_sub(remainder).is_none()` branch. + /// Waiting for completion of the first `poll_complete` in the `n.checked_sub(remainder).is_none()` branch. PendingOverflowed(i64), - /// Waiting for completion of poll_complete. + /// Waiting for completion of `poll_complete`. Pending, } diff --git a/tokio/src/io/util/buf_writer.rs b/tokio/src/io/util/buf_writer.rs index 8f398fecdf9..2971a8e057a 100644 --- a/tokio/src/io/util/buf_writer.rs +++ b/tokio/src/io/util/buf_writer.rs @@ -212,11 +212,11 @@ impl AsyncWrite for BufWriter { #[derive(Debug, Clone, Copy)] pub(super) enum SeekState { - /// start_seek has not been called. + /// `start_seek` has not been called. Init, - /// start_seek has been called, but poll_complete has not yet been called. + /// `start_seek` has been called, but `poll_complete` has not yet been called. Start(SeekFrom), - /// Waiting for completion of poll_complete. + /// Waiting for completion of `poll_complete`. Pending, } diff --git a/tokio/src/io/util/read_exact.rs b/tokio/src/io/util/read_exact.rs index dbdd58bae99..217315dcb91 100644 --- a/tokio/src/io/util/read_exact.rs +++ b/tokio/src/io/util/read_exact.rs @@ -12,7 +12,7 @@ use std::task::{Context, Poll}; /// a buffer. /// /// Created by the [`AsyncReadExt::read_exact`][read_exact]. -/// [read_exact]: [crate::io::AsyncReadExt::read_exact] +/// [`read_exact`]: [`crate::io::AsyncReadExt::read_exact`] pub(crate) fn read_exact<'a, A>(reader: &'a mut A, buf: &'a mut [u8]) -> ReadExact<'a, A> where A: AsyncRead + Unpin + ?Sized, diff --git a/tokio/src/io/util/read_line.rs b/tokio/src/io/util/read_line.rs index e641f515324..eacc7d59602 100644 --- a/tokio/src/io/util/read_line.rs +++ b/tokio/src/io/util/read_line.rs @@ -51,7 +51,7 @@ fn put_back_original_data(output: &mut String, mut vector: Vec, num_bytes_re /// This handles the various failure cases and puts the string back into `output`. /// -/// The `truncate_on_io_error` bool is necessary because `read_to_string` and `read_line` +/// The `truncate_on_io_error` `bool` is necessary because `read_to_string` and `read_line` /// disagree on what should happen when an IO error occurs. pub(super) fn finish_string_read( io_res: io::Result, diff --git a/tokio/src/io/util/shutdown.rs b/tokio/src/io/util/shutdown.rs index 6d30b004b1c..fcd20dc402d 100644 --- a/tokio/src/io/util/shutdown.rs +++ b/tokio/src/io/util/shutdown.rs @@ -11,7 +11,7 @@ pin_project! { /// A future used to shutdown an I/O object. /// /// Created by the [`AsyncWriteExt::shutdown`][shutdown] function. - /// [shutdown]: crate::io::AsyncWriteExt::shutdown + /// [shutdown]: [`crate::io::AsyncWriteExt::shutdown`] #[must_use = "futures do nothing unless you `.await` or poll them"] #[derive(Debug)] pub struct Shutdown<'a, A: ?Sized> { diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs index 3a979396831..3f035098832 100644 --- a/tokio/src/lib.rs +++ b/tokio/src/lib.rs @@ -31,8 +31,8 @@ //! * APIs for [performing asynchronous I/O][io], including [TCP and UDP][net] sockets, //! [filesystem][fs] operations, and [process] and [signal] management. //! * A [runtime] for executing asynchronous code, including a task scheduler, -//! an I/O driver backed by the operating system's event queue (epoll, kqueue, -//! IOCP, etc...), and a high performance timer. +//! an I/O driver backed by the operating system's event queue (`epoll`, `kqueue`, +//! `IOCP`, etc...), and a high performance timer. //! //! Guide level documentation is found on the [website]. //! @@ -330,11 +330,11 @@ //! - `signal`: Enables all `tokio::signal` types. //! - `fs`: Enables `tokio::fs` types. //! - `test-util`: Enables testing based infrastructure for the Tokio runtime. -//! - `parking_lot`: As a potential optimization, use the _parking_lot_ crate's +//! - `parking_lot`: As a potential optimization, use the `_parking_lot_` crate's //! synchronization primitives internally. Also, this //! dependency is necessary to construct some of our primitives -//! in a const context. MSRV may increase according to the -//! _parking_lot_ release in use. +//! in a `const` context. `MSRV` may increase according to the +//! `_parking_lot_` release in use. //! //! _Note: `AsyncRead` and `AsyncWrite` traits do not require any features and are //! always available._ @@ -409,9 +409,9 @@ //! //! [mio-supported]: https://crates.io/crates/mio#platforms //! -//! ### WASM support +//! ### `WASM` support //! -//! Tokio has some limited support for the WASM platform. Without the +//! Tokio has some limited support for the `WASM` platform. Without the //! `tokio_unstable` flag, the following features are supported: //! //! * `sync` @@ -423,22 +423,22 @@ //! Enabling any other feature (including `full`) will cause a compilation //! failure. //! -//! The `time` module will only work on WASM platforms that have support for -//! timers (e.g. wasm32-wasi). The timing functions will panic if used on a WASM +//! The `time` module will only work on `WASM` platforms that have support for +//! timers (e.g. wasm32-wasi). The timing functions will panic if used on a `WASM` //! platform that does not support timers. //! //! Note also that if the runtime becomes indefinitely idle, it will panic //! immediately instead of blocking forever. On platforms that don't support //! time, this means that the runtime can never be idle in any way. //! -//! ### Unstable WASM support +//! ### Unstable `WASM` support //! -//! Tokio also has unstable support for some additional WASM features. This +//! Tokio also has unstable support for some additional `WASM` features. This //! requires the use of the `tokio_unstable` flag. //! //! Using this flag enables the use of `tokio::net` on the wasm32-wasi target. -//! However, not all methods are available on the networking types as WASI -//! currently does not support the creation of new sockets from within WASM. +//! However, not all methods are available on the networking types as `WASI` +//! currently does not support the creation of new sockets from within `WASM`. //! Because of this, sockets must currently be created via the `FromRawFd` //! trait. @@ -596,7 +596,7 @@ mod util; /// reach `std` on a stable compiler in time for the 1.0 release of Tokio. For /// this reason, the team has decided to move all `Stream` based utilities to /// the [`tokio-stream`] crate. While this is not ideal, once `Stream` has made -/// it into the standard library and the MSRV period has passed, we will implement +/// it into the standard library and the `MSRV` period has passed, we will implement /// stream for our different types. /// /// While this may seem unfortunate, not all is lost as you can get much of the @@ -689,6 +689,6 @@ cfg_macros! { #[cfg(test)] fn is_unpin() {} -/// fuzz test (fuzz_linked_list) +/// fuzz test (`fuzz_linked_list`) #[cfg(fuzzing)] pub mod fuzz; diff --git a/tokio/src/loom/std/atomic_u64.rs b/tokio/src/loom/std/atomic_u64.rs index ce391be3e11..ff6002114cd 100644 --- a/tokio/src/loom/std/atomic_u64.rs +++ b/tokio/src/loom/std/atomic_u64.rs @@ -1,4 +1,4 @@ -//! Implementation of an atomic u64 cell. On 64 bit platforms, this is a +//! Implementation of an atomic `u64` cell. On 64 bit platforms, this is a //! re-export of `AtomicU64`. On 32 bit platforms, this is implemented using a //! `Mutex`. diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs index 5f0c6638857..d2f7b42bf60 100644 --- a/tokio/src/macros/cfg.rs +++ b/tokio/src/macros/cfg.rs @@ -49,7 +49,7 @@ macro_rules! cfg_unstable_windows { } } -/// Enables enter::block_on. +/// Enables `enter::block_on`. macro_rules! cfg_block_on { ($($item:item)*) => { $( diff --git a/tokio/src/macros/try_join.rs b/tokio/src/macros/try_join.rs index 7b123709231..a72cdb4a87a 100644 --- a/tokio/src/macros/try_join.rs +++ b/tokio/src/macros/try_join.rs @@ -30,7 +30,7 @@ /// /// # Examples /// -/// Basic try_join with two branches. +/// Basic `try_join` with two branches. /// /// ``` /// async fn do_stuff_async() -> Result<(), &'static str> { diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs index f1befac26dc..3f6592abe19 100644 --- a/tokio/src/net/tcp/listener.rs +++ b/tokio/src/net/tcp/listener.rs @@ -58,7 +58,7 @@ cfg_net! { impl TcpListener { cfg_not_wasi! { - /// Creates a new TcpListener, which will be bound to the specified address. + /// Creates a new `TcpListener`, which will be bound to the specified address. /// /// The returned listener is ready for accepting connections. /// diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index 9b604b339f3..e20473e5cc3 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -1060,7 +1060,7 @@ impl TcpStream { /// returns the number of bytes peeked. /// /// Successive calls return the same data. This is accomplished by passing - /// `MSG_PEEK` as a flag to the underlying recv system call. + /// `MSG_PEEK` as a flag to the underlying `recv` system call. /// /// # Examples /// @@ -1178,13 +1178,13 @@ impl TcpStream { socket2::SockRef::from(self).linger() } - /// Sets the linger duration of this socket by setting the SO_LINGER option. + /// Sets the linger duration of this socket by setting the `SO_LINGER` option. /// /// This option controls the action taken when a stream has unsent messages and the stream is - /// closed. If SO_LINGER is set, the system shall block the process until it can transmit the + /// closed. If `SO_LINGER` is set, the system shall block the process until it can transmit the /// data or until the time expires. /// - /// If SO_LINGER is not specified, and the stream is closed, the system handles the call in a + /// If `SO_LINGER` is not specified, and the stream is closed, the system handles the call in a /// way that allows the process to continue as quickly as possible. /// /// # Examples diff --git a/tokio/src/net/udp.rs b/tokio/src/net/udp.rs index 74ea41d8378..4e2c140a856 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -180,7 +180,7 @@ impl UdpSocket { /// This function is intended to be used to wrap a UDP socket from the /// standard library in the Tokio equivalent. /// - /// This can be used in conjunction with socket2's `Socket` interface to + /// This can be used in conjunction with `socket2`'s `Socket` interface to /// configure a socket before it's handed off, such as setting options like /// `reuse_address` or binding to multiple addresses. /// @@ -313,7 +313,7 @@ impl UdpSocket { } /// Connects the UDP socket setting the default destination for send() and - /// limiting packets that are read via recv from the address specified in + /// limiting packets that are read via `recv` from the address specified in /// `addr`. /// /// # Example @@ -358,7 +358,7 @@ impl UdpSocket { /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_recv()` or `try_send()`. It - /// can be used to concurrently recv / send to the same socket on a single + /// can be used to concurrently `recv` / `send` to the same socket on a single /// task without splitting the socket. /// /// The function may complete without the socket being ready. This is a @@ -786,7 +786,7 @@ impl UdpSocket { /// The [`connect`] method will connect this socket to a remote address. This method /// resolves to an error if the socket is not connected. /// - /// Note that on multiple calls to a `poll_*` method in the recv direction, only the + /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the /// `Waker` from the `Context` passed to the most recent call will be scheduled to /// receive a wakeup. /// @@ -825,7 +825,7 @@ impl UdpSocket { /// address to which it is connected. On success, returns the number of /// bytes read. /// - /// This method must be called with valid byte array buf of sufficient size + /// This method must be called with valid byte array `buf` of sufficient size /// to hold the message bytes. If a message is too long to fit in the /// supplied buffer, excess bytes may be discarded. /// @@ -881,7 +881,7 @@ impl UdpSocket { /// Tries to receive data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// - /// This method must be called with valid byte array buf of sufficient size + /// This method must be called with valid byte array `buf` of sufficient size /// to hold the message bytes. If a message is too long to fit in the /// supplied buffer, excess bytes may be discarded. /// @@ -949,7 +949,7 @@ impl UdpSocket { /// to which it is connected, advancing the buffer's internal cursor, /// returning how many bytes were read. /// - /// This method must be called with valid byte array buf of sufficient size + /// This method must be called with valid byte array `buf` of sufficient size /// to hold the message bytes. If a message is too long to fit in the /// supplied buffer, excess bytes may be discarded. /// @@ -996,7 +996,7 @@ impl UdpSocket { /// Tries to receive a single datagram message on the socket. On success, /// returns the number of bytes read and the origin. /// - /// This method must be called with valid byte array buf of sufficient size + /// This method must be called with valid byte array `buf` of sufficient size /// to hold the message bytes. If a message is too long to fit in the /// supplied buffer, excess bytes may be discarded. /// @@ -1071,7 +1071,7 @@ impl UdpSocket { /// Receives a single datagram message on the socket, advancing the /// buffer's internal cursor, returning how many bytes were read and the origin. /// - /// This method must be called with valid byte array buf of sufficient size + /// This method must be called with valid byte array `buf` of sufficient size /// to hold the message bytes. If a message is too long to fit in the /// supplied buffer, excess bytes may be discarded. /// @@ -1311,7 +1311,7 @@ impl UdpSocket { /// Attempts to receive a single datagram on the socket. /// - /// Note that on multiple calls to a `poll_*` method in the recv direction, only the + /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the /// `Waker` from the `Context` passed to the most recent call will be scheduled to /// receive a wakeup. /// @@ -1360,7 +1360,7 @@ impl UdpSocket { /// Tries to receive a single datagram message on the socket. On success, /// returns the number of bytes read and the origin. /// - /// This method must be called with valid byte array buf of sufficient size + /// This method must be called with valid byte array `buf` of sufficient size /// to hold the message bytes. If a message is too long to fit in the /// supplied buffer, excess bytes may be discarded. /// @@ -1507,7 +1507,7 @@ impl UdpSocket { /// /// On Windows, if the data is larger than the buffer specified, the buffer /// is filled with the first part of the data, and `peek_from` returns the error - /// WSAEMSGSIZE(10040). The excess data is lost. + /// `WSAEMSGSIZE(10040)`. The excess data is lost. /// Make sure to always use a sufficiently large buffer to hold the /// maximum UDP packet size, which can be up to 65536 bytes in size. /// @@ -1555,13 +1555,13 @@ impl UdpSocket { /// /// # Notes /// - /// Note that on multiple calls to a `poll_*` method in the recv direction, only the + /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the /// `Waker` from the `Context` passed to the most recent call will be scheduled to /// receive a wakeup /// /// On Windows, if the data is larger than the buffer specified, the buffer /// is filled with the first part of the data, and peek returns the error - /// WSAEMSGSIZE(10040). The excess data is lost. + /// `WSAEMSGSIZE(10040)`. The excess data is lost. /// Make sure to always use a sufficiently large buffer to hold the /// maximum UDP packet size, which can be up to 65536 bytes in size. /// @@ -1623,7 +1623,7 @@ impl UdpSocket { /// /// On Windows, if the data is larger than the buffer specified, the buffer /// is filled with the first part of the data, and peek returns the error - /// WSAEMSGSIZE(10040). The excess data is lost. + /// `WSAEMSGSIZE(10040)`. The excess data is lost. /// Make sure to always use a sufficiently large buffer to hold the /// maximum UDP packet size, which can be up to 65536 bytes in size. /// @@ -1674,7 +1674,7 @@ impl UdpSocket { /// /// # Notes /// - /// Note that on multiple calls to a `poll_*` method in the recv direction, only the + /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the /// `Waker` from the `Context` passed to the most recent call will be scheduled to /// receive a wakeup. /// diff --git a/tokio/src/net/unix/datagram/socket.rs b/tokio/src/net/unix/datagram/socket.rs index bec4bf983d5..0da20f81f53 100644 --- a/tokio/src/net/unix/datagram/socket.rs +++ b/tokio/src/net/unix/datagram/socket.rs @@ -109,7 +109,7 @@ impl UnixDatagram { /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_recv()` or `try_send()`. It - /// can be used to concurrently recv / send to the same socket on a single + /// can be used to concurrently `recv` / `send` to the same socket on a single /// task without splitting the socket. /// /// The function may complete without the socket being ready. This is a @@ -435,12 +435,12 @@ impl UnixDatagram { /// Creates new [`UnixDatagram`] from a [`std::os::unix::net::UnixDatagram`]. /// - /// This function is intended to be used to wrap a UnixDatagram from the + /// This function is intended to be used to wrap a `UnixDatagram` from the /// standard library in the Tokio equivalent. /// /// # Notes /// - /// The caller is responsible for ensuring that the socker is in + /// The caller is responsible for ensuring that the socket is in /// non-blocking mode. Otherwise all I/O operations on the socket /// will block the thread, which will cause unexpected behavior. /// Non-blocking mode can be set using [`set_nonblocking`]. @@ -1141,7 +1141,7 @@ impl UnixDatagram { /// Attempts to receive a single datagram on the specified address. /// - /// Note that on multiple calls to a `poll_*` method in the recv direction, only the + /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the /// `Waker` from the `Context` passed to the most recent call will be scheduled to /// receive a wakeup. /// @@ -1244,7 +1244,7 @@ impl UnixDatagram { /// The [`connect`] method will connect this socket to a remote address. This method /// resolves to an error if the socket is not connected. /// - /// Note that on multiple calls to a `poll_*` method in the recv direction, only the + /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the /// `Waker` from the `Context` passed to the most recent call will be scheduled to /// receive a wakeup. /// diff --git a/tokio/src/net/unix/listener.rs b/tokio/src/net/unix/listener.rs index bc7b53b3b53..79b554ee1ab 100644 --- a/tokio/src/net/unix/listener.rs +++ b/tokio/src/net/unix/listener.rs @@ -77,7 +77,7 @@ impl UnixListener { /// Creates new [`UnixListener`] from a [`std::os::unix::net::UnixListener`]. /// - /// This function is intended to be used to wrap a UnixListener from the + /// This function is intended to be used to wrap a `UnixListener` from the /// standard library in the Tokio equivalent. /// /// # Notes diff --git a/tokio/src/net/unix/stream.rs b/tokio/src/net/unix/stream.rs index e1a4ff437f7..60d58139699 100644 --- a/tokio/src/net/unix/stream.rs +++ b/tokio/src/net/unix/stream.rs @@ -762,7 +762,7 @@ impl UnixStream { /// Creates new [`UnixStream`] from a [`std::os::unix::net::UnixStream`]. /// - /// This function is intended to be used to wrap a UnixStream from the + /// This function is intended to be used to wrap a `UnixStream` from the /// standard library in the Tokio equivalent. /// /// # Notes diff --git a/tokio/src/net/windows/named_pipe.rs b/tokio/src/net/windows/named_pipe.rs index a03e1d0acd1..98e63f0c450 100644 --- a/tokio/src/net/windows/named_pipe.rs +++ b/tokio/src/net/windows/named_pipe.rs @@ -2059,7 +2059,7 @@ impl ServerOptions { /// /// ``` /// use std::{io, os::windows::prelude::AsRawHandle, ptr}; - // + /// /// use tokio::net::windows::named_pipe::ServerOptions; /// use windows_sys::{ /// Win32::Foundation::ERROR_SUCCESS, @@ -2094,7 +2094,7 @@ impl ServerOptions { /// /// ``` /// use std::{io, os::windows::prelude::AsRawHandle, ptr}; - // + /// /// use tokio::net::windows::named_pipe::ServerOptions; /// use windows_sys::{ /// Win32::Foundation::ERROR_ACCESS_DENIED, diff --git a/tokio/src/process/mod.rs b/tokio/src/process/mod.rs index a688f63f213..0fad67cd01a 100644 --- a/tokio/src/process/mod.rs +++ b/tokio/src/process/mod.rs @@ -739,12 +739,12 @@ impl Command { } /// Sets the process group ID (PGID) of the child process. Equivalent to a - /// setpgid call in the child process, but may be more efficient. + /// `setpgid` call in the child process, but may be more efficient. /// /// Process groups determine which processes receive signals. /// /// **Note**: This is an [unstable API][unstable] but will be stabilised once - /// tokio's MSRV is sufficiently new. See [the documentation on + /// tokio's `MSRV` is sufficiently new. See [the documentation on /// unstable features][unstable] for details about using unstable features. /// /// If you want similar behavior without using this unstable feature you can @@ -1109,7 +1109,7 @@ impl Child { /// Attempts to force the child to exit, but does not wait for the request /// to take effect. /// - /// On Unix platforms, this is the equivalent to sending a SIGKILL. Note + /// On Unix platforms, this is the equivalent to sending a `SIGKILL`. Note /// that on Unix platforms it is possible for a zombie process to remain /// after a kill is sent; to avoid this, the caller should ensure that either /// `child.wait().await` or `child.try_wait()` is invoked successfully. @@ -1125,12 +1125,12 @@ impl Child { /// Forces the child to exit. /// - /// This is equivalent to sending a SIGKILL on unix platforms. + /// This is equivalent to sending a `SIGKILL` on unix platforms. /// /// If the child has to be killed remotely, it is possible to do it using - /// a combination of the select! macro and a oneshot channel. In the following + /// a combination of the select! macro and a `oneshot` channel. In the following /// example, the child will run until completion unless a message is sent on - /// the oneshot channel. If that happens, the child is killed immediately + /// the `oneshot` channel. If that happens, the child is killed immediately /// using the `.kill()` method. /// /// ```no_run diff --git a/tokio/src/runtime/blocking/pool.rs b/tokio/src/runtime/blocking/pool.rs index 3b6de8d7917..c74aea76568 100644 --- a/tokio/src/runtime/blocking/pool.rs +++ b/tokio/src/runtime/blocking/pool.rs @@ -105,16 +105,16 @@ struct Shared { num_notify: u32, shutdown: bool, shutdown_tx: Option, - /// Prior to shutdown, we clean up JoinHandles by having each timed-out + /// Prior to shutdown, we clean up `JoinHandles` by having each timed-out /// thread join on the previous timed-out thread. This is not strictly /// necessary but helps avoid Valgrind false positives, see /// /// for more information. last_exiting_thread: Option>, - /// This holds the JoinHandles for all running threads; on shutdown, the thread + /// This holds the `JoinHandles` for all running threads; on shutdown, the thread /// calling shutdown handles joining on these. worker_threads: HashMap>, - /// This is a counter used to iterate worker_threads in a consistent order (for loom's + /// This is a counter used to iterate `worker_threads` in a consistent order (for loom's /// benefit). worker_thread_index: usize, } diff --git a/tokio/src/runtime/builder.rs b/tokio/src/runtime/builder.rs index 78e6bf50d62..e20a3c4955b 100644 --- a/tokio/src/runtime/builder.rs +++ b/tokio/src/runtime/builder.rs @@ -78,7 +78,7 @@ pub struct Builder { /// To run after each thread is unparked. pub(super) after_unpark: Option, - /// Customizable keep alive timeout for BlockingPool + /// Customizable keep alive timeout for `BlockingPool` pub(super) keep_alive: Option, /// How many ticks before pulling a task from the global/remote queue? @@ -723,7 +723,7 @@ impl Builder { /// Sets a custom timeout for a thread in the blocking pool. /// /// By default, the timeout for a thread is set to 10 seconds. This can - /// be overridden using .thread_keep_alive(). + /// be overridden using `.thread_keep_alive()`. /// /// # Example /// diff --git a/tokio/src/runtime/context.rs b/tokio/src/runtime/context.rs index 07875a0723f..62e4fc9474c 100644 --- a/tokio/src/runtime/context.rs +++ b/tokio/src/runtime/context.rs @@ -61,7 +61,7 @@ struct Context { rng: Cell>, /// Tracks the amount of "work" a task may still do before yielding back to - /// the sheduler + /// the scheduler budget: Cell, #[cfg(all( diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs index 4a833539f38..7e7e5636c80 100644 --- a/tokio/src/runtime/handle.rs +++ b/tokio/src/runtime/handle.rs @@ -463,7 +463,7 @@ cfg_taskdump! { /// ## Debug Info Must Be Available /// /// To produce task traces, the application must **not** be compiled - /// with split debuginfo. On Linux, including debuginfo within the + /// with `split debuginfo`. On Linux, including `debuginfo` within the /// application binary is the (correct) default. You can further ensure /// this behavior with the following directive in your `Cargo.toml`: /// @@ -475,7 +475,7 @@ cfg_taskdump! { /// ## Unstable Features /// /// This functionality is **unstable**, and requires both the - /// `tokio_unstable` and `tokio_taskdump` cfg flags to be set. + /// `tokio_unstable` and `tokio_taskdump` `cfg` flags to be set. /// /// You can do this by setting the `RUSTFLAGS` environment variable /// before invoking `cargo`; e.g.: @@ -495,7 +495,7 @@ cfg_taskdump! { /// /// ## Platform Requirements /// - /// Task dumps are supported on Linux atop aarch64, x86 and x86_64. + /// Task dumps are supported on Linux atop `aarch64`, `x86` and `x86_64`. /// /// ## Current Thread Runtime Requirements /// diff --git a/tokio/src/runtime/io/driver.rs b/tokio/src/runtime/io/driver.rs index c34a2ac060a..bece3560b72 100644 --- a/tokio/src/runtime/io/driver.rs +++ b/tokio/src/runtime/io/driver.rs @@ -40,7 +40,7 @@ pub(crate) struct Handle { synced: Mutex, /// Used to wake up the reactor from a call to `turn`. - /// Not supported on Wasi due to lack of threading support. + /// Not supported on `Wasi` due to lack of threading support. #[cfg(not(target_os = "wasi"))] waker: mio::Waker, diff --git a/tokio/src/runtime/io/scheduled_io.rs b/tokio/src/runtime/io/scheduled_io.rs index c214beff039..527bb9808de 100644 --- a/tokio/src/runtime/io/scheduled_io.rs +++ b/tokio/src/runtime/io/scheduled_io.rs @@ -114,10 +114,10 @@ struct Waiters { /// List of all current waiters. list: WaitList, - /// Waker used for AsyncRead. + /// Waker used for `AsyncRead`. reader: Option, - /// Waker used for AsyncWrite. + /// Waker used for `AsyncWrite`. writer: Option, } @@ -191,7 +191,7 @@ impl ScheduledIo { mio::Token(self as *const _ as usize) } - /// Invoked when the IO driver is shut down; forces this ScheduledIo into a + /// Invoked when the IO driver is shut down; forces this `ScheduledIo` into a /// permanently shutdown state. pub(super) fn shutdown(&self) { let mask = SHUTDOWN.pack(1, 0); diff --git a/tokio/src/runtime/scheduler/multi_thread/park.rs b/tokio/src/runtime/scheduler/multi_thread/park.rs index 87be200a12d..bc369387395 100644 --- a/tokio/src/runtime/scheduler/multi_thread/park.rs +++ b/tokio/src/runtime/scheduler/multi_thread/park.rs @@ -22,10 +22,10 @@ struct Inner { /// Avoids entering the park if possible state: AtomicUsize, - /// Used to coordinate access to the driver / condvar + /// Used to coordinate access to the driver / `condvar` mutex: Mutex<()>, - /// Condvar to block on if the driver is unavailable. + /// `Condvar` to block on if the driver is unavailable. condvar: Condvar, /// Resource (I/O, time, ...) driver diff --git a/tokio/src/runtime/scheduler/multi_thread/queue.rs b/tokio/src/runtime/scheduler/multi_thread/queue.rs index e3a3105bbb6..35223289870 100644 --- a/tokio/src/runtime/scheduler/multi_thread/queue.rs +++ b/tokio/src/runtime/scheduler/multi_thread/queue.rs @@ -36,8 +36,8 @@ pub(crate) struct Steal(Arc>); pub(crate) struct Inner { /// Concurrently updated by many threads. /// - /// Contains two `UnsignedShort` values. The LSB byte is the "real" head of - /// the queue. The `UnsignedShort` in the MSB is set by a stealer in process + /// Contains two `UnsignedShort` values. The `LSB` byte is the "real" head of + /// the queue. The `UnsignedShort` in the `MSB` is set by a stealer in process /// of stealing values. It represents the first value being stolen in the /// batch. The `UnsignedShort` indices are intentionally wider than strictly /// required for buffer indexing in order to provide ABA mitigation and make diff --git a/tokio/src/runtime/scheduler/multi_thread/stats.rs b/tokio/src/runtime/scheduler/multi_thread/stats.rs index 3b8c5020e49..30c108c9dd6 100644 --- a/tokio/src/runtime/scheduler/multi_thread/stats.rs +++ b/tokio/src/runtime/scheduler/multi_thread/stats.rs @@ -22,7 +22,7 @@ pub(crate) struct Stats { /// Exponentially-weighted moving average of time spent polling scheduled a /// task. /// - /// Tracked in nanoseconds, stored as a f64 since that is what we use with + /// Tracked in nanoseconds, stored as a `f64` since that is what we use with /// the EWMA calculations task_poll_time_ewma: f64, } diff --git a/tokio/src/runtime/scheduler/multi_thread/worker.rs b/tokio/src/runtime/scheduler/multi_thread/worker.rs index 313e2ea68f7..9998870ab4d 100644 --- a/tokio/src/runtime/scheduler/multi_thread/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread/worker.rs @@ -9,19 +9,19 @@ //! Shutting down the runtime involves the following steps: //! //! 1. The Shared::close method is called. This closes the inject queue and -//! OwnedTasks instance and wakes up all worker threads. +//! `OwnedTasks` instance and wakes up all worker threads. //! //! 2. Each worker thread observes the close signal next time it runs //! Core::maintenance by checking whether the inject queue is closed. -//! The Core::is_shutdown flag is set to true. +//! The `Core::is_shutdown` flag is set to true. //! //! 3. The worker thread calls `pre_shutdown` in parallel. Here, the worker -//! will keep removing tasks from OwnedTasks until it is empty. No new -//! tasks can be pushed to the OwnedTasks during or after this step as it +//! will keep removing tasks from `OwnedTasks` until it is empty. No new +//! tasks can be pushed to the `OwnedTasks` during or after this step as it //! was closed in step 1. //! //! 5. The workers call Shared::shutdown to enter the single-threaded phase of -//! shutdown. These calls will push their core to Shared::shutdown_cores, +//! shutdown. These calls will push their core to `Shared::shutdown_cores`, //! and the last thread to push its core will finish the shutdown procedure. //! //! 6. The local run queue of each core is emptied, then the inject queue is @@ -35,22 +35,22 @@ //! //! When spawning tasks during shutdown, there are two cases: //! -//! * The spawner observes the OwnedTasks being open, and the inject queue is +//! * The spawner observes the `OwnedTasks` being open, and the inject queue is //! closed. -//! * The spawner observes the OwnedTasks being closed and doesn't check the +//! * The spawner observes the `OwnedTasks` being closed and doesn't check the //! inject queue. //! -//! The first case can only happen if the OwnedTasks::bind call happens before +//! The first case can only happen if the `OwnedTasks::bind` call happens before //! or during step 1 of shutdown. In this case, the runtime will clean up the //! task in step 3 of shutdown. //! //! In the latter case, the task was not spawned and the task is immediately //! cancelled by the spawner. //! -//! The correctness of shutdown requires both the inject queue and OwnedTasks +//! The correctness of shutdown requires both the inject queue and `OwnedTasks` //! collection to have a closed bit. With a close bit on only the inject queue, //! spawning could run in to a situation where a task is successfully bound long -//! after the runtime has shut down. With a close bit on only the OwnedTasks, +//! after the runtime has shut down. With a close bit on only the `OwnedTasks`, //! the first spawning situation could result in the notification being pushed //! to the inject queue after step 6 of shutdown, which would leave a task in //! the inject queue indefinitely. This would be a ref-count cycle and a memory @@ -184,7 +184,7 @@ pub(crate) struct Shared { /// Only held to trigger some code on drop. This is used to get internal /// runtime metrics that can be useful when doing performance /// investigations. This does nothing (empty struct, no drop impl) unless - /// the `tokio_internal_mt_counters` cfg flag is set. + /// the `tokio_internal_mt_counters` `cfg` flag is set. _counters: Counters, } @@ -234,7 +234,7 @@ type Task = task::Task>; type Notified = task::Notified>; /// Value picked out of thin-air. Running the LIFO slot a handful of times -/// seemms sufficient to benefit from locality. More than 3 times probably is +/// seems sufficient to benefit from locality. More than 3 times probably is /// overweighing. The value can be tuned in the future with data that shows /// improvements. const MAX_LIFO_POLLS_PER_TICK: usize = 3; @@ -677,7 +677,7 @@ impl Context { /// Also important to notice that, before parking, the worker thread will try to take /// ownership of the Driver (IO/Time) and dispatch any events that might have fired. /// Whenever a worker thread executes the Driver loop, all waken tasks are scheduled - /// in its own local queue until the queue saturates (ntasks > LOCAL_QUEUE_CAPACITY). + /// in its own local queue until the queue saturates (ntasks > `LOCAL_QUEUE_CAPACITY`). /// When the local queue is saturated, the overflow tasks are added to the injection queue /// from where other workers can pick them up. /// Also, we rely on the workstealing algorithm to spread the tasks amongst workers diff --git a/tokio/src/runtime/scheduler/multi_thread_alt/queue.rs b/tokio/src/runtime/scheduler/multi_thread_alt/queue.rs index 004715daec8..2694d27cbdf 100644 --- a/tokio/src/runtime/scheduler/multi_thread_alt/queue.rs +++ b/tokio/src/runtime/scheduler/multi_thread_alt/queue.rs @@ -37,8 +37,8 @@ pub(crate) struct Steal(Arc>); pub(crate) struct Inner { /// Concurrently updated by many threads. /// - /// Contains two `UnsignedShort` values. The LSB byte is the "real" head of - /// the queue. The `UnsignedShort` in the MSB is set by a stealer in process + /// Contains two `UnsignedShort` values. The `LSB` byte is the "real" head of + /// the queue. The `UnsignedShort` in the `MSB` is set by a stealer in process /// of stealing values. It represents the first value being stolen in the /// batch. The `UnsignedShort` indices are intentionally wider than strictly /// required for buffer indexing in order to provide ABA mitigation and make diff --git a/tokio/src/runtime/scheduler/multi_thread_alt/stats.rs b/tokio/src/runtime/scheduler/multi_thread_alt/stats.rs index 228e797714b..7118e4915a0 100644 --- a/tokio/src/runtime/scheduler/multi_thread_alt/stats.rs +++ b/tokio/src/runtime/scheduler/multi_thread_alt/stats.rs @@ -13,7 +13,7 @@ pub(crate) struct Stats { /// Exponentially-weighted moving average of time spent polling scheduled a /// task. /// - /// Tracked in nanoseconds, stored as a f64 since that is what we use with + /// Tracked in nanoseconds, stored as a `f64` since that is what we use with /// the EWMA calculations task_poll_time_ewma: f64, } diff --git a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs index 8d16418a80b..54c6b0ed7ba 100644 --- a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs @@ -9,19 +9,19 @@ //! Shutting down the runtime involves the following steps: //! //! 1. The Shared::close method is called. This closes the inject queue and -//! OwnedTasks instance and wakes up all worker threads. +//! `OwnedTasks` instance and wakes up all worker threads. //! //! 2. Each worker thread observes the close signal next time it runs //! Core::maintenance by checking whether the inject queue is closed. -//! The Core::is_shutdown flag is set to true. +//! The `Core::is_shutdown` flag is set to true. //! //! 3. The worker thread calls `pre_shutdown` in parallel. Here, the worker -//! will keep removing tasks from OwnedTasks until it is empty. No new -//! tasks can be pushed to the OwnedTasks during or after this step as it +//! will keep removing tasks from `OwnedTasks` until it is empty. No new +//! tasks can be pushed to the `OwnedTasks` during or after this step as it //! was closed in step 1. //! //! 5. The workers call Shared::shutdown to enter the single-threaded phase of -//! shutdown. These calls will push their core to Shared::shutdown_cores, +//! shutdown. These calls will push their core to `Shared::shutdown_cores`, //! and the last thread to push its core will finish the shutdown procedure. //! //! 6. The local run queue of each core is emptied, then the inject queue is @@ -35,22 +35,22 @@ //! //! When spawning tasks during shutdown, there are two cases: //! -//! * The spawner observes the OwnedTasks being open, and the inject queue is +//! * The spawner observes the `OwnedTasks` being open, and the inject queue is //! closed. -//! * The spawner observes the OwnedTasks being closed and doesn't check the +//! * The spawner observes the `OwnedTasks` being closed and doesn't check the //! inject queue. //! -//! The first case can only happen if the OwnedTasks::bind call happens before +//! The first case can only happen if the `OwnedTasks::bind` call happens before //! or during step 1 of shutdown. In this case, the runtime will clean up the //! task in step 3 of shutdown. //! //! In the latter case, the task was not spawned and the task is immediately //! cancelled by the spawner. //! -//! The correctness of shutdown requires both the inject queue and OwnedTasks +//! The correctness of shutdown requires both the inject queue and `OwnedTasks` //! collection to have a closed bit. With a close bit on only the inject queue, //! spawning could run in to a situation where a task is successfully bound long -//! after the runtime has shut down. With a close bit on only the OwnedTasks, +//! after the runtime has shut down. With a close bit on only the `OwnedTasks`, //! the first spawning situation could result in the notification being pushed //! to the inject queue after step 6 of shutdown, which would leave a task in //! the inject queue indefinitely. This would be a ref-count cycle and a memory @@ -157,7 +157,7 @@ pub(crate) struct Shared { driver: AtomicCell, /// Condition variables used to unblock worker threads. Each worker thread - /// has its own condvar it waits on. + /// has its own `condvar` it waits on. pub(super) condvars: Vec, /// The number of cores that have observed the trace signal. @@ -174,7 +174,7 @@ pub(crate) struct Shared { /// Only held to trigger some code on drop. This is used to get internal /// runtime metrics that can be useful when doing performance /// investigations. This does nothing (empty struct, no drop impl) unless - /// the `tokio_internal_mt_counters` cfg flag is set. + /// the `tokio_internal_mt_counters` `cfg` flag is set. _counters: Counters, } @@ -248,7 +248,7 @@ type Task = task::Task>; type Notified = task::Notified>; /// Value picked out of thin-air. Running the LIFO slot a handful of times -/// seemms sufficient to benefit from locality. More than 3 times probably is +/// seems sufficient to benefit from locality. More than 3 times probably is /// overweighing. The value can be tuned in the future with data that shows /// improvements. const MAX_LIFO_POLLS_PER_TICK: usize = 3; diff --git a/tokio/src/runtime/task/core.rs b/tokio/src/runtime/task/core.rs index e61bbe5061d..108b06bc8b6 100644 --- a/tokio/src/runtime/task/core.rs +++ b/tokio/src/runtime/task/core.rs @@ -28,7 +28,7 @@ use std::task::{Context, Poll, Waker}; /// be referenced by both *mut Cell and *mut Header. /// /// Any changes to the layout of this struct _must_ also be reflected in the -/// const fns in raw.rs. +/// `const` fns in raw.rs. /// // # This struct should be cache padded to avoid false sharing. The cache padding rules are copied // from crossbeam-utils/src/cache_padded.rs @@ -132,7 +132,7 @@ pub(super) struct CoreStage { /// Holds the future or output, depending on the stage of execution. /// /// Any changes to the layout of this struct _must_ also be reflected in the -/// const fns in raw.rs. +/// `const` fns in raw.rs. #[repr(C)] pub(super) struct Core { /// Scheduler used to drive this future. diff --git a/tokio/src/runtime/task/harness.rs b/tokio/src/runtime/task/harness.rs index 8bfd57e6fbf..cf19eea83bb 100644 --- a/tokio/src/runtime/task/harness.rs +++ b/tokio/src/runtime/task/harness.rs @@ -183,7 +183,7 @@ where /// If the return value is Complete, the caller is given ownership of a /// single ref-count, which should be passed on to `complete`. /// - /// If the return value is Dealloc, then this call consumed the last + /// If the return value is `Dealloc`, then this call consumed the last /// ref-count and the caller should call `dealloc`. /// /// Otherwise the ref-count is consumed and the caller should not access diff --git a/tokio/src/runtime/task/join.rs b/tokio/src/runtime/task/join.rs index 818d3c21dd5..19289cf5826 100644 --- a/tokio/src/runtime/task/join.rs +++ b/tokio/src/runtime/task/join.rs @@ -58,7 +58,7 @@ cfg_rt! { /// ``` /// /// The generic parameter `T` in `JoinHandle` is the return type of the spawned task. - /// If the return value is an i32, the join handle has type `JoinHandle`: + /// If the return value is an `i32`, the join handle has type `JoinHandle`: /// /// ``` /// use tokio::task; diff --git a/tokio/src/runtime/task/list.rs b/tokio/src/runtime/task/list.rs index 3d2a121cf1d..41a5fb439c9 100644 --- a/tokio/src/runtime/task/list.rs +++ b/tokio/src/runtime/task/list.rs @@ -84,8 +84,8 @@ impl OwnedTasks { } } - /// Binds the provided task to this OwnedTasks instance. This fails if the - /// OwnedTasks has been closed. + /// Binds the provided task to this `OwnedTasks` instance. This fails if the + /// `OwnedTasks` has been closed. pub(crate) fn bind( &self, task: T, @@ -125,8 +125,8 @@ impl OwnedTasks { Some(notified) } - /// Asserts that the given task is owned by this OwnedTasks and convert it to - /// a LocalNotified, giving the thread permission to poll this task. + /// Asserts that the given task is owned by this `OwnedTasks` and convert it to + /// a `LocalNotified`, giving the thread permission to poll this task. #[inline] pub(crate) fn assert_owner(&self, task: Notified) -> LocalNotified { debug_assert_eq!(task.header().get_owner_id(), Some(self.id)); @@ -284,8 +284,8 @@ impl LocalOwnedTasks { unsafe { inner.list.remove(task.header_ptr()) }) } - /// Asserts that the given task is owned by this LocalOwnedTasks and convert - /// it to a LocalNotified, giving the thread permission to poll this task. + /// Asserts that the given task is owned by this `LocalOwnedTasks` and convert + /// it to a `LocalNotified`, giving the thread permission to poll this task. #[inline] pub(crate) fn assert_owner(&self, task: Notified) -> LocalNotified { assert_eq!(task.header().get_owner_id(), Some(self.id)); diff --git a/tokio/src/runtime/task/mod.rs b/tokio/src/runtime/task/mod.rs index 0bd40cd875c..6b05f4d7d5c 100644 --- a/tokio/src/runtime/task/mod.rs +++ b/tokio/src/runtime/task/mod.rs @@ -2,52 +2,52 @@ //! //! The task module contains the code that manages spawned tasks and provides a //! safe API for the rest of the runtime to use. Each task in a runtime is -//! stored in an OwnedTasks or LocalOwnedTasks object. +//! stored in an `OwnedTasks` or `LocalOwnedTasks` object. //! //! # Task reference types //! //! A task is usually referenced by multiple handles, and there are several //! types of handles. //! -//! * OwnedTask - tasks stored in an OwnedTasks or LocalOwnedTasks are of this +//! * `OwnedTask` - tasks stored in an `OwnedTasks` or `LocalOwnedTasks` are of this //! reference type. //! -//! * JoinHandle - each task has a JoinHandle that allows access to the output +//! * `JoinHandle` - each task has a `JoinHandle` that allows access to the output //! of the task. //! -//! * Waker - every waker for a task has this reference type. There can be any +//! * `Waker` - every waker for a task has this reference type. There can be any //! number of waker references. //! -//! * Notified - tracks whether the task is notified. +//! * `Notified` - tracks whether the task is notified. //! -//! * Unowned - this task reference type is used for tasks not stored in any +//! * `Unowned` - this task reference type is used for tasks not stored in any //! runtime. Mainly used for blocking tasks, but also in tests. //! //! The task uses a reference count to keep track of how many active references -//! exist. The Unowned reference type takes up two ref-counts. All other +//! exist. The `Unowned` reference type takes up two ref-counts. All other //! reference types take up a single ref-count. //! //! Besides the waker type, each task has at most one of each reference type. //! //! # State //! -//! The task stores its state in an atomic usize with various bitfields for the +//! The task stores its state in an atomic `usize` with various bitfields for the //! necessary information. The state has the following bitfields: //! -//! * RUNNING - Tracks whether the task is currently being polled or cancelled. +//! * `RUNNING` - Tracks whether the task is currently being polled or cancelled. //! This bit functions as a lock around the task. //! -//! * COMPLETE - Is one once the future has fully completed and has been +//! * `COMPLETE` - Is one once the future has fully completed and has been //! dropped. Never unset once set. Never set together with RUNNING. //! -//! * NOTIFIED - Tracks whether a Notified object currently exists. +//! * `NOTIFIED` - Tracks whether a Notified object currently exists. //! -//! * CANCELLED - Is set to one for tasks that should be cancelled as soon as +//! * `CANCELLED` - Is set to one for tasks that should be cancelled as soon as //! possible. May take any value for completed tasks. //! -//! * JOIN_INTEREST - Is set to one if there exists a JoinHandle. +//! * `JOIN_INTEREST` - Is set to one if there exists a `JoinHandle`. //! -//! * JOIN_WAKER - Acts as an access control bit for the join handle waker. The +//! * `JOIN_WAKER` - Acts as an access control bit for the join handle waker. The //! protocol for its usage is described below. //! //! The rest of the bits are used for the ref-count. @@ -59,7 +59,7 @@ //! //! * The state field is accessed with atomic instructions. //! -//! * The OwnedTask reference has exclusive access to the `owned` field. +//! * The `OwnedTask` reference has exclusive access to the `owned` field. //! //! * The Notified reference has exclusive access to the `queue_next` field. //! @@ -67,42 +67,42 @@ //! is otherwise immutable and anyone can access the field immutably without //! synchronization. //! -//! * If COMPLETE is one, then the JoinHandle has exclusive access to the +//! * If COMPLETE is one, then the `JoinHandle` has exclusive access to the //! stage field. If COMPLETE is zero, then the RUNNING bitfield functions as //! a lock for the stage field, and it can be accessed only by the thread //! that set RUNNING to one. //! //! * The waker field may be concurrently accessed by different threads: in one //! thread the runtime may complete a task and *read* the waker field to -//! invoke the waker, and in another thread the task's JoinHandle may be -//! polled, and if the task hasn't yet completed, the JoinHandle may *write* -//! a waker to the waker field. The JOIN_WAKER bit ensures safe access by +//! invoke the waker, and in another thread the task's `JoinHandle` may be +//! polled, and if the task hasn't yet completed, the `JoinHandle` may *write* +//! a waker to the waker field. The `JOIN_WAKER` bit ensures safe access by //! multiple threads to the waker field using the following rules: //! -//! 1. JOIN_WAKER is initialized to zero. +//! 1. `JOIN_WAKER` is initialized to zero. //! -//! 2. If JOIN_WAKER is zero, then the JoinHandle has exclusive (mutable) +//! 2. If `JOIN_WAKER` is zero, then the `JoinHandle` has exclusive (mutable) //! access to the waker field. //! -//! 3. If JOIN_WAKER is one, then the JoinHandle has shared (read-only) +//! 3. If `JOIN_WAKER` is one, then the `JoinHandle` has shared (read-only) //! access to the waker field. //! -//! 4. If JOIN_WAKER is one and COMPLETE is one, then the runtime has shared +//! 4. If `JOIN_WAKER` is one and COMPLETE is one, then the runtime has shared //! (read-only) access to the waker field. //! -//! 5. If the JoinHandle needs to write to the waker field, then the -//! JoinHandle needs to (i) successfully set JOIN_WAKER to zero if it is +//! 5. If the `JoinHandle` needs to write to the waker field, then the +//! `JoinHandle` needs to (i) successfully set `JOIN_WAKER` to zero if it is //! not already zero to gain exclusive access to the waker field per rule -//! 2, (ii) write a waker, and (iii) successfully set JOIN_WAKER to one. +//! 2, (ii) write a waker, and (iii) successfully set `JOIN_WAKER` to one. //! -//! 6. The JoinHandle can change JOIN_WAKER only if COMPLETE is zero (i.e. +//! 6. The `JoinHandle` can change `JOIN_WAKER` only if COMPLETE is zero (i.e. //! the task hasn't yet completed). //! //! Rule 6 implies that the steps (i) or (iii) of rule 5 may fail due to a //! race. If step (i) fails, then the attempt to write a waker is aborted. If //! step (iii) fails because COMPLETE is set to one by another thread after //! step (i), then the waker field is cleared. Once COMPLETE is one (i.e. -//! task has completed), the JoinHandle will not modify JOIN_WAKER. After the +//! task has completed), the `JoinHandle` will not modify `JOIN_WAKER`. After the //! runtime sets COMPLETE to one, it invokes the waker if there is one. //! //! All other fields are immutable and can be accessed immutably without @@ -119,18 +119,18 @@ //! the RUNNING field, so exclusive access is ensured. //! //! When the task completes, exclusive access to the output is transferred to -//! the JoinHandle. If the JoinHandle is already dropped when the transition to +//! the `JoinHandle`. If the `JoinHandle` is already dropped when the transition to //! complete happens, the thread performing that transition retains exclusive //! access to the output and should immediately drop it. //! //! ## Non-Send futures //! -//! If a future is not Send, then it is bound to a LocalOwnedTasks. The future -//! will only ever be polled or dropped given a LocalNotified or inside a call -//! to LocalOwnedTasks::shutdown_all. In either case, it is guaranteed that the +//! If a future is not Send, then it is bound to a `LocalOwnedTasks`. The future +//! will only ever be polled or dropped given a `LocalNotified` or inside a call +//! to `LocalOwnedTasks::shutdown_all`. In either case, it is guaranteed that the //! future is on the right thread. //! -//! If the task is never removed from the LocalOwnedTasks, then it is leaked, so +//! If the task is never removed from the `LocalOwnedTasks`, then it is leaked, so //! there is no risk that the task is dropped on some other thread when the last //! ref-count drops. //! @@ -138,21 +138,21 @@ //! //! When a task completes, the output is placed in the stage of the task. Then, //! a transition that sets COMPLETE to true is performed, and the value of -//! JOIN_INTEREST when this transition happens is read. +//! `JOIN_INTEREST` when this transition happens is read. //! -//! If JOIN_INTEREST is zero when the transition to COMPLETE happens, then the +//! If `JOIN_INTEREST` is zero when the transition to COMPLETE happens, then the //! output is immediately dropped. //! -//! If JOIN_INTEREST is one when the transition to COMPLETE happens, then the -//! JoinHandle is responsible for cleaning up the output. If the output is not +//! If `JOIN_INTEREST` is one when the transition to COMPLETE happens, then the +//! `JoinHandle` is responsible for cleaning up the output. If the output is not //! Send, then this happens: //! //! 1. The output is created on the thread that the future was polled on. Since //! only non-Send futures can have non-Send output, the future was polled on //! the thread that the future was spawned from. //! 2. Since `JoinHandle` is not Send if Output is not Send, the -//! JoinHandle is also on the thread that the future was spawned from. -//! 3. Thus, the JoinHandle will not move the output across threads when it +//! `JoinHandle` is also on the thread that the future was spawned from. +//! 3. Thus, the `JoinHandle` will not move the output across threads when it //! takes or drops the output. //! //! ## Recursive poll/shutdown @@ -241,7 +241,7 @@ pub(crate) struct LocalNotified { _not_send: PhantomData<*const ()>, } -/// A task that is not owned by any OwnedTasks. Used for blocking tasks. +/// A task that is not owned by any `OwnedTasks`. Used for blocking tasks. /// This type holds two ref-counts. pub(crate) struct UnownedTask { raw: RawTask, @@ -280,7 +280,7 @@ pub(crate) trait Schedule: Sync + Sized + 'static { cfg_rt! { /// This is the constructor for a new task. Three references to the task are - /// created. The first task reference is usually put into an OwnedTasks + /// created. The first task reference is usually put into an `OwnedTasks` /// immediately. The Notified is sent to the scheduler as an ordinary /// notification. fn new_task( diff --git a/tokio/src/runtime/task/state.rs b/tokio/src/runtime/task/state.rs index 24cb4338b96..9f1a8ec5a14 100644 --- a/tokio/src/runtime/task/state.rs +++ b/tokio/src/runtime/task/state.rs @@ -53,9 +53,9 @@ const REF_ONE: usize = 1 << REF_COUNT_SHIFT; /// /// A task is initialized with three references: /// -/// * A reference that will be stored in an OwnedTasks or LocalOwnedTasks. +/// * A reference that will be stored in an `OwnedTasks` or `LocalOwnedTasks`. /// * A reference that will be sent to the scheduler as an ordinary notification. -/// * A reference for the JoinHandle. +/// * A reference for the `JoinHandle`. /// /// As the task starts with a `JoinHandle`, `JOIN_INTEREST` is set. /// As the task starts with a `Notified`, `NOTIFIED` is set. diff --git a/tokio/src/runtime/task/trace/mod.rs b/tokio/src/runtime/task/trace/mod.rs index 34d40a5a253..7c9acc035af 100644 --- a/tokio/src/runtime/task/trace/mod.rs +++ b/tokio/src/runtime/task/trace/mod.rs @@ -265,7 +265,7 @@ impl Future for Root { } } -/// Trace and poll all tasks of the current_thread runtime. +/// Trace and poll all tasks of the `current_thread` runtime. pub(in crate::runtime) fn trace_current_thread( owned: &OwnedTasks>, local: &mut VecDeque>>, @@ -293,7 +293,7 @@ cfg_rt_multi_thread! { use crate::runtime::scheduler::multi_thread::Synced; use crate::runtime::scheduler::inject::Shared; - /// Trace and poll all tasks of the current_thread runtime. + /// Trace and poll all tasks of the `current_thread` runtime. /// /// ## Safety /// diff --git a/tokio/src/runtime/tests/loom_local.rs b/tokio/src/runtime/tests/loom_local.rs index d9a07a45f05..89d025b811c 100644 --- a/tokio/src/runtime/tests/loom_local.rs +++ b/tokio/src/runtime/tests/loom_local.rs @@ -9,7 +9,7 @@ use std::task::Poll; /// to the runtime itself. This means that if they are not properly removed at /// runtime shutdown, this will cause a memory leak. /// -/// This test verifies that waking something during shutdown of a LocalSet does +/// This test verifies that waking something during shutdown of a `LocalSet` does /// not result in tasks lingering in the queue once shutdown is complete. This /// is verified using loom's leak finder. #[test] diff --git a/tokio/src/runtime/time/entry.rs b/tokio/src/runtime/time/entry.rs index 634ed2031ac..0998b53011d 100644 --- a/tokio/src/runtime/time/entry.rs +++ b/tokio/src/runtime/time/entry.rs @@ -11,10 +11,10 @@ //! 2) a held driver lock. //! //! It follows from this that any changes made while holding BOTH 1 and 2 will -//! be reliably visible, regardless of ordering. This is because of the acq/rel +//! be reliably visible, regardless of ordering. This is because of the `acq/rel` //! fences on the driver lock ensuring ordering with 2, and rust mutable //! reference rules for 1 (a mutable reference to an object can't be passed -//! between threads without an acq/rel barrier, and same-thread we have local +//! between threads without an `acq/rel` barrier, and same-thread we have local //! happens-before ordering). //! //! # State field @@ -81,12 +81,12 @@ pub(super) const MAX_SAFE_MILLIS_DURATION: u64 = u64::MAX - 2; /// time (if registered), or otherwise the result of the timer completing, as /// well as the registered waker. /// -/// Generally, the StateCell is only permitted to be accessed from two contexts: -/// Either a thread holding the corresponding &mut TimerEntry, or a thread -/// holding the timer driver lock. The write actions on the StateCell amount to -/// passing "ownership" of the StateCell between these contexts; moving a timer -/// from the TimerEntry to the driver requires _both_ holding the &mut -/// TimerEntry and the driver lock, while moving it back (firing the timer) +/// Generally, the `StateCell` is only permitted to be accessed from two contexts: +/// Either a thread holding the corresponding `&mut TimerEntry`, or a thread +/// holding the timer driver lock. The write actions on the `StateCell` amount to +/// passing "ownership" of the `StateCell` between these contexts; moving a timer +/// from the `TimerEntry` to the driver requires _both_ holding the `&mut +/// TimerEntry` and the driver lock, while moving it back (firing the timer) /// requires only the driver lock. pub(super) struct StateCell { /// Holds either the scheduled expiration time for this timer, or (if the @@ -164,7 +164,7 @@ impl StateCell { /// Marks this timer as being moved to the pending list, if its scheduled /// time is not after `not_after`. /// - /// If the timer is scheduled for a time after not_after, returns an Err + /// If the timer is scheduled for a time after `not_after`, returns an Err /// containing the current scheduled time. /// /// SAFETY: Must hold the driver lock. @@ -314,15 +314,15 @@ pub(crate) struct TimerEntry { unsafe impl Send for TimerEntry {} unsafe impl Sync for TimerEntry {} -/// An TimerHandle is the (non-enforced) "unique" pointer from the driver to the -/// timer entry. Generally, at most one TimerHandle exists for a timer at a time +/// An `TimerHandle` is the (non-enforced) "unique" pointer from the driver to the +/// timer entry. Generally, at most one `TimerHandle` exists for a timer at a time /// (enforced by the timer state machine). /// -/// SAFETY: An TimerHandle is essentially a raw pointer, and the usual caveats -/// of pointer safety apply. In particular, TimerHandle does not itself enforce -/// that the timer does still exist; however, normally an TimerHandle is created +/// SAFETY: An `TimerHandle` is essentially a raw pointer, and the usual caveats +/// of pointer safety apply. In particular, `TimerHandle` does not itself enforce +/// that the timer does still exist; however, normally an `TimerHandle` is created /// immediately before registering the timer, and is consumed when firing the -/// timer, to help minimize mistakes. Still, because TimerHandle cannot enforce +/// timer, to help minimize mistakes. Still, because `TimerHandle` cannot enforce /// memory safety, all operations are unsafe. #[derive(Debug)] pub(crate) struct TimerHandle { @@ -437,7 +437,7 @@ impl TimerShared { self.state.extend_expiration(t) } - /// Returns a TimerHandle for this timer. + /// Returns a `TimerHandle` for this timer. pub(super) fn handle(&self) -> TimerHandle { TimerHandle { inner: NonNull::from(self), diff --git a/tokio/src/runtime/time/source.rs b/tokio/src/runtime/time/source.rs index 4647bc41223..c709dc5380f 100644 --- a/tokio/src/runtime/time/source.rs +++ b/tokio/src/runtime/time/source.rs @@ -1,7 +1,7 @@ use super::MAX_SAFE_MILLIS_DURATION; use crate::time::{Clock, Duration, Instant}; -/// A structure which handles conversion from Instants to u64 timestamps. +/// A structure which handles conversion from Instants to `u64` timestamps. #[derive(Debug)] pub(crate) struct TimeSource { start_time: Instant, diff --git a/tokio/src/runtime/time/wheel/level.rs b/tokio/src/runtime/time/wheel/level.rs index 4c9ba18cd89..a828c0067ef 100644 --- a/tokio/src/runtime/time/wheel/level.rs +++ b/tokio/src/runtime/time/wheel/level.rs @@ -15,7 +15,7 @@ pub(crate) struct Level { /// The least-significant bit represents slot zero. occupied: u64, - /// Slots. We access these via the EntryInner `current_list` as well, so this needs to be an UnsafeCell. + /// Slots. We access these via the EntryInner `current_list` as well, so this needs to be an `UnsafeCell`. slot: [EntryList; LEVEL_MULT], } diff --git a/tokio/src/signal/ctrl_c.rs b/tokio/src/signal/ctrl_c.rs index b26ab7ead64..e1e92fa9977 100644 --- a/tokio/src/signal/ctrl_c.rs +++ b/tokio/src/signal/ctrl_c.rs @@ -23,10 +23,10 @@ use std::io; /// the entire process**. /// /// For example, Unix systems will terminate a process by default when it -/// receives a signal generated by "CTRL+C" on the terminal. But, when a +/// receives a signal generated by `"CTRL+C"` on the terminal. But, when a /// `ctrl_c` stream is created to listen for this signal, the time it arrives, /// it will be translated to a stream event, and the process will continue to -/// execute. **Even if this `Signal` instance is dropped, subsequent SIGINT +/// execute. **Even if this `Signal` instance is dropped, subsequent `SIGINT` /// deliveries will end up captured by Tokio, and the default platform behavior /// will NOT be reset**. /// diff --git a/tokio/src/signal/mod.rs b/tokio/src/signal/mod.rs index ab47e8af27b..59f71db0e46 100644 --- a/tokio/src/signal/mod.rs +++ b/tokio/src/signal/mod.rs @@ -23,7 +23,7 @@ //! } //! ``` //! -//! Wait for SIGHUP on Unix +//! Wait for `SIGHUP` on Unix //! //! ```rust,no_run //! # #[cfg(unix)] { diff --git a/tokio/src/signal/registry.rs b/tokio/src/signal/registry.rs index 74973293a2d..3fff8df9303 100644 --- a/tokio/src/signal/registry.rs +++ b/tokio/src/signal/registry.rs @@ -26,7 +26,7 @@ impl Default for EventInfo { } } -/// An interface for retrieving the `EventInfo` for a particular eventId. +/// An interface for retrieving the `EventInfo` for a particular `eventId`. pub(crate) trait Storage { /// Gets the `EventInfo` for `id` if it exists. fn event_info(&self, id: EventId) -> Option<&EventInfo>; @@ -59,7 +59,7 @@ pub(crate) trait Init { /// Manages and distributes event notifications to any registered listeners. /// /// Generic over the underlying storage to allow for domain specific -/// optimizations (e.g. eventIds may or may not be contiguous). +/// optimizations (e.g. `eventIds` may or may not be contiguous). #[derive(Debug)] pub(crate) struct Registry { storage: S, diff --git a/tokio/src/signal/unix.rs b/tokio/src/signal/unix.rs index d3d7fd4ab76..52a9cbaac40 100644 --- a/tokio/src/signal/unix.rs +++ b/tokio/src/signal/unix.rs @@ -97,7 +97,7 @@ impl SignalKind { self.0 } - /// Represents the SIGALRM signal. + /// Represents the `SIGALRM` signal. /// /// On Unix systems this signal is sent when a real-time timer has expired. /// By default, the process is terminated by this signal. @@ -105,7 +105,7 @@ impl SignalKind { Self(libc::SIGALRM) } - /// Represents the SIGCHLD signal. + /// Represents the `SIGCHLD` signal. /// /// On Unix systems this signal is sent when the status of a child process /// has changed. By default, this signal is ignored. @@ -113,7 +113,7 @@ impl SignalKind { Self(libc::SIGCHLD) } - /// Represents the SIGHUP signal. + /// Represents the `SIGHUP` signal. /// /// On Unix systems this signal is sent when the terminal is disconnected. /// By default, the process is terminated by this signal. @@ -121,7 +121,7 @@ impl SignalKind { Self(libc::SIGHUP) } - /// Represents the SIGINFO signal. + /// Represents the `SIGINFO` signal. /// /// On Unix systems this signal is sent to request a status update from the /// process. By default, this signal is ignored. @@ -136,7 +136,7 @@ impl SignalKind { Self(libc::SIGINFO) } - /// Represents the SIGINT signal. + /// Represents the `SIGINT` signal. /// /// On Unix systems this signal is sent to interrupt a program. /// By default, the process is terminated by this signal. @@ -144,7 +144,7 @@ impl SignalKind { Self(libc::SIGINT) } - /// Represents the SIGIO signal. + /// Represents the `SIGIO` signal. /// /// On Unix systems this signal is sent when I/O operations are possible /// on some file descriptor. By default, this signal is ignored. @@ -152,7 +152,7 @@ impl SignalKind { Self(libc::SIGIO) } - /// Represents the SIGPIPE signal. + /// Represents the `SIGPIPE` signal. /// /// On Unix systems this signal is sent when the process attempts to write /// to a pipe which has no reader. By default, the process is terminated by @@ -161,7 +161,7 @@ impl SignalKind { Self(libc::SIGPIPE) } - /// Represents the SIGQUIT signal. + /// Represents the `SIGQUIT` signal. /// /// On Unix systems this signal is sent to issue a shutdown of the /// process, after which the OS will dump the process core. @@ -170,7 +170,7 @@ impl SignalKind { Self(libc::SIGQUIT) } - /// Represents the SIGTERM signal. + /// Represents the `SIGTERM` signal. /// /// On Unix systems this signal is sent to issue a shutdown of the /// process. By default, the process is terminated by this signal. @@ -178,7 +178,7 @@ impl SignalKind { Self(libc::SIGTERM) } - /// Represents the SIGUSR1 signal. + /// Represents the `SIGUSR1` signal. /// /// On Unix systems this is a user defined signal. /// By default, the process is terminated by this signal. @@ -186,7 +186,7 @@ impl SignalKind { Self(libc::SIGUSR1) } - /// Represents the SIGUSR2 signal. + /// Represents the `SIGUSR2` signal. /// /// On Unix systems this is a user defined signal. /// By default, the process is terminated by this signal. @@ -194,7 +194,7 @@ impl SignalKind { Self(libc::SIGUSR2) } - /// Represents the SIGWINCH signal. + /// Represents the `SIGWINCH` signal. /// /// On Unix systems this signal is sent when the terminal window is resized. /// By default, this signal is ignored. @@ -330,10 +330,10 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> { /// entire process**. /// /// For example, Unix systems will terminate a process by default when it -/// receives SIGINT. But, when a `Signal` instance is created to listen for -/// this signal, the next SIGINT that arrives will be translated to a stream +/// receives `SIGINT`. But, when a `Signal` instance is created to listen for +/// this signal, the next `SIGINT` that arrives will be translated to a stream /// event, and the process will continue to execute. **Even if this `Signal` -/// instance is dropped, subsequent SIGINT deliveries will end up captured by +/// instance is dropped, subsequent `SIGINT` deliveries will end up captured by /// Tokio, and the default platform behavior will NOT be reset**. /// /// Thus, applications should take care to ensure the expected signal behavior @@ -341,7 +341,7 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> { /// /// # Examples /// -/// Wait for SIGHUP +/// Wait for `SIGHUP` /// /// ```rust,no_run /// use tokio::signal::unix::{signal, SignalKind}; @@ -424,7 +424,7 @@ impl Signal { /// /// # Examples /// - /// Wait for SIGHUP + /// Wait for `SIGHUP` /// /// ```rust,no_run /// use tokio::signal::unix::{signal, SignalKind}; diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index 2f70f98b15a..d8af9b4c9d9 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -3,7 +3,7 @@ //! This module is only defined on Windows and allows receiving "ctrl-c", //! "ctrl-break", "ctrl-logoff", "ctrl-shutdown", and "ctrl-close" //! notifications. These events are listened for via the `SetConsoleCtrlHandler` -//! function which receives the corresponding windows_sys event type. +//! function which receives the corresponding `windows_sys` event type. #![cfg(any(windows, docsrs))] #![cfg_attr(docsrs, doc(cfg(all(windows, feature = "signal"))))] @@ -257,8 +257,8 @@ pub fn ctrl_close() -> io::Result { }) } -/// Represents a listener which receives "ctrl-close" notitifications sent to the process -/// via 'SetConsoleCtrlHandler'. +/// Represents a listener which receives "ctrl-close" notifications sent to the process +/// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for /// this event. Moreover, the notifications **are coalesced** if they aren't processed @@ -354,8 +354,8 @@ pub fn ctrl_shutdown() -> io::Result { }) } -/// Represents a listener which receives "ctrl-shutdown" notitifications sent to the process -/// via 'SetConsoleCtrlHandler'. +/// Represents a listener which receives "ctrl-shutdown" notifications sent to the process +/// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for /// this event. Moreover, the notifications **are coalesced** if they aren't processed @@ -451,8 +451,8 @@ pub fn ctrl_logoff() -> io::Result { }) } -/// Represents a listener which receives "ctrl-logoff" notitifications sent to the process -/// via 'SetConsoleCtrlHandler'. +/// Represents a listener which receives "ctrl-logoff" notifications sent to the process +/// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for /// this event. Moreover, the notifications **are coalesced** if they aren't processed diff --git a/tokio/src/sync/mpsc/error.rs b/tokio/src/sync/mpsc/error.rs index e41885664da..2fc24b38d83 100644 --- a/tokio/src/sync/mpsc/error.rs +++ b/tokio/src/sync/mpsc/error.rs @@ -24,7 +24,7 @@ impl Error for SendError {} // ===== TrySendError ===== /// This enumeration is the list of the possible error outcomes for the -/// [try_send](super::Sender::try_send) method. +/// [`try_send`](super::Sender::try_send) method. #[derive(PartialEq, Eq, Clone, Copy)] pub enum TrySendError { /// The data could not be sent on the channel because the channel is diff --git a/tokio/src/sync/oneshot.rs b/tokio/src/sync/oneshot.rs index 3fa77031e51..9e8c3fcb7f7 100644 --- a/tokio/src/sync/oneshot.rs +++ b/tokio/src/sync/oneshot.rs @@ -59,7 +59,7 @@ //! } //! ``` //! -//! To use a oneshot channel in a `tokio::select!` loop, add `&mut` in front of +//! To use a `oneshot` channel in a `tokio::select!` loop, add `&mut` in front of //! the channel. //! //! ``` @@ -330,7 +330,7 @@ pub struct Receiver { } pub mod error { - //! Oneshot error types. + //! `Oneshot` error types. use std::fmt; @@ -555,8 +555,8 @@ impl Sender { /// Attempts to send a value on this channel, returning it back if it could /// not be sent. /// - /// This method consumes `self` as only one value may ever be sent on a oneshot - /// channel. It is not marked async because sending a message to an oneshot + /// This method consumes `self` as only one value may ever be sent on a `oneshot` + /// channel. It is not marked async because sending a message to an `oneshot` /// channel never requires any form of waiting. Because of this, the `send` /// method can be used in both synchronous and asynchronous code without /// problems. @@ -750,7 +750,7 @@ impl Sender { state.is_closed() } - /// Checks whether the oneshot channel has been closed, and if not, schedules the + /// Checks whether the `oneshot` channel has been closed, and if not, schedules the /// `Waker` in the provided `Context` to receive a notification when the channel is /// closed. /// diff --git a/tokio/src/task/local.rs b/tokio/src/task/local.rs index fb49d1f2768..a40708d08c2 100644 --- a/tokio/src/task/local.rs +++ b/tokio/src/task/local.rs @@ -237,7 +237,7 @@ struct Context { unhandled_panic: Cell, } -/// LocalSet state shared between threads. +/// `LocalSet` state shared between threads. struct Shared { /// # Safety /// @@ -290,7 +290,7 @@ struct LocalData { impl LocalData { /// Should be called except when we call `LocalSet::enter`. - /// Especially when we poll a LocalSet. + /// Especially when we poll a `LocalSet`. #[must_use = "dropping this guard will reset the entered state"] fn enter(&self, ctx: Rc) -> LocalDataEnterGuard<'_> { let ctx = self.ctx.replace(Some(ctx)); @@ -392,7 +392,7 @@ const MAX_TASKS_PER_TICK: usize = 61; /// How often it check the remote queue first. const REMOTE_FIRST_INTERVAL: u8 = 31; -/// Context guard for LocalSet +/// Context guard for `LocalSet` pub struct LocalEnterGuard { ctx: Option>, @@ -526,7 +526,7 @@ impl LocalSet { /// This runs the given future on the runtime, blocking until it is /// complete, and yielding its resolved result. Any tasks or timers which /// the future spawns internally will be executed on the runtime. The future - /// may also call [`spawn_local`] to spawn_local additional local futures on the + /// may also call [`spawn_local`] to `spawn_local` additional local futures on the /// current thread. /// /// This method should not be called from an asynchronous context. diff --git a/tokio/src/task/mod.rs b/tokio/src/task/mod.rs index aefa395c044..806b9aebe76 100644 --- a/tokio/src/task/mod.rs +++ b/tokio/src/task/mod.rs @@ -5,8 +5,8 @@ //! A _task_ is a light weight, non-blocking unit of execution. A task is similar //! to an OS thread, but rather than being managed by the OS scheduler, they are //! managed by the [Tokio runtime][rt]. Another name for this general pattern is -//! [green threads]. If you are familiar with [Go's goroutines], [Kotlin's -//! coroutines], or [Erlang's processes], you can think of Tokio's tasks as +//! [green threads]. If you are familiar with [`Go's goroutines`], [`Kotlin's +//! coroutines`], or [`Erlang's processes`], you can think of Tokio's tasks as //! something similar. //! //! Key points about tasks include: @@ -167,7 +167,7 @@ //! blocking operations there. This includes destructors of objects destroyed in //! async code. //! -//! #### spawn_blocking +//! #### `spawn_blocking` //! //! The `task::spawn_blocking` function is similar to the `task::spawn` function //! discussed in the previous section, but rather than spawning an @@ -202,7 +202,7 @@ //! # } //! ``` //! -//! #### block_in_place +//! #### `block_in_place` //! //! When using the [multi-threaded runtime][rt-multi-thread], the [`task::block_in_place`] //! function is also available. Like `task::spawn_blocking`, this function @@ -227,7 +227,7 @@ //! # } //! ``` //! -//! #### yield_now +//! #### `yield_now` //! //! In addition, this module provides a [`task::yield_now`] async function //! that is analogous to the standard library's [`thread::yield_now`]. Calling diff --git a/tokio/src/util/idle_notified_set.rs b/tokio/src/util/idle_notified_set.rs index bd9c2ef1bbc..8fe13095a2c 100644 --- a/tokio/src/util/idle_notified_set.rs +++ b/tokio/src/util/idle_notified_set.rs @@ -42,8 +42,8 @@ pub(crate) struct EntryInOneOfTheLists<'a, T> { type Lists = Mutex>; -/// The linked lists hold strong references to the ListEntry items, and the -/// ListEntry items also hold a strong reference back to the Lists object, but +/// The linked lists hold strong references to the `ListEntry` items, and the +/// `ListEntry` items also hold a strong reference back to the Lists object, but /// the destructor of the `IdleNotifiedSet` will clear the two lists, so once /// that object is destroyed, no ref-cycles will remain. struct ListsInner { diff --git a/tokio/src/util/rand.rs b/tokio/src/util/rand.rs index d96c8d37e0a..67c45693c9c 100644 --- a/tokio/src/util/rand.rs +++ b/tokio/src/util/rand.rs @@ -20,9 +20,9 @@ pub struct RngSeed { /// Fast random number generate. /// -/// Implement xorshift64+: 2 32-bit xorshift sequences added together. +/// Implement `xorshift64+`: 2 32-bit `xorshift` sequences added together. /// Shift triplet `[17,7,16]` was calculated as indicated in Marsaglia's -/// Xorshift paper: +/// `Xorshift` paper: /// This generator passes the SmallCrush suite, part of TestU01 framework: /// #[derive(Clone, Copy, Debug)] diff --git a/tokio/src/util/sharded_list.rs b/tokio/src/util/sharded_list.rs index c1009db94c9..4da0bcdf7f1 100644 --- a/tokio/src/util/sharded_list.rs +++ b/tokio/src/util/sharded_list.rs @@ -56,7 +56,7 @@ pub(crate) struct ShardGuard<'a, L, T> { } impl ShardedList { - /// Removes the last element from a list specified by shard_id and returns it, or None if it is + /// Removes the last element from a list specified by `shard_id` and returns it, or None if it is /// empty. pub(crate) fn pop_back(&self, shard_id: usize) -> Option { let mut lock = self.shard_inner(shard_id); @@ -87,7 +87,7 @@ impl ShardedList { node } - /// Gets the lock of ShardedList, makes us have the write permission. + /// Gets the lock of `ShardedList`, makes us have the write permission. pub(crate) fn lock_shard(&self, val: &L::Handle) -> ShardGuard<'_, L, L::Target> { let id = unsafe { L::get_shard_id(L::as_raw(val)) }; ShardGuard { @@ -107,7 +107,7 @@ impl ShardedList { self.len() == 0 } - /// Gets the shard size of this SharedList. + /// Gets the shard size of this `SharedList`. /// /// Used to help us to decide the parameter `shard_id` of the `pop_back` method. pub(crate) fn shard_size(&self) -> usize {