Skip to content

Commit

Permalink
Fix a doc typo and clarify the render performance considerations
Browse files Browse the repository at this point in the history
  • Loading branch information
alexrutar committed Jan 20, 2025
1 parent 0a3861c commit 7b2e012
Showing 1 changed file with 14 additions and 10 deletions.
24 changes: 14 additions & 10 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -179,18 +179,22 @@ pub use nucleo;
/// ```
///
/// ## Performance considerations
/// Generally speaking, this crate assumes that the [`Render`] implementation is quite
/// fast. For each item, the [`Render`] implementation is first called to generate the match
/// objects, and then if the item is not ASCII, [`Render`] is called again in order to render
/// the interactive picker screen with the relevant matches.
///
/// In particular, very slow [`Render`] implementations which output non-ASCII will reduce
/// interactivity of the terminal interface. A crude rule of thumb is that rendering a single
/// In the majority of situations, performance of the [`Render`] implementation is only relevant
/// when sending the items to the picker, and not for generating the match list interactively. In
/// particular, in the majority of situations, [`Render::render`] is called exactly once per item
/// when it is sent to the picker.
///
/// The **only** exception to this rule occurs the value returned by [`Render::render`] contains
/// non-ASCII characters. In this situation, it can happen that *exceptionally slow* [`Render`]
/// implementations will reduce interactivity. A crude rule of thumb is that rendering a single
/// item should take (in the worst case) at most 100μs. For comparison, display formatting a
/// `f64` takes around 100ns.
///
/// If this is not the case for your type, it is highly recommended to cache the render
/// computation:
/// 100μs is an extremely large amount of time in the vast majority of situations. If after
/// benchmarking you determine that this is not the case for your [`Render`] implementation,
/// and moreover your [`Render`] implementation outputs (in the majority of cases) non-ASCII
/// Unicode, you can internally cache the render computation (at the cost of increased memory
/// overhead):
/// ```
/// # use nucleo_picker::Render;
/// pub struct Item<D> {
Expand Down Expand Up @@ -506,7 +510,7 @@ impl<T: Send + Sync + 'static, R: Render<T>> Picker<T, R> {
}

/// Returns an [`Observer`] containing up-to-date [`Injector`]s for this picker. For example,
/// this is the channel to which new injectors will be sent when the picker process a
/// this is the channel to which new injectors will be sent when the picker processes a
/// [restart event](Event::Restart). See the [`Event`] documentation for more detail.
///
/// Restart events are not generated by this library. You only need this channel if you
Expand Down

0 comments on commit 7b2e012

Please sign in to comment.