From b1601f1c5727f463824da657696ff179bffb6c97 Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Thu, 18 Jan 2024 22:42:22 +0800 Subject: [PATCH 01/11] Add new CI Spellcheck job add spellcheck.dic, spellcheck.toml, and add new CI spellcheck job --- .github/workflows/ci.yml | 19 ++ Cargo.toml | 3 + spellcheck.dic | 446 +++++++++++++++++++++++++++++++++++++++ spellcheck.toml | 12 ++ 4 files changed, 480 insertions(+) create mode 100644 spellcheck.dic create mode 100644 spellcheck.toml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 60a962f8b25..8880fd775b0 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,21 @@ 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 \ No newline at end of file diff --git a/Cargo.toml b/Cargo.toml index f3e19312e8b..508bb54a696 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,3 +14,6 @@ members = [ "tests-build", "tests-integration", ] + +[workspace.metadata.spellcheck] +config = "spellcheck.toml" \ No newline at end of file diff --git a/spellcheck.dic b/spellcheck.dic new file mode 100644 index 00000000000..f5c24e5b786 --- /dev/null +++ b/spellcheck.dic @@ -0,0 +1,446 @@ +445 +\ +~ +~4 +~12 +±1m +±1ms +— +& +&mut +&str ++ +0o777 +0s +0xA +0xD +100ms +10ms +1ms +1s +250ms +2x +443 +450ms +50ms +8MB +< += +> +aarch64 +acq +adaptor +adaptors +Adaptors +AIO +ambiant +amongst +api +APIs +as_handle +as_raw_handle +as_raw_socket +as_socket +AsHandle +AsRawHandle +AsRawSocket +assert_eq +AsSocket +async +AsyncRead +AsyncReadExt +AsyncWrite +AsyncWriteExt +awaitable +backend +backpressure +backtrace +backtraces +backtracing +binded +bitfield +bitfields +block_in_place +block_on +Blockingly +BlockingPool +bool +boolean +BorrowedHandle +BorrowedSocket +broadcasted +buf +CancellationToken +CancellationTokens +CANCELLED +cancelled +cancelling +Cancelling +cfg +CLI +cloneable +codebase +codec +codecs +combinator +combinators +condvar +Config +config +connectionless +const +coroutines +cpu +cpus +CRLF +CTRL +current_thread +Customizable +DACL_SECURITY_INFORMATION +Datagram +datagram +datagrams +Dealloc +deallocate +deallocated +Deallocates +debuginfo +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 +EOF +epoll +Erlang's +ERROR_ACCESS_DENIED +ERROR_SUCCESS +errored +eventId +eventIds +EWMA +expirations +f64 +fcntl +fd's +FIFOs +filename +filesystem +filesystems +fn +fns +FreeBSD +from_raw_handle +from_raw_socket +FromRawHandle +FromRawSocket +frontend +fs +functionalities +fuzz_linked_list +getters +GID +goroutines +Growable +gzip +hashmaps +HashMaps +hashsets +i32 +ie +Illumos +impl +implementers +implementor +implementors +incrementing +InspectReader +InspectWriter +interoperate +into_raw_socket +IntoRawSocket +Invariants +invariants +io +IOCP +iOS +IOs +IP +IPv4 +IPv6 +is_shutdown +iteratively +JOIN_INTEREST +JOIN_WAKER +JoinHandle +JoinHandles +JoinMap +Kotlin's +kqueue +latencies +Lauck +libc +lifecycle +lifo +lio_listio +ListEntry +LOCAL_QUEUE_CAPACITY +LocalNotified +LocalOwnedTasks +LocalSet +lookups +LSB +macOS +MacOS +Marsaglia's +metadata +mio +Mio +mio's +misconfigured +mock's +mpmc +mpsc +MSB +MSRV +Multi +multi +multicast +Multithreaded +mut +mutex +Mutex +Nagle +named_pipe +nonblocking +nondecreasing +noop +not_after +notitifications +ntasks +null_mut +ok +Ok +oneshot +Oneshot +OpenOptions +ORed +os +overweighing +OwnedHandle +OwnedTask +OwnedTasks +parker +parking_lot +parsers +peekable +PGID +PID +PIPE_NAME +pipe_template +plaintext +poll_accept +poll_complete +poller +POSIX +proxied +ptr +ptr} +qos +RAII +RawHandle +RawSocket +read_exact +readbuffer +reallocations +recv +recv's +refactors +refcount +refcounting +repo +repr +representable +reqwest +reregistering +resize +resized +RMW +Runtime +Runtime's +runtime +runtimes +runtime's +rurururus +rwlock +rx +scalability +ScheduledIo +scheduler's +SE_KERNEL_OBJECT +SE_KERNEL_OBJECT} +seemms +semver +ServerOptions +SetConsoleCtrlHandler'. +setpgid +SetSecurityInfo +shard_id +sharded +ShardedList +SharedList +sheduler +shutdown_all +shutdown_cores +SIGALRM +SIGCHLD +SIGHUP +SIGINFO +SIGINT +SIGIO +SIGKILL +signalled +signalling +SIGPIPE +SIGQUIT +SIGTERM +SIGUSR1 +SIGUSR2 +SIGWINCH +SmallCrush +SO_LINGER +socker +socket2's +Solaris +spawn_blocking +spawn_local +spawner +Splitter +spmc +spsc +src +stabilised +start_seek +startup +StateCell +stateful +stderr +stdin +stdout +stealable +stealer +stealers +struct +structs +subfield +suboptimal +subprocess +superset +symlink +symlinks +sys +syscall +syscalls +TCP +tcp +TcpListener +TestU01 +thread_keep_alive +threadpool +TimerEntry +TimerHandle +timestamp +timestamps +TLS +TOCTOU +TODO +Tokio +tokio +tokio's +Tokio's +TreeNode +try_join +try_send +Tuple +tuple +tx +u64 +UDP +udp +UID +unhandled +unix +UnixDatagram +UnixListener +UnixStream +unlink +Unowned +unpark +Unpark +unparked +unparking +Unparks +unparks +unreceived +UnsafeCell +unsafety +Unsets +unsynchronized +untrusted +usecases +usize +utf8 +Valgrind +Varghese +vec +versa +versioned +versioning +vtable +Waker +waker +wakers +Wakers +wakeup +wakeups +WASI +Wasi +WASM +WatchStream +Win32 +windows_sys +with_locked_node_and_parent +worker_threads +workstealing +write_dac +write_dac_pipe +write_dac_pipe_fail +writebuffer +WSAEMSGSIZE +x86 +x86_64 +xorshift +Xorshift +xorshift64 +yield_now +{io +{SetSecurityInfo \ No newline at end of file diff --git a/spellcheck.toml b/spellcheck.toml new file mode 100644 index 00000000000..410c1c8f9bb --- /dev/null +++ b/spellcheck.toml @@ -0,0 +1,12 @@ +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 \ No newline at end of file From f6c2bfc76248a57ed2f47cbf17e1364689b5f08d Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Tue, 23 Jan 2024 10:11:24 +0800 Subject: [PATCH 02/11] Test if backticks will create doctest error --- spellcheck.dic | 2 -- tokio/src/net/windows/named_pipe.rs | 4 ++-- tokio/src/runtime/time/entry.rs | 6 +++--- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/spellcheck.dic b/spellcheck.dic index f5c24e5b786..4c39b672687 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -7,8 +7,6 @@ ±1ms — & -&mut -&str + 0o777 0s diff --git a/tokio/src/net/windows/named_pipe.rs b/tokio/src/net/windows/named_pipe.rs index a03e1d0acd1..9bba5e81f94 100644 --- a/tokio/src/net/windows/named_pipe.rs +++ b/tokio/src/net/windows/named_pipe.rs @@ -2067,7 +2067,7 @@ impl ServerOptions { /// Win32::Security::Authorization::{SetSecurityInfo, SE_KERNEL_OBJECT}, /// }; /// - /// const PIPE_NAME: &str = r"\\.\pipe\write_dac_pipe"; + /// const PIPE_NAME: `&str` = r"\\.\pipe\write_dac_pipe"; /// /// # #[tokio::main] async fn main() -> io::Result<()> { /// let mut pipe_template = ServerOptions::new(); @@ -2102,7 +2102,7 @@ impl ServerOptions { /// Win32::Security::Authorization::{SetSecurityInfo, SE_KERNEL_OBJECT}, /// }; /// - /// const PIPE_NAME: &str = r"\\.\pipe\write_dac_pipe_fail"; + /// const PIPE_NAME: `&str` = r"\\.\pipe\write_dac_pipe_fail"; /// /// # #[tokio::main] async fn main() -> io::Result<()> { /// let mut pipe_template = ServerOptions::new(); diff --git a/tokio/src/runtime/time/entry.rs b/tokio/src/runtime/time/entry.rs index 634ed2031ac..69da84c30d1 100644 --- a/tokio/src/runtime/time/entry.rs +++ b/tokio/src/runtime/time/entry.rs @@ -82,11 +82,11 @@ pub(super) const MAX_SAFE_MILLIS_DURATION: u64 = u64::MAX - 2; /// 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 +/// 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) +/// 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 From 3679414ff0732917ea09e88acae50c1afdcff4d3 Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Tue, 23 Jan 2024 10:18:50 +0800 Subject: [PATCH 03/11] Revert change in named_pipe.rs --- tokio/src/net/windows/named_pipe.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/windows/named_pipe.rs b/tokio/src/net/windows/named_pipe.rs index 9bba5e81f94..a03e1d0acd1 100644 --- a/tokio/src/net/windows/named_pipe.rs +++ b/tokio/src/net/windows/named_pipe.rs @@ -2067,7 +2067,7 @@ impl ServerOptions { /// Win32::Security::Authorization::{SetSecurityInfo, SE_KERNEL_OBJECT}, /// }; /// - /// const PIPE_NAME: `&str` = r"\\.\pipe\write_dac_pipe"; + /// const PIPE_NAME: &str = r"\\.\pipe\write_dac_pipe"; /// /// # #[tokio::main] async fn main() -> io::Result<()> { /// let mut pipe_template = ServerOptions::new(); @@ -2102,7 +2102,7 @@ impl ServerOptions { /// Win32::Security::Authorization::{SetSecurityInfo, SE_KERNEL_OBJECT}, /// }; /// - /// const PIPE_NAME: `&str` = r"\\.\pipe\write_dac_pipe_fail"; + /// const PIPE_NAME: &str = r"\\.\pipe\write_dac_pipe_fail"; /// /// # #[tokio::main] async fn main() -> io::Result<()> { /// let mut pipe_template = ServerOptions::new(); From c712d5229589196f4e786f8d10d18821238e0a73 Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Thu, 25 Jan 2024 23:10:53 +0800 Subject: [PATCH 04/11] backticks common rust / tokio words backticks common rust / tokio words, and fix some typos --- CONTRIBUTING.md | 10 +++ spellcheck.dic | 80 +------------------ tokio-stream/src/lib.rs | 2 +- tokio-stream/src/wrappers/watch.rs | 2 +- tokio-util/src/codec/mod.rs | 2 +- tokio-util/src/io/inspect.rs | 4 +- .../src/sync/cancellation_token/tree_node.rs | 14 ++-- tokio-util/src/task/join_map.rs | 2 +- tokio/src/doc/os.rs | 44 +++++----- .../src/fs/open_options/mock_open_options.rs | 2 +- tokio/src/io/interest.rs | 4 +- tokio/src/io/mod.rs | 4 +- tokio/src/io/util/read_exact.rs | 2 +- tokio/src/io/util/shutdown.rs | 2 +- tokio/src/macros/try_join.rs | 2 +- tokio/src/net/tcp/stream.rs | 8 +- tokio/src/net/udp.rs | 14 ++-- tokio/src/net/unix/datagram/socket.rs | 10 +-- tokio/src/net/unix/listener.rs | 2 +- tokio/src/net/unix/stream.rs | 2 +- tokio/src/process/mod.rs | 4 +- tokio/src/runtime/blocking/pool.rs | 4 +- tokio/src/runtime/builder.rs | 4 +- tokio/src/runtime/context.rs | 2 +- tokio/src/runtime/handle.rs | 2 +- tokio/src/runtime/io/scheduled_io.rs | 6 +- .../runtime/scheduler/multi_thread/worker.rs | 22 ++--- .../scheduler/multi_thread_alt/worker.rs | 22 ++--- tokio/src/runtime/task/list.rs | 12 +-- tokio/src/runtime/task/mod.rs | 80 +++++++++---------- tokio/src/runtime/task/state.rs | 4 +- tokio/src/runtime/tests/loom_local.rs | 2 +- tokio/src/runtime/time/entry.rs | 26 +++--- tokio/src/runtime/time/wheel/level.rs | 2 +- tokio/src/signal/windows.rs | 6 +- tokio/src/sync/mpsc/error.rs | 2 +- tokio/src/sync/mpsc/mod.rs | 4 +- tokio/src/sync/oneshot.rs | 10 +-- tokio/src/task/local.rs | 6 +- tokio/src/task/mod.rs | 2 +- tokio/src/util/idle_notified_set.rs | 4 +- tokio/src/util/sharded_list.rs | 4 +- 42 files changed, 188 insertions(+), 254 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1fd3bf0d28..9d0d70d4e81 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -194,6 +194,16 @@ MIRIFLAGS="-Zmiri-disable-isolation -Zmiri-tag-raw-pointers" \ cargo +nightly miri test --features full --lib ``` +You can also 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 spell check +``` + ### Tests If the change being proposed alters code (as opposed to only documentation for diff --git a/spellcheck.dic b/spellcheck.dic index 4c39b672687..0f2bf588cc9 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -1,4 +1,4 @@ -445 +367 \ ~ ~4 @@ -7,6 +7,7 @@ ±1ms — & +&str + 0o777 0s @@ -25,8 +26,6 @@ < = > -aarch64 -acq adaptor adaptors Adaptors @@ -35,20 +34,10 @@ ambiant amongst api APIs -as_handle as_raw_handle -as_raw_socket -as_socket -AsHandle AsRawHandle -AsRawSocket assert_eq -AsSocket async -AsyncRead -AsyncReadExt -AsyncWrite -AsyncWriteExt awaitable backend backpressure @@ -61,15 +50,10 @@ bitfields block_in_place block_on Blockingly -BlockingPool bool boolean -BorrowedHandle -BorrowedSocket broadcasted buf -CancellationToken -CancellationTokens CANCELLED cancelled cancelling @@ -147,10 +131,6 @@ filesystems fn fns FreeBSD -from_raw_handle -from_raw_socket -FromRawHandle -FromRawSocket frontend fs functionalities @@ -171,11 +151,7 @@ implementers implementor implementors incrementing -InspectReader -InspectWriter interoperate -into_raw_socket -IntoRawSocket Invariants invariants io @@ -185,13 +161,7 @@ IOs IP IPv4 IPv6 -is_shutdown iteratively -JOIN_INTEREST -JOIN_WAKER -JoinHandle -JoinHandles -JoinMap Kotlin's kqueue latencies @@ -199,12 +169,7 @@ Lauck libc lifecycle lifo -lio_listio -ListEntry LOCAL_QUEUE_CAPACITY -LocalNotified -LocalOwnedTasks -LocalSet lookups LSB macOS @@ -237,16 +202,9 @@ notitifications ntasks null_mut ok -Ok -oneshot -Oneshot -OpenOptions ORed os overweighing -OwnedHandle -OwnedTask -OwnedTasks parker parking_lot parsers @@ -265,12 +223,8 @@ ptr ptr} qos RAII -RawHandle -RawSocket -read_exact readbuffer reallocations -recv recv's refactors refcount @@ -288,27 +242,18 @@ Runtime's runtime runtimes runtime's -rurururus rwlock rx scalability -ScheduledIo scheduler's SE_KERNEL_OBJECT SE_KERNEL_OBJECT} -seemms semver ServerOptions -SetConsoleCtrlHandler'. setpgid SetSecurityInfo shard_id sharded -ShardedList -SharedList -sheduler -shutdown_all -shutdown_cores SIGALRM SIGCHLD SIGHUP @@ -325,11 +270,7 @@ SIGUSR1 SIGUSR2 SIGWINCH SmallCrush -SO_LINGER -socker -socket2's Solaris -spawn_blocking spawn_local spawner Splitter @@ -339,7 +280,6 @@ src stabilised start_seek startup -StateCell stateful stderr stdin @@ -362,10 +302,7 @@ TCP tcp TcpListener TestU01 -thread_keep_alive threadpool -TimerEntry -TimerHandle timestamp timestamps TLS @@ -375,9 +312,6 @@ Tokio tokio tokio's Tokio's -TreeNode -try_join -try_send Tuple tuple tx @@ -387,11 +321,7 @@ udp UID unhandled unix -UnixDatagram -UnixListener -UnixStream unlink -Unowned unpark Unpark unparked @@ -399,7 +329,6 @@ unparking Unparks unparks unreceived -UnsafeCell unsafety Unsets unsynchronized @@ -414,7 +343,6 @@ versa versioned versioning vtable -Waker waker wakers Wakers @@ -423,10 +351,8 @@ wakeups WASI Wasi WASM -WatchStream Win32 windows_sys -with_locked_node_and_parent worker_threads workstealing write_dac @@ -434,8 +360,6 @@ write_dac_pipe write_dac_pipe_fail writebuffer WSAEMSGSIZE -x86 -x86_64 xorshift Xorshift xorshift64 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/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/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/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/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/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/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..485801ff84a 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. /// @@ -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. /// @@ -1555,7 +1555,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 /// @@ -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 d92ad5940e0..d28a0fe62fd 100644 --- a/tokio/src/net/unix/datagram/socket.rs +++ b/tokio/src/net/unix/datagram/socket.rs @@ -99,7 +99,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 @@ -425,12 +425,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`]. @@ -1131,7 +1131,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. /// @@ -1234,7 +1234,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 a7e9115eadd..07fb0dd32f5 100644 --- a/tokio/src/net/unix/listener.rs +++ b/tokio/src/net/unix/listener.rs @@ -72,7 +72,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 4821260ff6a..261e646145f 100644 --- a/tokio/src/net/unix/stream.rs +++ b/tokio/src/net/unix/stream.rs @@ -744,7 +744,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/process/mod.rs b/tokio/src/process/mod.rs index a688f63f213..f90d5998162 100644 --- a/tokio/src/process/mod.rs +++ b/tokio/src/process/mod.rs @@ -1128,9 +1128,9 @@ impl Child { /// 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..9c87725fb67 100644 --- a/tokio/src/runtime/blocking/pool.rs +++ b/tokio/src/runtime/blocking/pool.rs @@ -105,13 +105,13 @@ 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 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..7aa896f9eec 100644 --- a/tokio/src/runtime/handle.rs +++ b/tokio/src/runtime/handle.rs @@ -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/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/worker.rs b/tokio/src/runtime/scheduler/multi_thread/worker.rs index 313e2ea68f7..7e2ff95a374 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 @@ -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; diff --git a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs index 8d16418a80b..c0baa38315f 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 @@ -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/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..443e38501cf 100644 --- a/tokio/src/runtime/task/mod.rs +++ b/tokio/src/runtime/task/mod.rs @@ -2,29 +2,29 @@ //! //! 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. @@ -34,20 +34,20 @@ //! 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/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 69da84c30d1..0a776c32284 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,11 +81,11 @@ 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: +/// 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 +/// 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 { @@ -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/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/windows.rs b/tokio/src/signal/windows.rs index 2f70f98b15a..3cf569a65af 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -258,7 +258,7 @@ pub fn ctrl_close() -> io::Result { } /// Represents a listener which receives "ctrl-close" notitifications sent to the process -/// via 'SetConsoleCtrlHandler'. +/// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for /// this event. Moreover, the notifications **are coalesced** if they aren't processed @@ -355,7 +355,7 @@ pub fn ctrl_shutdown() -> io::Result { } /// Represents a listener which receives "ctrl-shutdown" notitifications sent to the process -/// via 'SetConsoleCtrlHandler'. +/// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for /// this event. Moreover, the notifications **are coalesced** if they aren't processed @@ -452,7 +452,7 @@ pub fn ctrl_logoff() -> io::Result { } /// Represents a listener which receives "ctrl-logoff" notitifications sent to the process -/// via 'SetConsoleCtrlHandler'. +/// 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/mpsc/mod.rs b/tokio/src/sync/mpsc/mod.rs index 052620be1a9..27c6828a79f 100644 --- a/tokio/src/sync/mpsc/mod.rs +++ b/tokio/src/sync/mpsc/mod.rs @@ -23,7 +23,7 @@ //! //! This channel is also suitable for the single-producer single-consumer //! use-case. (Unless you only need to send one message, in which case you -//! should use the [oneshot] channel.) +//! should use the [`oneshot`] channel.) //! //! # Disconnection //! @@ -66,7 +66,7 @@ //! in mind, but they can also be generalized to other kinds of channels. In //! general, any channel method that isn't marked async can be called anywhere, //! including outside of the runtime. For example, sending a message on a -//! [oneshot] channel from outside the runtime is perfectly fine. +//! [`oneshot`] channel from outside the runtime is perfectly fine. //! //! # Multiple runtimes //! 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..01c15800646 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>, diff --git a/tokio/src/task/mod.rs b/tokio/src/task/mod.rs index aefa395c044..c7510d8f202 100644 --- a/tokio/src/task/mod.rs +++ b/tokio/src/task/mod.rs @@ -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 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/sharded_list.rs b/tokio/src/util/sharded_list.rs index c1009db94c9..8c8e3ad0a02 100644 --- a/tokio/src/util/sharded_list.rs +++ b/tokio/src/util/sharded_list.rs @@ -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 { From 163e76511e197eb7f4dc97ed39f855eb6e5e2fea Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Thu, 25 Jan 2024 23:18:43 +0800 Subject: [PATCH 05/11] fix failing doc CI fix failing doc CI --- spellcheck.dic | 1 + tokio/src/sync/mpsc/mod.rs | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/spellcheck.dic b/spellcheck.dic index 0f2bf588cc9..7638c536dd7 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -202,6 +202,7 @@ notitifications ntasks null_mut ok +oneshot ORed os overweighing diff --git a/tokio/src/sync/mpsc/mod.rs b/tokio/src/sync/mpsc/mod.rs index 27c6828a79f..052620be1a9 100644 --- a/tokio/src/sync/mpsc/mod.rs +++ b/tokio/src/sync/mpsc/mod.rs @@ -23,7 +23,7 @@ //! //! This channel is also suitable for the single-producer single-consumer //! use-case. (Unless you only need to send one message, in which case you -//! should use the [`oneshot`] channel.) +//! should use the [oneshot] channel.) //! //! # Disconnection //! @@ -66,7 +66,7 @@ //! in mind, but they can also be generalized to other kinds of channels. In //! general, any channel method that isn't marked async can be called anywhere, //! including outside of the runtime. For example, sending a message on a -//! [`oneshot`] channel from outside the runtime is perfectly fine. +//! [oneshot] channel from outside the runtime is perfectly fine. //! //! # Multiple runtimes //! From b4482c82a5932a81c4eec327a7046385250fad9b Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Sun, 28 Jan 2024 15:46:36 +0800 Subject: [PATCH 06/11] Further trim down the dic size, revise a few formatting error, and revise the contributing.md Further trim down the dic size, revise a few formatting error, and revise the contributing.md --- CONTRIBUTING.md | 12 ++- spellcheck.dic | 86 +------------------ tokio-stream/src/stream_map.rs | 4 +- tokio-util/src/codec/framed.rs | 2 +- tokio/src/io/poll_evented.rs | 2 +- tokio/src/io/stdio_common.rs | 2 +- tokio/src/io/util/async_buf_read_ext.rs | 2 +- tokio/src/io/util/buf_reader.rs | 8 +- tokio/src/io/util/buf_writer.rs | 6 +- tokio/src/lib.rs | 28 +++--- tokio/src/loom/std/atomic_u64.rs | 2 +- tokio/src/macros/cfg.rs | 2 +- tokio/src/net/tcp/listener.rs | 2 +- tokio/src/net/udp.rs | 6 +- tokio/src/net/windows/named_pipe.rs | 4 +- tokio/src/process/mod.rs | 8 +- tokio/src/runtime/blocking/pool.rs | 2 +- tokio/src/runtime/handle.rs | 2 +- tokio/src/runtime/io/driver.rs | 2 +- .../runtime/scheduler/multi_thread/park.rs | 4 +- .../runtime/scheduler/multi_thread/queue.rs | 4 +- .../runtime/scheduler/multi_thread/stats.rs | 2 +- .../runtime/scheduler/multi_thread/worker.rs | 2 +- .../scheduler/multi_thread_alt/queue.rs | 4 +- .../scheduler/multi_thread_alt/stats.rs | 2 +- .../scheduler/multi_thread_alt/worker.rs | 2 +- tokio/src/runtime/task/harness.rs | 2 +- tokio/src/runtime/task/join.rs | 2 +- tokio/src/runtime/task/mod.rs | 2 +- tokio/src/runtime/task/trace/mod.rs | 4 +- tokio/src/runtime/time/entry.rs | 2 +- tokio/src/runtime/time/source.rs | 2 +- tokio/src/signal/ctrl_c.rs | 4 +- tokio/src/signal/mod.rs | 2 +- tokio/src/signal/registry.rs | 4 +- tokio/src/signal/unix.rs | 34 ++++---- tokio/src/signal/windows.rs | 2 +- tokio/src/task/local.rs | 2 +- tokio/src/task/mod.rs | 8 +- tokio/src/util/rand.rs | 4 +- 40 files changed, 101 insertions(+), 175 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d0d70d4e81..cd6f651a2ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -194,16 +194,24 @@ MIRIFLAGS="-Zmiri-disable-isolation -Zmiri-tag-raw-pointers" \ cargo +nightly miri test --features full --lib ``` -You can also perform spell-check on tokio codebase. For details of how to use the spellcheck tool, feel free to visit +### 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 spell check +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/spellcheck.dic b/spellcheck.dic index 7638c536dd7..041986cb343 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -1,4 +1,4 @@ -367 +286 \ ~ ~4 @@ -34,8 +34,6 @@ ambiant amongst api APIs -as_raw_handle -AsRawHandle assert_eq async awaitable @@ -47,14 +45,11 @@ backtracing binded bitfield bitfields -block_in_place -block_on Blockingly bool boolean broadcasted buf -CANCELLED cancelled cancelling Cancelling @@ -66,27 +61,19 @@ codec codecs combinator combinators -condvar Config config connectionless const -coroutines cpu cpus -CRLF -CTRL -current_thread Customizable -DACL_SECURITY_INFORMATION Datagram datagram datagrams -Dealloc deallocate deallocated Deallocates -debuginfo decrementing dequeued deregister @@ -111,17 +98,9 @@ enqueued EntryInner enum eof -EOF -epoll -Erlang's -ERROR_ACCESS_DENIED -ERROR_SUCCESS errored -eventId -eventIds EWMA expirations -f64 fcntl fd's FIFOs @@ -137,13 +116,11 @@ functionalities fuzz_linked_list getters GID -goroutines Growable gzip hashmaps HashMaps hashsets -i32 ie Illumos impl @@ -162,16 +139,12 @@ IP IPv4 IPv6 iteratively -Kotlin's -kqueue latencies Lauck libc lifecycle lifo -LOCAL_QUEUE_CAPACITY lookups -LSB macOS MacOS Marsaglia's @@ -183,8 +156,6 @@ misconfigured mock's mpmc mpsc -MSB -MSRV Multi multi multicast @@ -193,38 +164,27 @@ mut mutex Mutex Nagle -named_pipe nonblocking nondecreasing noop -not_after notitifications ntasks -null_mut ok oneshot ORed os overweighing parker -parking_lot parsers peekable PGID PID -PIPE_NAME -pipe_template plaintext -poll_accept -poll_complete poller POSIX proxied -ptr -ptr} qos RAII -readbuffer reallocations recv's refactors @@ -238,8 +198,6 @@ reregistering resize resized RMW -Runtime -Runtime's runtime runtimes runtime's @@ -247,39 +205,20 @@ rwlock rx scalability scheduler's -SE_KERNEL_OBJECT -SE_KERNEL_OBJECT} semver -ServerOptions setpgid -SetSecurityInfo shard_id sharded -SIGALRM -SIGCHLD -SIGHUP -SIGINFO -SIGINT -SIGIO -SIGKILL signalled signalling -SIGPIPE -SIGQUIT -SIGTERM -SIGUSR1 -SIGUSR2 -SIGWINCH SmallCrush Solaris -spawn_local spawner Splitter spmc spsc src stabilised -start_seek startup stateful stderr @@ -301,7 +240,6 @@ syscall syscalls TCP tcp -TcpListener TestU01 threadpool timestamp @@ -316,7 +254,6 @@ Tokio's Tuple tuple tx -u64 UDP udp UID @@ -335,8 +272,6 @@ Unsets unsynchronized untrusted usecases -usize -utf8 Valgrind Varghese vec @@ -349,21 +284,4 @@ wakers Wakers wakeup wakeups -WASI -Wasi -WASM -Win32 -windows_sys -worker_threads -workstealing -write_dac -write_dac_pipe -write_dac_pipe_fail -writebuffer -WSAEMSGSIZE -xorshift -Xorshift -xorshift64 -yield_now -{io -{SetSecurityInfo \ No newline at end of file +workstealing \ No newline at end of file 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-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/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/lib.rs b/tokio/src/lib.rs index 3a979396831..c1daa2b26f4 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 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/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/udp.rs b/tokio/src/net/udp.rs index 485801ff84a..9192317bbcc 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -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. /// @@ -1561,7 +1561,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. /// @@ -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. /// 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 f90d5998162..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,7 +1125,7 @@ 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 diff --git a/tokio/src/runtime/blocking/pool.rs b/tokio/src/runtime/blocking/pool.rs index 9c87725fb67..c74aea76568 100644 --- a/tokio/src/runtime/blocking/pool.rs +++ b/tokio/src/runtime/blocking/pool.rs @@ -114,7 +114,7 @@ struct Shared { /// 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/handle.rs b/tokio/src/runtime/handle.rs index 7aa896f9eec..7a866367ae6 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`: /// 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/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 7e2ff95a374..2bd1b5678ea 100644 --- a/tokio/src/runtime/scheduler/multi_thread/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread/worker.rs @@ -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 c0baa38315f..e24d0b2e541 100644 --- a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs @@ -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. 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/mod.rs b/tokio/src/runtime/task/mod.rs index 443e38501cf..6b05f4d7d5c 100644 --- a/tokio/src/runtime/task/mod.rs +++ b/tokio/src/runtime/task/mod.rs @@ -31,7 +31,7 @@ //! //! # 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. 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/time/entry.rs b/tokio/src/runtime/time/entry.rs index 0a776c32284..0998b53011d 100644 --- a/tokio/src/runtime/time/entry.rs +++ b/tokio/src/runtime/time/entry.rs @@ -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. 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/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 3cf569a65af..e6ca599de70 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"))))] diff --git a/tokio/src/task/local.rs b/tokio/src/task/local.rs index 01c15800646..a40708d08c2 100644 --- a/tokio/src/task/local.rs +++ b/tokio/src/task/local.rs @@ -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 c7510d8f202..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: @@ -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/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)] From cafb489238074edd3eda44ce4a52a43cee160bbc Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Sun, 28 Jan 2024 15:52:22 +0800 Subject: [PATCH 07/11] add newline for ci.yml, cargo.toml, spellcheck.dic, spellcheck.toml add newline for ci.yml, cargo.toml, spellcheck.dic, spellcheck.toml --- .github/workflows/ci.yml | 3 ++- Cargo.toml | 3 ++- spellcheck.dic | 3 ++- spellcheck.toml | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8880fd775b0..c0e728e63b0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1012,4 +1012,5 @@ jobs: tool: cargo-spellcheck - uses: actions/checkout@v4 - name: Run cargo-spellcheck - run: cargo spellcheck --code 1 \ No newline at end of file + run: cargo spellcheck --code 1 + diff --git a/Cargo.toml b/Cargo.toml index 508bb54a696..d8ac248189d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -16,4 +16,5 @@ members = [ ] [workspace.metadata.spellcheck] -config = "spellcheck.toml" \ No newline at end of file +config = "spellcheck.toml" + diff --git a/spellcheck.dic b/spellcheck.dic index 041986cb343..b978af4f1ee 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -284,4 +284,5 @@ wakers Wakers wakeup wakeups -workstealing \ No newline at end of file +workstealing + diff --git a/spellcheck.toml b/spellcheck.toml index 410c1c8f9bb..fb14364be0c 100644 --- a/spellcheck.toml +++ b/spellcheck.toml @@ -9,4 +9,5 @@ skip_os_lookups = true use_builtin = true [Hunspell.quirks] -allow_concatenation = true \ No newline at end of file +allow_concatenation = true + From 5f0f103df36256d0c84c943772df409e4f509560 Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Sun, 28 Jan 2024 21:42:26 +0800 Subject: [PATCH 08/11] Backticked more words & trim down dictionary Backticked more words & trim down dictionary --- spellcheck.dic | 23 +------------------ tokio-macros/src/entry.rs | 2 +- tokio-util/src/io/mod.rs | 2 +- tokio-util/src/task/task_tracker.rs | 2 +- tokio/src/fs/mocks.rs | 2 +- tokio/src/io/async_fd.rs | 2 +- tokio/src/io/mod.rs | 6 ++--- tokio/src/io/util/read_line.rs | 2 +- tokio/src/lib.rs | 18 +++++++-------- tokio/src/loom/std/mutex.rs | 2 +- tokio/src/net/udp.rs | 14 +++++------ tokio/src/process/mod.rs | 2 +- tokio/src/runtime/blocking/mod.rs | 4 ++-- tokio/src/runtime/context.rs | 2 +- tokio/src/runtime/handle.rs | 2 +- .../runtime/scheduler/multi_thread/worker.rs | 6 ++--- .../scheduler/multi_thread_alt/worker.rs | 2 +- tokio/src/runtime/task/core.rs | 4 ++-- tokio/src/runtime/task/mod.rs | 8 +++---- tokio/src/runtime/time/entry.rs | 2 +- tokio/src/signal/windows.rs | 6 ++--- tokio/src/sync/mpsc/block.rs | 2 +- tokio/src/task/blocking.rs | 4 ++-- tokio/src/task/mod.rs | 6 ++--- tokio/src/util/linked_list.rs | 2 +- tokio/src/util/sharded_list.rs | 2 +- 26 files changed, 54 insertions(+), 75 deletions(-) diff --git a/spellcheck.dic b/spellcheck.dic index b978af4f1ee..08f8633402d 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -1,4 +1,4 @@ -286 +265 \ ~ ~4 @@ -32,9 +32,6 @@ Adaptors AIO ambiant amongst -api -APIs -assert_eq async awaitable backend @@ -43,17 +40,11 @@ backtrace backtraces backtracing binded -bitfield -bitfields Blockingly -bool -boolean broadcasted -buf cancelled cancelling Cancelling -cfg CLI cloneable codebase @@ -61,10 +52,6 @@ codec codecs combinator combinators -Config -config -connectionless -const cpu cpus Customizable @@ -110,10 +97,7 @@ filesystems fn fns FreeBSD -frontend -fs functionalities -fuzz_linked_list getters GID Growable @@ -167,7 +151,6 @@ Nagle nonblocking nondecreasing noop -notitifications ntasks ok oneshot @@ -204,10 +187,6 @@ runtime's rwlock rx scalability -scheduler's -semver -setpgid -shard_id sharded signalled signalling diff --git a/tokio-macros/src/entry.rs b/tokio-macros/src/entry.rs index ed782ad38f6..828f779107c 100644 --- a/tokio-macros/src/entry.rs +++ b/tokio-macros/src/entry.rs @@ -32,7 +32,7 @@ struct FinalConfig { crate_name: Option, } -/// Config used in case of the attribute not being able to build a valid config +/// `Config` used in case of the attribute not being able to build a valid `config` const DEFAULT_ERROR_CONFIG: FinalConfig = FinalConfig { flavor: RuntimeFlavor::CurrentThread, worker_threads: None, diff --git a/tokio-util/src/io/mod.rs b/tokio-util/src/io/mod.rs index 6c40d739014..4f1584184c3 100644 --- a/tokio-util/src/io/mod.rs +++ b/tokio-util/src/io/mod.rs @@ -4,7 +4,7 @@ //! allow converting between a hyper [`Body`] and [`AsyncRead`]. //! //! The [`SyncIoBridge`] type converts from the world of async I/O -//! to synchronous I/O; this may often come up when using synchronous APIs +//! to synchronous I/O; this may often come up when using synchronous `APIs` //! inside [`tokio::task::spawn_blocking`]. //! //! [`Body`]: https://docs.rs/hyper/0.13/hyper/struct.Body.html diff --git a/tokio-util/src/task/task_tracker.rs b/tokio-util/src/task/task_tracker.rs index d8f3bb4859a..8e3b6206283 100644 --- a/tokio-util/src/task/task_tracker.rs +++ b/tokio-util/src/task/task_tracker.rs @@ -23,7 +23,7 @@ use tokio::{ /// `CancellationToken` is used to signal to tasks that they should shut down, and the /// `TaskTracker` is used to wait for them to finish shutting down. /// -/// The `TaskTracker` will also keep track of a `closed` boolean. This is used to handle the case +/// The `TaskTracker` will also keep track of a `closed` `boolean`. This is used to handle the case /// where the `TaskTracker` is empty, but we don't want to shut down yet. This means that the /// [`wait`] method will wait until *both* of the following happen at the same time: /// diff --git a/tokio/src/fs/mocks.rs b/tokio/src/fs/mocks.rs index b718ed54f95..531e8a8c872 100644 --- a/tokio/src/fs/mocks.rs +++ b/tokio/src/fs/mocks.rs @@ -1,4 +1,4 @@ -//! Mock version of std::fs::File; +//! Mock version of `std::fs::File`; use mockall::mock; use crate::sync::oneshot; diff --git a/tokio/src/io/async_fd.rs b/tokio/src/io/async_fd.rs index aaf17584198..6c400242b22 100644 --- a/tokio/src/io/async_fd.rs +++ b/tokio/src/io/async_fd.rs @@ -55,7 +55,7 @@ use std::{task::Context, task::Poll}; /// /// ## Use with to a poll-based API /// -/// In some cases it may be desirable to use `AsyncFd` from APIs similar to +/// In some cases it may be desirable to use `AsyncFd` from `APIs` similar to /// [`TcpStream::poll_read_ready`]. The [`AsyncFd::poll_read_ready`] and /// [`AsyncFd::poll_write_ready`] functions are provided for this purpose. /// Because these functions don't create a future to hold their state, they have diff --git a/tokio/src/io/mod.rs b/tokio/src/io/mod.rs index 5e903c04842..553b57d398d 100644 --- a/tokio/src/io/mod.rs +++ b/tokio/src/io/mod.rs @@ -150,11 +150,11 @@ //! //! # Standard input and output //! -//! Tokio provides asynchronous APIs to standard [input], [output], and [error]. -//! These APIs are very similar to the ones provided by `std`, but they also +//! Tokio provides asynchronous `APIs` to standard [input], [output], and [error]. +//! These `APIs` are very similar to the ones provided by `std`, but they also //! implement [`AsyncRead`] and [`AsyncWrite`]. //! -//! Note that the standard input / output APIs **must** be used from the +//! Note that the standard input / output `APIs` **must** be used from the //! context of the Tokio runtime, as they require Tokio-specific features to //! function. Calling these functions outside of a Tokio runtime will panic. //! 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/lib.rs b/tokio/src/lib.rs index c1daa2b26f4..f0ac5741512 100644 --- a/tokio/src/lib.rs +++ b/tokio/src/lib.rs @@ -28,7 +28,7 @@ //! * Tools for [working with asynchronous tasks][tasks], including //! [synchronization primitives and channels][sync] and [timeouts, sleeps, and //! intervals][time]. -//! * APIs for [performing asynchronous I/O][io], including [TCP and UDP][net] sockets, +//! * `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`, @@ -52,7 +52,7 @@ //! //! Tokio consists of a number of modules that provide a range of functionality //! essential for implementing asynchronous applications in Rust. In this -//! section, we will take a brief tour of Tokio, summarizing the major APIs and +//! section, we will take a brief tour of Tokio, summarizing the major `APIs` and //! their uses. //! //! The easiest way to get started is to enable all features. Do this by @@ -149,7 +149,7 @@ //! Finally, Tokio provides a _runtime_ for executing asynchronous tasks. Most //! applications can use the [`#[tokio::main]`][main] macro to run their code on the //! Tokio runtime. However, this macro provides only basic configuration options. As -//! an alternative, the [`tokio::runtime`] module provides more powerful APIs for configuring +//! an alternative, the [`tokio::runtime`] module provides more powerful `APIs` for configuring //! and managing runtimes. You should use that module if the `#[tokio::main]` macro doesn't //! provide the functionality you need. //! @@ -234,13 +234,13 @@ //! functions for working with these traits, forming as an asynchronous //! counterpart to [`std::io`]. //! -//! Tokio also includes APIs for performing various kinds of I/O and interacting +//! Tokio also includes `APIs` for performing various kinds of I/O and interacting //! with the operating system asynchronously. These include: //! //! * [`tokio::net`], which contains non-blocking versions of [TCP], [UDP], and //! [Unix Domain Sockets][UDS] (enabled by the "net" feature flag), //! * [`tokio::fs`], similar to [`std::fs`] but for performing filesystem I/O -//! asynchronously (enabled by the "fs" feature flag), +//! asynchronously (enabled by the `"fs"` feature flag), //! * [`tokio::signal`], for asynchronously handling Unix and Windows OS signals //! (enabled by the "signal" feature flag), //! * [`tokio::process`], for spawning and managing child processes (enabled by @@ -309,7 +309,7 @@ //! case. Below is a list of the available feature flags. You may also notice //! above each function, struct and trait there is listed one or more feature flags //! that are required for that item to be used. If you are new to Tokio it is -//! recommended that you use the `full` feature flag which will enable all public APIs. +//! recommended that you use the `full` feature flag which will enable all public `APIs`. //! Beware though that this will pull in many extra dependencies that you may not //! need. //! @@ -333,7 +333,7 @@ //! - `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 +//! 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 @@ -356,7 +356,7 @@ //! This flag enables **unstable** features. The public API of these features //! may break in 1.x releases. To enable these features, the `--cfg //! tokio_unstable` argument must be passed to `rustc` when compiling. This -//! serves to explicitly opt-in to features which may break semver conventions, +//! serves to explicitly opt-in to features which may break `semver` conventions, //! since Cargo [does not yet directly support such opt-ins][unstable features]. //! //! You can specify it in your project's `.cargo/config.toml` file: @@ -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/mutex.rs b/tokio/src/loom/std/mutex.rs index 7b8f9ba1e24..820448ba1de 100644 --- a/tokio/src/loom/std/mutex.rs +++ b/tokio/src/loom/std/mutex.rs @@ -1,7 +1,7 @@ use std::sync::{self, MutexGuard, TryLockError}; /// Adapter for `std::Mutex` that removes the poisoning aspects -/// from its api. +/// from its `api`. #[derive(Debug)] pub(crate) struct Mutex(sync::Mutex); diff --git a/tokio/src/net/udp.rs b/tokio/src/net/udp.rs index 9192317bbcc..9f182e7738e 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -13,7 +13,7 @@ cfg_io_util! { cfg_net! { /// A UDP socket. /// - /// UDP is "connectionless", unlike TCP. Meaning, regardless of what address you've bound to, a `UdpSocket` + /// UDP is `"connectionless"`, unlike TCP. Meaning, regardless of what address you've bound to, a `UdpSocket` /// is free to communicate with many different remotes. In tokio there are basically two main ways to use `UdpSocket`: /// /// * one to many: [`bind`](`UdpSocket::bind`) and use [`send_to`](`UdpSocket::send_to`) @@ -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. /// @@ -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. /// diff --git a/tokio/src/process/mod.rs b/tokio/src/process/mod.rs index 0fad67cd01a..995ec88cba6 100644 --- a/tokio/src/process/mod.rs +++ b/tokio/src/process/mod.rs @@ -4,7 +4,7 @@ //! [`std::process::Command`] type in the standard library, but provides asynchronous versions of //! functions that create processes. These functions (`spawn`, `status`, `output` and their //! variants) return "future aware" types that interoperate with Tokio. The asynchronous process -//! support is provided through signal handling on Unix and system APIs on Windows. +//! support is provided through signal handling on Unix and system `APIs` on Windows. //! //! [`std::process::Command`]: std::process::Command //! diff --git a/tokio/src/runtime/blocking/mod.rs b/tokio/src/runtime/blocking/mod.rs index c42924be77d..c5bcc5fb5cc 100644 --- a/tokio/src/runtime/blocking/mod.rs +++ b/tokio/src/runtime/blocking/mod.rs @@ -1,5 +1,5 @@ -//! Abstracts out the APIs necessary to `Runtime` for integrating the blocking -//! pool. When the `blocking` feature flag is **not** enabled, these APIs are +//! Abstracts out the `APIs` necessary to `Runtime` for integrating the blocking +//! pool. When the `blocking` feature flag is **not** enabled, these `APIs` are //! shells. This isolates the complexity of dealing with conditional //! compilation. diff --git a/tokio/src/runtime/context.rs b/tokio/src/runtime/context.rs index 62e4fc9474c..e142629c210 100644 --- a/tokio/src/runtime/context.rs +++ b/tokio/src/runtime/context.rs @@ -42,7 +42,7 @@ struct Context { #[cfg(feature = "rt")] current: current::HandleCell, - /// Handle to the scheduler's internal "context" + /// Handle to the `scheduler's` internal "context" #[cfg(feature = "rt")] scheduler: Scoped, diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs index 7a866367ae6..7e7e5636c80 100644 --- a/tokio/src/runtime/handle.rs +++ b/tokio/src/runtime/handle.rs @@ -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.: diff --git a/tokio/src/runtime/scheduler/multi_thread/worker.rs b/tokio/src/runtime/scheduler/multi_thread/worker.rs index 2bd1b5678ea..235087f4b3a 100644 --- a/tokio/src/runtime/scheduler/multi_thread/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread/worker.rs @@ -88,7 +88,7 @@ cfg_not_taskdump! { /// A scheduler worker pub(super) struct Worker { - /// Reference to scheduler's handle + /// Reference to `scheduler's` handle handle: Arc, /// Index holding this worker's remote state @@ -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, } @@ -995,7 +995,7 @@ impl Core { } impl Worker { - /// Returns a reference to the scheduler's injection queue. + /// Returns a reference to the `scheduler's` injection queue. fn inject(&self) -> &inject::Shared> { &self.handle.shared.inject } diff --git a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs index e24d0b2e541..54c6b0ed7ba 100644 --- a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs @@ -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, } 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/mod.rs b/tokio/src/runtime/task/mod.rs index 6b05f4d7d5c..9238d52c68b 100644 --- a/tokio/src/runtime/task/mod.rs +++ b/tokio/src/runtime/task/mod.rs @@ -31,8 +31,8 @@ //! //! # State //! -//! The task stores its state in an atomic `usize` with various bitfields for the -//! necessary information. The state has the following bitfields: +//! 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. //! This bit functions as a lock around the task. @@ -68,7 +68,7 @@ //! synchronization. //! //! * If COMPLETE is one, then the `JoinHandle` has exclusive access to the -//! stage field. If COMPLETE is zero, then the RUNNING bitfield functions as +//! 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. //! @@ -159,7 +159,7 @@ //! //! Calling poll from inside a shutdown call or vice-versa is not prevented by //! the API exposed by the task module, so this has to be safe. In either case, -//! the lock in the RUNNING bitfield makes the inner call return immediately. If +//! the lock in the RUNNING `bitfield` makes the inner call return immediately. If //! the inner call is a `shutdown` call, then the CANCELLED bit is set, and the //! poll call will notice it when the poll finishes, and the task is cancelled //! at that point. diff --git a/tokio/src/runtime/time/entry.rs b/tokio/src/runtime/time/entry.rs index 0998b53011d..48d5f4cf7d7 100644 --- a/tokio/src/runtime/time/entry.rs +++ b/tokio/src/runtime/time/entry.rs @@ -332,7 +332,7 @@ pub(crate) struct TimerHandle { pub(super) type EntryList = crate::util::linked_list::LinkedList; /// The shared state structure of a timer. This structure is shared between the -/// frontend (`Entry`) and driver backend. +/// `frontend` (`Entry`) and driver backend. /// /// Note that this structure is located inside the `TimerEntry` structure. pub(crate) struct TimerShared { diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index e6ca599de70..d8af9b4c9d9 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -257,7 +257,7 @@ pub fn ctrl_close() -> io::Result { }) } -/// Represents a listener which receives "ctrl-close" notitifications sent to the process +/// Represents a listener which receives "ctrl-close" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for @@ -354,7 +354,7 @@ pub fn ctrl_shutdown() -> io::Result { }) } -/// Represents a listener which receives "ctrl-shutdown" notitifications sent to the process +/// Represents a listener which receives "ctrl-shutdown" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for @@ -451,7 +451,7 @@ pub fn ctrl_logoff() -> io::Result { }) } -/// Represents a listener which receives "ctrl-logoff" notitifications sent to the process +/// Represents a listener which receives "ctrl-logoff" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for diff --git a/tokio/src/sync/mpsc/block.rs b/tokio/src/sync/mpsc/block.rs index befcfd29efa..0598f54ab34 100644 --- a/tokio/src/sync/mpsc/block.rs +++ b/tokio/src/sync/mpsc/block.rs @@ -30,7 +30,7 @@ struct BlockHeader { /// The next block in the linked list. next: AtomicPtr>, - /// Bitfield tracking slots that are ready to have their values consumed. + /// `Bitfield` tracking slots that are ready to have their values consumed. ready_slots: AtomicUsize, /// The observed `tail_position` value *after* the block has been passed by diff --git a/tokio/src/task/blocking.rs b/tokio/src/task/blocking.rs index 1cce466394e..ddd5e1c463c 100644 --- a/tokio/src/task/blocking.rs +++ b/tokio/src/task/blocking.rs @@ -121,9 +121,9 @@ cfg_rt! { /// /// Note that if you are using the single threaded runtime, this function will /// still spawn additional threads for blocking operations. The current-thread - /// scheduler's single thread is only used for asynchronous code. + /// `scheduler's` single thread is only used for asynchronous code. /// - /// # Related APIs and patterns for bridging asynchronous and blocking code + /// # Related `APIs` and patterns for bridging asynchronous and blocking code /// /// In simple cases, it is sufficient to have the closure accept input /// parameters at creation time and return a single value (or struct/tuple, etc.). diff --git a/tokio/src/task/mod.rs b/tokio/src/task/mod.rs index 806b9aebe76..347fed2c078 100644 --- a/tokio/src/task/mod.rs +++ b/tokio/src/task/mod.rs @@ -33,7 +33,7 @@ //! yield instead, allowing the Tokio runtime to schedule another task. Tasks //! should generally not perform system calls or other operations that could //! block a thread, as this would prevent other tasks running on the same -//! thread from executing as well. Instead, this module provides APIs for +//! thread from executing as well. Instead, this module provides `APIs` for //! running blocking operations in an asynchronous context. //! //! [rt]: crate::runtime @@ -44,7 +44,7 @@ //! //! ## Working with Tasks //! -//! This module provides the following APIs for working with tasks: +//! This module provides the following `APIs` for working with tasks: //! //! ### Spawning //! @@ -159,7 +159,7 @@ //! on a thread that is also running other tasks would block the entire thread, //! preventing other tasks from running. //! -//! Instead, Tokio provides two APIs for running blocking operations in an +//! Instead, Tokio provides two `APIs` for running blocking operations in an //! asynchronous context: [`task::spawn_blocking`] and [`task::block_in_place`]. //! //! Be aware that if you call a non-async method from async code, that non-async diff --git a/tokio/src/util/linked_list.rs b/tokio/src/util/linked_list.rs index 0ed2b616456..24be18491ab 100644 --- a/tokio/src/util/linked_list.rs +++ b/tokio/src/util/linked_list.rs @@ -3,7 +3,7 @@ //! An intrusive double linked list of data. //! //! The data structure supports tracking pinned nodes. Most of the data -//! structure's APIs are `unsafe` as they require the caller to ensure the +//! structure's `APIs` are `unsafe` as they require the caller to ensure the //! specified node is actually contained by the list. use core::cell::UnsafeCell; diff --git a/tokio/src/util/sharded_list.rs b/tokio/src/util/sharded_list.rs index 8c8e3ad0a02..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); From b04e46f378f7ded7ac3b5a0a8f2f856424b31720 Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Sun, 28 Jan 2024 23:33:17 +0800 Subject: [PATCH 09/11] Revert "Backticked more words & trim down dictionary" This reverts commit 5f0f103df36256d0c84c943772df409e4f509560. --- spellcheck.dic | 23 ++++++++++++++++++- tokio-macros/src/entry.rs | 2 +- tokio-util/src/io/mod.rs | 2 +- tokio-util/src/task/task_tracker.rs | 2 +- tokio/src/fs/mocks.rs | 2 +- tokio/src/io/async_fd.rs | 2 +- tokio/src/io/mod.rs | 6 ++--- tokio/src/io/util/read_line.rs | 2 +- tokio/src/lib.rs | 18 +++++++-------- tokio/src/loom/std/mutex.rs | 2 +- tokio/src/net/udp.rs | 14 +++++------ tokio/src/process/mod.rs | 2 +- tokio/src/runtime/blocking/mod.rs | 4 ++-- tokio/src/runtime/context.rs | 2 +- tokio/src/runtime/handle.rs | 2 +- .../runtime/scheduler/multi_thread/worker.rs | 6 ++--- .../scheduler/multi_thread_alt/worker.rs | 2 +- tokio/src/runtime/task/core.rs | 4 ++-- tokio/src/runtime/task/mod.rs | 8 +++---- tokio/src/runtime/time/entry.rs | 2 +- tokio/src/signal/windows.rs | 6 ++--- tokio/src/sync/mpsc/block.rs | 2 +- tokio/src/task/blocking.rs | 4 ++-- tokio/src/task/mod.rs | 6 ++--- tokio/src/util/linked_list.rs | 2 +- tokio/src/util/sharded_list.rs | 2 +- 26 files changed, 75 insertions(+), 54 deletions(-) diff --git a/spellcheck.dic b/spellcheck.dic index 08f8633402d..b978af4f1ee 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -1,4 +1,4 @@ -265 +286 \ ~ ~4 @@ -32,6 +32,9 @@ Adaptors AIO ambiant amongst +api +APIs +assert_eq async awaitable backend @@ -40,11 +43,17 @@ backtrace backtraces backtracing binded +bitfield +bitfields Blockingly +bool +boolean broadcasted +buf cancelled cancelling Cancelling +cfg CLI cloneable codebase @@ -52,6 +61,10 @@ codec codecs combinator combinators +Config +config +connectionless +const cpu cpus Customizable @@ -97,7 +110,10 @@ filesystems fn fns FreeBSD +frontend +fs functionalities +fuzz_linked_list getters GID Growable @@ -151,6 +167,7 @@ Nagle nonblocking nondecreasing noop +notitifications ntasks ok oneshot @@ -187,6 +204,10 @@ runtime's rwlock rx scalability +scheduler's +semver +setpgid +shard_id sharded signalled signalling diff --git a/tokio-macros/src/entry.rs b/tokio-macros/src/entry.rs index 828f779107c..ed782ad38f6 100644 --- a/tokio-macros/src/entry.rs +++ b/tokio-macros/src/entry.rs @@ -32,7 +32,7 @@ struct FinalConfig { crate_name: Option, } -/// `Config` used in case of the attribute not being able to build a valid `config` +/// Config used in case of the attribute not being able to build a valid config const DEFAULT_ERROR_CONFIG: FinalConfig = FinalConfig { flavor: RuntimeFlavor::CurrentThread, worker_threads: None, diff --git a/tokio-util/src/io/mod.rs b/tokio-util/src/io/mod.rs index 4f1584184c3..6c40d739014 100644 --- a/tokio-util/src/io/mod.rs +++ b/tokio-util/src/io/mod.rs @@ -4,7 +4,7 @@ //! allow converting between a hyper [`Body`] and [`AsyncRead`]. //! //! The [`SyncIoBridge`] type converts from the world of async I/O -//! to synchronous I/O; this may often come up when using synchronous `APIs` +//! to synchronous I/O; this may often come up when using synchronous APIs //! inside [`tokio::task::spawn_blocking`]. //! //! [`Body`]: https://docs.rs/hyper/0.13/hyper/struct.Body.html diff --git a/tokio-util/src/task/task_tracker.rs b/tokio-util/src/task/task_tracker.rs index 8e3b6206283..d8f3bb4859a 100644 --- a/tokio-util/src/task/task_tracker.rs +++ b/tokio-util/src/task/task_tracker.rs @@ -23,7 +23,7 @@ use tokio::{ /// `CancellationToken` is used to signal to tasks that they should shut down, and the /// `TaskTracker` is used to wait for them to finish shutting down. /// -/// The `TaskTracker` will also keep track of a `closed` `boolean`. This is used to handle the case +/// The `TaskTracker` will also keep track of a `closed` boolean. This is used to handle the case /// where the `TaskTracker` is empty, but we don't want to shut down yet. This means that the /// [`wait`] method will wait until *both* of the following happen at the same time: /// diff --git a/tokio/src/fs/mocks.rs b/tokio/src/fs/mocks.rs index 531e8a8c872..b718ed54f95 100644 --- a/tokio/src/fs/mocks.rs +++ b/tokio/src/fs/mocks.rs @@ -1,4 +1,4 @@ -//! Mock version of `std::fs::File`; +//! Mock version of std::fs::File; use mockall::mock; use crate::sync::oneshot; diff --git a/tokio/src/io/async_fd.rs b/tokio/src/io/async_fd.rs index 6c400242b22..aaf17584198 100644 --- a/tokio/src/io/async_fd.rs +++ b/tokio/src/io/async_fd.rs @@ -55,7 +55,7 @@ use std::{task::Context, task::Poll}; /// /// ## Use with to a poll-based API /// -/// In some cases it may be desirable to use `AsyncFd` from `APIs` similar to +/// In some cases it may be desirable to use `AsyncFd` from APIs similar to /// [`TcpStream::poll_read_ready`]. The [`AsyncFd::poll_read_ready`] and /// [`AsyncFd::poll_write_ready`] functions are provided for this purpose. /// Because these functions don't create a future to hold their state, they have diff --git a/tokio/src/io/mod.rs b/tokio/src/io/mod.rs index 553b57d398d..5e903c04842 100644 --- a/tokio/src/io/mod.rs +++ b/tokio/src/io/mod.rs @@ -150,11 +150,11 @@ //! //! # Standard input and output //! -//! Tokio provides asynchronous `APIs` to standard [input], [output], and [error]. -//! These `APIs` are very similar to the ones provided by `std`, but they also +//! Tokio provides asynchronous APIs to standard [input], [output], and [error]. +//! These APIs are very similar to the ones provided by `std`, but they also //! implement [`AsyncRead`] and [`AsyncWrite`]. //! -//! Note that the standard input / output `APIs` **must** be used from the +//! Note that the standard input / output APIs **must** be used from the //! context of the Tokio runtime, as they require Tokio-specific features to //! function. Calling these functions outside of a Tokio runtime will panic. //! diff --git a/tokio/src/io/util/read_line.rs b/tokio/src/io/util/read_line.rs index eacc7d59602..e641f515324 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/lib.rs b/tokio/src/lib.rs index f0ac5741512..c1daa2b26f4 100644 --- a/tokio/src/lib.rs +++ b/tokio/src/lib.rs @@ -28,7 +28,7 @@ //! * Tools for [working with asynchronous tasks][tasks], including //! [synchronization primitives and channels][sync] and [timeouts, sleeps, and //! intervals][time]. -//! * `APIs` for [performing asynchronous I/O][io], including [TCP and UDP][net] sockets, +//! * 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`, @@ -52,7 +52,7 @@ //! //! Tokio consists of a number of modules that provide a range of functionality //! essential for implementing asynchronous applications in Rust. In this -//! section, we will take a brief tour of Tokio, summarizing the major `APIs` and +//! section, we will take a brief tour of Tokio, summarizing the major APIs and //! their uses. //! //! The easiest way to get started is to enable all features. Do this by @@ -149,7 +149,7 @@ //! Finally, Tokio provides a _runtime_ for executing asynchronous tasks. Most //! applications can use the [`#[tokio::main]`][main] macro to run their code on the //! Tokio runtime. However, this macro provides only basic configuration options. As -//! an alternative, the [`tokio::runtime`] module provides more powerful `APIs` for configuring +//! an alternative, the [`tokio::runtime`] module provides more powerful APIs for configuring //! and managing runtimes. You should use that module if the `#[tokio::main]` macro doesn't //! provide the functionality you need. //! @@ -234,13 +234,13 @@ //! functions for working with these traits, forming as an asynchronous //! counterpart to [`std::io`]. //! -//! Tokio also includes `APIs` for performing various kinds of I/O and interacting +//! Tokio also includes APIs for performing various kinds of I/O and interacting //! with the operating system asynchronously. These include: //! //! * [`tokio::net`], which contains non-blocking versions of [TCP], [UDP], and //! [Unix Domain Sockets][UDS] (enabled by the "net" feature flag), //! * [`tokio::fs`], similar to [`std::fs`] but for performing filesystem I/O -//! asynchronously (enabled by the `"fs"` feature flag), +//! asynchronously (enabled by the "fs" feature flag), //! * [`tokio::signal`], for asynchronously handling Unix and Windows OS signals //! (enabled by the "signal" feature flag), //! * [`tokio::process`], for spawning and managing child processes (enabled by @@ -309,7 +309,7 @@ //! case. Below is a list of the available feature flags. You may also notice //! above each function, struct and trait there is listed one or more feature flags //! that are required for that item to be used. If you are new to Tokio it is -//! recommended that you use the `full` feature flag which will enable all public `APIs`. +//! recommended that you use the `full` feature flag which will enable all public APIs. //! Beware though that this will pull in many extra dependencies that you may not //! need. //! @@ -333,7 +333,7 @@ //! - `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 +//! 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 @@ -356,7 +356,7 @@ //! This flag enables **unstable** features. The public API of these features //! may break in 1.x releases. To enable these features, the `--cfg //! tokio_unstable` argument must be passed to `rustc` when compiling. This -//! serves to explicitly opt-in to features which may break `semver` conventions, +//! serves to explicitly opt-in to features which may break semver conventions, //! since Cargo [does not yet directly support such opt-ins][unstable features]. //! //! You can specify it in your project's `.cargo/config.toml` file: @@ -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/mutex.rs b/tokio/src/loom/std/mutex.rs index 820448ba1de..7b8f9ba1e24 100644 --- a/tokio/src/loom/std/mutex.rs +++ b/tokio/src/loom/std/mutex.rs @@ -1,7 +1,7 @@ use std::sync::{self, MutexGuard, TryLockError}; /// Adapter for `std::Mutex` that removes the poisoning aspects -/// from its `api`. +/// from its api. #[derive(Debug)] pub(crate) struct Mutex(sync::Mutex); diff --git a/tokio/src/net/udp.rs b/tokio/src/net/udp.rs index 9f182e7738e..9192317bbcc 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -13,7 +13,7 @@ cfg_io_util! { cfg_net! { /// A UDP socket. /// - /// UDP is `"connectionless"`, unlike TCP. Meaning, regardless of what address you've bound to, a `UdpSocket` + /// UDP is "connectionless", unlike TCP. Meaning, regardless of what address you've bound to, a `UdpSocket` /// is free to communicate with many different remotes. In tokio there are basically two main ways to use `UdpSocket`: /// /// * one to many: [`bind`](`UdpSocket::bind`) and use [`send_to`](`UdpSocket::send_to`) @@ -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. /// @@ -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. /// diff --git a/tokio/src/process/mod.rs b/tokio/src/process/mod.rs index 995ec88cba6..0fad67cd01a 100644 --- a/tokio/src/process/mod.rs +++ b/tokio/src/process/mod.rs @@ -4,7 +4,7 @@ //! [`std::process::Command`] type in the standard library, but provides asynchronous versions of //! functions that create processes. These functions (`spawn`, `status`, `output` and their //! variants) return "future aware" types that interoperate with Tokio. The asynchronous process -//! support is provided through signal handling on Unix and system `APIs` on Windows. +//! support is provided through signal handling on Unix and system APIs on Windows. //! //! [`std::process::Command`]: std::process::Command //! diff --git a/tokio/src/runtime/blocking/mod.rs b/tokio/src/runtime/blocking/mod.rs index c5bcc5fb5cc..c42924be77d 100644 --- a/tokio/src/runtime/blocking/mod.rs +++ b/tokio/src/runtime/blocking/mod.rs @@ -1,5 +1,5 @@ -//! Abstracts out the `APIs` necessary to `Runtime` for integrating the blocking -//! pool. When the `blocking` feature flag is **not** enabled, these `APIs` are +//! Abstracts out the APIs necessary to `Runtime` for integrating the blocking +//! pool. When the `blocking` feature flag is **not** enabled, these APIs are //! shells. This isolates the complexity of dealing with conditional //! compilation. diff --git a/tokio/src/runtime/context.rs b/tokio/src/runtime/context.rs index e142629c210..62e4fc9474c 100644 --- a/tokio/src/runtime/context.rs +++ b/tokio/src/runtime/context.rs @@ -42,7 +42,7 @@ struct Context { #[cfg(feature = "rt")] current: current::HandleCell, - /// Handle to the `scheduler's` internal "context" + /// Handle to the scheduler's internal "context" #[cfg(feature = "rt")] scheduler: Scoped, diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs index 7e7e5636c80..7a866367ae6 100644 --- a/tokio/src/runtime/handle.rs +++ b/tokio/src/runtime/handle.rs @@ -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.: diff --git a/tokio/src/runtime/scheduler/multi_thread/worker.rs b/tokio/src/runtime/scheduler/multi_thread/worker.rs index 235087f4b3a..2bd1b5678ea 100644 --- a/tokio/src/runtime/scheduler/multi_thread/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread/worker.rs @@ -88,7 +88,7 @@ cfg_not_taskdump! { /// A scheduler worker pub(super) struct Worker { - /// Reference to `scheduler's` handle + /// Reference to scheduler's handle handle: Arc, /// Index holding this worker's remote state @@ -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, } @@ -995,7 +995,7 @@ impl Core { } impl Worker { - /// Returns a reference to the `scheduler's` injection queue. + /// Returns a reference to the scheduler's injection queue. fn inject(&self) -> &inject::Shared> { &self.handle.shared.inject } diff --git a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs index 54c6b0ed7ba..e24d0b2e541 100644 --- a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs @@ -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, } diff --git a/tokio/src/runtime/task/core.rs b/tokio/src/runtime/task/core.rs index 108b06bc8b6..e61bbe5061d 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/mod.rs b/tokio/src/runtime/task/mod.rs index 9238d52c68b..6b05f4d7d5c 100644 --- a/tokio/src/runtime/task/mod.rs +++ b/tokio/src/runtime/task/mod.rs @@ -31,8 +31,8 @@ //! //! # State //! -//! The task stores its state in an atomic `usize` with various `bitfields` for the -//! necessary information. The state has the following `bitfields`: +//! 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. //! This bit functions as a lock around the task. @@ -68,7 +68,7 @@ //! synchronization. //! //! * If COMPLETE is one, then the `JoinHandle` has exclusive access to the -//! stage field. If COMPLETE is zero, then the RUNNING `bitfield` functions as +//! 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. //! @@ -159,7 +159,7 @@ //! //! Calling poll from inside a shutdown call or vice-versa is not prevented by //! the API exposed by the task module, so this has to be safe. In either case, -//! the lock in the RUNNING `bitfield` makes the inner call return immediately. If +//! the lock in the RUNNING bitfield makes the inner call return immediately. If //! the inner call is a `shutdown` call, then the CANCELLED bit is set, and the //! poll call will notice it when the poll finishes, and the task is cancelled //! at that point. diff --git a/tokio/src/runtime/time/entry.rs b/tokio/src/runtime/time/entry.rs index 48d5f4cf7d7..0998b53011d 100644 --- a/tokio/src/runtime/time/entry.rs +++ b/tokio/src/runtime/time/entry.rs @@ -332,7 +332,7 @@ pub(crate) struct TimerHandle { pub(super) type EntryList = crate::util::linked_list::LinkedList; /// The shared state structure of a timer. This structure is shared between the -/// `frontend` (`Entry`) and driver backend. +/// frontend (`Entry`) and driver backend. /// /// Note that this structure is located inside the `TimerEntry` structure. pub(crate) struct TimerShared { diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index d8af9b4c9d9..e6ca599de70 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -257,7 +257,7 @@ pub fn ctrl_close() -> io::Result { }) } -/// Represents a listener which receives "ctrl-close" notifications sent to the process +/// Represents a listener which receives "ctrl-close" notitifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for @@ -354,7 +354,7 @@ pub fn ctrl_shutdown() -> io::Result { }) } -/// Represents a listener which receives "ctrl-shutdown" notifications sent to the process +/// Represents a listener which receives "ctrl-shutdown" notitifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for @@ -451,7 +451,7 @@ pub fn ctrl_logoff() -> io::Result { }) } -/// Represents a listener which receives "ctrl-logoff" notifications sent to the process +/// Represents a listener which receives "ctrl-logoff" notitifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for diff --git a/tokio/src/sync/mpsc/block.rs b/tokio/src/sync/mpsc/block.rs index 0598f54ab34..befcfd29efa 100644 --- a/tokio/src/sync/mpsc/block.rs +++ b/tokio/src/sync/mpsc/block.rs @@ -30,7 +30,7 @@ struct BlockHeader { /// The next block in the linked list. next: AtomicPtr>, - /// `Bitfield` tracking slots that are ready to have their values consumed. + /// Bitfield tracking slots that are ready to have their values consumed. ready_slots: AtomicUsize, /// The observed `tail_position` value *after* the block has been passed by diff --git a/tokio/src/task/blocking.rs b/tokio/src/task/blocking.rs index ddd5e1c463c..1cce466394e 100644 --- a/tokio/src/task/blocking.rs +++ b/tokio/src/task/blocking.rs @@ -121,9 +121,9 @@ cfg_rt! { /// /// Note that if you are using the single threaded runtime, this function will /// still spawn additional threads for blocking operations. The current-thread - /// `scheduler's` single thread is only used for asynchronous code. + /// scheduler's single thread is only used for asynchronous code. /// - /// # Related `APIs` and patterns for bridging asynchronous and blocking code + /// # Related APIs and patterns for bridging asynchronous and blocking code /// /// In simple cases, it is sufficient to have the closure accept input /// parameters at creation time and return a single value (or struct/tuple, etc.). diff --git a/tokio/src/task/mod.rs b/tokio/src/task/mod.rs index 347fed2c078..806b9aebe76 100644 --- a/tokio/src/task/mod.rs +++ b/tokio/src/task/mod.rs @@ -33,7 +33,7 @@ //! yield instead, allowing the Tokio runtime to schedule another task. Tasks //! should generally not perform system calls or other operations that could //! block a thread, as this would prevent other tasks running on the same -//! thread from executing as well. Instead, this module provides `APIs` for +//! thread from executing as well. Instead, this module provides APIs for //! running blocking operations in an asynchronous context. //! //! [rt]: crate::runtime @@ -44,7 +44,7 @@ //! //! ## Working with Tasks //! -//! This module provides the following `APIs` for working with tasks: +//! This module provides the following APIs for working with tasks: //! //! ### Spawning //! @@ -159,7 +159,7 @@ //! on a thread that is also running other tasks would block the entire thread, //! preventing other tasks from running. //! -//! Instead, Tokio provides two `APIs` for running blocking operations in an +//! Instead, Tokio provides two APIs for running blocking operations in an //! asynchronous context: [`task::spawn_blocking`] and [`task::block_in_place`]. //! //! Be aware that if you call a non-async method from async code, that non-async diff --git a/tokio/src/util/linked_list.rs b/tokio/src/util/linked_list.rs index 24be18491ab..0ed2b616456 100644 --- a/tokio/src/util/linked_list.rs +++ b/tokio/src/util/linked_list.rs @@ -3,7 +3,7 @@ //! An intrusive double linked list of data. //! //! The data structure supports tracking pinned nodes. Most of the data -//! structure's `APIs` are `unsafe` as they require the caller to ensure the +//! structure's APIs are `unsafe` as they require the caller to ensure the //! specified node is actually contained by the list. use core::cell::UnsafeCell; diff --git a/tokio/src/util/sharded_list.rs b/tokio/src/util/sharded_list.rs index 4da0bcdf7f1..8c8e3ad0a02 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); From fa2510bc78ba19e4b156ff065f6eb5bf224a624b Mon Sep 17 00:00:00 2001 From: Owen Leung Date: Sun, 28 Jan 2024 23:41:49 +0800 Subject: [PATCH 10/11] remove assert_eq, bool, buf, cfg, const, fuzz_linked_list, shard_id from dictionary remove assert_eq, bool, buf, cfg, const, fuzz_linked_list, shard_id from dictionary --- spellcheck.dic | 9 +-------- tokio/src/io/util/read_line.rs | 2 +- tokio/src/lib.rs | 4 ++-- tokio/src/net/udp.rs | 12 ++++++------ tokio/src/runtime/handle.rs | 2 +- tokio/src/runtime/scheduler/multi_thread/worker.rs | 2 +- .../src/runtime/scheduler/multi_thread_alt/worker.rs | 2 +- tokio/src/runtime/task/core.rs | 4 ++-- tokio/src/util/sharded_list.rs | 2 +- 9 files changed, 16 insertions(+), 23 deletions(-) diff --git a/spellcheck.dic b/spellcheck.dic index b978af4f1ee..80d9afe512e 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -1,4 +1,4 @@ -286 +279 \ ~ ~4 @@ -34,7 +34,6 @@ ambiant amongst api APIs -assert_eq async awaitable backend @@ -46,14 +45,11 @@ binded bitfield bitfields Blockingly -bool boolean broadcasted -buf cancelled cancelling Cancelling -cfg CLI cloneable codebase @@ -64,7 +60,6 @@ combinators Config config connectionless -const cpu cpus Customizable @@ -113,7 +108,6 @@ FreeBSD frontend fs functionalities -fuzz_linked_list getters GID Growable @@ -207,7 +201,6 @@ scalability scheduler's semver setpgid -shard_id sharded signalled signalling 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/lib.rs b/tokio/src/lib.rs index c1daa2b26f4..3f035098832 100644 --- a/tokio/src/lib.rs +++ b/tokio/src/lib.rs @@ -333,7 +333,7 @@ //! - `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 +//! 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 @@ -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/net/udp.rs b/tokio/src/net/udp.rs index 9192317bbcc..4e2c140a856 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -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. /// @@ -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. /// diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs index 7a866367ae6..7e7e5636c80 100644 --- a/tokio/src/runtime/handle.rs +++ b/tokio/src/runtime/handle.rs @@ -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.: diff --git a/tokio/src/runtime/scheduler/multi_thread/worker.rs b/tokio/src/runtime/scheduler/multi_thread/worker.rs index 2bd1b5678ea..9998870ab4d 100644 --- a/tokio/src/runtime/scheduler/multi_thread/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread/worker.rs @@ -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, } diff --git a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs index e24d0b2e541..54c6b0ed7ba 100644 --- a/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs +++ b/tokio/src/runtime/scheduler/multi_thread_alt/worker.rs @@ -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, } 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/util/sharded_list.rs b/tokio/src/util/sharded_list.rs index 8c8e3ad0a02..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); From 623e4bb8fc4862f36d08643bd640c085668be054 Mon Sep 17 00:00:00 2001 From: "M.Amin Rayej" Date: Sun, 28 Jan 2024 21:25:15 +0330 Subject: [PATCH 11/11] small fix --- spellcheck.dic | 2 -- tokio/src/signal/windows.rs | 6 +++--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/spellcheck.dic b/spellcheck.dic index 80d9afe512e..ddedb90730d 100644 --- a/spellcheck.dic +++ b/spellcheck.dic @@ -7,7 +7,6 @@ ±1ms — & -&str + 0o777 0s @@ -161,7 +160,6 @@ Nagle nonblocking nondecreasing noop -notitifications ntasks ok oneshot diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index e6ca599de70..d8af9b4c9d9 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -257,7 +257,7 @@ pub fn ctrl_close() -> io::Result { }) } -/// Represents a listener which receives "ctrl-close" notitifications sent to the process +/// Represents a listener which receives "ctrl-close" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for @@ -354,7 +354,7 @@ pub fn ctrl_shutdown() -> io::Result { }) } -/// Represents a listener which receives "ctrl-shutdown" notitifications sent to the process +/// Represents a listener which receives "ctrl-shutdown" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for @@ -451,7 +451,7 @@ pub fn ctrl_logoff() -> io::Result { }) } -/// Represents a listener which receives "ctrl-logoff" notitifications sent to the process +/// Represents a listener which receives "ctrl-logoff" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// A notification to this process notifies *all* listeners listening for