From 8650eda7d6c9080502014f2daba0e38ec836ef20 Mon Sep 17 00:00:00 2001 From: Antonello Palazzi Date: Sun, 17 Oct 2021 21:17:44 +0100 Subject: [PATCH] conversion of doc comments to indicative mood Conversion of doc comments from imperative to indicative mood. Addition of trailing periods as well. Fixes: #4074 --- tokio/src/coop.rs | 10 ++-- tokio/src/fs/create_dir.rs | 2 +- tokio/src/fs/dir_builder.rs | 2 +- tokio/src/fs/file.rs | 4 +- tokio/src/fs/open_options.rs | 2 +- tokio/src/fs/read_dir.rs | 4 +- tokio/src/future/maybe_done.rs | 8 ++-- tokio/src/future/poll_fn.rs | 2 +- tokio/src/io/async_fd.rs | 4 +- tokio/src/io/blocking.rs | 4 +- tokio/src/io/bsd/poll_aio.rs | 8 ++-- tokio/src/io/driver/interest.rs | 12 ++--- tokio/src/io/driver/mod.rs | 18 ++++---- tokio/src/io/driver/ready.rs | 12 ++--- tokio/src/io/driver/scheduled_io.rs | 20 ++++---- tokio/src/io/mod.rs | 2 +- tokio/src/io/poll_evented.rs | 4 +- tokio/src/io/split.rs | 2 +- tokio/src/io/stdio_common.rs | 2 +- tokio/src/io/util/async_write_ext.rs | 4 +- tokio/src/io/util/buf_reader.rs | 2 +- tokio/src/io/util/lines.rs | 6 +-- tokio/src/loom/std/mutex.rs | 2 +- tokio/src/macros/cfg.rs | 4 +- tokio/src/macros/join.rs | 2 +- tokio/src/macros/scoped_tls.rs | 2 +- tokio/src/macros/select.rs | 2 +- tokio/src/macros/try_join.rs | 2 +- tokio/src/net/tcp/listener.rs | 2 +- tokio/src/net/tcp/mod.rs | 2 +- tokio/src/net/tcp/socket.rs | 20 ++++---- tokio/src/net/tcp/split.rs | 20 ++++---- tokio/src/net/tcp/split_owned.rs | 20 ++++---- tokio/src/net/tcp/stream.rs | 18 ++++---- tokio/src/net/udp.rs | 24 +++++----- tokio/src/net/unix/datagram/socket.rs | 22 ++++----- tokio/src/net/unix/listener.rs | 2 +- tokio/src/net/unix/mod.rs | 2 +- tokio/src/net/unix/split.rs | 16 +++---- tokio/src/net/unix/split_owned.rs | 20 ++++---- tokio/src/net/unix/stream.rs | 20 ++++---- tokio/src/net/unix/ucred.rs | 8 ++-- tokio/src/net/windows/named_pipe.rs | 46 +++++++++---------- tokio/src/park/mod.rs | 12 ++--- tokio/src/park/thread.rs | 6 +-- tokio/src/process/mod.rs | 8 ++-- tokio/src/process/unix/driver.rs | 2 +- tokio/src/process/unix/mod.rs | 2 +- tokio/src/runtime/basic_scheduler.rs | 6 +-- tokio/src/runtime/blocking/pool.rs | 18 ++++---- tokio/src/runtime/blocking/task.rs | 4 +- tokio/src/runtime/context.rs | 2 +- tokio/src/runtime/enter.rs | 2 +- tokio/src/runtime/handle.rs | 10 ++-- tokio/src/runtime/mod.rs | 16 +++---- tokio/src/runtime/task/core.rs | 16 +++---- tokio/src/runtime/task/error.rs | 4 +- tokio/src/runtime/task/harness.rs | 18 ++++---- tokio/src/runtime/task/inject.rs | 12 ++--- tokio/src/runtime/task/list.rs | 10 ++-- tokio/src/runtime/task/mod.rs | 12 ++--- tokio/src/runtime/task/raw.rs | 12 ++--- tokio/src/runtime/task/state.rs | 36 +++++++-------- tokio/src/runtime/thread_pool/idle.rs | 2 +- tokio/src/runtime/thread_pool/mod.rs | 2 +- tokio/src/runtime/thread_pool/worker.rs | 14 +++--- tokio/src/signal/mod.rs | 2 +- tokio/src/signal/reusable_box.rs | 12 ++--- tokio/src/sync/batch_semaphore.rs | 8 ++-- tokio/src/sync/broadcast.rs | 32 ++++++------- tokio/src/sync/mpsc/block.rs | 4 +- tokio/src/sync/mpsc/bounded.rs | 20 ++++---- tokio/src/sync/mpsc/chan.rs | 6 +-- tokio/src/sync/mpsc/error.rs | 2 +- tokio/src/sync/mpsc/list.rs | 4 +- tokio/src/sync/mpsc/unbounded.rs | 2 +- tokio/src/sync/notify.rs | 14 +++--- tokio/src/sync/once_cell.rs | 8 ++-- tokio/src/sync/oneshot.rs | 10 ++-- tokio/src/sync/rwlock/owned_read_guard.rs | 2 +- tokio/src/sync/rwlock/owned_write_guard.rs | 2 +- .../sync/rwlock/owned_write_guard_mapped.rs | 2 +- tokio/src/sync/rwlock/read_guard.rs | 2 +- tokio/src/sync/rwlock/write_guard.rs | 2 +- tokio/src/sync/rwlock/write_guard_mapped.rs | 2 +- tokio/src/sync/task/atomic_waker.rs | 2 +- tokio/src/sync/watch.rs | 16 +++---- tokio/src/task/local.rs | 18 ++++---- tokio/src/time/clock.rs | 12 ++--- tokio/src/time/driver/entry.rs | 2 +- tokio/src/time/driver/handle.rs | 6 +-- tokio/src/time/driver/mod.rs | 18 ++++---- tokio/src/time/driver/wheel/level.rs | 2 +- tokio/src/time/driver/wheel/mod.rs | 12 ++--- tokio/src/time/driver/wheel/stack.rs | 4 +- tokio/src/time/error.rs | 4 +- tokio/src/time/interval.rs | 8 ++-- tokio/src/time/timeout.rs | 4 +- tokio/src/util/bit.rs | 6 +-- tokio/src/util/linked_list.rs | 8 ++-- tokio/src/util/rand.rs | 4 +- tokio/src/util/slab.rs | 30 ++++++------ tokio/src/util/vec_deque_cell.rs | 2 +- tokio/src/util/wake.rs | 6 +-- 104 files changed, 458 insertions(+), 458 deletions(-) diff --git a/tokio/src/coop.rs b/tokio/src/coop.rs index 16d93fb7516..256e9620e75 100644 --- a/tokio/src/coop.rs +++ b/tokio/src/coop.rs @@ -69,14 +69,14 @@ cfg_rt_multi_thread! { } } -/// Run the given closure with a cooperative task budget. When the function +/// Runs the given closure with a cooperative task budget. When the function /// returns, the budget is reset to the value prior to calling the function. #[inline(always)] pub(crate) fn budget(f: impl FnOnce() -> R) -> R { with_budget(Budget::initial(), f) } -/// Run the given closure with an unconstrained task budget. When the function returns, the budget +/// Runs the given closure with an unconstrained task budget. When the function returns, the budget /// is reset to the value prior to calling the function. #[inline(always)] pub(crate) fn with_unconstrained(f: impl FnOnce() -> R) -> R { @@ -108,7 +108,7 @@ fn with_budget(budget: Budget, f: impl FnOnce() -> R) -> R { } cfg_rt_multi_thread! { - /// Set the current task's budget + /// Sets the current task's budget. pub(crate) fn set(budget: Budget) { CURRENT.with(|cell| cell.set(budget)) } @@ -120,7 +120,7 @@ cfg_rt_multi_thread! { } cfg_rt! { - /// Forcibly remove the budgeting constraints early. + /// Forcibly removes the budgeting constraints early. /// /// Returns the remaining budget pub(crate) fn stop() -> Budget { @@ -186,7 +186,7 @@ cfg_coop! { } impl Budget { - /// Decrement the budget. Returns `true` if successful. Decrementing fails + /// Decrements the budget. Returns `true` if successful. Decrementing fails /// when there is not enough remaining budget. fn decrement(&mut self) -> bool { if let Some(num) = &mut self.0 { diff --git a/tokio/src/fs/create_dir.rs b/tokio/src/fs/create_dir.rs index e03b04dc4b0..411969500f0 100644 --- a/tokio/src/fs/create_dir.rs +++ b/tokio/src/fs/create_dir.rs @@ -3,7 +3,7 @@ use crate::fs::asyncify; use std::io; use std::path::Path; -/// Creates a new, empty directory at the provided path +/// Creates a new, empty directory at the provided path. /// /// This is an async version of [`std::fs::create_dir`][std] /// diff --git a/tokio/src/fs/dir_builder.rs b/tokio/src/fs/dir_builder.rs index b1849344b9c..97168bff704 100644 --- a/tokio/src/fs/dir_builder.rs +++ b/tokio/src/fs/dir_builder.rs @@ -14,7 +14,7 @@ pub struct DirBuilder { /// Indicates whether to create parent directories if they are missing. recursive: bool, - /// Set the Unix mode for newly created directories. + /// Sets the Unix mode for newly created directories. #[cfg(unix)] pub(super) mode: Option, } diff --git a/tokio/src/fs/file.rs b/tokio/src/fs/file.rs index 5286e6c5c5d..61071cf6309 100644 --- a/tokio/src/fs/file.rs +++ b/tokio/src/fs/file.rs @@ -74,7 +74,7 @@ use std::fs::File as StdFile; /// # } /// ``` /// -/// Read the contents of a file into a buffer +/// Read the contents of a file into a buffer: /// /// ```no_run /// use tokio::fs::File; @@ -383,7 +383,7 @@ impl File { asyncify(move || std.metadata()).await } - /// Create a new `File` instance that shares the same underlying file handle + /// Creates a new `File` instance that shares the same underlying file handle /// as the existing `File` instance. Reads, writes, and seeks will affect both /// File instances simultaneously. /// diff --git a/tokio/src/fs/open_options.rs b/tokio/src/fs/open_options.rs index 3e73529ecf6..f3b4654741e 100644 --- a/tokio/src/fs/open_options.rs +++ b/tokio/src/fs/open_options.rs @@ -430,7 +430,7 @@ feature! { self } - /// Pass custom flags to the `flags` argument of `open`. + /// Passes custom flags to the `flags` argument of `open`. /// /// The bits that define the access mode are masked out with `O_ACCMODE`, to /// ensure they do not interfere with the access mode set by Rusts options. diff --git a/tokio/src/fs/read_dir.rs b/tokio/src/fs/read_dir.rs index 514d59cadac..281ea4cd756 100644 --- a/tokio/src/fs/read_dir.rs +++ b/tokio/src/fs/read_dir.rs @@ -34,7 +34,7 @@ pub async fn read_dir(path: impl AsRef) -> io::Result { Ok(ReadDir(State::Idle(Some(std)))) } -/// Read the the entries in a directory. +/// Reads the the entries in a directory. /// /// This struct is returned from the [`read_dir`] function of this module and /// will yield instances of [`DirEntry`]. Through a [`DirEntry`] information @@ -287,7 +287,7 @@ impl DirEntry { asyncify(move || std.file_type()).await } - /// Returns a reference to the underlying `std::fs::DirEntry` + /// Returns a reference to the underlying `std::fs::DirEntry`. #[cfg(unix)] pub(super) fn as_inner(&self) -> &std::fs::DirEntry { &self.0 diff --git a/tokio/src/future/maybe_done.rs b/tokio/src/future/maybe_done.rs index 1e083ad7fd5..486efbe01ad 100644 --- a/tokio/src/future/maybe_done.rs +++ b/tokio/src/future/maybe_done.rs @@ -1,4 +1,4 @@ -//! Definition of the MaybeDone combinator +//! Definition of the MaybeDone combinator. use std::future::Future; use std::mem; @@ -8,9 +8,9 @@ use std::task::{Context, Poll}; /// A future that may have completed. #[derive(Debug)] pub enum MaybeDone { - /// A not-yet-completed future + /// A not-yet-completed future. Future(Fut), - /// The output of the completed future + /// The output of the completed future. Done(Fut::Output), /// The empty variant after the result of a [`MaybeDone`] has been /// taken using the [`take_output`](MaybeDone::take_output) method. @@ -20,7 +20,7 @@ pub enum MaybeDone { // Safe because we never generate `Pin<&mut Fut::Output>` impl Unpin for MaybeDone {} -/// Wraps a future into a `MaybeDone` +/// Wraps a future into a `MaybeDone`. pub fn maybe_done(future: Fut) -> MaybeDone { MaybeDone::Future(future) } diff --git a/tokio/src/future/poll_fn.rs b/tokio/src/future/poll_fn.rs index 0169bd5fcd4..d82ce8961d1 100644 --- a/tokio/src/future/poll_fn.rs +++ b/tokio/src/future/poll_fn.rs @@ -1,6 +1,6 @@ #![allow(dead_code)] -//! Definition of the `PollFn` adapter combinator +//! Definition of the `PollFn` adapter combinator. use std::fmt; use std::future::Future; diff --git a/tokio/src/io/async_fd.rs b/tokio/src/io/async_fd.rs index fa5bec530fa..9ec5b7f2387 100644 --- a/tokio/src/io/async_fd.rs +++ b/tokio/src/io/async_fd.rs @@ -205,13 +205,13 @@ impl AsyncFd { }) } - /// Returns a shared reference to the backing object of this [`AsyncFd`] + /// Returns a shared reference to the backing object of this [`AsyncFd`]. #[inline] pub fn get_ref(&self) -> &T { self.inner.as_ref().unwrap() } - /// Returns a mutable reference to the backing object of this [`AsyncFd`] + /// Returns a mutable reference to the backing object of this [`AsyncFd`]. #[inline] pub fn get_mut(&mut self) -> &mut T { self.inner.as_mut().unwrap() diff --git a/tokio/src/io/blocking.rs b/tokio/src/io/blocking.rs index 94a3484ff0b..1d79ee7a279 100644 --- a/tokio/src/io/blocking.rs +++ b/tokio/src/io/blocking.rs @@ -16,7 +16,7 @@ use self::State::*; pub(crate) struct Blocking { inner: Option, state: State, - /// `true` if the lower IO layer needs flushing + /// `true` if the lower IO layer needs flushing. need_flush: bool, } @@ -175,7 +175,7 @@ where } } -/// Repeats operations that are interrupted +/// Repeats operations that are interrupted. macro_rules! uninterruptibly { ($e:expr) => {{ loop { diff --git a/tokio/src/io/bsd/poll_aio.rs b/tokio/src/io/bsd/poll_aio.rs index a765d76773a..f1ac4b2d77a 100644 --- a/tokio/src/io/bsd/poll_aio.rs +++ b/tokio/src/io/bsd/poll_aio.rs @@ -1,4 +1,4 @@ -//! Use POSIX AIO futures with Tokio +//! Use POSIX AIO futures with Tokio. use crate::io::driver::{Handle, Interest, ReadyEvent, Registration}; use mio::event::Source; @@ -16,14 +16,14 @@ use std::task::{Context, Poll}; /// Tokio's consumer must pass an implementor of this trait to create a /// [`Aio`] object. pub trait AioSource { - /// Register this AIO event source with Tokio's reactor + /// Registers this AIO event source with Tokio's reactor. fn register(&mut self, kq: RawFd, token: usize); - /// Deregister this AIO event source with Tokio's reactor + /// Deregisters this AIO event source with Tokio's reactor. fn deregister(&mut self); } -/// Wrap the user's AioSource in order to implement mio::event::Source, which +/// Wraps the user's AioSource in order to implement mio::event::Source, which /// is what the rest of the crate wants. struct MioSource(T); diff --git a/tokio/src/io/driver/interest.rs b/tokio/src/io/driver/interest.rs index c5b18edd44c..d6b46dfb7c6 100644 --- a/tokio/src/io/driver/interest.rs +++ b/tokio/src/io/driver/interest.rs @@ -5,7 +5,7 @@ use crate::io::driver::Ready; use std::fmt; use std::ops; -/// Readiness event interest +/// Readiness event interest. /// /// Specifies the readiness events the caller is interested in when awaiting on /// I/O resource readiness states. @@ -17,19 +17,19 @@ impl Interest { // The non-FreeBSD definitions in this block are active only when // building documentation. cfg_aio! { - /// Interest for POSIX AIO + /// Interest for POSIX AIO. #[cfg(target_os = "freebsd")] pub const AIO: Interest = Interest(mio::Interest::AIO); - /// Interest for POSIX AIO + /// Interest for POSIX AIO. #[cfg(not(target_os = "freebsd"))] pub const AIO: Interest = Interest(mio::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(mio::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(mio::Interest::READABLE); } @@ -39,7 +39,7 @@ impl Interest { /// Readable interest includes read-closed events. pub const READABLE: Interest = Interest(mio::Interest::READABLE); - /// Interest in all writable events + /// Interest in all writable events. /// /// Writable interest includes write-closed events. pub const WRITABLE: Interest = Interest(mio::Interest::WRITABLE); diff --git a/tokio/src/io/driver/mod.rs b/tokio/src/io/driver/mod.rs index 1511884ce77..19f67a24e7f 100644 --- a/tokio/src/io/driver/mod.rs +++ b/tokio/src/io/driver/mod.rs @@ -23,10 +23,10 @@ use std::io; use std::sync::{Arc, Weak}; use std::time::Duration; -/// I/O driver, backed by Mio +/// I/O driver, backed by Mio. pub(crate) struct Driver { /// Tracks the number of times `turn` is called. It is safe for this to wrap - /// as it is mostly used to determine when to call `compact()` + /// as it is mostly used to determine when to call `compact()`. tick: u8, /// Reuse the `mio::Events` value across calls to poll. @@ -35,17 +35,17 @@ pub(crate) struct Driver { /// Primary slab handle containing the state for each resource registered /// with this driver. During Drop this is moved into the Inner structure, so /// this is an Option to allow it to be vacated (until Drop this is always - /// Some) + /// Some). resources: Option>, - /// The system event queue + /// The system event queue. poll: mio::Poll, /// State shared between the reactor and the handles. inner: Arc, } -/// A reference to an I/O driver +/// A reference to an I/O driver. #[derive(Clone)] pub(crate) struct Handle { inner: Weak, @@ -66,13 +66,13 @@ pub(super) struct Inner { /// without risking new ones being registered in the meantime. resources: Mutex>>, - /// Registers I/O resources + /// Registers I/O resources. registry: mio::Registry, /// Allocates `ScheduledIo` handles when creating new resources. pub(super) io_dispatch: slab::Allocator, - /// Used to wake up the reactor from a call to `turn` + /// Used to wake up the reactor from a call to `turn`. waker: mio::Waker, } @@ -253,7 +253,7 @@ impl fmt::Debug for Driver { cfg_rt! { impl Handle { - /// Returns a handle to the current reactor + /// Returns a handle to the current reactor. /// /// # Panics /// @@ -267,7 +267,7 @@ cfg_rt! { cfg_not_rt! { impl Handle { - /// Returns a handle to the current reactor + /// Returns a handle to the current reactor. /// /// # Panics /// diff --git a/tokio/src/io/driver/ready.rs b/tokio/src/io/driver/ready.rs index 305dc91f0ae..2430d3022f1 100644 --- a/tokio/src/io/driver/ready.rs +++ b/tokio/src/io/driver/ready.rs @@ -68,7 +68,7 @@ impl Ready { ready } - /// Returns true if `Ready` is the empty set + /// Returns true if `Ready` is the empty set. /// /// # Examples /// @@ -82,7 +82,7 @@ impl Ready { self == Ready::EMPTY } - /// Returns `true` if the value includes `readable` + /// Returns `true` if the value includes `readable`. /// /// # Examples /// @@ -98,7 +98,7 @@ impl Ready { self.contains(Ready::READABLE) || self.is_read_closed() } - /// Returns `true` if the value includes writable `readiness` + /// Returns `true` if the value includes writable `readiness`. /// /// # Examples /// @@ -114,7 +114,7 @@ impl Ready { self.contains(Ready::WRITABLE) || self.is_write_closed() } - /// Returns `true` if the value includes read-closed `readiness` + /// Returns `true` if the value includes read-closed `readiness`. /// /// # Examples /// @@ -129,7 +129,7 @@ impl Ready { self.contains(Ready::READ_CLOSED) } - /// Returns `true` if the value includes write-closed `readiness` + /// Returns `true` if the value includes write-closed `readiness`. /// /// # Examples /// @@ -154,7 +154,7 @@ impl Ready { (self & other) == other } - /// Create a `Ready` instance using the given `usize` representation. + /// Creates a `Ready` instance using the given `usize` representation. /// /// The `usize` representation must have been obtained from a call to /// `Readiness::as_usize`. diff --git a/tokio/src/io/driver/scheduled_io.rs b/tokio/src/io/driver/scheduled_io.rs index a2657203fb5..76f93431ba2 100644 --- a/tokio/src/io/driver/scheduled_io.rs +++ b/tokio/src/io/driver/scheduled_io.rs @@ -36,16 +36,16 @@ cfg_io_readiness! { #[derive(Debug, Default)] struct Waiters { #[cfg(feature = "net")] - /// List of all current 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, - /// True if this ScheduledIo has been killed due to IO driver shutdown + /// True if this ScheduledIo has been killed due to IO driver shutdown. is_shutdown: bool, } @@ -54,19 +54,19 @@ cfg_io_readiness! { struct Waiter { pointers: linked_list::Pointers, - /// The waker for this task + /// The waker for this task. waker: Option, - /// The interest this waiter is waiting on + /// The interest this waiter is waiting on. interest: Interest, is_ready: bool, - /// Should never be `!Unpin` + /// Should never be `!Unpin`. _p: PhantomPinned, } - /// Future returned by `readiness()` + /// Future returned by `readiness()`. struct Readiness<'a> { scheduled_io: &'a ScheduledIo, @@ -276,7 +276,7 @@ impl ScheduledIo { } } - /// Poll version of checking readiness for a certain direction. + /// Polls for readiness events in a given direction. /// /// These are to support `AsyncRead` and `AsyncWrite` polling methods, /// which cannot use the `async fn` version. This uses reserved reader @@ -363,7 +363,7 @@ unsafe impl Sync for ScheduledIo {} cfg_io_readiness! { impl ScheduledIo { - /// An async version of `poll_readiness` which uses a linked list of wakers + /// An async version of `poll_readiness` which uses a linked list of wakers. pub(crate) async fn readiness(&self, interest: Interest) -> ReadyEvent { self.readiness_fut(interest).await } diff --git a/tokio/src/io/mod.rs b/tokio/src/io/mod.rs index a5ee1080042..cfdda61f694 100644 --- a/tokio/src/io/mod.rs +++ b/tokio/src/io/mod.rs @@ -218,7 +218,7 @@ cfg_io_driver_impl! { } cfg_aio! { - /// BSD-specific I/O types + /// BSD-specific I/O types. pub mod bsd { mod poll_aio; diff --git a/tokio/src/io/poll_evented.rs b/tokio/src/io/poll_evented.rs index 9872574807e..44e68a2a9a0 100644 --- a/tokio/src/io/poll_evented.rs +++ b/tokio/src/io/poll_evented.rs @@ -113,7 +113,7 @@ impl PollEvented { }) } - /// Returns a reference to the registration + /// Returns a reference to the registration. #[cfg(any( feature = "net", all(unix, feature = "process"), @@ -123,7 +123,7 @@ impl PollEvented { &self.registration } - /// Deregister the inner io from the registration and returns a Result containing the inner io + /// Deregisters the inner io from the registration and returns a Result containing the inner io. #[cfg(any(feature = "net", feature = "process"))] pub(crate) fn into_inner(mut self) -> io::Result { let mut inner = self.io.take().unwrap(); // As io shouldn't ever be None, just unwrap here. diff --git a/tokio/src/io/split.rs b/tokio/src/io/split.rs index f35273fd70e..8258a0f7a08 100644 --- a/tokio/src/io/split.rs +++ b/tokio/src/io/split.rs @@ -90,7 +90,7 @@ impl ReadHalf { } impl WriteHalf { - /// Check if this `WriteHalf` and some `ReadHalf` were split from the same + /// Checks if this `WriteHalf` and some `ReadHalf` were split from the same /// stream. pub fn is_pair_of(&self, other: &ReadHalf) -> bool { Arc::ptr_eq(&self.inner, &other.inner) diff --git a/tokio/src/io/stdio_common.rs b/tokio/src/io/stdio_common.rs index 56c4520c6a4..7e4a198a82b 100644 --- a/tokio/src/io/stdio_common.rs +++ b/tokio/src/io/stdio_common.rs @@ -7,7 +7,7 @@ use std::task::{Context, Poll}; /// 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 +/// Passes data to `inner` as is. #[derive(Debug)] pub(crate) struct SplitByUtf8BoundaryIfWindows { inner: W, diff --git a/tokio/src/io/util/async_write_ext.rs b/tokio/src/io/util/async_write_ext.rs index a1f77f80187..2926fe4d21d 100644 --- a/tokio/src/io/util/async_write_ext.rs +++ b/tokio/src/io/util/async_write_ext.rs @@ -20,7 +20,7 @@ use std::io::IoSlice; use bytes::Buf; cfg_io_util! { - /// Defines numeric writer + /// Defines numeric writer. macro_rules! write_impl { ( $( @@ -256,7 +256,7 @@ cfg_io_util! { write_buf(self, src) } - /// Attempts to write an entire buffer into this writer + /// Attempts to write an entire buffer into this writer. /// /// Equivalent to: /// diff --git a/tokio/src/io/util/buf_reader.rs b/tokio/src/io/util/buf_reader.rs index 7cfd46ce03e..7df610b143a 100644 --- a/tokio/src/io/util/buf_reader.rs +++ b/tokio/src/io/util/buf_reader.rs @@ -155,7 +155,7 @@ pub(super) enum SeekState { Pending, } -/// Seek to an offset, in bytes, in the underlying reader. +/// Seeks to an offset, in bytes, in the underlying reader. /// /// The position used for seeking with `SeekFrom::Current(_)` is the /// position the underlying reader would be at if the `BufReader` had no diff --git a/tokio/src/io/util/lines.rs b/tokio/src/io/util/lines.rs index 3fbf5e3a309..717f633f950 100644 --- a/tokio/src/io/util/lines.rs +++ b/tokio/src/io/util/lines.rs @@ -8,7 +8,7 @@ use std::pin::Pin; use std::task::{Context, Poll}; pin_project! { - /// Read lines from an [`AsyncBufRead`]. + /// Reads lines from an [`AsyncBufRead`]. /// /// A `Lines` can be turned into a `Stream` with [`LinesStream`]. /// @@ -72,12 +72,12 @@ where poll_fn(|cx| Pin::new(&mut *self).poll_next_line(cx)).await } - /// Obtain a mutable reference to the underlying reader + /// Obtains a mutable reference to the underlying reader. pub fn get_mut(&mut self) -> &mut R { &mut self.reader } - /// Obtain a reference to the underlying reader + /// Obtains a reference to the underlying reader. pub fn get_ref(&mut self) -> &R { &self.reader } diff --git a/tokio/src/loom/std/mutex.rs b/tokio/src/loom/std/mutex.rs index bf14d624205..3f686e0a78e 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/macros/cfg.rs b/tokio/src/macros/cfg.rs index 193bcd7d9a4..051713f1c1e 100644 --- a/tokio/src/macros/cfg.rs +++ b/tokio/src/macros/cfg.rs @@ -13,7 +13,7 @@ macro_rules! feature { } } -/// Enables enter::block_on +/// Enables enter::block_on. macro_rules! cfg_block_on { ($($item:item)*) => { $( @@ -28,7 +28,7 @@ macro_rules! cfg_block_on { } } -/// Enables internal `AtomicWaker` impl +/// Enables internal `AtomicWaker` impl. macro_rules! cfg_atomic_waker_impl { ($($item:item)*) => { $( diff --git a/tokio/src/macros/join.rs b/tokio/src/macros/join.rs index 5f37af510d3..f91b5f19145 100644 --- a/tokio/src/macros/join.rs +++ b/tokio/src/macros/join.rs @@ -1,4 +1,4 @@ -/// Wait on multiple concurrent branches, returning when **all** branches +/// Waits on multiple concurrent branches, returning when **all** branches /// complete. /// /// The `join!` macro must be used inside of async functions, closures, and diff --git a/tokio/src/macros/scoped_tls.rs b/tokio/src/macros/scoped_tls.rs index a00aae2fbae..f2504cbadf7 100644 --- a/tokio/src/macros/scoped_tls.rs +++ b/tokio/src/macros/scoped_tls.rs @@ -3,7 +3,7 @@ use crate::loom::thread::LocalKey; use std::cell::Cell; use std::marker; -/// Set a reference as a thread-local +/// Sets a reference as a thread-local. macro_rules! scoped_thread_local { ($(#[$attrs:meta])* $vis:vis static $name:ident: $ty:ty) => ( $(#[$attrs])* diff --git a/tokio/src/macros/select.rs b/tokio/src/macros/select.rs index a90ee9eb577..c726649b7b4 100644 --- a/tokio/src/macros/select.rs +++ b/tokio/src/macros/select.rs @@ -1,4 +1,4 @@ -/// Wait on multiple concurrent branches, returning when the **first** branch +/// Waits on multiple concurrent branches, returning when the **first** branch /// completes, cancelling the remaining branches. /// /// The `select!` macro must be used inside of async functions, closures, and diff --git a/tokio/src/macros/try_join.rs b/tokio/src/macros/try_join.rs index 454dbfe4beb..6d3a893b7e1 100644 --- a/tokio/src/macros/try_join.rs +++ b/tokio/src/macros/try_join.rs @@ -1,4 +1,4 @@ -/// Wait on multiple concurrent branches, returning when **all** branches +/// Waits on multiple concurrent branches, returning when **all** branches /// complete with `Ok(_)` or on the first `Err(_)`. /// /// The `try_join!` macro must be used inside of async functions, closures, and diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs index 86f0ec1d261..8aecb21aaa9 100644 --- a/tokio/src/net/tcp/listener.rs +++ b/tokio/src/net/tcp/listener.rs @@ -227,7 +227,7 @@ impl TcpListener { Ok(TcpListener { io }) } - /// Turn a [`tokio::net::TcpListener`] into a [`std::net::TcpListener`]. + /// Turns a [`tokio::net::TcpListener`] into a [`std::net::TcpListener`]. /// /// The returned [`std::net::TcpListener`] will have nonblocking mode set as /// `true`. Use [`set_nonblocking`] to change the blocking mode if needed. diff --git a/tokio/src/net/tcp/mod.rs b/tokio/src/net/tcp/mod.rs index 7f0f6d91473..cb8a8b238be 100644 --- a/tokio/src/net/tcp/mod.rs +++ b/tokio/src/net/tcp/mod.rs @@ -1,4 +1,4 @@ -//! TCP utility types +//! TCP utility types. pub(crate) mod listener; diff --git a/tokio/src/net/tcp/socket.rs b/tokio/src/net/tcp/socket.rs index 02cb6377e1d..f54ff958f80 100644 --- a/tokio/src/net/tcp/socket.rs +++ b/tokio/src/net/tcp/socket.rs @@ -87,7 +87,7 @@ cfg_net! { } impl TcpSocket { - /// Create a new socket configured for IPv4. + /// Creates a new socket configured for IPv4. /// /// Calls `socket(2)` with `AF_INET` and `SOCK_STREAM`. /// @@ -121,7 +121,7 @@ impl TcpSocket { Ok(TcpSocket { inner }) } - /// Create a new socket configured for IPv6. + /// Creates a new socket configured for IPv6. /// /// Calls `socket(2)` with `AF_INET6` and `SOCK_STREAM`. /// @@ -155,7 +155,7 @@ impl TcpSocket { Ok(TcpSocket { inner }) } - /// Allow the socket to bind to an in-use address. + /// Allows the socket to bind to an in-use address. /// /// Behavior is platform specific. Refer to the target platform's /// documentation for more details. @@ -185,7 +185,7 @@ impl TcpSocket { self.inner.set_reuseaddr(reuseaddr) } - /// Retrieves the value set for `SO_REUSEADDR` on this socket + /// Retrieves the value set for `SO_REUSEADDR` on this socket. /// /// # Examples /// @@ -211,7 +211,7 @@ impl TcpSocket { self.inner.get_reuseaddr() } - /// Allow the socket to bind to an in-use port. Only available for unix systems + /// Allows the socket to bind to an in-use port. Only available for unix systems /// (excluding Solaris & Illumos). /// /// Behavior is platform specific. Refer to the target platform's @@ -245,7 +245,7 @@ impl TcpSocket { self.inner.set_reuseport(reuseport) } - /// Allow the socket to bind to an in-use port. Only available for unix systems + /// Allows the socket to bind to an in-use port. Only available for unix systems /// (excluding Solaris & Illumos). /// /// Behavior is platform specific. Refer to the target platform's @@ -348,7 +348,7 @@ impl TcpSocket { self.inner.get_recv_buffer_size() } - /// Get the local address of this socket. + /// Gets the local address of this socket. /// /// Will fail on windows if called before `bind`. /// @@ -374,7 +374,7 @@ impl TcpSocket { self.inner.get_localaddr() } - /// Bind the socket to the given address. + /// Binds the socket to the given address. /// /// This calls the `bind(2)` operating-system function. Behavior is /// platform specific. Refer to the target platform's documentation for more @@ -406,7 +406,7 @@ impl TcpSocket { self.inner.bind(addr) } - /// Establish a TCP connection with a peer at the specified socket address. + /// Establishes a TCP connection with a peer at the specified socket address. /// /// The `TcpSocket` is consumed. Once the connection is established, a /// connected [`TcpStream`] is returned. If the connection fails, the @@ -443,7 +443,7 @@ impl TcpSocket { TcpStream::connect_mio(mio).await } - /// Convert the socket into a `TcpListener`. + /// Converts the socket into a `TcpListener`. /// /// `backlog` defines the maximum number of pending connections are queued /// by the operating system at any given time. Connection are removed from diff --git a/tokio/src/net/tcp/split.rs b/tokio/src/net/tcp/split.rs index 437ee19ea86..0e02928495f 100644 --- a/tokio/src/net/tcp/split.rs +++ b/tokio/src/net/tcp/split.rs @@ -53,7 +53,7 @@ pub(crate) fn split(stream: &mut TcpStream) -> (ReadHalf<'_>, WriteHalf<'_>) { } impl ReadHalf<'_> { - /// Attempt to receive data on the socket, without removing that data from + /// Attempts to receive data on the socket, without removing that data from /// the queue, registering the current task for wakeup if data is not yet /// available. /// @@ -139,7 +139,7 @@ impl ReadHalf<'_> { poll_fn(|cx| self.poll_peek(cx, &mut buf)).await } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -157,7 +157,7 @@ impl ReadHalf<'_> { self.0.ready(interest).await } - /// Wait for the socket to become readable. + /// Waits for the socket to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_read()`. @@ -174,7 +174,7 @@ impl ReadHalf<'_> { self.0.readable().await } - /// Try to read data from the stream into the provided buffer, returning how + /// Tries to read data from the stream into the provided buffer, returning how /// many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -197,7 +197,7 @@ impl ReadHalf<'_> { self.0.try_read(buf) } - /// Try to read data from the stream into the provided buffers, returning + /// Tries to read data from the stream into the provided buffers, returning /// how many bytes were read. /// /// Data is copied to fill each buffer in order, with the final buffer @@ -227,7 +227,7 @@ impl ReadHalf<'_> { } cfg_io_util! { - /// Try to read data from the stream into the provided buffer, advancing the + /// Tries to read data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -263,7 +263,7 @@ impl ReadHalf<'_> { } impl WriteHalf<'_> { - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -281,7 +281,7 @@ impl WriteHalf<'_> { self.0.ready(interest).await } - /// Wait for the socket to become writable. + /// Waits for the socket to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is usually /// paired with `try_write()`. @@ -296,7 +296,7 @@ impl WriteHalf<'_> { self.0.writable().await } - /// Try to write a buffer to the stream, returning how many bytes were + /// Tries to write a buffer to the stream, returning how many bytes were /// written. /// /// The function will attempt to write the entire contents of `buf`, but @@ -313,7 +313,7 @@ impl WriteHalf<'_> { self.0.try_write(buf) } - /// Try to write several buffers to the stream, returning how many bytes + /// Tries to write several buffers to the stream, returning how many bytes /// were written. /// /// Data is written from each buffer in order, with the final buffer read diff --git a/tokio/src/net/tcp/split_owned.rs b/tokio/src/net/tcp/split_owned.rs index 7485fffe451..ef4e7b53611 100644 --- a/tokio/src/net/tcp/split_owned.rs +++ b/tokio/src/net/tcp/split_owned.rs @@ -194,7 +194,7 @@ impl OwnedReadHalf { poll_fn(|cx| self.poll_peek(cx, &mut buf)).await } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -212,7 +212,7 @@ impl OwnedReadHalf { self.inner.ready(interest).await } - /// Wait for the socket to become readable. + /// Waits for the socket to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_read()`. @@ -229,7 +229,7 @@ impl OwnedReadHalf { self.inner.readable().await } - /// Try to read data from the stream into the provided buffer, returning how + /// Tries to read data from the stream into the provided buffer, returning how /// many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -252,7 +252,7 @@ impl OwnedReadHalf { self.inner.try_read(buf) } - /// Try to read data from the stream into the provided buffers, returning + /// Tries to read data from the stream into the provided buffers, returning /// how many bytes were read. /// /// Data is copied to fill each buffer in order, with the final buffer @@ -282,7 +282,7 @@ impl OwnedReadHalf { } cfg_io_util! { - /// Try to read data from the stream into the provided buffer, advancing the + /// Tries to read data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -337,7 +337,7 @@ impl OwnedWriteHalf { reunite(other, self) } - /// Destroy the write half, but don't close the write half of the stream + /// Destroys the write half, but don't close the write half of the stream /// until the read half is dropped. If the read half has already been /// dropped, this closes the stream. pub fn forget(mut self) { @@ -345,7 +345,7 @@ impl OwnedWriteHalf { drop(self); } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -363,7 +363,7 @@ impl OwnedWriteHalf { self.inner.ready(interest).await } - /// Wait for the socket to become writable. + /// Waits for the socket to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is usually /// paired with `try_write()`. @@ -378,7 +378,7 @@ impl OwnedWriteHalf { self.inner.writable().await } - /// Try to write a buffer to the stream, returning how many bytes were + /// Tries to write a buffer to the stream, returning how many bytes were /// written. /// /// The function will attempt to write the entire contents of `buf`, but @@ -395,7 +395,7 @@ impl OwnedWriteHalf { self.inner.try_write(buf) } - /// Try to write several buffers to the stream, returning how many bytes + /// Tries to write several buffers to the stream, returning how many bytes /// were written. /// /// Data is written from each buffer in order, with the final buffer read diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index 34ac6eeb872..60d20fd74b2 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -192,7 +192,7 @@ impl TcpStream { Ok(TcpStream { io }) } - /// Turn a [`tokio::net::TcpStream`] into a [`std::net::TcpStream`]. + /// Turns a [`tokio::net::TcpStream`] into a [`std::net::TcpStream`]. /// /// The returned [`std::net::TcpStream`] will have nonblocking mode set as `true`. /// Use [`set_nonblocking`] to change the blocking mode if needed. @@ -350,7 +350,7 @@ impl TcpStream { } } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -422,7 +422,7 @@ impl TcpStream { Ok(event.ready) } - /// Wait for the socket to become readable. + /// Waits for the socket to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_read()`. @@ -510,7 +510,7 @@ impl TcpStream { self.io.registration().poll_read_ready(cx).map_ok(|_| ()) } - /// Try to read data from the stream into the provided buffer, returning how + /// Tries to read data from the stream into the provided buffer, returning how /// many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -577,7 +577,7 @@ impl TcpStream { .try_io(Interest::READABLE, || (&*self.io).read(buf)) } - /// Try to read data from the stream into the provided buffers, returning + /// Tries to read data from the stream into the provided buffers, returning /// how many bytes were read. /// /// Data is copied to fill each buffer in order, with the final buffer @@ -656,7 +656,7 @@ impl TcpStream { } cfg_io_util! { - /// Try to read data from the stream into the provided buffer, advancing the + /// Tries to read data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -734,7 +734,7 @@ impl TcpStream { } } - /// Wait for the socket to become writable. + /// Waits for the socket to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is usually /// paired with `try_write()`. @@ -874,7 +874,7 @@ impl TcpStream { .try_io(Interest::WRITABLE, || (&*self.io).write(buf)) } - /// Try to write several buffers to the stream, returning how many bytes + /// Tries to write several buffers to the stream, returning how many bytes /// were written. /// /// Data is written from each buffer in order, with the final buffer read @@ -936,7 +936,7 @@ impl TcpStream { .try_io(Interest::WRITABLE, || (&*self.io).write_vectored(bufs)) } - /// Try to read or write from the socket using a user-provided IO operation. + /// Tries to read or write from the socket using a user-provided IO operation. /// /// If the socket is ready, the provided closure is called. The closure /// should attempt to perform IO operation from the socket by manually diff --git a/tokio/src/net/udp.rs b/tokio/src/net/udp.rs index 9782f174eb2..504d74eb491 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -12,7 +12,7 @@ cfg_io_util! { } cfg_net! { - /// A UDP socket + /// A UDP socket. /// /// 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`: @@ -211,7 +211,7 @@ impl UdpSocket { UdpSocket::new(io) } - /// Turn a [`tokio::net::UdpSocket`] into a [`std::net::UdpSocket`]. + /// Turns a [`tokio::net::UdpSocket`] into a [`std::net::UdpSocket`]. /// /// The returned [`std::net::UdpSocket`] will have nonblocking mode set as /// `true`. Use [`set_nonblocking`] to change the blocking mode if needed. @@ -317,7 +317,7 @@ impl UdpSocket { })) } - /// Wait for any of the requested ready states. + /// 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 @@ -388,7 +388,7 @@ impl UdpSocket { Ok(event.ready) } - /// Wait for the socket to become writable. + /// Waits for the socket to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is /// usually paired with `try_send()` or `try_send_to()`. @@ -549,7 +549,7 @@ impl UdpSocket { .poll_write_io(cx, || self.io.send(buf)) } - /// Try to send data on the socket to the remote address to which it is + /// Tries to send data on the socket to the remote address to which it is /// connected. /// /// When the socket buffer is full, `Err(io::ErrorKind::WouldBlock)` is @@ -603,7 +603,7 @@ impl UdpSocket { .try_io(Interest::WRITABLE, || self.io.send(buf)) } - /// Wait for the socket to become readable. + /// Waits for the socket to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_recv()`. @@ -781,7 +781,7 @@ impl UdpSocket { Poll::Ready(Ok(())) } - /// Try to receive a single datagram message on the socket from the remote + /// Tries to receive a single datagram message on the socket from the remote /// address to which it is connected. On success, returns the number of /// bytes read. /// @@ -838,7 +838,7 @@ impl UdpSocket { } cfg_io_util! { - /// Try to receive data from the stream into the provided buffer, advancing the + /// Tries to receive data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// /// The function must be called with valid byte array buf of sufficient size @@ -903,7 +903,7 @@ impl UdpSocket { }) } - /// Try to receive a single datagram message on the socket. On success, + /// Tries to receive a single datagram message on the socket. On success, /// returns the number of bytes read and the origin. /// /// The function must be called with valid byte array buf of sufficient size @@ -1044,7 +1044,7 @@ impl UdpSocket { .poll_write_io(cx, || self.io.send_to(buf, target)) } - /// Try to send data on the socket to the given address, but if the send is + /// Tries to send data on the socket to the given address, but if the send is /// blocked this will return right away. /// /// This function is usually paired with `writable()`. @@ -1182,7 +1182,7 @@ impl UdpSocket { Poll::Ready(Ok(addr)) } - /// Try to receive a single datagram message on the socket. On success, + /// Tries to receive a single datagram message on the socket. On success, /// returns the number of bytes read and the origin. /// /// The function must be called with valid byte array buf of sufficient size @@ -1236,7 +1236,7 @@ impl UdpSocket { .try_io(Interest::READABLE, || self.io.recv_from(buf)) } - /// Try to read or write from the socket using a user-provided IO operation. + /// Tries to read or write from the socket using a user-provided IO operation. /// /// If the socket is ready, the provided closure is called. The closure /// should attempt to perform IO operation from the socket by manually diff --git a/tokio/src/net/unix/datagram/socket.rs b/tokio/src/net/unix/datagram/socket.rs index 2c283a5bff5..d5b618663dc 100644 --- a/tokio/src/net/unix/datagram/socket.rs +++ b/tokio/src/net/unix/datagram/socket.rs @@ -96,7 +96,7 @@ cfg_net_unix! { } impl UnixDatagram { - /// Wait for any of the requested ready states. + /// 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 @@ -169,7 +169,7 @@ impl UnixDatagram { Ok(event.ready) } - /// Wait for the socket to become writable. + /// Waits for the socket to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is /// usually paired with `try_send()` or `try_send_to()`. @@ -259,7 +259,7 @@ impl UnixDatagram { self.io.registration().poll_write_ready(cx).map_ok(|_| ()) } - /// Wait for the socket to become readable. + /// Waits for the socket to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_recv()`. @@ -463,7 +463,7 @@ impl UnixDatagram { Ok(UnixDatagram { io }) } - /// Turn a [`tokio::net::UnixDatagram`] into a [`std::os::unix::net::UnixDatagram`]. + /// Turns a [`tokio::net::UnixDatagram`] into a [`std::os::unix::net::UnixDatagram`]. /// /// The returned [`std::os::unix::net::UnixDatagram`] will have nonblocking /// mode set as `true`. Use [`set_nonblocking`] to change the blocking mode @@ -614,7 +614,7 @@ impl UnixDatagram { .await } - /// Try to send a datagram to the peer without waiting. + /// Tries to send a datagram to the peer without waiting. /// /// # Examples /// @@ -658,7 +658,7 @@ impl UnixDatagram { .try_io(Interest::WRITABLE, || self.io.send(buf)) } - /// Try to send a datagram to the peer without waiting. + /// Tries to send a datagram to the peer without waiting. /// /// # Examples /// @@ -744,7 +744,7 @@ impl UnixDatagram { .await } - /// Try to receive a datagram from the peer without waiting. + /// Tries to receive a datagram from the peer without waiting. /// /// # Examples /// @@ -795,7 +795,7 @@ impl UnixDatagram { } cfg_io_util! { - /// Try to receive data from the socket without waiting. + /// Tries to receive data from the socket without waiting. /// /// # Examples /// @@ -856,7 +856,7 @@ impl UnixDatagram { Ok((n, SocketAddr(addr))) } - /// Try to read data from the stream into the provided buffer, advancing the + /// Tries to read data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// /// # Examples @@ -1157,7 +1157,7 @@ impl UnixDatagram { Poll::Ready(Ok(())) } - /// Try to receive data from the socket without waiting. + /// Tries to receive data from the socket without waiting. /// /// # Examples /// @@ -1209,7 +1209,7 @@ impl UnixDatagram { Ok((n, SocketAddr(addr))) } - /// Try to read or write from the socket using a user-provided IO operation. + /// Tries to read or write from the socket using a user-provided IO operation. /// /// If the socket is ready, the provided closure is called. The closure /// should attempt to perform IO operation from the socket by manually diff --git a/tokio/src/net/unix/listener.rs b/tokio/src/net/unix/listener.rs index efb9503d407..1785f8b0f73 100644 --- a/tokio/src/net/unix/listener.rs +++ b/tokio/src/net/unix/listener.rs @@ -88,7 +88,7 @@ impl UnixListener { Ok(UnixListener { io }) } - /// Turn a [`tokio::net::UnixListener`] into a [`std::os::unix::net::UnixListener`]. + /// Turns a [`tokio::net::UnixListener`] into a [`std::os::unix::net::UnixListener`]. /// /// The returned [`std::os::unix::net::UnixListener`] will have nonblocking mode /// set as `true`. Use [`set_nonblocking`] to change the blocking mode if needed. diff --git a/tokio/src/net/unix/mod.rs b/tokio/src/net/unix/mod.rs index c3046f17e6b..14cb456705f 100644 --- a/tokio/src/net/unix/mod.rs +++ b/tokio/src/net/unix/mod.rs @@ -1,4 +1,4 @@ -//! Unix domain socket utility types +//! Unix domain socket utility types. // This module does not currently provide any public API, but it was // unintentionally defined as a public module. Hide it from the documentation diff --git a/tokio/src/net/unix/split.rs b/tokio/src/net/unix/split.rs index 7dc47280824..d4686c22d78 100644 --- a/tokio/src/net/unix/split.rs +++ b/tokio/src/net/unix/split.rs @@ -69,7 +69,7 @@ impl ReadHalf<'_> { self.0.ready(interest).await } - /// Wait for the socket to become readable. + /// Waits for the socket to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_read()`. @@ -84,7 +84,7 @@ impl ReadHalf<'_> { self.0.readable().await } - /// Try to read data from the stream into the provided buffer, returning how + /// Tries to read data from the stream into the provided buffer, returning how /// many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -108,7 +108,7 @@ impl ReadHalf<'_> { } cfg_io_util! { - /// Try to read data from the stream into the provided buffer, advancing the + /// Tries to read data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -131,7 +131,7 @@ impl ReadHalf<'_> { } } - /// Try to read data from the stream into the provided buffers, returning + /// Tries to read data from the stream into the provided buffers, returning /// how many bytes were read. /// /// Data is copied to fill each buffer in order, with the final buffer @@ -172,7 +172,7 @@ impl ReadHalf<'_> { } impl WriteHalf<'_> { - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -188,7 +188,7 @@ impl WriteHalf<'_> { self.0.ready(interest).await } - /// Wait for the socket to become writable. + /// Waits for the socket to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is usually /// paired with `try_write()`. @@ -203,7 +203,7 @@ impl WriteHalf<'_> { self.0.writable().await } - /// Try to write a buffer to the stream, returning how many bytes were + /// Tries to write a buffer to the stream, returning how many bytes were /// written. /// /// The function will attempt to write the entire contents of `buf`, but @@ -220,7 +220,7 @@ impl WriteHalf<'_> { self.0.try_write(buf) } - /// Try to write several buffers to the stream, returning how many bytes + /// Tries to write several buffers to the stream, returning how many bytes /// were written. /// /// Data is written from each buffer in order, with the final buffer read diff --git a/tokio/src/net/unix/split_owned.rs b/tokio/src/net/unix/split_owned.rs index 47380b522e9..9c3a2a41777 100644 --- a/tokio/src/net/unix/split_owned.rs +++ b/tokio/src/net/unix/split_owned.rs @@ -108,7 +108,7 @@ impl OwnedReadHalf { reunite(self, other) } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -124,7 +124,7 @@ impl OwnedReadHalf { self.inner.ready(interest).await } - /// Wait for the socket to become readable. + /// Waits for the socket to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_read()`. @@ -139,7 +139,7 @@ impl OwnedReadHalf { self.inner.readable().await } - /// Try to read data from the stream into the provided buffer, returning how + /// Tries to read data from the stream into the provided buffer, returning how /// many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -163,7 +163,7 @@ impl OwnedReadHalf { } cfg_io_util! { - /// Try to read data from the stream into the provided buffer, advancing the + /// Tries to read data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -187,7 +187,7 @@ impl OwnedReadHalf { } } - /// Try to read data from the stream into the provided buffers, returning + /// Tries to read data from the stream into the provided buffers, returning /// how many bytes were read. /// /// Data is copied to fill each buffer in order, with the final buffer @@ -247,7 +247,7 @@ impl OwnedWriteHalf { reunite(other, self) } - /// Destroy the write half, but don't close the write half of the stream + /// Destroys the write half, but don't close the write half of the stream /// until the read half is dropped. If the read half has already been /// dropped, this closes the stream. pub fn forget(mut self) { @@ -255,7 +255,7 @@ impl OwnedWriteHalf { drop(self); } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -271,7 +271,7 @@ impl OwnedWriteHalf { self.inner.ready(interest).await } - /// Wait for the socket to become writable. + /// Waits for the socket to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is usually /// paired with `try_write()`. @@ -286,7 +286,7 @@ impl OwnedWriteHalf { self.inner.writable().await } - /// Try to write a buffer to the stream, returning how many bytes were + /// Tries to write a buffer to the stream, returning how many bytes were /// written. /// /// The function will attempt to write the entire contents of `buf`, but @@ -303,7 +303,7 @@ impl OwnedWriteHalf { self.inner.try_write(buf) } - /// Try to write several buffers to the stream, returning how many bytes + /// Tries to write several buffers to the stream, returning how many bytes /// were written. /// /// Data is written from each buffer in order, with the final buffer read diff --git a/tokio/src/net/unix/stream.rs b/tokio/src/net/unix/stream.rs index 75e6f37af49..4e7ef87b416 100644 --- a/tokio/src/net/unix/stream.rs +++ b/tokio/src/net/unix/stream.rs @@ -59,7 +59,7 @@ impl UnixStream { Ok(stream) } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same socket on a single @@ -133,7 +133,7 @@ impl UnixStream { Ok(event.ready) } - /// Wait for the socket to become readable. + /// Waits for the socket to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_read()`. @@ -290,7 +290,7 @@ impl UnixStream { .try_io(Interest::READABLE, || (&*self.io).read(buf)) } - /// Try to read data from the stream into the provided buffers, returning + /// Tries to read data from the stream into the provided buffers, returning /// how many bytes were read. /// /// Data is copied to fill each buffer in order, with the final buffer @@ -369,7 +369,7 @@ impl UnixStream { } cfg_io_util! { - /// Try to read data from the stream into the provided buffer, advancing the + /// Tries to read data from the stream into the provided buffer, advancing the /// buffer's internal cursor, returning how many bytes were read. /// /// Receives any pending data from the socket but does not wait for new data @@ -449,7 +449,7 @@ impl UnixStream { } } - /// Wait for the socket to become writable. + /// Waits for the socket to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is usually /// paired with `try_write()`. @@ -535,7 +535,7 @@ impl UnixStream { self.io.registration().poll_write_ready(cx).map_ok(|_| ()) } - /// Try to write a buffer to the stream, returning how many bytes were + /// Tries to write a buffer to the stream, returning how many bytes were /// written. /// /// The function will attempt to write the entire contents of `buf`, but @@ -591,7 +591,7 @@ impl UnixStream { .try_io(Interest::WRITABLE, || (&*self.io).write(buf)) } - /// Try to write several buffers to the stream, returning how many bytes + /// Tries to write several buffers to the stream, returning how many bytes /// were written. /// /// Data is written from each buffer in order, with the final buffer read @@ -653,7 +653,7 @@ impl UnixStream { .try_io(Interest::WRITABLE, || (&*self.io).write_vectored(buf)) } - /// Try to read or write from the socket using a user-provided IO operation. + /// Tries to read or write from the socket using a user-provided IO operation. /// /// If the socket is ready, the provided closure is called. The closure /// should attempt to perform IO operation from the socket by manually @@ -709,7 +709,7 @@ impl UnixStream { Ok(UnixStream { io }) } - /// Turn a [`tokio::net::UnixStream`] into a [`std::os::unix::net::UnixStream`]. + /// Turns a [`tokio::net::UnixStream`] into a [`std::os::unix::net::UnixStream`]. /// /// The returned [`std::os::unix::net::UnixStream`] will have nonblocking /// mode set as `true`. Use [`set_nonblocking`] to change the blocking @@ -834,7 +834,7 @@ impl UnixStream { // These lifetime markers also appear in the generated documentation, and make // it more clear that this is a *borrowed* split. #[allow(clippy::needless_lifetimes)] - /// Split a `UnixStream` into a read half and a write half, which can be used + /// Splits a `UnixStream` into a read half and a write half, which can be used /// to read and write the stream concurrently. /// /// This method is more efficient than [`into_split`], but the halves cannot be diff --git a/tokio/src/net/unix/ucred.rs b/tokio/src/net/unix/ucred.rs index 49c714284e7..865303b4cef 100644 --- a/tokio/src/net/unix/ucred.rs +++ b/tokio/src/net/unix/ucred.rs @@ -1,13 +1,13 @@ use libc::{gid_t, pid_t, uid_t}; -/// Credentials of a process +/// Credentials of a process. #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct UCred { - /// PID (process ID) of the process + /// PID (process ID) of the process. pid: Option, - /// UID (user ID) of the process + /// UID (user ID) of the process. uid: uid_t, - /// GID (group ID) of the process + /// GID (group ID) of the process. gid: gid_t, } diff --git a/tokio/src/net/windows/named_pipe.rs b/tokio/src/net/windows/named_pipe.rs index de6ab58cf4d..550fd4df2bc 100644 --- a/tokio/src/net/windows/named_pipe.rs +++ b/tokio/src/net/windows/named_pipe.rs @@ -105,7 +105,7 @@ pub struct NamedPipeServer { } impl NamedPipeServer { - /// Construct a new named pipe server from the specified raw handle. + /// Constructs a new named pipe server from the specified raw handle. /// /// This function will consume ownership of the handle given, passing /// responsibility for closing the handle to the returned object. @@ -234,7 +234,7 @@ impl NamedPipeServer { self.io.disconnect() } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same pipe on a single @@ -301,7 +301,7 @@ impl NamedPipeServer { Ok(event.ready) } - /// Wait for the pipe to become readable. + /// Waits for the pipe to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_read()`. @@ -383,7 +383,7 @@ impl NamedPipeServer { self.io.registration().poll_read_ready(cx).map_ok(|_| ()) } - /// Try to read data from the pipe into the provided buffer, returning how + /// Tries to read data from the pipe into the provided buffer, returning how /// many bytes were read. /// /// Receives any pending data from the pipe but does not wait for new data @@ -450,7 +450,7 @@ impl NamedPipeServer { .try_io(Interest::READABLE, || (&*self.io).read(buf)) } - /// Try to read data from the pipe into the provided buffers, returning + /// Tries to read data from the pipe into the provided buffers, returning /// how many bytes were read. /// /// Data is copied to fill each buffer in order, with the final buffer @@ -528,7 +528,7 @@ impl NamedPipeServer { .try_io(Interest::READABLE, || (&*self.io).read_vectored(bufs)) } - /// Wait for the pipe to become writable. + /// Waits for the pipe to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is usually /// paired with `try_write()`. @@ -606,7 +606,7 @@ impl NamedPipeServer { self.io.registration().poll_write_ready(cx).map_ok(|_| ()) } - /// Try to write a buffer to the pipe, returning how many bytes were + /// Tries to write a buffer to the pipe, returning how many bytes were /// written. /// /// The function will attempt to write the entire contents of `buf`, but @@ -662,7 +662,7 @@ impl NamedPipeServer { .try_io(Interest::WRITABLE, || (&*self.io).write(buf)) } - /// Try to write several buffers to the pipe, returning how many bytes + /// Tries to write several buffers to the pipe, returning how many bytes /// were written. /// /// Data is written from each buffer in order, with the final buffer read @@ -724,7 +724,7 @@ impl NamedPipeServer { .try_io(Interest::WRITABLE, || (&*self.io).write_vectored(buf)) } - /// Try to read or write from the socket using a user-provided IO operation. + /// Tries to read or write from the socket using a user-provided IO operation. /// /// If the socket is ready, the provided closure is called. The closure /// should attempt to perform IO operation from the socket by manually @@ -846,7 +846,7 @@ pub struct NamedPipeClient { } impl NamedPipeClient { - /// Construct a new named pipe client from the specified raw handle. + /// Constructs a new named pipe client from the specified raw handle. /// /// This function will consume ownership of the handle given, passing /// responsibility for closing the handle to the returned object. @@ -896,7 +896,7 @@ impl NamedPipeClient { unsafe { named_pipe_info(self.io.as_raw_handle()) } } - /// Wait for any of the requested ready states. + /// Waits for any of the requested ready states. /// /// This function is usually paired with `try_read()` or `try_write()`. It /// can be used to concurrently read / write to the same pipe on a single @@ -962,7 +962,7 @@ impl NamedPipeClient { Ok(event.ready) } - /// Wait for the pipe to become readable. + /// Waits for the pipe to become readable. /// /// This function is equivalent to `ready(Interest::READABLE)` and is usually /// paired with `try_read()`. @@ -1043,7 +1043,7 @@ impl NamedPipeClient { self.io.registration().poll_read_ready(cx).map_ok(|_| ()) } - /// Try to read data from the pipe into the provided buffer, returning how + /// Tries to read data from the pipe into the provided buffer, returning how /// many bytes were read. /// /// Receives any pending data from the pipe but does not wait for new data @@ -1109,7 +1109,7 @@ impl NamedPipeClient { .try_io(Interest::READABLE, || (&*self.io).read(buf)) } - /// Try to read data from the pipe into the provided buffers, returning + /// Tries to read data from the pipe into the provided buffers, returning /// how many bytes were read. /// /// Data is copied to fill each buffer in order, with the final buffer @@ -1186,7 +1186,7 @@ impl NamedPipeClient { .try_io(Interest::READABLE, || (&*self.io).read_vectored(bufs)) } - /// Wait for the pipe to become writable. + /// Waits for the pipe to become writable. /// /// This function is equivalent to `ready(Interest::WRITABLE)` and is usually /// paired with `try_write()`. @@ -1263,7 +1263,7 @@ impl NamedPipeClient { self.io.registration().poll_write_ready(cx).map_ok(|_| ()) } - /// Try to write a buffer to the pipe, returning how many bytes were + /// Tries to write a buffer to the pipe, returning how many bytes were /// written. /// /// The function will attempt to write the entire contents of `buf`, but @@ -1318,7 +1318,7 @@ impl NamedPipeClient { .try_io(Interest::WRITABLE, || (&*self.io).write(buf)) } - /// Try to write several buffers to the pipe, returning how many bytes + /// Tries to write several buffers to the pipe, returning how many bytes /// were written. /// /// Data is written from each buffer in order, with the final buffer read @@ -1379,7 +1379,7 @@ impl NamedPipeClient { .try_io(Interest::WRITABLE, || (&*self.io).write_vectored(buf)) } - /// Try to read or write from the socket using a user-provided IO operation. + /// Tries to read or write from the socket using a user-provided IO operation. /// /// If the socket is ready, the provided closure is called. The closure /// should attempt to perform IO operation from the socket by manually @@ -1882,7 +1882,7 @@ impl ServerOptions { self } - /// Create the named pipe identified by `addr` for use as a server. + /// Creates the named pipe identified by `addr` for use as a server. /// /// This uses the [`CreateNamedPipe`] function. /// @@ -1913,7 +1913,7 @@ impl ServerOptions { unsafe { self.create_with_security_attributes_raw(addr, ptr::null_mut()) } } - /// Create the named pipe identified by `addr` for use as a server. + /// Creates the named pipe identified by `addr` for use as a server. /// /// This is the same as [`create`] except that it supports providing the raw /// pointer to a structure of [`SECURITY_ATTRIBUTES`] which will be passed @@ -2042,7 +2042,7 @@ impl ClientOptions { self } - /// Open the named pipe identified by `addr`. + /// Opens the named pipe identified by `addr`. /// /// This opens the client using [`CreateFile`] with the /// `dwCreationDisposition` option set to `OPEN_EXISTING`. @@ -2099,7 +2099,7 @@ impl ClientOptions { unsafe { self.open_with_security_attributes_raw(addr, ptr::null_mut()) } } - /// Open the named pipe identified by `addr`. + /// Opens the named pipe identified by `addr`. /// /// This is the same as [`open`] except that it supports providing the raw /// pointer to a structure of [`SECURITY_ATTRIBUTES`] which will be passed @@ -2201,7 +2201,7 @@ pub struct PipeInfo { pub in_buffer_size: u32, } -/// Encode an address so that it is a null-terminated wide string. +/// Encodes an address so that it is a null-terminated wide string. fn encode_addr(addr: impl AsRef) -> Box<[u16]> { let len = addr.as_ref().encode_wide().count(); let mut vec = Vec::with_capacity(len + 1); diff --git a/tokio/src/park/mod.rs b/tokio/src/park/mod.rs index edd93710016..87d04ff78ea 100644 --- a/tokio/src/park/mod.rs +++ b/tokio/src/park/mod.rs @@ -45,12 +45,12 @@ use std::fmt::Debug; use std::sync::Arc; use std::time::Duration; -/// Block the current thread. +/// Blocks the current thread. pub(crate) trait Park { /// Unpark handle type for the `Park` implementation. type Unpark: Unpark; - /// Error returned by `park` + /// Error returned by `park`. type Error: Debug; /// Gets a new `Unpark` handle associated with this `Park` instance. @@ -66,7 +66,7 @@ pub(crate) trait Park { /// /// This function **should** not panic, but ultimately, panics are left as /// an implementation detail. Refer to the documentation for the specific - /// `Park` implementation + /// `Park` implementation. fn park(&mut self) -> Result<(), Self::Error>; /// Parks the current thread for at most `duration`. @@ -82,10 +82,10 @@ pub(crate) trait Park { /// /// This function **should** not panic, but ultimately, panics are left as /// an implementation detail. Refer to the documentation for the specific - /// `Park` implementation + /// `Park` implementation. fn park_timeout(&mut self, duration: Duration) -> Result<(), Self::Error>; - /// Release all resources holded by the parker for proper leak-free shutdown + /// Releases all resources holded by the parker for proper leak-free shutdown. fn shutdown(&mut self); } @@ -100,7 +100,7 @@ pub(crate) trait Unpark: Sync + Send + 'static { /// /// This function **should** not panic, but ultimately, panics are left as /// an implementation detail. Refer to the documentation for the specific - /// `Unpark` implementation + /// `Unpark` implementation. fn unpark(&self); } diff --git a/tokio/src/park/thread.rs b/tokio/src/park/thread.rs index 2725e4563e9..27ce2024396 100644 --- a/tokio/src/park/thread.rs +++ b/tokio/src/park/thread.rs @@ -76,7 +76,7 @@ impl Park for ParkThread { // ==== impl Inner ==== impl Inner { - /// Park the current thread for at most `dur`. + /// Parks the current thread for at most `dur`. fn park(&self) { // If we were previously notified then we consume this notification and // return quickly. @@ -227,7 +227,7 @@ pub(crate) struct CachedParkThread { } impl CachedParkThread { - /// Create a new `ParkThread` handle for the current thread. + /// Creates a new `ParkThread` handle for the current thread. /// /// This type cannot be moved to other threads, so it should be created on /// the thread that the caller intends to park. @@ -241,7 +241,7 @@ impl CachedParkThread { self.with_current(|park_thread| park_thread.unpark()) } - /// Get a reference to the `ParkThread` handle for this thread. + /// Gets a reference to the `ParkThread` handle for this thread. fn with_current(&self, f: F) -> Result where F: FnOnce(&ParkThread) -> R, diff --git a/tokio/src/process/mod.rs b/tokio/src/process/mod.rs index 7a150242a67..6eeefdbef71 100644 --- a/tokio/src/process/mod.rs +++ b/tokio/src/process/mod.rs @@ -578,7 +578,7 @@ impl Command { self } - /// Set executable argument + /// Sets executable argument. /// /// Set the first process argument, `argv[0]`, to something other than the /// default executable path. @@ -1173,7 +1173,7 @@ pub struct ChildStderr { } impl ChildStdin { - /// Create an asynchronous `ChildStdin` from a synchronous one. + /// Creates an asynchronous `ChildStdin` from a synchronous one. /// /// # Errors /// @@ -1188,7 +1188,7 @@ impl ChildStdin { } impl ChildStdout { - /// Create an asynchronous `ChildStderr` from a synchronous one. + /// Creates an asynchronous `ChildStderr` from a synchronous one. /// /// # Errors /// @@ -1203,7 +1203,7 @@ impl ChildStdout { } impl ChildStderr { - /// Create an asynchronous `ChildStderr` from a synchronous one. + /// Creates an asynchronous `ChildStderr` from a synchronous one. /// /// # Errors /// diff --git a/tokio/src/process/unix/driver.rs b/tokio/src/process/unix/driver.rs index 43b2efa0a66..84dc8fbd027 100644 --- a/tokio/src/process/unix/driver.rs +++ b/tokio/src/process/unix/driver.rs @@ -1,6 +1,6 @@ #![cfg_attr(not(feature = "rt"), allow(dead_code))] -//! Process driver +//! Process driver. use crate::park::Park; use crate::process::unix::GlobalOrphanQueue; diff --git a/tokio/src/process/unix/mod.rs b/tokio/src/process/unix/mod.rs index 0f379c9fcd6..576fe6cb47f 100644 --- a/tokio/src/process/unix/mod.rs +++ b/tokio/src/process/unix/mod.rs @@ -1,4 +1,4 @@ -//! Unix handling of child processes +//! Unix handling of child processes. //! //! Right now the only "fancy" thing about this is how we implement the //! `Future` implementation on `Child` to get the exit status. Unix offers diff --git a/tokio/src/runtime/basic_scheduler.rs b/tokio/src/runtime/basic_scheduler.rs index af255dae9e7..7634e9c60b1 100644 --- a/tokio/src/runtime/basic_scheduler.rs +++ b/tokio/src/runtime/basic_scheduler.rs @@ -213,7 +213,7 @@ impl BasicScheduler

