mrrc 0.8.2

A Rust library for reading, writing, and manipulating MARC bibliographic records in ISO 2709 binary format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# Benchmarking

This directory contains benchmarking documentation and infrastructure notes.

## Contents

- [Results](results.md) - Measurement infrastructure, local benchmarking, and
  the procedure for producing citable numbers
- [FAQ](faq.md) - Common questions about performance and threading
- Rust benchmarks - Criterion sources in `benches/`
- Python benchmarks - pytest-benchmark suites in
  `tests/python/test_benchmark_*.py`

Related documentation:

- [Threading Guide](../guides/threading-python.md) - GIL release strategy and
  threading patterns
- [Performance Tuning](../guides/performance-tuning.md) - Usage patterns and
  optimization

## Overview

mrrc's performance comes from two design decisions:

1. **Parsing in Rust** - record parsing runs as compiled code with no
   per-record Python interpretation
2. **GIL release during parsing** - the Python bindings release the GIL while
   Rust parses, so multi-threaded workloads can parse in parallel

Early benchmarking suggested at least a 4x single-threaded speedup over
pymarc with the Python wrapper; these benchmarks need to be updated and
reconsidered. See [Results](results.md) for what is measured today and how to
benchmark mrrc on your own hardware and data.

## Benchmark Infrastructure

| System | Framework | Location |
|--------|-----------|----------|
| Rust | Criterion | `benches/` |
| Python | pytest-benchmark | `tests/python/test_benchmark*.py` |
| CI regression detection | CodSpeed (simulation mode) | `.github/workflows/benchmark-*.yml` |

CI uses CodSpeed simulation mode: deterministic instruction-count
measurement that detects regressions between commits but does not produce
wall-clock throughput numbers. Parallel-throughput benchmarks run locally
only — see [Results](results.md).

### Running Benchmarks

```bash
# Rust benchmarks
cargo bench --bench marc_benchmarks

# Python benchmarks
uv run maturin develop --release
uv run pytest tests/python/ -m "benchmark and not slow" --benchmark-only -v
```

## Test Fixtures

Located in `tests/data/fixtures/`, generated by
`scripts/generate_benchmark_fixtures.py`:

- `1k_records.mrc` (~257 KB) - quick tests
- `10k_records.mrc` (~2.5 MB) - standard benchmarks