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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
//! Codec selection for the `auto` family: compress with a tier of candidate
//! codecs and keep the smallest result.
extern crate alloc;
use Vec;
use CodecId;
/// Which codecs a selection pass is allowed to try.
///
/// Compression runs once, in the proc macro; decompression runs in every
/// consumer's shipped binary on every access. The two are not
/// interchangeable costs, so the tiers cut the codec set by decode speed and
/// each keeps the smallest output *within its own candidates*. Measured on a
/// 125,976-byte executable, with the decoders this crate actually ships:
///
/// | tier | wins with | payload | decode |
/// |---|---|---:|---:|
/// | [`Fast`](AutoTier::Fast) | LZ4 | 81,798 B | 2,775 MB/s |
/// | [`Balanced`](AutoTier::Balanced) | Zstd | 56,140 B | 112 MB/s |
/// | [`Small`](AutoTier::Small) | LZMA | 52,512 B | 41 MB/s |
///
/// The tiers are nested, so a wider one never picks a *larger* payload than
/// a narrower one. They are fixed membership rather than a cost function:
/// which codec a build selects has to be predictable from the asset and the
/// enabled features alone, never from how fast the build machine is.
///
/// The tier is a build-time policy. An entry header records the one
/// [`CodecId`] that won, so nothing about it reaches the decode side.
/// Whether `id` is one of `tier`'s candidates.
///
/// [`CodecId::Store`] is deliberately absent: it is the baseline every tier
/// falls back to when nothing shrinks the input, not a codec a tier chooses
/// between.
/// Whether this build compiled in any of `tier`'s candidates.
/// The tier a request for `tier` actually runs, after widening.
///
/// A tier whose candidates are all switched off at feature level would
/// otherwise emit `Store` and leave the asset uncompressed, which is the
/// worst outcome on both axes at once. The tiers nest, so widening is
/// well-defined: take the narrowest tier at or above the requested one that
/// this build has a candidate for. A build with only `lzma` on therefore
/// serves `auto_fast` with LZMA -- the fast codecs it asked for do not
/// exist here, and LZMA is strictly better than not compressing.
///
/// This depends only on the enabled features, never on the asset or the
/// build machine.
/// Compress `input` with each of `tier`'s candidates compiled into this
/// build and return the smallest result.
///
/// Only the tier's own candidates are encoded, so `AutoTier::Fast` does not
/// pay LZMA's encode time to then discard its output.
///
/// [`CodecId::Store`] is the baseline: a codec wins only if it is strictly
/// smaller than the input, and among codecs the earliest entry of the codec
/// table wins a tie, which is what `min_by_key` yields.
///
/// If none of `tier`'s candidates were compiled in, the selection widens to
/// the next tier rather than giving up and storing the input verbatim.
/// Compress `input` with every codec compiled into this build and return the
/// smallest result.
///
/// The smallest-output end of the family, equivalent to
/// [`compress_best_in`] with [`AutoTier::Small`].