Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs. #802

Merged
merged 1 commit into from
Aug 2, 2024
Merged

Improve docs. #802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 31 additions & 41 deletions src/bencher.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,22 @@ use crate::async_executor::AsyncExecutor;
/// way to time a routine and each has advantages and disadvantages.
///
/// * If you want to do the iteration and measurement yourself (eg. passing the iteration count
/// to a separate process), use `iter_custom`.
/// to a separate process), use [`iter_custom`].
/// * If your routine requires no per-iteration setup and returns a value with an expensive `drop`
/// method, use `iter_with_large_drop`.
/// * If your routine requires some per-iteration setup that shouldn't be timed, use `iter_batched`
/// or `iter_batched_ref`. See [`BatchSize`] for a discussion of batch sizes.
/// method, use [`iter_with_large_drop`].
/// * If your routine requires some per-iteration setup that shouldn't be timed, use [`iter_batched`]
/// or [`iter_batched_ref`]. See [`BatchSize`] for a discussion of batch sizes.
/// If the setup value implements `Drop` and you don't want to include the `drop` time in the
/// measurement, use `iter_batched_ref`, otherwise use `iter_batched`. These methods are also
/// measurement, use [`iter_batched_ref`], otherwise use [`iter_batched`]. These methods are also
/// suitable for benchmarking routines which return a value with an expensive `drop` method,
/// but are more complex than `iter_with_large_drop`.
/// * Otherwise, use `iter`.
/// but are more complex than [`iter_with_large_drop`].
/// * Otherwise, use [`iter`].
///
/// [`iter`]: Bencher::iter
/// [`iter_custom`]: Bencher::iter_custom
/// [`iter_with_large_drop`]: Bencher::iter_with_large_drop
/// [`iter_batched`]: Bencher::iter_batched
/// [`iter_batched_ref`]: Bencher::iter_batched_ref
pub struct Bencher<'a, M: Measurement = WallTime> {
pub(crate) iterated: bool, // Have we iterated this benchmark?
pub(crate) iters: u64, // Number of times to iterate this benchmark
Expand All @@ -56,9 +62,7 @@ impl<'a, M: Measurement> Bencher<'a, M> {
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
///
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, Criterion};
///
/// // The function to benchmark
/// fn foo() {
Expand Down Expand Up @@ -97,12 +101,11 @@ impl<'a, M: Measurement> Bencher<'a, M> {
/// and coordinate with multiple threads).
///
/// # Timing model
/// Custom, the timing model is whatever is returned as the Duration from `routine`.
/// Custom, the timing model is whatever is returned as the [`Duration`] from `routine`.
///
/// # Example
/// ```rust
/// #[macro_use] extern crate criterion;
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, Criterion};
/// use std::time::Instant;
///
/// fn foo() {
Expand Down Expand Up @@ -148,8 +151,9 @@ impl<'a, M: Measurement> Bencher<'a, M> {
/// Times a `routine` by collecting its output on each iteration. This avoids timing the
/// destructor of the value returned by `routine`.
///
/// WARNING: This requires `O(iters * mem::size_of::<O>())` of memory, and `iters` is not under the
/// control of the caller. If this causes out-of-memory errors, use `iter_batched` instead.
/// WARNING: This requires `O(iters * mem::size_of::<O>())` of memory, and `iters` is not
/// under the control of the caller. If this causes out-of-memory errors, use
/// [`iter_batched`](Self::iter_batched) instead.
///
/// # Timing model
///
Expand All @@ -160,9 +164,7 @@ impl<'a, M: Measurement> Bencher<'a, M> {
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
///
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, Criterion};
///
/// fn create_vector() -> Vec<u64> {
/// # vec![]
Expand Down Expand Up @@ -203,9 +205,7 @@ impl<'a, M: Measurement> Bencher<'a, M> {
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
///
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, BatchSize, Criterion};
///
/// fn create_scrambled_data() -> Vec<u64> {
/// # vec![]
Expand Down Expand Up @@ -293,9 +293,7 @@ impl<'a, M: Measurement> Bencher<'a, M> {
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
///
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, BatchSize, Criterion};
///
/// fn create_scrambled_data() -> Vec<u64> {
/// # vec![]
Expand Down Expand Up @@ -408,9 +406,7 @@ impl<'a, 'b, A: AsyncExecutor, M: Measurement> AsyncBencher<'a, 'b, A, M> {
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
///
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, Criterion};
/// use criterion::async_executor::FuturesExecutor;
///
/// // The function to benchmark
Expand Down Expand Up @@ -454,12 +450,11 @@ impl<'a, 'b, A: AsyncExecutor, M: Measurement> AsyncBencher<'a, 'b, A, M> {
/// and coordinate with multiple threads).
///
/// # Timing model
/// Custom, the timing model is whatever is returned as the Duration from `routine`.
/// Custom, the timing model is whatever is returned as the [`Duration`] from `routine`.
///
/// # Example
/// ```rust
/// #[macro_use] extern crate criterion;
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, Criterion};
/// use criterion::async_executor::FuturesExecutor;
/// use std::time::Instant;
///
Expand Down Expand Up @@ -513,8 +508,9 @@ impl<'a, 'b, A: AsyncExecutor, M: Measurement> AsyncBencher<'a, 'b, A, M> {
/// Times a `routine` by collecting its output on each iteration. This avoids timing the
/// destructor of the value returned by `routine`.
///
/// WARNING: This requires `O(iters * mem::size_of::<O>())` of memory, and `iters` is not under the
/// control of the caller. If this causes out-of-memory errors, use `iter_batched` instead.
/// WARNING: This requires `O(iters * mem::size_of::<O>())` of memory, and `iters`
/// is not under the control of the caller. If this causes out-of-memory errors, use
/// [`iter_batched`](Self::iter_batched) instead.
///
/// # Timing model
///
Expand All @@ -525,9 +521,7 @@ impl<'a, 'b, A: AsyncExecutor, M: Measurement> AsyncBencher<'a, 'b, A, M> {
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
///
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, Criterion};
/// use criterion::async_executor::FuturesExecutor;
///
/// async fn create_vector() -> Vec<u64> {
Expand Down Expand Up @@ -580,9 +574,7 @@ impl<'a, 'b, A: AsyncExecutor, M: Measurement> AsyncBencher<'a, 'b, A, M> {
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
///
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, BatchSize, Criterion};
/// use criterion::async_executor::FuturesExecutor;
///
/// fn create_scrambled_data() -> Vec<u64> {
Expand Down Expand Up @@ -678,9 +670,7 @@ impl<'a, 'b, A: AsyncExecutor, M: Measurement> AsyncBencher<'a, 'b, A, M> {
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
///
/// use criterion::*;
/// use criterion::{criterion_group, criterion_main, BatchSize, Criterion};
/// use criterion::async_executor::FuturesExecutor;
///
/// fn create_scrambled_data() -> Vec<u64> {
Expand Down
3 changes: 1 addition & 2 deletions src/benchmark_group.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,7 @@ use std::time::Duration;
/// # Examples:
///
/// ```no_run
/// #[macro_use] extern crate criterion;
/// use self::criterion::*;
/// use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
/// use std::time::Duration;
///
/// fn bench_simple(c: &mut Criterion) {
Expand Down
32 changes: 18 additions & 14 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1154,8 +1154,7 @@ https://bheisler.github.io/criterion.rs/book/faq.html
/// # Examples:
///
/// ```rust
/// #[macro_use] extern crate criterion;
/// use self::criterion::*;
/// use criterion::{criterion_group, criterion_main, Criterion};
///
/// fn bench_simple(c: &mut Criterion) {
/// let mut group = c.benchmark_group("My Group");
Expand Down Expand Up @@ -1187,13 +1186,13 @@ impl<M> Criterion<M>
where
M: Measurement + 'static,
{
/// Benchmarks a function. For comparing multiple functions, see `benchmark_group`.
/// Benchmarks a function. For comparing multiple functions, see
/// [`benchmark_group`](Self::benchmark_group).
///
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
/// use self::criterion::*;
/// use criterion::{criterion_group, criterion_main, Criterion};
///
/// fn bench(c: &mut Criterion) {
/// // Setup (construct data, allocate memory, etc)
Expand All @@ -1218,13 +1217,12 @@ where
}

/// Benchmarks a function with an input. For comparing multiple functions or multiple inputs,
/// see `benchmark_group`.
/// see [`benchmark_group`](Self::benchmark_group).
///
/// # Example
///
/// ```rust
/// #[macro_use] extern crate criterion;
/// use self::criterion::*;
/// use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
///
/// fn bench(c: &mut Criterion) {
/// // Setup (construct data, allocate memory, etc)
Expand Down Expand Up @@ -1285,7 +1283,7 @@ pub enum Throughput {
Elements(u64),
}

/// Axis scaling type
/// Axis scaling type. Specified via [`PlotConfiguration::summary_scale`].
#[derive(Debug, Default, Clone, Copy)]
pub enum AxisScale {
/// Axes scale linearly
Expand Down Expand Up @@ -1318,17 +1316,21 @@ pub struct PlotConfiguration {

impl PlotConfiguration {
#[must_use]
/// Set the axis scale (linear or logarithmic) for the summary plots. Typically, you would
/// set this to logarithmic if benchmarking over a range of inputs which scale exponentially.
/// Defaults to linear.
/// Set the axis scale ([linear] or [logarithmic]) for the summary plots.
///
/// Typically, you would set this to logarithmic if benchmarking over a
/// range of inputs which scale exponentially. Defaults to [`AxisScale::Linear`].
///
/// [linear]: AxisScale::Linear
/// [logarithmic]: AxisScale::Logarithmic
pub fn summary_scale(mut self, new_scale: AxisScale) -> PlotConfiguration {
self.summary_scale = new_scale;
self
}
}

/// This enum allows the user to control how Criterion.rs chooses the iteration count when sampling.
/// The default is Auto, which will choose a method automatically based on the iteration time during
/// The default is `Auto`, which will choose a method automatically based on the iteration time during
/// the warm-up phase.
#[derive(Debug, Default, Clone, Copy)]
pub enum SamplingMode {
Expand All @@ -1343,10 +1345,11 @@ pub enum SamplingMode {

/// Keep the iteration count the same for all samples. This is not recommended, as it affects
/// the statistics that Criterion.rs can compute. However, it requires fewer iterations than
/// the Linear method and therefore is more suitable for very long-running benchmarks where
/// the `Linear` method and therefore is more suitable for very long-running benchmarks where
/// benchmark execution time is more of a problem and statistical precision is less important.
Flat,
}

impl SamplingMode {
pub(crate) fn choose_sampling_mode(
&self,
Expand Down Expand Up @@ -1380,6 +1383,7 @@ pub(crate) enum ActualSamplingMode {
Linear,
Flat,
}

impl ActualSamplingMode {
pub(crate) fn iteration_counts(
&self,
Expand Down
14 changes: 4 additions & 10 deletions src/macros.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,7 @@
/// Complete form:
///
/// ```
/// # #[macro_use]
/// # extern crate criterion;
/// # use criterion::Criterion;
/// # use criterion::{criterion_group, Criterion};
/// # fn bench_method1(c: &mut Criterion) {
/// # }
/// #
Expand All @@ -44,9 +42,7 @@
/// Compact Form:
///
/// ```
/// # #[macro_use]
/// # extern crate criterion;
/// # use criterion::Criterion;
/// # use criterion::{criterion_group, Criterion};
/// # fn bench_method1(c: &mut Criterion) {
/// # }
/// #
Expand Down Expand Up @@ -100,10 +96,8 @@ macro_rules! criterion_group {
///
/// Since we've disabled the default benchmark harness, we need to add our own:
///
/// ```ignore
/// #[macro_use]
/// extern crate criterion;
/// use criterion::Criterion;
/// ```no_run
/// use criterion::{criterion_group, criterion_main, Criterion};
/// fn bench_method1(c: &mut Criterion) {
/// }
///
Expand Down
4 changes: 2 additions & 2 deletions src/measurement.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ use std::time::{Duration, Instant};
/// Trait providing functions to format measured values to string so that they can be displayed on
/// the command line or in the reports. The functions of this trait take measured values in f64
/// form; implementors can assume that the values are of the same scale as those produced by the
/// associated [MeasuredValue](trait.MeasuredValue.html) (eg. if your measurement produces values in
/// nanoseconds, the values passed to the formatter will be in nanoseconds).
/// associated [`Measurement`] (eg. if your measurement produces values in nanoseconds, the
/// values passed to the formatter will be in nanoseconds).
///
/// Implementors are encouraged to format the values in a way that is intuitive for humans and
/// uses the SI prefix system. For example, the format used by [`WallTime`] can display the value
Expand Down