diff --git a/copa/src/lib.rs b/copa/src/lib.rs index 0627663707..6da4aed6f2 100644 --- a/copa/src/lib.rs +++ b/copa/src/lib.rs @@ -135,8 +135,6 @@ impl Parser { /// [`Perform::terminated`] is true after reading a byte. /// /// Returns the number of bytes read before termination. - /// - /// See [`Perform::advance`] for more details. #[inline] #[must_use = "Returned value should be used to processs the remaining bytes"] pub fn advance_until_terminated( diff --git a/corcovado/src/poll.rs b/corcovado/src/poll.rs index 113a4dde2e..f4709a2061 100644 --- a/corcovado/src/poll.rs +++ b/corcovado/src/poll.rs @@ -1,3 +1,52 @@ +//! Poll is backed by two readiness queues. The first is a system readiness queue +//! represented by `sys::Selector`. The system readiness queue handles events +//! provided by the system, such as TCP and UDP. The second readiness queue is +//! implemented in user space by `ReadinessQueue`. It provides a way to implement +//! purely user space `Evented` types. +//! +//! `ReadinessQueue` is backed by a MPSC queue that supports reuse of linked +//! list nodes. This significantly reduces the number of required allocations. +//! Each `Registration` / `SetReadiness` pair allocates a single readiness node +//! that is used for the lifetime of the registration. +//! +//! The readiness node also includes a single atomic variable, `state` that +//! tracks most of the state associated with the registration. This includes the +//! current readiness, interest, poll options, and internal state. When the node +//! state is mutated, it is queued in the MPSC channel. A call to +//! `ReadinessQueue::poll` will dequeue and process nodes. The node state can +//! still be mutated while it is queued in the channel for processing. +//! Intermediate state values do not matter as long as the final state is +//! included in the call to `poll`. This is the eventually consistent nature of +//! the readiness queue. +//! +//! The readiness node is ref counted using the `ref_count` field. On creation, +//! the ref_count is initialized to 3: one `Registration` handle, one +//! `SetReadiness` handle, and one for the readiness queue. Since the readiness queue +//! doesn't *always* hold a handle to the node, we don't use the Arc type for +//! managing ref counts (this is to avoid constantly incrementing and +//! decrementing the ref count when pushing & popping from the queue). When the +//! `Registration` handle is dropped, the `dropped` flag is set on the node, then +//! the node is pushed into the registration queue. When Poll::poll pops the +//! node, it sees the drop flag is set, and decrements it's ref count. +//! +//! The MPSC queue is a modified version of the intrusive MPSC node based queue +//! described by 1024cores [1]. +//! +//! The first modification is that two markers are used instead of a single +//! `stub`. The second marker is a `sleep_marker` which is used to signal to +//! producers that the consumer is going to sleep. This sleep_marker is only used +//! when the queue is empty, implying that the only node in the queue is +//! `end_marker`. +//! +//! The second modification is an `until` argument passed to the dequeue +//! function. When `poll` encounters a level-triggered node, the node will be +//! immediately pushed back into the queue. In order to avoid an infinite loop, +//! `poll` before pushing the node, the pointer is saved off and then passed +//! again as the `until` argument. If the next node to pop is `until`, then +//! `Dequeue::Empty` is returned. +//! +//! [1] + use event_imp::{self as event, Event, Evented, PollOpt, Ready}; use std::cell::UnsafeCell; #[cfg(all(unix, not(target_os = "fuchsia")))] @@ -14,55 +63,6 @@ use std::{fmt, io, ptr}; use std::{mem, ops}; use {sys, Token}; -// Poll is backed by two readiness queues. The first is a system readiness queue -// represented by `sys::Selector`. The system readiness queue handles events -// provided by the system, such as TCP and UDP. The second readiness queue is -// implemented in user space by `ReadinessQueue`. It provides a way to implement -// purely user space `Evented` types. -// -// `ReadinessQueue` is backed by a MPSC queue that supports reuse of linked -// list nodes. This significantly reduces the number of required allocations. -// Each `Registration` / `SetReadiness` pair allocates a single readiness node -// that is used for the lifetime of the registration. -// -// The readiness node also includes a single atomic variable, `state` that -// tracks most of the state associated with the registration. This includes the -// current readiness, interest, poll options, and internal state. When the node -// state is mutated, it is queued in the MPSC channel. A call to -// `ReadinessQueue::poll` will dequeue and process nodes. The node state can -// still be mutated while it is queued in the channel for processing. -// Intermediate state values do not matter as long as the final state is -// included in the call to `poll`. This is the eventually consistent nature of -// the readiness queue. -// -// The readiness node is ref counted using the `ref_count` field. On creation, -// the ref_count is initialized to 3: one `Registration` handle, one -// `SetReadiness` handle, and one for the readiness queue. Since the readiness queue -// doesn't *always* hold a handle to the node, we don't use the Arc type for -// managing ref counts (this is to avoid constantly incrementing and -// decrementing the ref count when pushing & popping from the queue). When the -// `Registration` handle is dropped, the `dropped` flag is set on the node, then -// the node is pushed into the registration queue. When Poll::poll pops the -// node, it sees the drop flag is set, and decrements it's ref count. -// -// The MPSC queue is a modified version of the intrusive MPSC node based queue -// described by 1024cores [1]. -// -// The first modification is that two markers are used instead of a single -// `stub`. The second marker is a `sleep_marker` which is used to signal to -// producers that the consumer is going to sleep. This sleep_marker is only used -// when the queue is empty, implying that the only node in the queue is -// `end_marker`. -// -// The second modification is an `until` argument passed to the dequeue -// function. When `poll` encounters a level-triggered node, the node will be -// immediately pushed back into the queue. In order to avoid an infinite loop, -// `poll` before pushing the node, the pointer is saved off and then passed -// again as the `until` argument. If the next node to pop is `until`, then -// `Dequeue::Empty` is returned. -// -// [1] http://www.1024cores.net/home/lock-free-algorithms/queues/intrusive-mpsc-node-based-queue - /// Polls for readiness events on all registered values. /// /// `Poll` allows a program to monitor a large number of `Evented` types, @@ -261,8 +261,8 @@ use {sys, Token}; /// Unless otherwise noted, it should be assumed that types implementing /// [`Evented`] will never become ready unless they are registered with `Poll`. /// -/// For example: -/// +// For example: +// // ``` // # use std::error::Error; // # fn try_main() -> Result<(), Box> { @@ -851,11 +851,11 @@ impl Poll { // # try_main().unwrap(); // # } // ``` - // - // [`struct`]: # - // [`register`]: #method.register - // [`readable`]: struct.Ready.html#method.readable - // [`writable`]: struct.Ready.html#method.writable + /// + /// [`struct`]: # + /// [`register`]: #method.register + /// [`readable`]: struct.Ready.html#method.readable + /// [`writable`]: struct.Ready.html#method.writable pub fn reregister( &self, handle: &E, diff --git a/corcovado/src/sys/windows/from_raw_arc.rs b/corcovado/src/sys/windows/from_raw_arc.rs index 0b46d325b5..af6ce02dc7 100644 --- a/corcovado/src/sys/windows/from_raw_arc.rs +++ b/corcovado/src/sys/windows/from_raw_arc.rs @@ -17,7 +17,7 @@ //! //! * The size of `FromRawArc` is actually two words because of the drop flag //! * The compiler doesn't understand that the pointer in `FromRawArc` is never -//! null, so Option> is not a nullable pointer. +//! null, so `Option>` is not a nullable pointer. use std::mem; use std::ops::Deref; diff --git a/frontends/rioterm/src/hints.rs b/frontends/rioterm/src/hints.rs index 4259c2e45a..e9c7825c18 100644 --- a/frontends/rioterm/src/hints.rs +++ b/frontends/rioterm/src/hints.rs @@ -12,7 +12,7 @@ pub struct HintState { /// Visible matches for the current hint matches: Vec, - /// Labels for each match (as Vec) + /// Labels for each match (as `Vec`) labels: Vec>, /// Keys pressed so far for hint selection diff --git a/frontends/rioterm/src/screen/mod.rs b/frontends/rioterm/src/screen/mod.rs index 48874aba95..37ee2eb95c 100644 --- a/frontends/rioterm/src/screen/mod.rs +++ b/frontends/rioterm/src/screen/mod.rs @@ -687,7 +687,7 @@ impl Screen<'_> { } } - /// Check whether we should try to build escape sequence for the [`KeyEvent`]. + /// Check whether we should try to build escape sequence for the [`KeyEvent`](rio_window::event::KeyEvent). fn should_build_sequence( key: &rio_window::event::KeyEvent, text: &str, diff --git a/rio-backend/src/ansi/mode.rs b/rio-backend/src/ansi/mode.rs index e79f3f42e5..19ae71232a 100644 --- a/rio-backend/src/ansi/mode.rs +++ b/rio-backend/src/ansi/mode.rs @@ -118,7 +118,7 @@ pub enum NamedPrivateMode { UrgencyHints = 1042, SwapScreenAndSetRestoreCursor = 1049, BracketedPaste = 2004, - /// The mode is handled automatically by [`Processor`]. + /// The mode is handled automatically by [`Processor`](crate::performer::handler::Processor). SyncUpdate = 2026, } diff --git a/rio-backend/src/config/platform.rs b/rio-backend/src/config/platform.rs index 2d8344f449..55889186b2 100644 --- a/rio-backend/src/config/platform.rs +++ b/rio-backend/src/config/platform.rs @@ -13,7 +13,7 @@ pub struct Platform { /// Other platform specific configuration options can be added here. /// -/// When deserializing, each field is Option to distinguish between +/// When deserializing, each field is `Option` to distinguish between /// "not specified" vs "specified with value". During merge, we recursively /// merge individual fields rather than replacing entire structures. #[derive(Default, Debug, Serialize, Deserialize, PartialEq, Clone)] diff --git a/rio-backend/src/crosswords/grid/storage.rs b/rio-backend/src/crosswords/grid/storage.rs index 1cd2e1eca7..ebe72d318d 100644 --- a/rio-backend/src/crosswords/grid/storage.rs +++ b/rio-backend/src/crosswords/grid/storage.rs @@ -152,9 +152,9 @@ impl Storage { self.len == 0 } - /// Swap implementation for Row. + /// Swap implementation for `Row`. /// - /// Exploits the known size of Row to produce a slightly more efficient + /// Exploits the known size of `Row` to produce a slightly more efficient /// swap than going through slice::swap. /// /// The default implementation from swap generates 8 movups and 4 movaps diff --git a/rio-backend/src/crosswords/mod.rs b/rio-backend/src/crosswords/mod.rs index 7bc5ad5864..661e3432c0 100644 --- a/rio-backend/src/crosswords/mod.rs +++ b/rio-backend/src/crosswords/mod.rs @@ -170,7 +170,7 @@ impl From for Mode { } } -/// Terminal damage information collected since the last [`Term::reset_damage`] call. +/// Terminal damage information collected since the last [`Crosswords::reset_damage`] call. #[derive(Debug)] pub enum TermDamage<'a> { /// The entire terminal is damaged. diff --git a/rio-backend/src/selection.rs b/rio-backend/src/selection.rs index 06a2c005d6..d77797b9b2 100644 --- a/rio-backend/src/selection.rs +++ b/rio-backend/src/selection.rs @@ -111,17 +111,17 @@ pub enum SelectionType { /// Describes a region of a 2-dimensional area. /// /// Used to track a text selection. There are four supported modes, each with its own constructor: -/// [`simple`], [`block`], [`semantic`], and [`lines`]. The [`simple`] mode precisely tracks which +/// [`simple`], [`block`], [`semantic`], and [`semantic`]. The [`simple`] mode precisely tracks which /// cells are selected without any expansion. [`block`] will select rectangular regions. -/// [`lines`] will always select entire lines. +/// [`semantic`] will always select entire lines. /// /// Calls to [`update`] operate different based on the selection kind. The [`simple`] and [`block`] /// mode do nothing special, simply track points and sides. /// -/// [`simple`]: enum.Selection.html#method.simple -/// [`block`]: enum.Selection.html#method.block -/// [`lines`]: enum.Selection.html#method.rows -/// [`update`]: enum.Selection.html#method.update +/// [`simple`]: enum.SelectionType.html#variant.Simple +/// [`block`]: enum.SelectionType.html#variant.Block +/// [`semantic`]: enum.SelectionType.html#variant.Semantic +/// [`update`]: enum.SelectionType.html#variant.Update #[derive(Debug, Clone, PartialEq, Eq)] pub struct Selection { pub ty: SelectionType, diff --git a/rio-window/src/lib.rs b/rio-window/src/lib.rs index 95432cb9f7..c91d59b8f2 100644 --- a/rio-window/src/lib.rs +++ b/rio-window/src/lib.rs @@ -152,7 +152,7 @@ //! [`Window`]: window::Window //! [`WindowId`]: window::WindowId //! [`WindowAttributes`]: window::WindowAttributes -//! [window_new]: window::Window::new +//! [window_new]: event_loop::ActiveEventLoop::create_window //! [`create_window`]: event_loop::ActiveEventLoop::create_window //! [`Window::id()`]: window::Window::id //! [`WindowEvent`]: event::WindowEvent diff --git a/rio-window/src/platform/windows.rs b/rio-window/src/platform/windows.rs index 704b069092..e1eb8a308f 100644 --- a/rio-window/src/platform/windows.rs +++ b/rio-window/src/platform/windows.rs @@ -454,12 +454,12 @@ impl WindowExtWindows for Window { pub trait WindowBorrowExtWindows: Borrow + Sized { /// Create an object that allows accessing the inner window handle in a thread-unsafe way. /// - /// It is possible to call [`window_handle_any_thread`] to get around Windows's thread + /// It is possible to call [`window_handle_any_thread`](WindowExtWindows::window_handle_any_thread) to get around Windows's thread /// affinity limitations. However, it may be desired to pass the [`Window`] into something - /// that requires the [`HasWindowHandle`] trait, while ignoring thread affinity limitations. + /// that requires the [`HasWindowHandle`](raw_window_handle::HasWindowHandle) trait, while ignoring thread affinity limitations. /// /// This function wraps anything that implements `Borrow` into a structure that - /// uses the inner window handle as a mean of implementing [`HasWindowHandle`]. It wraps + /// uses the inner window handle as a mean of implementing [`HasWindowHandle`](raw_window_handle::HasWindowHandle). It wraps /// `Window`, `&Window`, `Arc`, and other reference types. /// /// # Safety diff --git a/sugarloaf/src/font_introspector/scale/mod.rs b/sugarloaf/src/font_introspector/scale/mod.rs index 15cecc5cb6..aa7e1f8119 100644 --- a/sugarloaf/src/font_introspector/scale/mod.rs +++ b/sugarloaf/src/font_introspector/scale/mod.rs @@ -58,11 +58,7 @@ that yields [`NormalizedCoord`]s (a type alias for `i16` which is a fixed point in 2.14 format). This method is faster than specifying variations by tag and value, but the difference is likely negligible outside of microbenchmarks. The real advantage is that a sequence of `i16` is more compact and easier to fold into a key in a glyph -cache. You can compute these normalized coordinates by using the -[`Variation::normalize`](crate::Variation::normalize) method for each available axis in -the font. The best strategy, however, is to simply capture these during shaping with -the [`Shaper::normalized_coords`](crate::shape::Shaper::normalized_coords) method which -will have already computed them for you. +cache. See [`ScalerBuilder`] for available options and default values. @@ -109,10 +105,6 @@ and [`scale_color_bitmap`](Scaler::scale_color_bitmap) for alpha and color bitma respectively. These methods return an [`Image`] wrapped in an option. The associated `_into` variants are also available. -Unlike outlines, bitmaps are available in [`strike`](crate::BitmapStrike)s of various sizes. -When requesting a bitmap, you specify the strategy for strike selection using the -[`StrikeWith`] enum. - For example, if we want the largest available unscaled image for the fire emoji: ```ignore # use sugarloaf::font_introspector::{FontRef, CacheKey, scale::*}; @@ -807,7 +799,7 @@ impl<'a> Render<'a> { } /// Specifies the target format for rasterizing an outline. Default is - /// [`Format::Alpha`](zeno::Format::Alpha). + /// [`Format::Alpha`]. pub fn format(&mut self, format: Format) -> &mut Self { self.format = format; self