From f9ddb93604a830d106475bd4c4cae436fafcc0da Mon Sep 17 00:00:00 2001 From: Oleg Nosov Date: Fri, 24 Jan 2020 20:31:13 +0300 Subject: docs: use third form in API docs (#2027) --- tokio/src/sync/barrier.rs | 2 +- tokio/src/sync/broadcast.rs | 10 +++++----- tokio/src/sync/mpsc/block.rs | 14 +++++++------- tokio/src/sync/mpsc/bounded.rs | 6 +++--- tokio/src/sync/mpsc/chan.rs | 2 +- tokio/src/sync/mpsc/list.rs | 8 ++++---- tokio/src/sync/mpsc/unbounded.rs | 4 ++-- tokio/src/sync/mutex.rs | 2 +- tokio/src/sync/oneshot.rs | 6 +++--- tokio/src/sync/semaphore.rs | 8 ++++---- tokio/src/sync/semaphore_ll.rs | 36 ++++++++++++++++++------------------ tokio/src/sync/watch.rs | 6 +++--- 12 files changed, 52 insertions(+), 52 deletions(-) (limited to 'tokio/src/sync') diff --git a/tokio/src/sync/barrier.rs b/tokio/src/sync/barrier.rs index 911e78fe..62863349 100644 --- a/tokio/src/sync/barrier.rs +++ b/tokio/src/sync/barrier.rs @@ -126,7 +126,7 @@ impl Barrier { pub struct BarrierWaitResult(bool); impl BarrierWaitResult { - /// Returns true if this thread from wait is the "leader thread". + /// Returns `true` if this thread from wait is the "leader thread". /// /// Only one thread will have `true` returned from their result, all other threads will have /// `false` returned. diff --git a/tokio/src/sync/broadcast.rs b/tokio/src/sync/broadcast.rs index 35854811..515e4e4d 100644 --- a/tokio/src/sync/broadcast.rs +++ b/tokio/src/sync/broadcast.rs @@ -301,7 +301,7 @@ struct Write { /// Tracks a waiting receiver #[derive(Debug)] struct WaitNode { - /// True if queued + /// `true` if queued queued: AtomicBool, /// Task to wake when a permit is made available. @@ -471,7 +471,7 @@ impl Sender { .map_err(|SendError(maybe_v)| SendError(maybe_v.unwrap())) } - /// Create a new [`Receiver`] handle that will receive values sent **after** + /// Creates a new [`Receiver`] handle that will receive values sent **after** /// this call to `subscribe`. /// /// # Examples @@ -658,7 +658,7 @@ impl Drop for Sender { } impl Receiver { - /// Lock the next value if there is one. + /// Locks the next value if there is one. /// /// The caller is responsible for unlocking fn recv_ref(&mut self, spin: bool) -> Result, TryRecvError> { @@ -776,7 +776,7 @@ where } } - /// Receive the next value for this receiver. + /// Receives the next value for this receiver. /// /// Each [`Receiver`] handle will receive a clone of all values sent /// **after** it has subscribed. @@ -946,7 +946,7 @@ impl fmt::Debug for Receiver { } impl Slot { - /// Try to lock the slot for a receiver. If `false`, then a sender holds the + /// Tries to lock the slot for a receiver. If `false`, then a sender holds the /// lock and the calling task will be notified once the sender has released /// the lock. fn try_rx_lock(&self) -> bool { diff --git a/tokio/src/sync/mpsc/block.rs b/tokio/src/sync/mpsc/block.rs index f03648ba..4af990bf 100644 --- a/tokio/src/sync/mpsc/block.rs +++ b/tokio/src/sync/mpsc/block.rs @@ -107,7 +107,7 @@ impl Block { other_index.wrapping_sub(self.start_index) / BLOCK_CAP } - /// Read the value at the given offset. + /// Reads the value at the given offset. /// /// Returns `None` if the slot is empty. /// @@ -135,7 +135,7 @@ impl Block { Some(Read::Value(value.assume_init())) } - /// Write a value to the block at the given offset. + /// Writes a value to the block at the given offset. /// /// # Safety /// @@ -162,7 +162,7 @@ impl Block { self.ready_slots.fetch_or(TX_CLOSED, Release); } - /// Reset the block to a blank state. This enables reusing blocks in the + /// Resets the block to a blank state. This enables reusing blocks in the /// channel. /// /// # Safety @@ -177,7 +177,7 @@ impl Block { self.ready_slots = AtomicUsize::new(0); } - /// Release the block to the rx half for freeing. + /// Releases the block to the rx half for freeing. /// /// This function is called by the tx half once it can be guaranteed that no /// more senders will attempt to access the block. @@ -229,7 +229,7 @@ impl Block { } } - /// Load the next block + /// Loads the next block pub(crate) fn load_next(&self, ordering: Ordering) -> Option>> { let ret = NonNull::new(self.next.load(ordering)); @@ -241,7 +241,7 @@ impl Block { ret } - /// Push `block` as the next block in the link. + /// Pushes `block` as the next block in the link. /// /// Returns Ok if successful, otherwise, a pointer to the next block in /// the list is returned. @@ -274,7 +274,7 @@ impl Block { } } - /// Grow the `Block` linked list by allocating and appending a new block. + /// Grows the `Block` linked list by allocating and appending a new block. /// /// The next block in the linked list is returned. This may or may not be /// the one allocated by the function call. diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index da3bd638..b95611d8 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -44,7 +44,7 @@ impl fmt::Debug for Receiver { } } -/// Create a bounded mpsc channel for communicating between asynchronous tasks, +/// Creates a bounded mpsc channel for communicating between asynchronous tasks, /// returning the sender/receiver halves. /// /// All data sent on `Sender` will become available on `Receiver` in the same @@ -100,7 +100,7 @@ impl Receiver { Receiver { chan } } - /// Receive the next value for this receiver. + /// Receives the next value for this receiver. /// /// `None` is returned when all `Sender` halves have dropped, indicating /// that no further values can be sent on the channel. @@ -263,7 +263,7 @@ impl Sender { Ok(()) } - /// Send a value, waiting until there is capacity. + /// Sends a value, waiting until there is capacity. /// /// A successful send occurs when it is determined that the other end of the /// channel has not hung up already. An unsuccessful send would be one where diff --git a/tokio/src/sync/mpsc/chan.rs b/tokio/src/sync/mpsc/chan.rs index 847a0b70..2fc915d0 100644 --- a/tokio/src/sync/mpsc/chan.rs +++ b/tokio/src/sync/mpsc/chan.rs @@ -307,7 +307,7 @@ where }) } - /// Receive the next value without blocking + /// Receives the next value without blocking pub(crate) fn try_recv(&mut self) -> Result { use super::block::Read::*; self.inner.rx_fields.with_mut(|rx_fields_ptr| { diff --git a/tokio/src/sync/mpsc/list.rs b/tokio/src/sync/mpsc/list.rs index dc956403..53f82a25 100644 --- a/tokio/src/sync/mpsc/list.rs +++ b/tokio/src/sync/mpsc/list.rs @@ -54,7 +54,7 @@ pub(crate) fn channel() -> (Tx, Rx) { } impl Tx { - /// Push a value into the list. + /// Pushes a value into the list. pub(crate) fn push(&self, value: T) { // First, claim a slot for the value. `Acquire` is used here to // synchronize with the `fetch_add` in `reclaim_blocks`. @@ -69,7 +69,7 @@ impl Tx { } } - /// Close 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. @@ -220,7 +220,7 @@ impl fmt::Debug for Tx { } impl Rx { - /// Pop the next value off the queue + /// Pops the next value off the queue pub(crate) fn pop(&mut self, tx: &Tx) -> Option> { // Advance `head`, if needed if !self.try_advancing_head() { @@ -242,7 +242,7 @@ impl Rx { } } - /// Try advancing the block pointer to the block referenced by `self.index`. + /// Tries advancing the block pointer to the block referenced by `self.index`. /// /// Returns `true` if successful, `false` if there is no next block to load. fn try_advancing_head(&mut self) -> bool { diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs index d1222f28..b6b621d2 100644 --- a/tokio/src/sync/mpsc/unbounded.rs +++ b/tokio/src/sync/mpsc/unbounded.rs @@ -46,7 +46,7 @@ impl fmt::Debug for UnboundedReceiver { } } -/// Create an unbounded mpsc channel for communicating between asynchronous +/// Creates an unbounded mpsc channel for communicating between asynchronous /// tasks. /// /// A `send` on this channel will always succeed as long as the receive half has @@ -78,7 +78,7 @@ impl UnboundedReceiver { self.chan.recv(cx) } - /// Receive the next value for this receiver. + /// Receives the next value for this receiver. /// /// `None` is returned when all `Sender` halves have dropped, indicating /// that no further values can be sent on the channel. diff --git a/tokio/src/sync/mutex.rs b/tokio/src/sync/mutex.rs index 48451357..c625ce27 100644 --- a/tokio/src/sync/mutex.rs +++ b/tokio/src/sync/mutex.rs @@ -166,7 +166,7 @@ impl Mutex { guard } - /// Try to acquire the lock + /// Tries to acquire the lock pub fn try_lock(&self) -> Result, TryLockError> { let mut permit = semaphore::Permit::new(); match permit.try_acquire(1, &self.s) { diff --git a/tokio/src/sync/oneshot.rs b/tokio/src/sync/oneshot.rs index 5bbea381..aadb4996 100644 --- a/tokio/src/sync/oneshot.rs +++ b/tokio/src/sync/oneshot.rs @@ -237,7 +237,7 @@ impl Sender { Pending } - /// Wait for the associated [`Receiver`] handle to close. + /// Waits for the associated [`Receiver`] handle to close. /// /// A [`Receiver`] is closed by either calling [`close`] explicitly or the /// [`Receiver`] value is dropped. @@ -354,7 +354,7 @@ impl Drop for Sender { } impl Receiver { - /// Prevent the associated [`Sender`] handle from sending a value. + /// Prevents the associated [`Sender`] handle from sending a value. /// /// Any `send` operation which happens after calling `close` is guaranteed /// to fail. After calling `close`, `Receiver::poll`] should be called to @@ -610,7 +610,7 @@ impl Inner { } } - /// Consume the value. This function does not check `state`. + /// Consumes the value. This function does not check `state`. unsafe fn consume_value(&self) -> Option { self.value.with_mut(|ptr| (*ptr).take()) } diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs index 13d5cfb2..7721e01f 100644 --- a/tokio/src/sync/semaphore.rs +++ b/tokio/src/sync/semaphore.rs @@ -49,12 +49,12 @@ impl Semaphore { self.ll_sem.available_permits() } - /// Add `n` new permits to the semaphore. + /// Adds `n` new permits to the semaphore. pub fn add_permits(&self, n: usize) { self.ll_sem.add_permits(n); } - /// Acquire permit from the semaphore + /// Acquires permit from the semaphore pub async fn acquire(&self) -> SemaphorePermit<'_> { let mut permit = SemaphorePermit { sem: &self, @@ -66,7 +66,7 @@ impl Semaphore { permit } - /// Try to acquire a permit form the semaphore + /// Tries to acquire a permit form the semaphore pub fn try_acquire(&self) -> Result, TryAcquireError> { let mut ll_permit = ll::Permit::new(); match ll_permit.try_acquire(1, &self.ll_sem) { @@ -80,7 +80,7 @@ impl Semaphore { } impl<'a> SemaphorePermit<'a> { - /// Forget the permit **without** releasing it back to the semaphore. + /// Forgets the permit **without** releasing it back to the semaphore. /// This can be used to reduce the amount of permits available from a /// semaphore. pub fn forget(mut self) { diff --git a/tokio/src/sync/semaphore_ll.rs b/tokio/src/sync/semaphore_ll.rs index 6550f13d..69fd4a6a 100644 --- a/tokio/src/sync/semaphore_ll.rs +++ b/tokio/src/sync/semaphore_ll.rs @@ -177,7 +177,7 @@ impl Semaphore { curr.available_permits() } - /// Try to acquire the requested number of permits, registering the waiter + /// Tries to acquire the requested number of permits, registering the waiter /// if not enough permits are available. fn poll_acquire( &self, @@ -201,7 +201,7 @@ impl Semaphore { } } - /// Poll for a permit + /// Polls for a permit /// /// Tries to acquire available permits first. If unable to acquire a /// sufficient number of permits, the caller's waiter is pushed onto the @@ -319,7 +319,7 @@ impl Semaphore { } } - /// Close the semaphore. This prevents the semaphore from issuing new + /// Closes the semaphore. This prevents the semaphore from issuing new /// permits and notifies all pending waiters. pub(crate) fn close(&self) { // Acquire the `rx_lock`, setting the "closed" flag on the lock. @@ -334,7 +334,7 @@ impl Semaphore { self.add_permits_locked(0, true); } - /// Add `n` new permits to the semaphore. + /// Adds `n` new permits to the semaphore. pub(crate) fn add_permits(&self, n: usize) { if n == 0 { return; @@ -378,7 +378,7 @@ impl Semaphore { } } - /// Release a specific amount of permits to the semaphore + /// Releases a specific amount of permits to the semaphore /// /// This function is called by `add_permits` after the add lock has been /// acquired. @@ -597,7 +597,7 @@ unsafe impl Sync for Semaphore {} // ===== impl Permit ===== impl Permit { - /// Create a new `Permit`. + /// Creates a new `Permit`. /// /// The permit begins in the "unacquired" state. pub(crate) fn new() -> Permit { @@ -609,7 +609,7 @@ impl Permit { } } - /// Returns true if the permit has been acquired + /// Returns `true` if the permit has been acquired pub(crate) fn is_acquired(&self) -> bool { match self.state { PermitState::Acquired(num) if num > 0 => true, @@ -617,7 +617,7 @@ impl Permit { } } - /// Try to acquire the permit. If no permits are available, the current task + /// Tries to acquire the permit. If no permits are available, the current task /// is notified once a new permit becomes available. pub(crate) fn poll_acquire( &mut self, @@ -693,7 +693,7 @@ impl Permit { } } - /// Try to acquire the permit. + /// Tries to acquire the permit. pub(crate) fn try_acquire( &mut self, num_permits: u16, @@ -739,13 +739,13 @@ impl Permit { } } - /// Release a permit back to the semaphore + /// Releases a permit back to the semaphore pub(crate) fn release(&mut self, n: u16, semaphore: &Semaphore) { let n = self.forget(n); semaphore.add_permits(n as usize); } - /// Forget the permit **without** releasing it back to the semaphore. + /// Forgets the permit **without** releasing it back to the semaphore. /// /// After calling `forget`, `poll_acquire` is able to acquire new permit /// from the sempahore. @@ -831,7 +831,7 @@ impl std::error::Error for AcquireError {} // ===== impl TryAcquireError ===== impl TryAcquireError { - /// Returns true if the error was caused by a closed semaphore. + /// Returns `true` if the error was caused by a closed semaphore. pub(crate) fn is_closed(&self) -> bool { match self { TryAcquireError::Closed => true, @@ -839,7 +839,7 @@ impl TryAcquireError { } } - /// Returns true if the error was caused by calling `try_acquire` on a + /// Returns `true` if the error was caused by calling `try_acquire` on a /// semaphore with no available permits. pub(crate) fn is_no_permits(&self) -> bool { match self { @@ -1061,7 +1061,7 @@ impl SemState { self.0 >> NUM_SHIFT } - /// Returns true if the state has permits that can be claimed by a waiter. + /// Returns `true` if the state has permits that can be claimed by a waiter. fn has_available_permits(self) -> bool { self.0 & NUM_FLAG == NUM_FLAG } @@ -1070,7 +1070,7 @@ impl SemState { !self.has_available_permits() && !self.is_stub(stub) } - /// Try to atomically acquire specified number of permits. + /// Tries to atomically acquire specified number of permits. /// /// # Return /// @@ -1096,7 +1096,7 @@ impl SemState { true } - /// Release permits + /// Releases permits /// /// Returns `true` if the permits were accepted. fn release_permits(&mut self, permits: usize, stub: &Waiter) { @@ -1132,7 +1132,7 @@ impl SemState { (self.0 & !CLOSED_FLAG) as *mut Waiter } - /// Set to a pointer to a waiter. + /// Sets to a pointer to a waiter. /// /// This can only be done from the full state. fn set_waiter(&mut self, waiter: NonNull) { @@ -1146,7 +1146,7 @@ impl SemState { self.as_ptr() as usize == stub as *const _ as usize } - /// Load the state from an AtomicUsize. + /// Loads the state from an AtomicUsize. fn load(cell: &AtomicUsize, ordering: Ordering) -> SemState { let value = cell.load(ordering); SemState(value) diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs index ebcad45c..3e945563 100644 --- a/tokio/src/sync/watch.rs +++ b/tokio/src/sync/watch.rs @@ -151,7 +151,7 @@ struct WatchInner { const CLOSED: usize = 1; -/// Create a new watch channel, returning the "send" and "receive" handles. +/// Creates a new watch channel, returning the "send" and "receive" handles. /// /// All values sent by [`Sender`] will become visible to the [`Receiver`] handles. /// Only the last value sent is made available to the [`Receiver`] half. All @@ -320,7 +320,7 @@ impl WatchInner { } impl Sender { - /// Broadcast a new value via the channel, notifying all receivers. + /// Broadcasts a new value via the channel, notifying all receivers. pub fn broadcast(&self, value: T) -> Result<(), error::SendError> { let shared = match self.shared.upgrade() { Some(shared) => shared, @@ -363,7 +363,7 @@ impl Sender { } } -/// Notify all watchers of a change +/// Notifies all watchers of a change fn notify_all(shared: &Shared) { let watchers = shared.watchers.lock().unwrap(); -- cgit v1.2.3