bench: end-to-end search throughput via uumain

The existing match/throughput benches call Matcher::match_line on
pre-split lines, so they only measure matching in isolation and cannot
observe how the searcher feeds data to the matcher. Add a 'search'
group that drives the whole pipeline through uumain over a multi-MB
file: a literal pattern (which a buffer-at-a-time searcher can speed
up) and an extended-regex control (which it cannot). Uses -q with a
non-matching pattern for a silent full-file scan.

.github/workflows/codspeed.yml

@@ -0,0 +1,37 @@
+name: CodSpeed
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+  # `workflow_dispatch` allows CodSpeed to trigger backtest
+  # performance analysis in order to generate initial data.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  codspeed:
+    name: Run benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain, cache and cargo-codspeed binary
+        uses: moonrepo/setup-rust@v0
+        with:
+          channel: stable
+          cache-target: release
+          bins: cargo-codspeed
+
+      - name: Build the benchmark target(s)
+        run: cargo codspeed build
+
+      - name: Run the benchmarks
+        uses: CodSpeedHQ/action@v4
+        with:
+          mode: simulation
+          run: cargo codspeed run

.pre-commit-config.yaml

@@ -0,0 +1,55 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+exclude: ^tests/fixtures/
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-executables-have-shebangs
+      - id: check-json
+        exclude: '\.vscode/(cSpell|extensions)\.json' # cSpell.json and extensions.json use comments
+      - id: check-shebang-scripts-are-executable
+        exclude: '.+\.rs' # would be triggered by #![some_attribute]
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-yaml
+        args: [ --allow-multiple-documents ]
+      - id: destroyed-symlinks
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [ --fix=lf ]
+      - id: trailing-whitespace
+
+  - repo: local
+    hooks:
+      - id: rust-linting
+        name: Rust linting
+        description: Run cargo fmt on files included in the commit.
+        entry: cargo +stable fmt --
+        pass_filenames: true
+        types: [file, rust]
+        language: system
+      - id: rust-clippy
+        name: Rust clippy
+        description: Run cargo clippy on files included in the commit.
+        entry: cargo +stable clippy --workspace --all-targets --all-features -- -D warnings
+        pass_filenames: false
+        types: [file, rust]
+        language: system
+      - id: cargo-lock-check
+        name: Cargo.lock sync check
+        description: Ensure Cargo.lock and fuzz/Cargo.lock are up-to-date.
+        entry: bash -c 'for dir in . fuzz; do if [ -d "$dir" ]; then ( cd "$dir" && cargo fetch --quiet ); fi; done'
+        pass_filenames: false
+        files: 'Cargo\.(toml|lock)$'
+        language: system
+      - id: cspell
+        name: Code spell checker (cspell)
+        description: Run cspell to check for spelling errors (if available).
+        entry: bash -c 'if command -v cspell >/dev/null 2>&1; then cspell --no-must-find-files -- "$@"; else echo "cspell not found, skipping spell check"; exit 0; fi' --
+        pass_filenames: true
+        language: system
+
+ci:
+  skip: [rust-linting, rust-clippy, cargo-lock-check, cspell]

Cargo.toml

@@ -27,5 +27,10 @@ onig_sys = { version = "*", default-features = false }
 uucore = "0.8.0"
 walkdir = "2.5"
 
+[[bench]]
+name = "grep_bench"
+harness = false
+
 [dev-dependencies]
+criterion = { version = "4.7.0", package = "codspeed-criterion-compat" }
 uutests = "0.8.0"

README.md

