captrack 0.1.0

Capacity telemetry for Rust collections — call-site macros that record peak capacity, with zero overhead when disabled.
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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

// CapHasher — feature-selected default hasher (Axis 2A).
//
// Exactly one hasher feature may be active at a time.  Selecting more than one
// is a compile error (see the guard below).  When no hasher feature is enabled
// the default is `std::collections::hash_map::RandomState` — the safe OSS
// default that is not vulnerable to hash-flooding attacks from untrusted input.
//
// Users who want a faster hasher opt in explicitly:
//   [features]
//   captrack = { version = "...", features = ["fxhash"] }

// ── Guard: at most one hasher feature ────────────────────────────────────────

#[cfg(all(feature = "fxhash", feature = "ahash"))]
compile_error!(
    "captrack: select at most one default-hasher feature (fxhash / ahash / foldhash / rustc-hash)"
);

#[cfg(all(feature = "fxhash", feature = "foldhash"))]
compile_error!(
    "captrack: select at most one default-hasher feature (fxhash / ahash / foldhash / rustc-hash)"
);

#[cfg(all(feature = "fxhash", feature = "rustc-hash"))]
compile_error!(
    "captrack: select at most one default-hasher feature (fxhash / ahash / foldhash / rustc-hash)"
);

#[cfg(all(feature = "ahash", feature = "foldhash"))]
compile_error!(
    "captrack: select at most one default-hasher feature (fxhash / ahash / foldhash / rustc-hash)"
);

#[cfg(all(feature = "ahash", feature = "rustc-hash"))]
compile_error!(
    "captrack: select at most one default-hasher feature (fxhash / ahash / foldhash / rustc-hash)"
);

#[cfg(all(feature = "foldhash", feature = "rustc-hash"))]
compile_error!(
    "captrack: select at most one default-hasher feature (fxhash / ahash / foldhash / rustc-hash)"
);

// ── CapHasher type alias ──────────────────────────────────────────────────────

/// The default build-hasher used by all hash-keyed `captrack` macros.
///
/// Resolved at compile time based on which feature flag (if any) is enabled:
///
/// | Feature      | `CapHasher`                                              |
/// |--------------|----------------------------------------------------------|
/// | *(none)*     | `std::collections::hash_map::RandomState` (DoS-safe)     |
/// | `fxhash`     | `fxhash::FxBuildHasher`                                  |
/// | `ahash`      | `ahash::RandomState`                                     |
/// | `foldhash`   | `foldhash::fast::RandomState`                            |
/// | `rustc-hash` | `rustc_hash::FxBuildHasher`                              |
///
/// # Selecting a faster hasher
///
/// ```toml
/// # Cargo.toml
/// [dependencies]
/// captrack = { version = "0.1", features = ["ahash"] }
/// ```
///
/// # Per-call override (Axis 2B)
///
/// Use the `;`-arm of any hash macro to override the hasher for a single
/// call-site without changing `CapHasher` globally:
///
/// ```ignore
/// use captrack::tmap;
/// // uses CapHasher (the workspace default):
/// let m1 = tmap!("my/map", 16);
/// // uses ahash for this one call:
/// let m2 = tmap!("my/special", 8; ahash::RandomState::new());
/// ```
#[cfg(not(any(
    feature = "fxhash",
    feature = "ahash",
    feature = "foldhash",
    feature = "rustc-hash"
)))]
pub type CapHasher = std::collections::hash_map::RandomState;

#[cfg(feature = "fxhash")]
pub type CapHasher = fxhash::FxBuildHasher;

#[cfg(feature = "ahash")]
pub type CapHasher = ahash::RandomState;

#[cfg(feature = "foldhash")]
pub type CapHasher = foldhash::fast::RandomState;

#[cfg(feature = "rustc-hash")]
pub type CapHasher = rustc_hash::FxBuildHasher;