{ } impl Inner

{ - /// Block on the future provided and drive the runtime's driver. + /// Blocks on the provided future and drives the runtime's driver. fn block_on(&mut self, future: F) -> F::Output { enter(self, |scheduler, context| { let _enter = crate::runtime::enter(false); @@ -299,8 +299,8 @@ impl Inner

{ } } -/// Enter the scheduler context. This sets the queue and other necessary -/// scheduler state in the thread-local +/// Enters the scheduler context. This sets the queue and other necessary +/// scheduler state in the thread-local. fn enter(scheduler: &mut Inner

, f: F) -> R where F: FnOnce(&mut Inner

, &Context) -> R, diff --git a/tokio/src/runtime/blocking/pool.rs b/tokio/src/runtime/blocking/pool.rs index 0c23bb0dc86..8e25ffa5a3e 100644 --- a/tokio/src/runtime/blocking/pool.rs +++ b/tokio/src/runtime/blocking/pool.rs @@ -25,28 +25,28 @@ pub(crate) struct Spawner { } struct Inner { - /// State shared between worker threads + /// State shared between worker threads. shared: Mutex, /// Pool threads wait on this. condvar: Condvar, - /// Spawned threads use this name + /// Spawned threads use this name. thread_name: ThreadNameFn, - /// Spawned thread stack size + /// Spawned thread stack size. stack_size: Option, - /// Call after a thread starts + /// Call after a thread starts. after_start: Option, - /// Call before a thread stops + /// Call before a thread stops. before_stop: Option, - // Maximum number of threads + // Maximum number of threads. thread_cap: usize, - // Customizable wait timeout + // Customizable wait timeout. keep_alive: Duration, } @@ -67,7 +67,7 @@ struct Shared { /// 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 - /// benefit) + /// benefit). worker_thread_index: usize, } @@ -75,7 +75,7 @@ type Task = task::UnownedTask; const KEEP_ALIVE: Duration = Duration::from_secs(10); -/// Run the provided function on an executor dedicated to blocking operations. +/// Runs the provided function on an executor dedicated to blocking operations. pub(crate) fn spawn_blocking(func: F) -> JoinHandle where F: FnOnce() -> R + Send + 'static, diff --git a/tokio/src/runtime/blocking/task.rs b/tokio/src/runtime/blocking/task.rs index ee2d8d6d608..0b7803a6c0b 100644 --- a/tokio/src/runtime/blocking/task.rs +++ b/tokio/src/runtime/blocking/task.rs @@ -2,13 +2,13 @@ use std::future::Future; use std::pin::Pin; use std::task::{Context, Poll}; -/// Converts a function to a future that completes on poll +/// Converts a function to a future that completes on poll. pub(crate) struct BlockingTask { func: Option, } impl BlockingTask { - /// Initializes a new blocking task from the given function + /// Initializes a new blocking task from the given function. pub(crate) fn new(func: T) -> BlockingTask { BlockingTask { func: Some(func) } } diff --git a/tokio/src/runtime/context.rs b/tokio/src/runtime/context.rs index a727ed4979d..7ed6520667d 100644 --- a/tokio/src/runtime/context.rs +++ b/tokio/src/runtime/context.rs @@ -51,7 +51,7 @@ cfg_rt! { } } -/// Set this [`Handle`] as the current active [`Handle`]. +/// Sets this [`Handle`] as the current active [`Handle`]. /// /// [`Handle`]: Handle pub(crate) fn enter(new: Handle) -> EnterGuard { diff --git a/tokio/src/runtime/enter.rs b/tokio/src/runtime/enter.rs index e91408f382f..3f14cb58782 100644 --- a/tokio/src/runtime/enter.rs +++ b/tokio/src/runtime/enter.rs @@ -92,7 +92,7 @@ cfg_rt_multi_thread! { } cfg_rt! { - /// Disallow blocking in the current runtime context until the guard is dropped. + /// Disallows blocking in the current runtime context until the guard is dropped. pub(crate) fn disallow_blocking() -> DisallowBlockingGuard { let reset = ENTERED.with(|c| { if let EnterContext::Entered { diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs index 605041b4b6a..1eeef6575ae 100644 --- a/tokio/src/runtime/handle.rs +++ b/tokio/src/runtime/handle.rs @@ -47,7 +47,7 @@ pub struct EnterGuard<'a> { } impl Handle { - /// Enter the runtime context. This allows you to construct types that must + /// Enters the runtime context. This allows you to construct types that must /// have an executor available on creation such as [`Sleep`] or [`TcpStream`]. /// It will also allow you to call methods such as [`tokio::spawn`]. /// @@ -61,7 +61,7 @@ impl Handle { } } - /// Returns a `Handle` view over the currently running `Runtime` + /// Returns a `Handle` view over the currently running `Runtime`. /// /// # Panic /// @@ -120,7 +120,7 @@ impl Handle { } } - /// Spawn a future onto the Tokio runtime. + /// Spawns a future onto the Tokio runtime. /// /// This spawns the given future onto the runtime's executor, usually a /// thread pool. The thread pool is then responsible for polling the future @@ -158,7 +158,7 @@ impl Handle { self.spawner.spawn(future) } - /// Run the provided function on an executor dedicated to blocking + /// Runs the provided function on an executor dedicated to blocking. /// operations. /// /// # Examples @@ -227,7 +227,7 @@ impl Handle { handle } - /// Run a future to completion on this `Handle`'s associated `Runtime`. + /// Runs a future to completion on this `Handle`'s associated `Runtime`. /// /// This runs the given future on the current thread, blocking until it is /// complete, and yielding its resolved result. Any tasks or timers which diff --git a/tokio/src/runtime/mod.rs b/tokio/src/runtime/mod.rs index ec7d0c09abc..a07c1657119 100644 --- a/tokio/src/runtime/mod.rs +++ b/tokio/src/runtime/mod.rs @@ -294,7 +294,7 @@ cfg_rt! { type Callback = std::sync::Arc; impl Runtime { - /// Create a new runtime instance with default configuration values. + /// Creates a new runtime instance with default configuration values. /// /// This results in the multi threaded scheduler, I/O driver, and time driver being /// initialized. @@ -329,7 +329,7 @@ cfg_rt! { Builder::new_multi_thread().enable_all().build() } - /// Return a handle to the runtime's spawner. + /// Returns a handle to the runtime's spawner. /// /// The returned handle can be used to spawn tasks that run on this runtime, and can /// be cloned to allow moving the `Handle` to other threads. @@ -350,7 +350,7 @@ cfg_rt! { &self.handle } - /// Spawn a future onto the Tokio runtime. + /// Spawns a future onto the Tokio runtime. /// /// This spawns the given future onto the runtime's executor, usually a /// thread pool. The thread pool is then responsible for polling the future @@ -384,7 +384,7 @@ cfg_rt! { self.handle.spawn(future) } - /// Run the provided function on an executor dedicated to blocking operations. + /// Runs the provided function on an executor dedicated to blocking operations. /// /// # Examples /// @@ -409,7 +409,7 @@ cfg_rt! { self.handle.spawn_blocking(func) } - /// Run a future to completion on the Tokio runtime. This is the + /// Runs a future to completion on the Tokio runtime. This is the /// runtime's entry point. /// /// This runs the given future on the current thread, blocking until it is @@ -464,7 +464,7 @@ cfg_rt! { } } - /// Enter the runtime context. + /// Enters the runtime context. /// /// This allows you to construct types that must have an executor /// available on creation such as [`Sleep`] or [`TcpStream`]. It will @@ -500,7 +500,7 @@ cfg_rt! { self.handle.enter() } - /// Shutdown the runtime, waiting for at most `duration` for all spawned + /// Shuts down the runtime, waiting for at most `duration` for all spawned /// task to shutdown. /// /// Usually, dropping a `Runtime` handle is sufficient as tasks are able to @@ -541,7 +541,7 @@ cfg_rt! { self.blocking_pool.shutdown(Some(duration)); } - /// Shutdown the runtime, without waiting for any spawned tasks to shutdown. + /// Shuts down the runtime, without waiting for any spawned tasks to shutdown. /// /// This can be useful if you want to drop a runtime from within another runtime. /// Normally, dropping a runtime will block indefinitely for spawned blocking tasks diff --git a/tokio/src/runtime/task/core.rs b/tokio/src/runtime/task/core.rs index 51b64966af9..776e8341f37 100644 --- a/tokio/src/runtime/task/core.rs +++ b/tokio/src/runtime/task/core.rs @@ -44,22 +44,22 @@ pub(super) struct CoreStage { /// /// Holds the future or output, depending on the stage of execution. pub(super) struct Core { - /// Scheduler used to drive this future + /// Scheduler used to drive this future. pub(super) scheduler: S, - /// Either the future or the output + /// Either the future or the output. pub(super) stage: CoreStage, } /// Crate public as this is also needed by the pool. #[repr(C)] pub(crate) struct Header { - /// Task state + /// Task state. pub(super) state: State, pub(super) owned: UnsafeCell>, - /// Pointer to next task, used with the injection queue + /// Pointer to next task, used with the injection queue. pub(super) queue_next: UnsafeCell>>, /// Table of function pointers for executing actions on the task. @@ -133,7 +133,7 @@ impl CoreStage { self.stage.with_mut(f) } - /// Poll the future + /// Polls the future. /// /// # Safety /// @@ -169,7 +169,7 @@ impl CoreStage { res } - /// Drop the future + /// Drops the future. /// /// # Safety /// @@ -181,7 +181,7 @@ impl CoreStage { } } - /// Store the task output + /// Stores the task output. /// /// # Safety /// @@ -193,7 +193,7 @@ impl CoreStage { } } - /// Take the task output + /// Takes the task output. /// /// # Safety /// diff --git a/tokio/src/runtime/task/error.rs b/tokio/src/runtime/task/error.rs index 17fb09390ae..1a8129b2b6f 100644 --- a/tokio/src/runtime/task/error.rs +++ b/tokio/src/runtime/task/error.rs @@ -29,12 +29,12 @@ impl JoinError { } } - /// Returns true if the error was caused by the task being cancelled + /// Returns true if the error was caused by the task being cancelled. pub fn is_cancelled(&self) -> bool { matches!(&self.repr, Repr::Cancelled) } - /// Returns true if the error was caused by the task panicking + /// Returns true if the error was caused by the task panicking. /// /// # Examples /// diff --git a/tokio/src/runtime/task/harness.rs b/tokio/src/runtime/task/harness.rs index 41b41938e11..0996e5232db 100644 --- a/tokio/src/runtime/task/harness.rs +++ b/tokio/src/runtime/task/harness.rs @@ -10,7 +10,7 @@ use std::panic; use std::ptr::NonNull; use std::task::{Context, Poll, Waker}; -/// Typed raw task handle +/// Typed raw task handle. pub(super) struct Harness { cell: NonNull>, } @@ -74,7 +74,7 @@ where } } - /// Poll the task and cancel it if necessary. This takes ownership of a + /// Polls the task and cancel it if necessary. This takes ownership of a /// ref-count. /// /// If the return value is Notified, the caller is given ownership of two @@ -124,7 +124,7 @@ where } } - /// Forcibly shutdown the task + /// Forcibly shuts down the task. /// /// Attempt to transition to `Running` in order to forcibly shutdown the /// task. If the task is currently running or in a state of completion, then @@ -192,7 +192,7 @@ where } } - /// Remotely abort the task. + /// Remotely aborts the task. /// /// The caller should hold a ref-count, but we do not consume it. /// @@ -280,7 +280,7 @@ where // ====== internal ====== - /// Complete the task. This method assumes that the state is RUNNING. + /// Completes the task. This method assumes that the state is RUNNING. fn complete(self) { // The future has completed and its output has been written to the task // stage. We transition from running to complete. @@ -310,7 +310,7 @@ where } } - /// Release the task from the scheduler. Returns the number of ref-counts + /// Releases the task from the scheduler. Returns the number of ref-counts /// that should be decremented. fn release(&self) -> usize { // We don't actually increment the ref-count here, but the new task is @@ -325,7 +325,7 @@ where } } - /// Create a new task that holds its own ref-count. + /// Creates a new task that holds its own ref-count. /// /// # Safety /// @@ -425,7 +425,7 @@ enum PollFuture { Dealloc, } -/// Cancel the task and store the appropriate error in the stage field. +/// Cancels the task and store the appropriate error in the stage field. fn cancel_task(stage: &CoreStage) { // Drop the future from a panic guard. let res = panic::catch_unwind(panic::AssertUnwindSafe(|| { @@ -442,7 +442,7 @@ fn cancel_task(stage: &CoreStage) { } } -/// Poll the future. If the future completes, the output is written to the +/// Polls the future. If the future completes, the output is written to the /// stage field. fn poll_future(core: &CoreStage, cx: Context<'_>) -> Poll<()> { // Poll the future. diff --git a/tokio/src/runtime/task/inject.rs b/tokio/src/runtime/task/inject.rs index d1f0aee9d81..1585e13a019 100644 --- a/tokio/src/runtime/task/inject.rs +++ b/tokio/src/runtime/task/inject.rs @@ -11,7 +11,7 @@ use std::sync::atomic::Ordering::{Acquire, Release}; /// Growable, MPMC queue used to inject new tasks into the scheduler and as an /// overflow queue when the local, fixed-size, array queue overflows. pub(crate) struct Inject { - /// Pointers to the head and tail of the queue + /// Pointers to the head and tail of the queue. pointers: Mutex, /// Number of pending tasks in the queue. This helps prevent unnecessary @@ -22,13 +22,13 @@ pub(crate) struct Inject { } struct Pointers { - /// True if the queue is closed + /// True if the queue is closed. is_closed: bool, - /// Linked-list head + /// Linked-list head. head: Option>, - /// Linked-list tail + /// Linked-list tail. tail: Option>, } @@ -52,7 +52,7 @@ impl Inject { self.len() == 0 } - /// Close the injection queue, returns `true` if the queue is open when the + /// Closes the injection queue, returns `true` if the queue is open when the /// transition is made. pub(crate) fn close(&self) -> bool { let mut p = self.pointers.lock(); @@ -137,7 +137,7 @@ impl Inject { self.push_batch_inner(first, prev, counter); } - /// Insert several tasks that have been linked together into the queue. + /// Inserts several tasks that have been linked together into the queue. /// /// The provided head and tail may be be the same task. In this case, a /// single task is inserted. diff --git a/tokio/src/runtime/task/list.rs b/tokio/src/runtime/task/list.rs index edd3c4fac1f..7758f8db7aa 100644 --- a/tokio/src/runtime/task/list.rs +++ b/tokio/src/runtime/task/list.rs @@ -78,7 +78,7 @@ impl OwnedTasks { } } - /// Bind the provided task to this OwnedTasks instance. This fails if the + /// Binds the provided task to this OwnedTasks instance. This fails if the /// OwnedTasks has been closed. pub(crate) fn bind( &self, @@ -110,7 +110,7 @@ impl OwnedTasks { } } - /// Assert that the given task is owned by this OwnedTasks and convert it to + /// 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 { @@ -124,7 +124,7 @@ impl OwnedTasks { } } - /// Shut down all tasks in the collection. This call also closes the + /// Shuts down all tasks in the collection. This call also closes the /// collection, preventing new items from being added. pub(crate) fn close_and_shutdown_all(&self) where @@ -213,7 +213,7 @@ impl LocalOwnedTasks { } } - /// Shut down all tasks in the collection. This call also closes the + /// Shuts down all tasks in the collection. This call also closes the /// collection, preventing new items from being added. pub(crate) fn close_and_shutdown_all(&self) where @@ -241,7 +241,7 @@ impl LocalOwnedTasks { unsafe { inner.list.remove(task.header().into()) }) } - /// Assert that the given task is owned by this LocalOwnedTasks and convert + /// 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 { diff --git a/tokio/src/runtime/task/mod.rs b/tokio/src/runtime/task/mod.rs index 5f0d5aba132..1f18209a6fb 100644 --- a/tokio/src/runtime/task/mod.rs +++ b/tokio/src/runtime/task/mod.rs @@ -173,7 +173,7 @@ use std::marker::PhantomData; use std::ptr::NonNull; use std::{fmt, mem}; -/// An owned handle to the task, tracked by ref count +/// An owned handle to the task, tracked by ref count. #[repr(transparent)] pub(crate) struct Task { raw: RawTask, @@ -211,7 +211,7 @@ pub(crate) struct UnownedTask { unsafe impl Send for UnownedTask {} unsafe impl Sync for UnownedTask {} -/// Task result sent back +/// Task result sent back. pub(crate) type Result = std::result::Result; pub(crate) trait Schedule: Sync + Sized + 'static { @@ -260,7 +260,7 @@ cfg_rt! { (task, notified, join) } - /// Create a new task with an associated join handle. This method is used + /// Creates a new task with an associated join handle. This method is used /// only when the task is not going to be stored in an `OwnedTasks` list. /// /// Currently only blocking tasks use this method. @@ -327,7 +327,7 @@ cfg_rt_multi_thread! { } impl Task { - /// Pre-emptively cancel the task as part of the shutdown process. + /// Pre-emptively cancels the task as part of the shutdown process. pub(crate) fn shutdown(self) { let raw = self.raw; mem::forget(self); @@ -336,7 +336,7 @@ impl Task { } impl LocalNotified { - /// Run the task + /// Runs the task. pub(crate) fn run(self) { let raw = self.task.raw; mem::forget(self); @@ -420,7 +420,7 @@ impl fmt::Debug for Notified { /// # Safety /// -/// Tasks are pinned +/// Tasks are pinned. unsafe impl linked_list::Link for Task { type Handle = Task; type Target = Header; diff --git a/tokio/src/runtime/task/raw.rs b/tokio/src/runtime/task/raw.rs index 8c2c3f73291..fbc9574f1a4 100644 --- a/tokio/src/runtime/task/raw.rs +++ b/tokio/src/runtime/task/raw.rs @@ -10,22 +10,22 @@ pub(super) struct RawTask { } pub(super) struct Vtable { - /// Poll the future + /// Polls the future. pub(super) poll: unsafe fn(NonNull

), - /// Deallocate the memory + /// Deallocates the memory. pub(super) dealloc: unsafe fn(NonNull
), - /// Read the task output, if complete + /// Reads the task output, if complete. pub(super) try_read_output: unsafe fn(NonNull
, *mut (), &Waker), - /// The join handle has been dropped + /// The join handle has been dropped. pub(super) drop_join_handle_slow: unsafe fn(NonNull
), - /// The task is remotely aborted + /// The task is remotely aborted. pub(super) remote_abort: unsafe fn(NonNull
), - /// Scheduler is being shutdown + /// Scheduler is being shutdown. pub(super) shutdown: unsafe fn(NonNull
), } diff --git a/tokio/src/runtime/task/state.rs b/tokio/src/runtime/task/state.rs index 059a7f9ee99..c2d5b28eac2 100644 --- a/tokio/src/runtime/task/state.rs +++ b/tokio/src/runtime/task/state.rs @@ -8,7 +8,7 @@ pub(super) struct State { val: AtomicUsize, } -/// Current state value +/// Current state value. #[derive(Copy, Clone)] pub(super) struct Snapshot(usize); @@ -19,20 +19,20 @@ const RUNNING: usize = 0b0001; /// The task is complete. /// -/// Once this bit is set, it is never unset +/// Once this bit is set, it is never unset. const COMPLETE: usize = 0b0010; -/// Extracts the task's lifecycle value from the state +/// Extracts the task's lifecycle value from the state. const LIFECYCLE_MASK: usize = 0b11; /// Flag tracking if the task has been pushed into a run queue. const NOTIFIED: usize = 0b100; -/// The join handle is still around +/// The join handle is still around. #[allow(clippy::unusual_byte_groupings)] // https://github.com/rust-lang/rust-clippy/issues/6556 const JOIN_INTEREST: usize = 0b1_000; -/// A join handle waker has been set +/// A join handle waker has been set. #[allow(clippy::unusual_byte_groupings)] // https://github.com/rust-lang/rust-clippy/issues/6556 const JOIN_WAKER: usize = 0b10_000; @@ -40,19 +40,19 @@ const JOIN_WAKER: usize = 0b10_000; #[allow(clippy::unusual_byte_groupings)] // https://github.com/rust-lang/rust-clippy/issues/6556 const CANCELLED: usize = 0b100_000; -/// All bits +/// All bits. const STATE_MASK: usize = LIFECYCLE_MASK | NOTIFIED | JOIN_INTEREST | JOIN_WAKER | CANCELLED; /// Bits used by the ref count portion of the state. const REF_COUNT_MASK: usize = !STATE_MASK; -/// Number of positions to shift the ref count +/// Number of positions to shift the ref count. const REF_COUNT_SHIFT: usize = REF_COUNT_MASK.count_zeros() as usize; -/// One ref count +/// One ref count. const REF_ONE: usize = 1 << REF_COUNT_SHIFT; -/// State a task is initialized with +/// State a task is initialized with. /// /// A task is initialized with three references: /// @@ -96,7 +96,7 @@ pub(super) enum TransitionToNotifiedByRef { /// All transitions are performed via RMW operations. This establishes an /// unambiguous modification order. impl State { - /// Return a task's initial state + /// Returns a task's initial state. pub(super) fn new() -> State { // The raw task returned by this method has a ref-count of three. See // the comment on INITIAL_STATE for more. @@ -110,7 +110,7 @@ impl State { Snapshot(self.val.load(Acquire)) } - /// Attempt to transition the lifecycle to `Running`. This sets the + /// Attempts to transition the lifecycle to `Running`. This sets the /// notified bit to false so notifications during the poll can be detected. pub(super) fn transition_to_running(&self) -> TransitionToRunning { self.fetch_update_action(|mut next| { @@ -190,7 +190,7 @@ impl State { Snapshot(prev.0 ^ DELTA) } - /// Transition from `Complete` -> `Terminal`, decrementing the reference + /// Transitions from `Complete` -> `Terminal`, decrementing the reference /// count the specified number of times. /// /// Returns true if the task should be deallocated. @@ -270,10 +270,10 @@ impl State { }) } - /// Set the cancelled bit and transition the state to `NOTIFIED` if idle. + /// Sets the cancelled bit and transitions the state to `NOTIFIED` if idle. /// /// Returns `true` if the task needs to be submitted to the pool for - /// execution + /// execution. pub(super) fn transition_to_notified_and_cancel(&self) -> bool { self.fetch_update_action(|mut snapshot| { if snapshot.is_cancelled() || snapshot.is_complete() { @@ -306,7 +306,7 @@ impl State { }) } - /// Set the `CANCELLED` bit and attempt to transition to `Running`. + /// Sets the `CANCELLED` bit and attempts to transition to `Running`. /// /// Returns `true` if the transition to `Running` succeeded. pub(super) fn transition_to_shutdown(&self) -> bool { @@ -330,7 +330,7 @@ impl State { } /// Optimistically tries to swap the state assuming the join handle is - /// __immediately__ dropped on spawn + /// __immediately__ dropped on spawn. pub(super) fn drop_join_handle_fast(&self) -> Result<(), ()> { use std::sync::atomic::Ordering::Relaxed; @@ -352,7 +352,7 @@ impl State { .map_err(|_| ()) } - /// Try to unset the JOIN_INTEREST flag. + /// Tries to unset the JOIN_INTEREST flag. /// /// Returns `Ok` if the operation happens before the task transitions to a /// completed state, `Err` otherwise. @@ -371,7 +371,7 @@ impl State { }) } - /// Set the `JOIN_WAKER` bit. + /// Sets the `JOIN_WAKER` bit. /// /// Returns `Ok` if the bit is set, `Err` otherwise. This operation fails if /// the task has completed. diff --git a/tokio/src/runtime/thread_pool/idle.rs b/tokio/src/runtime/thread_pool/idle.rs index 2cac30ee846..6b7ee1289ce 100644 --- a/tokio/src/runtime/thread_pool/idle.rs +++ b/tokio/src/runtime/thread_pool/idle.rs @@ -126,7 +126,7 @@ impl Idle { } } - /// Returns `true` if `worker_id` is contained in the sleep set + /// Returns `true` if `worker_id` is contained in the sleep set. pub(super) fn is_parked(&self, worker_id: usize) -> bool { let sleepers = self.sleepers.lock(); sleepers.contains(&worker_id) diff --git a/tokio/src/runtime/thread_pool/mod.rs b/tokio/src/runtime/thread_pool/mod.rs index f2e68f6b9eb..82e34c78d28 100644 --- a/tokio/src/runtime/thread_pool/mod.rs +++ b/tokio/src/runtime/thread_pool/mod.rs @@ -24,7 +24,7 @@ pub(crate) struct ThreadPool { spawner: Spawner, } -/// Submit futures to the associated thread pool for execution. +/// Submits futures to the associated thread pool for execution. /// /// A `Spawner` instance is a handle to a single thread pool that allows the owner /// of the handle to spawn futures onto the thread pool. diff --git a/tokio/src/runtime/thread_pool/worker.rs b/tokio/src/runtime/thread_pool/worker.rs index 44f8db86b05..ae8efe6724f 100644 --- a/tokio/src/runtime/thread_pool/worker.rs +++ b/tokio/src/runtime/thread_pool/worker.rs @@ -126,7 +126,7 @@ pub(super) struct Shared { /// how they communicate between each other. remotes: Box<[Remote]>, - /// Submit work to the scheduler while **not** currently on a worker thread. + /// Submits work to the scheduler while **not** currently on a worker thread. inject: Inject>, /// Coordinates idle workers @@ -147,13 +147,13 @@ pub(super) struct Shared { /// Callback for a worker unparking itself after_unpark: Option, - /// Collect stats from the runtime. + /// Collects stats from the runtime. stats: RuntimeStats, } /// Used to communicate with a worker from other threads. struct Remote { - /// Steal tasks from this worker. + /// Steals tasks from this worker. steal: queue::Steal>, /// Unparks the associated worker thread @@ -587,9 +587,9 @@ impl Core { worker.shared.transition_worker_from_searching(); } - /// Prepare the worker state for parking + /// Prepares the worker state for parking. /// - /// Returns true if the transition happend, false if there is work to do first + /// Returns true if the transition happend, false if there is work to do first. fn transition_to_parked(&mut self, worker: &Worker) -> bool { // Workers should not park if they have work to do if self.lifo_slot.is_some() || self.run_queue.has_tasks() { @@ -653,7 +653,7 @@ impl Core { self.stats.submit(&worker.shared.stats); } - /// Shutdown the core + /// Shuts down the core. fn shutdown(&mut self) { // Take the core let mut park = self.park.take().expect("park missing"); @@ -666,7 +666,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> { &self.shared.inject } diff --git a/tokio/src/signal/mod.rs b/tokio/src/signal/mod.rs index fe572f041f3..882218a0f6d 100644 --- a/tokio/src/signal/mod.rs +++ b/tokio/src/signal/mod.rs @@ -1,4 +1,4 @@ -//! Asynchronous signal handling for Tokio +//! Asynchronous signal handling for Tokio. //! //! Note that signal handling is in general a very tricky topic and should be //! used with great care. This crate attempts to implement 'best practice' for diff --git a/tokio/src/signal/reusable_box.rs b/tokio/src/signal/reusable_box.rs index 426ecb06fb9..796fa210b03 100644 --- a/tokio/src/signal/reusable_box.rs +++ b/tokio/src/signal/reusable_box.rs @@ -30,7 +30,7 @@ impl ReusableBoxFuture { Self { boxed } } - /// Replace the future currently stored in this box. + /// Replaces the future currently stored in this box. /// /// This reallocates if and only if the layout of the provided future is /// different from the layout of the currently stored future. @@ -43,7 +43,7 @@ impl ReusableBoxFuture { } } - /// Replace the future currently stored in this box. + /// Replaces the future currently stored in this box. /// /// This function never reallocates, but returns an error if the provided /// future has a different size or alignment from the currently stored @@ -70,7 +70,7 @@ impl ReusableBoxFuture { } } - /// Set the current future. + /// Sets the current future. /// /// # Safety /// @@ -103,14 +103,14 @@ impl ReusableBoxFuture { } } - /// Get a pinned reference to the underlying future. + /// Gets a pinned reference to the underlying future. pub(crate) fn get_pin(&mut self) -> Pin<&mut (dyn Future + Send)> { // SAFETY: The user of this box cannot move the box, and we do not move it // either. unsafe { Pin::new_unchecked(self.boxed.as_mut()) } } - /// Poll the future stored inside this box. + /// Polls the future stored inside this box. pub(crate) fn poll(&mut self, cx: &mut Context<'_>) -> Poll { self.get_pin().poll(cx) } @@ -119,7 +119,7 @@ impl ReusableBoxFuture { impl Future for ReusableBoxFuture { type Output = T; - /// Poll the future stored inside this box. + /// Polls the future stored inside this box. fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { Pin::into_inner(self).get_pin().poll(cx) } diff --git a/tokio/src/sync/batch_semaphore.rs b/tokio/src/sync/batch_semaphore.rs index 9b43404f918..b5c39d2a05d 100644 --- a/tokio/src/sync/batch_semaphore.rs +++ b/tokio/src/sync/batch_semaphore.rs @@ -1,5 +1,5 @@ #![cfg_attr(not(feature = "sync"), allow(unreachable_pub, dead_code))] -//! # Implementation Details +//! # Implementation Details. //! //! The semaphore is implemented using an intrusive linked list of waiters. An //! atomic counter tracks the number of available permits. If the semaphore does @@ -138,7 +138,7 @@ impl Semaphore { } } - /// Creates a new semaphore with the initial number of permits + /// Creates a new semaphore with the initial number of permits. /// /// Maximum number of permits on 32-bit platforms is `1<<29`. /// @@ -159,7 +159,7 @@ impl Semaphore { } } - /// Returns the current number of available permits + /// Returns the current number of available permits. pub(crate) fn available_permits(&self) -> usize { self.permits.load(Acquire) >> Self::PERMIT_SHIFT } @@ -197,7 +197,7 @@ impl Semaphore { } } - /// Returns true if the semaphore is closed + /// Returns true if the semaphore is closed. pub(crate) fn is_closed(&self) -> bool { self.permits.load(Acquire) & Self::CLOSED == Self::CLOSED } diff --git a/tokio/src/sync/broadcast.rs b/tokio/src/sync/broadcast.rs index a2ca4459e3c..0d9cd3bc176 100644 --- a/tokio/src/sync/broadcast.rs +++ b/tokio/src/sync/broadcast.rs @@ -293,37 +293,37 @@ pub mod error { use self::error::*; -/// Data shared between senders and receivers +/// Data shared between senders and receivers. struct Shared { - /// slots in the channel + /// slots in the channel. buffer: Box<[RwLock>]>, - /// Mask a position -> index + /// Mask a position -> index. mask: usize, /// Tail of the queue. Includes the rx wait list. tail: Mutex, - /// Number of outstanding Sender handles + /// Number of outstanding Sender handles. num_tx: AtomicUsize, } -/// Next position to write a value +/// Next position to write a value. struct Tail { - /// Next position to write to + /// Next position to write to. pos: u64, - /// Number of active receivers + /// Number of active receivers. rx_cnt: usize, - /// True if the channel is closed + /// True if the channel is closed. closed: bool, - /// Receivers waiting for a value + /// Receivers waiting for a value. waiters: LinkedList::Target>, } -/// Slot in the buffer +/// Slot in the buffer. struct Slot { /// Remaining number of receivers that are expected to see this value. /// @@ -333,7 +333,7 @@ struct Slot { /// acquired. rem: AtomicUsize, - /// Uniquely identifies the `send` stored in the slot + /// Uniquely identifies the `send` stored in the slot. pos: u64, /// True signals the channel is closed. @@ -346,9 +346,9 @@ struct Slot { val: UnsafeCell>, } -/// An entry in the wait queue +/// An entry in the wait queue. struct Waiter { - /// True if queued + /// True if queued. queued: bool, /// Task waiting on the broadcast channel. @@ -365,12 +365,12 @@ struct RecvGuard<'a, T> { slot: RwLockReadGuard<'a, Slot>, } -/// Receive a value future +/// Receive a value future. struct Recv<'a, T> { - /// Receiver being waited on + /// Receiver being waited on. receiver: &'a mut Receiver, - /// Entry in the waiter `LinkedList` + /// Entry in the waiter `LinkedList`. waiter: UnsafeCell, } diff --git a/tokio/src/sync/mpsc/block.rs b/tokio/src/sync/mpsc/block.rs index 6e7b70058c9..58f4a9f6cc3 100644 --- a/tokio/src/sync/mpsc/block.rs +++ b/tokio/src/sync/mpsc/block.rs @@ -40,7 +40,7 @@ struct Values([UnsafeCell>; BLOCK_CAP]); use super::BLOCK_CAP; -/// Masks an index to get the block identifier +/// Masks an index to get the block identifier. const BLOCK_MASK: usize = !(BLOCK_CAP - 1); /// Masks an index to get the value offset in a block. @@ -89,7 +89,7 @@ impl Block { } } - /// Returns `true` if the block matches the given index + /// Returns `true` if the block matches the given index. pub(crate) fn is_at_index(&self, index: usize) -> bool { debug_assert!(offset(index) == 0); self.start_index == index diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index bcad84dd373..5a2bfa6e868 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -10,7 +10,7 @@ cfg_time! { use std::fmt; use std::task::{Context, Poll}; -/// Send values to the associated `Receiver`. +/// Sends values to the associated `Receiver`. /// /// Instances are created by the [`channel`](channel) function. /// @@ -22,7 +22,7 @@ pub struct Sender { chan: chan::Tx, } -/// Permit to send one value into the channel. +/// Permits to send one value into the channel. /// /// `Permit` values are returned by [`Sender::reserve()`] and [`Sender::try_reserve()`] /// and are used to guarantee channel capacity before generating a message to send. @@ -49,7 +49,7 @@ pub struct OwnedPermit { chan: Option>, } -/// Receive values from the associated `Sender`. +/// Receives values from the associated `Sender`. /// /// Instances are created by the [`channel`](channel) function. /// @@ -57,7 +57,7 @@ pub struct OwnedPermit { /// /// [`ReceiverStream`]: https://docs.rs/tokio-stream/0.1/tokio_stream/wrappers/struct.ReceiverStream.html pub struct Receiver { - /// The channel receiver + /// The channel receiver. chan: chan::Rx, } @@ -187,7 +187,7 @@ impl Receiver { poll_fn(|cx| self.chan.recv(cx)).await } - /// Try to receive the next value for this receiver. + /// Tries to receive the next value for this receiver. /// /// This method returns the [`Empty`] error if the channel is currently /// empty, but there are still outstanding [senders] or [permits]. @@ -672,7 +672,7 @@ impl Sender { self.chan.is_closed() } - /// Wait for channel capacity. Once capacity to send one message is + /// Waits for channel capacity. Once capacity to send one message is /// available, it is reserved for the caller. /// /// If the channel is full, the function waits for the number of unreceived @@ -721,7 +721,7 @@ impl Sender { Ok(Permit { chan: &self.chan }) } - /// Wait for channel capacity, moving the `Sender` and returning an owned + /// Waits for channel capacity, moving the `Sender` and returning an owned /// permit. Once capacity to send one message is available, it is reserved /// for the caller. /// @@ -815,7 +815,7 @@ impl Sender { } } - /// Try to acquire a slot in the channel without waiting for the slot to become + /// Tries to acquire a slot in the channel without waiting for the slot to become /// available. /// /// If the channel is full this function will return [`TrySendError`], otherwise @@ -868,7 +868,7 @@ impl Sender { Ok(Permit { chan: &self.chan }) } - /// Try to acquire a slot in the channel without waiting for the slot to become + /// Tries to acquire a slot in the channel without waiting for the slot to become /// available, returning an owned permit. /// /// This moves the sender _by value_, and returns an owned permit that can @@ -1117,7 +1117,7 @@ impl OwnedPermit { Sender { chan } } - /// Release the reserved capacity *without* sending a message, returning the + /// Releases the reserved capacity *without* sending a message, returning the /// [`Sender`]. /// /// # Examples diff --git a/tokio/src/sync/mpsc/chan.rs b/tokio/src/sync/mpsc/chan.rs index 637ae1fd16f..c3007de89c7 100644 --- a/tokio/src/sync/mpsc/chan.rs +++ b/tokio/src/sync/mpsc/chan.rs @@ -14,7 +14,7 @@ use std::sync::atomic::Ordering::{AcqRel, Relaxed}; use std::task::Poll::{Pending, Ready}; use std::task::{Context, Poll}; -/// Channel sender +/// Channel sender. pub(crate) struct Tx { inner: Arc>, } @@ -25,7 +25,7 @@ impl fmt::Debug for Tx { } } -/// Channel receiver +/// Channel receiver. pub(crate) struct Rx { inner: Arc>, } @@ -47,7 +47,7 @@ pub(crate) trait Semaphore { } struct Chan { - /// Notifies all tasks listening for the receiver being dropped + /// Notifies all tasks listening for the receiver being dropped. notify_rx_closed: Notify, /// Handle to the push half of the lock-free list. diff --git a/tokio/src/sync/mpsc/error.rs b/tokio/src/sync/mpsc/error.rs index 48ca379d9ca..b7b9cf7a256 100644 --- a/tokio/src/sync/mpsc/error.rs +++ b/tokio/src/sync/mpsc/error.rs @@ -1,4 +1,4 @@ -//! Channel error types +//! Channel error types. use std::error::Error; use std::fmt; diff --git a/tokio/src/sync/mpsc/list.rs b/tokio/src/sync/mpsc/list.rs index 53c34d2fa6f..e4eeb454118 100644 --- a/tokio/src/sync/mpsc/list.rs +++ b/tokio/src/sync/mpsc/list.rs @@ -8,7 +8,7 @@ use std::fmt; use std::ptr::NonNull; use std::sync::atomic::Ordering::{AcqRel, Acquire, Relaxed, Release}; -/// List queue transmit handle +/// List queue transmit handle. pub(crate) struct Tx { /// Tail in the `Block` mpmc list. block_tail: AtomicPtr>, @@ -79,7 +79,7 @@ impl Tx { } } - /// Closes the send half of the list + /// Closes the send half of the list. /// /// Similar process as pushing a value, but instead of writing the value & /// setting the ready flag, the TX_CLOSED flag is set on the block. diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs index 89619309295..b133f9f35e3 100644 --- a/tokio/src/sync/mpsc/unbounded.rs +++ b/tokio/src/sync/mpsc/unbounded.rs @@ -129,7 +129,7 @@ impl UnboundedReceiver { poll_fn(|cx| self.poll_recv(cx)).await } - /// Try to receive the next value for this receiver. + /// Tries to receive the next value for this receiver. /// /// This method returns the [`Empty`] error if the channel is currently /// empty, but there are still outstanding [senders] or [permits]. diff --git a/tokio/src/sync/notify.rs b/tokio/src/sync/notify.rs index 787147b36ab..417f87b4143 100644 --- a/tokio/src/sync/notify.rs +++ b/tokio/src/sync/notify.rs @@ -20,7 +20,7 @@ use std::task::{Context, Poll, Waker}; type WaitList = LinkedList::Target>; -/// Notify a single task to wake up. +/// Notifies a single task to wake up. /// /// `Notify` provides a basic mechanism to notify a single task of an event. /// `Notify` itself does not carry any data. Instead, it is to be used to signal @@ -128,10 +128,10 @@ enum NotificationType { #[derive(Debug)] struct Waiter { - /// Intrusive linked-list pointers + /// Intrusive linked-list pointers. pointers: linked_list::Pointers, - /// Waiting task's waker + /// Waiting task's waker. waker: Option, /// `true` if the notification has been assigned to this waiter. @@ -168,13 +168,13 @@ const NOTIFY_WAITERS_SHIFT: usize = 2; const STATE_MASK: usize = (1 << NOTIFY_WAITERS_SHIFT) - 1; const NOTIFY_WAITERS_CALLS_MASK: usize = !STATE_MASK; -/// Initial "idle" state +/// Initial "idle" state. const EMPTY: usize = 0; /// One or more threads are currently waiting to be notified. const WAITING: usize = 1; -/// Pending notification +/// Pending notification. const NOTIFIED: usize = 2; fn set_state(data: usize, state: usize) -> usize { @@ -289,7 +289,7 @@ impl Notify { } } - /// Notifies a waiting task + /// Notifies a waiting task. /// /// If a task is currently waiting, that task is notified. Otherwise, a /// permit is stored in this `Notify` value and the **next** call to @@ -359,7 +359,7 @@ impl Notify { } } - /// Notifies all waiting tasks + /// Notifies all waiting tasks. /// /// If a task is currently waiting, that task is notified. Unlike with /// `notify_one()`, no permit is stored to be used by the next call to diff --git a/tokio/src/sync/once_cell.rs b/tokio/src/sync/once_cell.rs index 91705a55899..d31a40e2c85 100644 --- a/tokio/src/sync/once_cell.rs +++ b/tokio/src/sync/once_cell.rs @@ -245,7 +245,7 @@ impl OnceCell { } } - /// Set the value of the `OnceCell` to the given value if the `OnceCell` is + /// Sets the value of the `OnceCell` to the given value if the `OnceCell` is /// empty. /// /// If the `OnceCell` already has a value, this call will fail with an @@ -283,7 +283,7 @@ impl OnceCell { } } - /// Get the value currently in the `OnceCell`, or initialize it with the + /// Gets the value currently in the `OnceCell`, or initialize it with the /// given asynchronous operation. /// /// If some other task is currently working on initializing the `OnceCell`, @@ -331,7 +331,7 @@ impl OnceCell { } } - /// Get the value currently in the `OnceCell`, or initialize it with the + /// Gets the value currently in the `OnceCell`, or initialize it with the /// given asynchronous operation. /// /// If some other task is currently working on initializing the `OnceCell`, @@ -382,7 +382,7 @@ impl OnceCell { } } - /// Take the value from the cell, destroying the cell in the process. + /// Takes the value from the cell, destroying the cell in the process. /// Returns `None` if the cell is empty. pub fn into_inner(mut self) -> Option { if self.initialized_mut() { diff --git a/tokio/src/sync/oneshot.rs b/tokio/src/sync/oneshot.rs index 03697a7b263..c23fcb32ba0 100644 --- a/tokio/src/sync/oneshot.rs +++ b/tokio/src/sync/oneshot.rs @@ -214,7 +214,7 @@ pub struct Sender { inner: Option>>, } -/// Receive a value from the associated [`Sender`]. +/// Receives a value from the associated [`Sender`]. /// /// A pair of both a [`Sender`] and a [`Receiver`] are created by the /// [`channel`](fn@channel) function. @@ -305,7 +305,7 @@ pub struct Receiver { } pub mod error { - //! Oneshot error types + //! Oneshot error types. use std::fmt; @@ -350,7 +350,7 @@ pub mod error { use self::error::*; struct Inner { - /// Manages the state of the inner cell + /// Manages the state of the inner cell. state: AtomicUsize, /// The value. This is set by `Sender` and read by `Receiver`. The state of @@ -399,7 +399,7 @@ impl Task { #[derive(Clone, Copy)] struct State(usize); -/// Create a new one-shot channel for sending single values across asynchronous +/// Creates a new one-shot channel for sending single values across asynchronous /// tasks. /// /// The function returns separate "send" and "receive" handles. The `Sender` @@ -609,7 +609,7 @@ impl Sender { state.is_closed() } - /// Check 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/sync/rwlock/owned_read_guard.rs b/tokio/src/sync/rwlock/owned_read_guard.rs index b7f3926a485..1881295846e 100644 --- a/tokio/src/sync/rwlock/owned_read_guard.rs +++ b/tokio/src/sync/rwlock/owned_read_guard.rs @@ -22,7 +22,7 @@ pub struct OwnedRwLockReadGuard { } impl OwnedRwLockReadGuard { - /// Make a new `OwnedRwLockReadGuard` for a component of the locked data. + /// Makes a new `OwnedRwLockReadGuard` for a component of the locked data. /// This operation cannot fail as the `OwnedRwLockReadGuard` passed in /// already locked the data. /// diff --git a/tokio/src/sync/rwlock/owned_write_guard.rs b/tokio/src/sync/rwlock/owned_write_guard.rs index 91b659524f5..0a78d28e903 100644 --- a/tokio/src/sync/rwlock/owned_write_guard.rs +++ b/tokio/src/sync/rwlock/owned_write_guard.rs @@ -24,7 +24,7 @@ pub struct OwnedRwLockWriteGuard { } impl OwnedRwLockWriteGuard { - /// Make a new [`OwnedRwLockMappedWriteGuard`] for a component of the locked + /// Makes a new [`OwnedRwLockMappedWriteGuard`] for a component of the locked /// data. /// /// This operation cannot fail as the `OwnedRwLockWriteGuard` passed in diff --git a/tokio/src/sync/rwlock/owned_write_guard_mapped.rs b/tokio/src/sync/rwlock/owned_write_guard_mapped.rs index 6453236eb56..d88ee01e1fd 100644 --- a/tokio/src/sync/rwlock/owned_write_guard_mapped.rs +++ b/tokio/src/sync/rwlock/owned_write_guard_mapped.rs @@ -23,7 +23,7 @@ pub struct OwnedRwLockMappedWriteGuard { } impl OwnedRwLockMappedWriteGuard { - /// Make a new `OwnedRwLockMappedWriteGuard` for a component of the locked + /// Makes a new `OwnedRwLockMappedWriteGuard` for a component of the locked /// data. /// /// This operation cannot fail as the `OwnedRwLockMappedWriteGuard` passed diff --git a/tokio/src/sync/rwlock/read_guard.rs b/tokio/src/sync/rwlock/read_guard.rs index 38eec7727c3..090b297e4af 100644 --- a/tokio/src/sync/rwlock/read_guard.rs +++ b/tokio/src/sync/rwlock/read_guard.rs @@ -19,7 +19,7 @@ pub struct RwLockReadGuard<'a, T: ?Sized> { } impl<'a, T: ?Sized> RwLockReadGuard<'a, T> { - /// Make a new `RwLockReadGuard` for a component of the locked data. + /// Makes a new `RwLockReadGuard` for a component of the locked data. /// /// This operation cannot fail as the `RwLockReadGuard` passed in already /// locked the data. diff --git a/tokio/src/sync/rwlock/write_guard.rs b/tokio/src/sync/rwlock/write_guard.rs index 865a121ed87..8c80ee70db4 100644 --- a/tokio/src/sync/rwlock/write_guard.rs +++ b/tokio/src/sync/rwlock/write_guard.rs @@ -22,7 +22,7 @@ pub struct RwLockWriteGuard<'a, T: ?Sized> { } impl<'a, T: ?Sized> RwLockWriteGuard<'a, T> { - /// Make a new [`RwLockMappedWriteGuard`] for a component of the locked data. + /// Makes a new [`RwLockMappedWriteGuard`] for a component of the locked data. /// /// This operation cannot fail as the `RwLockWriteGuard` passed in already /// locked the data. diff --git a/tokio/src/sync/rwlock/write_guard_mapped.rs b/tokio/src/sync/rwlock/write_guard_mapped.rs index 9c5b1e7c321..3cf69de4bdd 100644 --- a/tokio/src/sync/rwlock/write_guard_mapped.rs +++ b/tokio/src/sync/rwlock/write_guard_mapped.rs @@ -21,7 +21,7 @@ pub struct RwLockMappedWriteGuard<'a, T: ?Sized> { } impl<'a, T: ?Sized> RwLockMappedWriteGuard<'a, T> { - /// Make a new `RwLockMappedWriteGuard` for a component of the locked data. + /// Makes a new `RwLockMappedWriteGuard` for a component of the locked data. /// /// This operation cannot fail as the `RwLockMappedWriteGuard` passed in already /// locked the data. diff --git a/tokio/src/sync/task/atomic_waker.rs b/tokio/src/sync/task/atomic_waker.rs index 8616007a3b1..d81063375d0 100644 --- a/tokio/src/sync/task/atomic_waker.rs +++ b/tokio/src/sync/task/atomic_waker.rs @@ -123,7 +123,7 @@ pub(crate) struct AtomicWaker { // Thread A still holds the `wake` lock, the call to `register` will result // in the task waking itself and get scheduled again. -/// Idle state +/// Idle state. const WAITING: usize = 0; /// A new waker value is being registered with the `AtomicWaker` cell. diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs index 0293e6293c6..74c5b40ecee 100644 --- a/tokio/src/sync/watch.rs +++ b/tokio/src/sync/watch.rs @@ -86,7 +86,7 @@ pub struct Sender { shared: Arc>, } -/// Returns a reference to the inner value +/// Returns a reference to the inner value. /// /// Outstanding borrows hold a read lock on the inner value. This means that /// long lived borrows could cause the produce half to block. It is recommended @@ -98,27 +98,27 @@ pub struct Ref<'a, T> { #[derive(Debug)] struct Shared { - /// The most recent value + /// The most recent value. value: RwLock, - /// The current version + /// The current version. /// /// The lowest bit represents a "closed" state. The rest of the bits /// represent the current version. state: AtomicState, - /// Tracks the number of `Receiver` instances + /// Tracks the number of `Receiver` instances. ref_count_rx: AtomicUsize, /// Notifies waiting receivers that the value changed. notify_rx: Notify, - /// Notifies any task listening for `Receiver` dropped events + /// Notifies any task listening for `Receiver` dropped events. notify_tx: Notify, } pub mod error { - //! Watch error types + //! Watch error types. use std::fmt; @@ -318,7 +318,7 @@ impl Receiver { Ref { inner } } - /// Wait for a change notification, then mark the newest value as seen. + /// Waits for a change notification, then marks the newest value as seen. /// /// If the newest value in the channel has not yet been marked seen when /// this method is called, the method marks that value seen and returns @@ -617,7 +617,7 @@ impl Sender { Receiver::from_shared(version, shared) } - /// Returns the number of receivers that currently exist + /// Returns the number of receivers that currently exist. /// /// # Examples /// diff --git a/tokio/src/task/local.rs b/tokio/src/task/local.rs index a28d793c233..4a5d313c6e4 100644 --- a/tokio/src/task/local.rs +++ b/tokio/src/task/local.rs @@ -211,10 +211,10 @@ cfg_rt! { /// [`task::spawn_local`]: fn@spawn_local /// [`mpsc`]: mod@crate::sync::mpsc pub struct LocalSet { - /// Current scheduler tick + /// Current scheduler tick. tick: Cell, - /// State available from thread-local + /// State available from thread-local. context: Context, /// This type should not be Send. @@ -222,7 +222,7 @@ cfg_rt! { } } -/// State available from the thread-local +/// State available from the thread-local. struct Context { /// Collection of all active tasks spawned onto this executor. owned: LocalOwnedTasks>, @@ -236,10 +236,10 @@ struct Context { /// LocalSet state shared between threads. struct Shared { - /// Remote run queue sender + /// Remote run queue sender. queue: Mutex>>>>, - /// Wake the `LocalSet` task + /// Wake the `LocalSet` task. waker: AtomicWaker, } @@ -315,13 +315,13 @@ cfg_rt! { } } -/// Initial queue capacity +/// Initial queue capacity. const INITIAL_CAPACITY: usize = 64; /// Max number of tasks to poll per tick. const MAX_TASKS_PER_TICK: usize = 61; -/// How often it check the remote queue first +/// How often it check the remote queue first. const REMOTE_FIRST_INTERVAL: u8 = 31; impl LocalSet { @@ -466,7 +466,7 @@ impl LocalSet { rt.block_on(self.run_until(future)) } - /// Run a future to completion on the local set, returning its output. + /// Runs a future to completion on the local set, returning its output. /// /// This returns a future that runs the given future with a local set, /// allowing it to call [`spawn_local`] to spawn additional `!Send` futures. @@ -505,7 +505,7 @@ impl LocalSet { run_until.await } - /// Tick the scheduler, returning whether the local future needs to be + /// Ticks the scheduler, returning whether the local future needs to be /// notified again. fn tick(&self) -> bool { for _ in 0..MAX_TASKS_PER_TICK { diff --git a/tokio/src/time/clock.rs b/tokio/src/time/clock.rs index fae5c768a55..41be9bac48c 100644 --- a/tokio/src/time/clock.rs +++ b/tokio/src/time/clock.rs @@ -57,11 +57,11 @@ cfg_test_util! { /// Instant to use as the clock's base instant. base: std::time::Instant, - /// Instant at which the clock was last unfrozen + /// Instant at which the clock was last unfrozen. unfrozen: Option, } - /// Pause time + /// Pauses time. /// /// The current value of `Instant::now()` is saved and all subsequent calls /// to `Instant::now()` will return the saved value. The saved value can be @@ -101,7 +101,7 @@ cfg_test_util! { clock.pause(); } - /// Resume time + /// Resumes time. /// /// Clears the saved `Instant::now()` value. Subsequent calls to /// `Instant::now()` will return the value returned by the system call. @@ -121,7 +121,7 @@ cfg_test_util! { inner.unfrozen = Some(std::time::Instant::now()); } - /// Advance time. + /// Advances time. /// /// Increments the saved `Instant::now()` value by `duration`. Subsequent /// calls to `Instant::now()` will return the result of the increment. @@ -159,7 +159,7 @@ cfg_test_util! { crate::task::yield_now().await; } - /// Return the current instant, factoring in frozen time. + /// Returns the current instant, factoring in frozen time. pub(crate) fn now() -> Instant { if let Some(clock) = clock() { clock.now() @@ -169,7 +169,7 @@ cfg_test_util! { } impl Clock { - /// Return a new `Clock` instance that uses the current execution context's + /// Returns a new `Clock` instance that uses the current execution context's /// source of time. pub(crate) fn new(enable_pausing: bool, start_paused: bool) -> Clock { let now = std::time::Instant::now(); diff --git a/tokio/src/time/driver/entry.rs b/tokio/src/time/driver/entry.rs index 168e0b9956a..9e9f0dc8592 100644 --- a/tokio/src/time/driver/entry.rs +++ b/tokio/src/time/driver/entry.rs @@ -345,7 +345,7 @@ impl TimerShared { } } - /// Gets the cached time-of-expiration value + /// Gets the cached time-of-expiration value. pub(super) fn cached_when(&self) -> u64 { // Cached-when is only accessed under the driver lock, so we can use relaxed self.driver_state.0.cached_when.load(Ordering::Relaxed) diff --git a/tokio/src/time/driver/handle.rs b/tokio/src/time/driver/handle.rs index 77b435873b2..7aaf65a79e4 100644 --- a/tokio/src/time/driver/handle.rs +++ b/tokio/src/time/driver/handle.rs @@ -16,17 +16,17 @@ impl Handle { Handle { time_source, inner } } - /// Returns the time source associated with this handle + /// Returns the time source associated with this handle. pub(super) fn time_source(&self) -> &ClockTime { &self.time_source } - /// Access the driver's inner structure + /// Access the driver's inner structure. pub(super) fn get(&self) -> &super::Inner { &*self.inner } - // Check whether the driver has been shutdown + /// Checks whether the driver has been shutdown. pub(super) fn is_shutdown(&self) -> bool { self.inner.is_shutdown() } diff --git a/tokio/src/time/driver/mod.rs b/tokio/src/time/driver/mod.rs index f611fbb9c8e..cf2290bc3b9 100644 --- a/tokio/src/time/driver/mod.rs +++ b/tokio/src/time/driver/mod.rs @@ -4,7 +4,7 @@ #![allow(unused_unsafe)] #![cfg_attr(not(feature = "rt"), allow(dead_code))] -//! Time driver +//! Time driver. mod entry; pub(self) use self::entry::{EntryList, TimerEntry, TimerHandle, TimerShared}; @@ -83,13 +83,13 @@ use std::{num::NonZeroU64, ptr::NonNull, task::Waker}; /// [interval]: crate::time::Interval #[derive(Debug)] pub(crate) struct Driver { - /// Timing backend in use + /// Timing backend in use. time_source: ClockTime, - /// Shared state + /// Shared state. handle: Handle, - /// Parker to delegate to + /// Parker to delegate to. park: P, // When `true`, a call to `park_timeout` should immediately return and time @@ -146,25 +146,25 @@ struct Inner { // The state is split like this so `Handle` can access `is_shutdown` without locking the mutex pub(super) state: Mutex, - /// True if the driver is being shutdown + /// True if the driver is being shutdown. pub(super) is_shutdown: AtomicBool, } /// Time state shared which must be protected by a `Mutex` struct InnerState { - /// Timing backend in use + /// Timing backend in use. time_source: ClockTime, /// The last published timer `elapsed` value. elapsed: u64, - /// The earliest time at which we promise to wake up without unparking + /// The earliest time at which we promise to wake up without unparking. next_wake: Option, - /// Timer wheel + /// Timer wheel. wheel: wheel::Wheel, - /// Unparker that can be used to wake the time driver + /// Unparker that can be used to wake the time driver. unpark: Box, } diff --git a/tokio/src/time/driver/wheel/level.rs b/tokio/src/time/driver/wheel/level.rs index 81d6b58c71f..34d31766ce1 100644 --- a/tokio/src/time/driver/wheel/level.rs +++ b/tokio/src/time/driver/wheel/level.rs @@ -250,7 +250,7 @@ fn level_range(level: usize) -> u64 { LEVEL_MULT as u64 * slot_range(level) } -/// Convert a duration (milliseconds) and a level to a slot position +/// Converts a duration (milliseconds) and a level to a slot position. fn slot_for(duration: u64, level: usize) -> usize { ((duration >> (level * 6)) % LEVEL_MULT as u64) as usize } diff --git a/tokio/src/time/driver/wheel/mod.rs b/tokio/src/time/driver/wheel/mod.rs index 5a40f6db857..f088f2cfd66 100644 --- a/tokio/src/time/driver/wheel/mod.rs +++ b/tokio/src/time/driver/wheel/mod.rs @@ -46,11 +46,11 @@ pub(crate) struct Wheel { /// precision of 1 millisecond. const NUM_LEVELS: usize = 6; -/// The maximum duration of a `Sleep` +/// The maximum duration of a `Sleep`. pub(super) const MAX_DURATION: u64 = (1 << (6 * NUM_LEVELS)) - 1; impl Wheel { - /// Create a new timing wheel + /// Creates a new timing wheel. pub(crate) fn new() -> Wheel { let levels = (0..NUM_LEVELS).map(Level::new).collect(); @@ -61,13 +61,13 @@ impl Wheel { } } - /// Return the number of milliseconds that have elapsed since the timing + /// Returns the number of milliseconds that have elapsed since the timing /// wheel's creation. pub(crate) fn elapsed(&self) -> u64 { self.elapsed } - /// Insert an entry into the timing wheel. + /// Inserts an entry into the timing wheel. /// /// # Arguments /// @@ -115,7 +115,7 @@ impl Wheel { Ok(when) } - /// Remove `item` from the timing wheel. + /// Removes `item` from the timing wheel. pub(crate) unsafe fn remove(&mut self, item: NonNull) { unsafe { let when = item.as_ref().cached_when(); @@ -136,7 +136,7 @@ impl Wheel { } } - /// Instant at which to poll + /// Instant at which to poll. pub(crate) fn poll_at(&self) -> Option { self.next_expiration().map(|expiration| expiration.deadline) } diff --git a/tokio/src/time/driver/wheel/stack.rs b/tokio/src/time/driver/wheel/stack.rs index e7ed137f55a..80651c309e6 100644 --- a/tokio/src/time/driver/wheel/stack.rs +++ b/tokio/src/time/driver/wheel/stack.rs @@ -3,7 +3,7 @@ use crate::time::driver::Entry; use std::ptr; -/// A doubly linked stack +/// A doubly linked stack. #[derive(Debug)] pub(crate) struct Stack { head: Option, @@ -50,7 +50,7 @@ impl Stack { self.head = Some(entry); } - /// Pops an item from the stack + /// Pops an item from the stack. pub(crate) fn pop(&mut self) -> Option { let entry = self.head.take(); diff --git a/tokio/src/time/error.rs b/tokio/src/time/error.rs index 8674febe98d..63f0a3b0bda 100644 --- a/tokio/src/time/error.rs +++ b/tokio/src/time/error.rs @@ -40,7 +40,7 @@ impl From for Error { } } -/// Error returned by `Timeout`. +/// Errors returned by `Timeout`. #[derive(Debug, PartialEq)] pub struct Elapsed(()); @@ -72,7 +72,7 @@ impl Error { matches!(self.0, Kind::AtCapacity) } - /// Create an error representing a misconfigured timer. + /// Creates an error representing a misconfigured timer. pub fn invalid() -> Error { Error(Invalid) } diff --git a/tokio/src/time/interval.rs b/tokio/src/time/interval.rs index fe581707185..7e07e51267e 100644 --- a/tokio/src/time/interval.rs +++ b/tokio/src/time/interval.rs @@ -147,7 +147,7 @@ pub fn interval_at(start: Instant, period: Duration) -> Interval { /// milliseconds. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum MissedTickBehavior { - /// Tick as fast as possible until caught up. + /// Ticks as fast as possible until caught up. /// /// When this strategy is used, [`Interval`] schedules ticks "normally" (the /// same as it would have if the ticks hadn't been delayed), which results @@ -252,7 +252,7 @@ pub enum MissedTickBehavior { /// [`tick`]: Interval::tick Delay, - /// Skip missed ticks and tick on the next multiple of `period` from + /// Skips missed ticks and tick on the next multiple of `period` from /// `start`. /// /// When this strategy is used, [`Interval`] schedules the next tick to fire @@ -342,7 +342,7 @@ impl Default for MissedTickBehavior { } } -/// Interval returned by [`interval`] and [`interval_at`] +/// Interval returned by [`interval`] and [`interval_at`]. /// /// This type allows you to wait on a sequence of instants with a certain /// duration between each instant. Unlike calling [`sleep`] in a loop, this lets @@ -394,7 +394,7 @@ impl Interval { poll_fn(|cx| self.poll_tick(cx)).await } - /// Poll for the next instant in the interval to be reached. + /// Polls for the next instant in the interval to be reached. /// /// This method can return the following values: /// diff --git a/tokio/src/time/timeout.rs b/tokio/src/time/timeout.rs index 007fde86cb2..6725caa09f8 100644 --- a/tokio/src/time/timeout.rs +++ b/tokio/src/time/timeout.rs @@ -14,7 +14,7 @@ use std::future::Future; use std::pin::Pin; use std::task::{self, Poll}; -/// Require a `Future` to complete before the specified duration has elapsed. +/// Requires a `Future` to complete before the specified duration has elapsed. /// /// If the future completes before the duration has elapsed, then the completed /// value is returned. Otherwise, an error is returned and the future is @@ -63,7 +63,7 @@ where Timeout::new_with_delay(future, delay) } -/// Require a `Future` to complete before the specified instant in time. +/// Requires a `Future` to complete before the specified instant in time. /// /// If the future completes before the instant is reached, then the completed /// value is returned. Otherwise, an error is returned. diff --git a/tokio/src/util/bit.rs b/tokio/src/util/bit.rs index 392a0e8b0c9..a43c2c2d364 100644 --- a/tokio/src/util/bit.rs +++ b/tokio/src/util/bit.rs @@ -27,7 +27,7 @@ impl Pack { pointer_width() - (self.mask >> self.shift).leading_zeros() } - /// Max representable value + /// Max representable value. pub(crate) const fn max_value(&self) -> usize { (1 << self.width()) - 1 } @@ -60,7 +60,7 @@ impl fmt::Debug for Pack { } } -/// Returns the width of a pointer in bits +/// Returns the width of a pointer in bits. pub(crate) const fn pointer_width() -> u32 { std::mem::size_of::() as u32 * 8 } @@ -71,7 +71,7 @@ pub(crate) const fn mask_for(n: u32) -> usize { shift | (shift - 1) } -/// Unpack a value using a mask & shift +/// Unpacks a value using a mask & shift. pub(crate) const fn unpack(src: usize, mask: usize, shift: u32) -> usize { (src & mask) >> shift } diff --git a/tokio/src/util/linked_list.rs b/tokio/src/util/linked_list.rs index 1eab81c317c..894d2164b9d 100644 --- a/tokio/src/util/linked_list.rs +++ b/tokio/src/util/linked_list.rs @@ -1,6 +1,6 @@ #![cfg_attr(not(feature = "full"), allow(dead_code))] -//! An intrusive double linked list of data +//! 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 @@ -46,10 +46,10 @@ pub(crate) unsafe trait Link { /// This is usually a pointer-ish type. type Handle; - /// Node type + /// Node type. type Target; - /// Convert the handle to a raw pointer without consuming the handle + /// Convert the handle to a raw pointer without consuming the handle. #[allow(clippy::wrong_self_convention)] fn as_raw(handle: &Self::Handle) -> NonNull; @@ -60,7 +60,7 @@ pub(crate) unsafe trait Link { unsafe fn pointers(target: NonNull) -> NonNull>; } -/// Previous / next pointers +/// Previous / next pointers. pub(crate) struct Pointers { inner: UnsafeCell>, } diff --git a/tokio/src/util/rand.rs b/tokio/src/util/rand.rs index 17b3ec1ae21..6b19c8be957 100644 --- a/tokio/src/util/rand.rs +++ b/tokio/src/util/rand.rs @@ -1,6 +1,6 @@ use std::cell::Cell; -/// Fast random number generate +/// Fast random number generate. /// /// Implement xorshift64+: 2 32-bit xorshift sequences added together. /// Shift triplet `[17,7,16]` was calculated as indicated in Marsaglia's @@ -14,7 +14,7 @@ pub(crate) struct FastRand { } impl FastRand { - /// Initialize a new, thread-local, fast random number generator. + /// Initializes a new, thread-local, fast random number generator. pub(crate) fn new(seed: u64) -> FastRand { let one = (seed >> 32) as u32; let mut two = seed as u32; diff --git a/tokio/src/util/slab.rs b/tokio/src/util/slab.rs index 2ddaa6c74e4..97355d500fc 100644 --- a/tokio/src/util/slab.rs +++ b/tokio/src/util/slab.rs @@ -85,11 +85,11 @@ pub(crate) struct Address(usize); /// An entry in the slab. pub(crate) trait Entry: Default { - /// Reset the entry's value and track the generation. + /// Resets the entry's value and track the generation. fn reset(&self); } -/// A reference to a value stored in the slab +/// A reference to a value stored in the slab. pub(crate) struct Ref { value: *const Value, } @@ -101,9 +101,9 @@ const NUM_PAGES: usize = 19; const PAGE_INITIAL_SIZE: usize = 32; const PAGE_INDEX_SHIFT: u32 = PAGE_INITIAL_SIZE.trailing_zeros() + 1; -/// A page in the slab +/// A page in the slab. struct Page { - /// Slots + /// Slots. slots: Mutex>, // Number of slots currently being used. This is not guaranteed to be up to @@ -116,7 +116,7 @@ struct Page { // The number of slots the page can hold. len: usize, - // Length of all previous pages combined + // Length of all previous pages combined. prev_len: usize, } @@ -128,9 +128,9 @@ struct CachedPage { init: usize, } -/// Page state +/// Page state. struct Slots { - /// Slots + /// Slots. slots: Vec>, head: usize, @@ -159,9 +159,9 @@ struct Slot { next: u32, } -/// Value paired with a reference to the page +/// Value paired with a reference to the page. struct Value { - /// Value stored in the value + /// Value stored in the value. value: T, /// Pointer to the page containing the slot. @@ -171,7 +171,7 @@ struct Value { } impl Slab { - /// Create a new, empty, slab + /// Create a new, empty, slab. pub(crate) fn new() -> Slab { // Initializing arrays is a bit annoying. Instead of manually writing // out an array and every single entry, `Default::default()` is used to @@ -455,7 +455,7 @@ impl Page { addr.0 - self.prev_len } - /// Returns the address for the given slot + /// Returns the address for the given slot. fn addr(&self, slot: usize) -> Address { Address(slot + self.prev_len) } @@ -478,7 +478,7 @@ impl Default for Page { } impl Page { - /// Release a slot into the page's free list + /// Release a slot into the page's free list. fn release(&self, value: *const Value) { let mut locked = self.slots.lock(); @@ -492,7 +492,7 @@ impl Page { } impl CachedPage { - /// Refresh the cache + /// Refreshes the cache. fn refresh(&mut self, page: &Page) { let slots = page.slots.lock(); @@ -502,7 +502,7 @@ impl CachedPage { } } - // Get a value by index + /// Gets a value by index. fn get(&self, idx: usize) -> &T { assert!(idx < self.init); @@ -576,7 +576,7 @@ impl Slot { } impl Value { - // Release the slot, returning the `Arc>` logically owned by the ref. + /// Releases the slot, returning the `Arc>` logically owned by the ref. fn release(&self) -> Arc> { // Safety: called by `Ref`, which owns an `Arc>` instance. let page = unsafe { Arc::from_raw(self.page) }; diff --git a/tokio/src/util/vec_deque_cell.rs b/tokio/src/util/vec_deque_cell.rs index 12883abdccd..b4e124c1519 100644 --- a/tokio/src/util/vec_deque_cell.rs +++ b/tokio/src/util/vec_deque_cell.rs @@ -45,7 +45,7 @@ impl VecDequeCell { } } - /// Replace the inner VecDeque with an empty VecDeque and return the current + /// Replaces the inner VecDeque with an empty VecDeque and return the current /// contents. pub(crate) fn take(&self) -> VecDeque { unsafe { self.with_inner(|inner| std::mem::take(inner)) } diff --git a/tokio/src/util/wake.rs b/tokio/src/util/wake.rs index 57739371d20..8f89668c61a 100644 --- a/tokio/src/util/wake.rs +++ b/tokio/src/util/wake.rs @@ -4,12 +4,12 @@ use std::ops::Deref; use std::sync::Arc; use std::task::{RawWaker, RawWakerVTable, Waker}; -/// Simplified waking interface based on Arcs +/// Simplified waking interface based on Arcs. pub(crate) trait Wake: Send + Sync { - /// Wake by value + /// Wake by value. fn wake(self: Arc); - /// Wake by reference + /// Wake by reference. fn wake_by_ref(arc_self: &Arc); }