@@ -4,6 +4,7 @@
 [![dependency status](https://deps.rs/repo/github/uutils/grep/status.svg)](https://deps.rs/repo/github/uutils/grep)
 
 [![CodeCov](https://codecov.io/gh/uutils/grep/branch/main/graph/badge.svg)](https://codecov.io/gh/uutils/grep)
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/uutils/grep?utm_source=badge)
 
 # Grep, now in Rust
 
@@ -29,6 +30,10 @@ cargo build --release
 cargo test
 ```
 
+## Pre-commit hooks
+
+This project uses [pre-commit](https://pre-commit.com); run `pre-commit install` to enable the git hooks.
+
 ## Known Issues
 
 * Does not take `LANG`, etc., into account for handling file encodings (non-UTF8 matches are treated as binary)

benches/grep_bench.rs

@@ -0,0 +1,356 @@
+// This file is part of the uutils grep package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use criterion::{Criterion, black_box, criterion_group, criterion_main};
+use uu_grep::matcher::Matcher;
+use uu_grep::{BinaryMode, ColorConfig, Config, DeviceMode, DirectoryMode, GlobSet, RegexMode};
+
+fn make_config<'a>(
+    patterns: &'a [&'a str],
+    regex_mode: RegexMode,
+    ignore_case: bool,
+    invert_match: bool,
+    word_regexp: bool,
+) -> Config<'a> {
+    Config {
+        directory_mode: DirectoryMode::Read,
+        device_mode: DeviceMode::Default,
+        follow_symlinks: false,
+        include_globs: GlobSet::new(),
+        exclude_globs: GlobSet::new(),
+        exclude_dir_globs: GlobSet::new(),
+        label: "(standard input)",
+        #[cfg(windows)]
+        strip_cr: false,
+        binary_mode: BinaryMode::Binary,
+        max_count: None,
+        before_context: 0,
+        after_context: 0,
+        has_context: false,
+        patterns,
+        regex_mode,
+        ignore_case,
+        invert_match,
+        word_regexp,
+        line_regexp: false,
+        quiet: true,
+        count: false,
+        show_filename: false,
+        files_with_matches: false,
+        files_without_match: false,
+        only_matching: false,
+        byte_offset: false,
+        line_number: false,
+        initial_tab: false,
+        null_separator: false,
+        null_data: false,
+        line_buffered: false,
+        no_messages: true,
+        group_separator: None,
+        use_color: false,
+        color_config: ColorConfig {
+            matched_selected: "",
+            matched_context: "",
+            filename: "",
+            line_number: "",
+            byte_offset: "",
+            separator: "",
+            selected_line: "",
+            context_line: "",
+            reverse_video: false,
+            no_erase: false,
+        },
+    }
+}
+
+fn bench_compile(c: &mut Criterion) {
+    let mut group = c.benchmark_group("compile");
+
+    group.bench_function("fixed_string", |b| {
+        b.iter(|| {
+            let patterns: &[&str] = &["hello world"];
+            let config = make_config(patterns, RegexMode::Fixed, false, false, false);
+            let matcher = Matcher::compile(black_box(&config)).unwrap();
+            let _ = black_box(&matcher);
+        })
+    });
+
+    group.bench_function("basic_regex", |b| {
+        b.iter(|| {
+            let patterns: &[&str] = &[r"[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}"];
+            let config = make_config(patterns, RegexMode::Basic, false, false, false);
+            let matcher = Matcher::compile(black_box(&config)).unwrap();
+            let _ = black_box(&matcher);
+        })
+    });
+
+    group.bench_function("extended_regex", |b| {
+        b.iter(|| {
+            let patterns: &[&str] = &[r"[0-9]{4}-[0-9]{2}-[0-9]{2}"];
+            let config = make_config(patterns, RegexMode::Extended, false, false, false);
+            let matcher = Matcher::compile(black_box(&config)).unwrap();
+            let _ = black_box(&matcher);
+        })
+    });
+
+    group.bench_function("perl_regex", |b| {
+        b.iter(|| {
+            let patterns: &[&str] = &[r"\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}"];
+            let config = make_config(patterns, RegexMode::Perl, false, false, false);
+            let matcher = Matcher::compile(black_box(&config)).unwrap();
+            let _ = black_box(&matcher);
+        })
+    });
+
+    group.bench_function("multiple_patterns", |b| {
+        b.iter(|| {
+            let patterns: &[&str] = &["error", "warning", "critical", "fatal", "panic"];
+            let config = make_config(patterns, RegexMode::Fixed, false, false, false);
+            let matcher = Matcher::compile(black_box(&config)).unwrap();
+            let _ = black_box(&matcher);
+        })
+    });
+
+    group.finish();
+}
+
+fn bench_match(c: &mut Criterion) {
+    let mut group = c.benchmark_group("match");
+
+    // Fixed string match - hit
+    {
+        let patterns: &[&str] = &["ERROR"];
+        let config = make_config(patterns, RegexMode::Fixed, false, false, false);
+        let matcher = Matcher::compile(&config).unwrap();
+        let line = b"2024-01-15 10:30:45 ERROR: Connection timeout on server-42";
+
+        group.bench_function("fixed_string_hit", |b| {
+            b.iter(|| black_box(matcher.match_line(black_box(line))))
+        });
+    }
+
+    // Fixed string match - miss
+    {
+        let patterns: &[&str] = &["CRITICAL"];
+        let config = make_config(patterns, RegexMode::Fixed, false, false, false);
+        let matcher = Matcher::compile(&config).unwrap();
+        let line = b"2024-01-15 10:30:45 INFO: Server started successfully";
+
+        group.bench_function("fixed_string_miss", |b| {
+            b.iter(|| black_box(matcher.match_line(black_box(line))))
+        });
+    }
+
+    // Extended regex match
+    {
+        let patterns: &[&str] = &[r"[0-9]{4}-[0-9]{2}-[0-9]{2}"];
+        let config = make_config(patterns, RegexMode::Extended, false, false, false);
+        let matcher = Matcher::compile(&config).unwrap();
+        let line = b"2024-01-15 10:30:45 ERROR: Connection timeout";
+
+        group.bench_function("extended_regex_hit", |b| {
+            b.iter(|| black_box(matcher.match_line(black_box(line))))
+        });
+    }
+
+    // Case-insensitive match
+    {
+        let patterns: &[&str] = &["error"];
+        let config = make_config(patterns, RegexMode::Fixed, true, false, false);
+        let matcher = Matcher::compile(&config).unwrap();
+        let line = b"2024-01-15 10:30:45 ERROR: Connection timeout";
+
+        group.bench_function("case_insensitive_hit", |b| {
+            b.iter(|| black_box(matcher.match_line(black_box(line))))
+        });
+    }
+
+    // Inverted match
+    {
+        let patterns: &[&str] = &["ERROR"];
+        let config = make_config(patterns, RegexMode::Fixed, false, true, false);
+        let matcher = Matcher::compile(&config).unwrap();
+        let line = b"2024-01-15 10:30:45 INFO: Server started successfully";
+
+        group.bench_function("inverted_match", |b| {
+            b.iter(|| black_box(matcher.match_line(black_box(line))))
+        });
+    }
+
+    // Word boundary match
+    {
+        let patterns: &[&str] = &["error"];
+        let config = make_config(patterns, RegexMode::Fixed, true, false, true);
+        let matcher = Matcher::compile(&config).unwrap();
+        let line = b"2024-01-15 10:30:45 error: Connection timeout";
+
+        group.bench_function("word_boundary_hit", |b| {
+            b.iter(|| black_box(matcher.match_line(black_box(line))))
+        });
+    }
+
+    // Multiple patterns
+    {
+        let patterns: &[&str] = &["error", "warning", "critical", "fatal", "panic"];
+        let config = make_config(patterns, RegexMode::Fixed, true, false, false);
+        let matcher = Matcher::compile(&config).unwrap();
+        let line = b"2024-01-15 10:30:45 WARNING: High memory usage detected on node-7";
+
+        group.bench_function("multi_pattern_hit", |b| {
+            b.iter(|| black_box(matcher.match_line(black_box(line))))
+        });
+    }
+
+    // Long line
+    {
+        let patterns: &[&str] = &["needle"];
+        let config = make_config(patterns, RegexMode::Fixed, false, false, false);
+        let matcher = Matcher::compile(&config).unwrap();
+        let mut long_line = "a".repeat(5000);
+        long_line.push_str("needle");
+        long_line.push_str(&"b".repeat(5000));
+        let long_line_bytes = long_line.into_bytes();
+
+        group.bench_function("long_line_hit", |b| {
+            b.iter(|| black_box(matcher.match_line(black_box(&long_line_bytes))))
+        });
+    }
+
+    group.finish();
+}
+
+fn bench_throughput(c: &mut Criterion) {
+    let mut group = c.benchmark_group("throughput");
+
+    // Simulate processing many lines (like searching a log file)
+    let lines: Vec<Vec<u8>> = (0..1000)
+        .map(|i| {
+            if i % 50 == 0 {
+                format!(
+                    "2024-01-15 10:30:{:02} ERROR: Connection timeout on server-{}",
+                    i % 60,
+                    i
+                )
+                .into_bytes()
+            } else {
+                format!(
+                    "2024-01-15 10:30:{:02} INFO: Request processed in {}ms",
+                    i % 60,
+                    i * 3
+                )
+                .into_bytes()
+            }
+        })
+        .collect();
+
+    {
+        let patterns: &[&str] = &["ERROR"];
+        let config = make_config(patterns, RegexMode::Fixed, false, false, false);
+        let matcher = Matcher::compile(&config).unwrap();
+
+        group.bench_function("scan_1000_lines_fixed", |b| {
+            b.iter(|| {
+                let mut matches = 0u64;
+                for line in &lines {
+                    if matcher.match_line(black_box(line)).is_some() {
+                        matches += 1;
+                    }
+                }
+                black_box(matches)
+            })
+        });
+    }
+
+    {
+        let patterns: &[&str] = &[r"[0-9]+ *ms"];
+        let config = make_config(patterns, RegexMode::Extended, false, false, false);
+        let matcher = Matcher::compile(&config).unwrap();
+
+        group.bench_function("scan_1000_lines_regex", |b| {
+            b.iter(|| {
+                let mut matches = 0u64;
+                for line in &lines {
+                    if matcher.match_line(black_box(line)).is_some() {
+                        matches += 1;
+                    }
+                }
+                black_box(matches)
+            })
+        });
+    }
+
+    group.finish();
+}
+
+/// End-to-end search throughput, driven through the real `uumain` entry point
+/// so the whole pipeline (input buffering, searcher, output) is exercised.
+///
+/// `bench_match` / `bench_throughput` call `Matcher::match_line` on pre-split
+/// lines, which measures matching in isolation. They cannot see a change to how
+/// the *searcher* feeds data to the matcher (e.g. scanning whole buffers instead
+/// of testing one line at a time), because they never run the searcher. These
+/// cases do: a literal pattern (which a buffer-at-a-time engine can accelerate)
+/// and an extended-regex control (which cannot), over a multi-megabyte file.
+fn bench_search(c: &mut Criterion) {
+    use std::ffi::OsString;
+
+    // A log-like file large enough to cross many internal read buffers.
+    let mut content = String::new();
+    for i in 0..80_000u32 {
+        if i % 100 == 0 {
+            content.push_str(&format!(
+                "2024-01-15 10:30:{:02} ERROR worker-{i} connection reset\n",
+                i % 60
+            ));
+        } else {
+            content.push_str(&format!(
+                "2024-01-15 10:30:{:02} INFO  worker-{i} request handled in {}ms\n",
+                i % 60,
+                i % 1000
+            ));
+        }
+    }
+    assert!(content.len() > 4 * 1024 * 1024);
+
+    let mut path = std::env::temp_dir();
+    path.push(format!("uu_grep_bench_{}.log", std::process::id()));
+    std::fs::write(&path, &content).unwrap();
+    let path_arg = path.clone().into_os_string();
+
+    // `-q` with a pattern that never matches forces a full scan of the file and
+    // produces no output, so the timing reflects pure scanning throughput.
+    let run = |extra_flag: Option<&str>, pattern: &str| {
+        let mut args: Vec<OsString> = vec![OsString::from("grep"), OsString::from("-q")];
+        if let Some(flag) = extra_flag {
+            args.push(OsString::from(flag));
+        }
+        args.push(OsString::from(pattern));
+        args.push(path_arg.clone());
+        // No match => Err(exit code 1); we only care about the work, not status.
+        let _ = uu_grep::uumain(args.into_iter());
+    };
+
+    let mut group = c.benchmark_group("search");
+
+    group.bench_function("scan_literal_no_match", |b| {
+        b.iter(|| run(None, black_box("NONEXISTENT_TOKEN_XYZ")))
+    });
+
+    group.bench_function("scan_regex_no_match", |b| {
+        b.iter(|| run(Some("-E"), black_box("NON[0-9]EXISTENT_TOKEN")))
+    });
+
+    group.finish();
+    let _ = std::fs::remove_file(&path);
+}
+
+criterion_group!(
+    benches,
+    bench_compile,
+    bench_match,
+    bench_throughput,
+    bench_search
+);
+criterion_main!(benches);

src/lib.rs

@@ -3,9 +3,12 @@
 // For the full copyright and license information, please view the LICENSE
 // file that was distributed with this source code.
 
-mod context_buffer;
-mod line_buffer;
-mod matcher;
+#[doc(hidden)]
+pub mod context_buffer;
+#[doc(hidden)]
+pub mod line_buffer;
+#[doc(hidden)]
+pub mod matcher;
 mod output;
 mod searcher;
 
@@ -20,7 +23,8 @@ use std::path::Path;
 use uucore::error::{FromIo, UResult, USimpleError};
 
 #[derive(Clone, Copy, PartialEq, Eq)]
-enum RegexMode {
+#[doc(hidden)]
+pub enum RegexMode {
     Fixed,
     Basic,
     Extended,
@@ -28,7 +32,8 @@ enum RegexMode {
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]
-enum BinaryMode {
+#[doc(hidden)]
+pub enum BinaryMode {
     Binary,
     Text,
     WithoutMatch,
@@ -42,79 +47,84 @@ enum ColorMode {
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]
-enum DirectoryMode {
+#[doc(hidden)]
+pub enum DirectoryMode {
     Read,
     Skip,
     Recurse,
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]
-enum DeviceMode {
+#[doc(hidden)]
+pub enum DeviceMode {
     Default,
     Read,
     Skip,
 }
 
-struct ColorConfig<'a> {
-    matched_selected: &'a str,
-    matched_context: &'a str,
-    filename: &'a str,
-    line_number: &'a str,
-    byte_offset: &'a str,
-    separator: &'a str,
-    selected_line: &'a str,
-    context_line: &'a str,
+#[doc(hidden)]
+pub struct ColorConfig<'a> {
+    pub matched_selected: &'a str,
+    pub matched_context: &'a str,
+    pub filename: &'a str,
+    pub line_number: &'a str,
+    pub byte_offset: &'a str,
+    pub separator: &'a str,
+    pub selected_line: &'a str,
+    pub context_line: &'a str,
 
-    reverse_video: bool,
-    no_erase: bool,
+    pub reverse_video: bool,
+    pub no_erase: bool,
 }
 
-struct GlobSet {
+#[doc(hidden)]
+pub struct GlobSet {
     patterns: Vec<glob::Pattern>,
 }
 
-struct Config<'a> {
+#[doc(hidden)]
+pub struct Config<'a> {
     // Searcher
-    directory_mode: DirectoryMode,
-    device_mode: DeviceMode,
-    follow_symlinks: bool,
-    include_globs: GlobSet,
-    exclude_globs: GlobSet,
-    exclude_dir_globs: GlobSet,
-    label: &'a str,
+    pub directory_mode: DirectoryMode,
+    pub device_mode: DeviceMode,
+    pub follow_symlinks: bool,
+    pub include_globs: GlobSet,
+    pub exclude_globs: GlobSet,
+    pub exclude_dir_globs: GlobSet,
+    pub label: &'a str,
     #[cfg(windows)]
-    strip_cr: bool,
-    binary_mode: BinaryMode,
-    max_count: Option<u64>,
-    before_context: usize,
-    after_context: usize,
-    has_context: bool,
+    pub strip_cr: bool,
+    pub binary_mode: BinaryMode,
+    pub max_count: Option<u64>,
+    pub before_context: usize,
+    pub after_context: usize,
+    pub has_context: bool,
 
     // Matcher
-    patterns: &'a [&'a str],
-    regex_mode: RegexMode,
-    ignore_case: bool,
-    invert_match: bool,
-    word_regexp: bool,
-    line_regexp: bool,
+    pub patterns: &'a [&'a str],
+    pub regex_mode: RegexMode,
+    pub ignore_case: bool,
+    pub invert_match: bool,
+    pub word_regexp: bool,
+    pub line_regexp: bool,
 
     // Output
-    quiet: bool,
-    count: bool,
-    show_filename: bool,
-    files_with_matches: bool,
-    files_without_match: bool,
-    only_matching: bool,
-    byte_offset: bool,
-    line_number: bool,
-    initial_tab: bool,
-    null_separator: bool,
-    null_data: bool,
-    line_buffered: bool,
-    no_messages: bool,
-    group_separator: Option<&'a str>,
-    use_color: bool,
-    color_config: ColorConfig<'a>,
+    pub quiet: bool,
+    pub count: bool,
+    pub show_filename: bool,
+    pub files_with_matches: bool,
+    pub files_without_match: bool,
+    pub only_matching: bool,
+    pub byte_offset: bool,
+    pub line_number: bool,
+    pub initial_tab: bool,
+    pub null_separator: bool,
+    pub null_data: bool,
+    pub line_buffered: bool,
+    pub no_messages: bool,
+    pub group_separator: Option<&'a str>,
+    pub use_color: bool,
+    pub color_config: ColorConfig<'a>,
 }
 
 #[uucore::main(no_signals)]
@@ -854,8 +864,21 @@ fn expand_num_shorthand(args: impl Iterator<Item = OsString>) -> Vec<OsString> {
     out
 }
 
+impl Default for GlobSet {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl GlobSet {
-    fn with_capacity(capacity: usize) -> Self {
+    /// Create an empty GlobSet.
+    pub fn new() -> Self {
+        Self {
+            patterns: Vec::new(),
+        }
+    }
+
+    pub fn with_capacity(capacity: usize) -> Self {
         Self {
             patterns: Vec::with_capacity(capacity),
         }