unityrs_testkit/env/catalog/race.rs
1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/ContainerHelper.py, UnityPy/environment.py. See THIRD_PARTY_LICENSES.
2//! The scenes whose container preload walk races a load another thread
3//! makes (review round 14): `tools/fixtures/env.py` records UnityPy's walk
4//! (`helpers/ContainerHelper.py:31-49`) with the load made before the walk,
5//! before each element of each row's span it looks at, after each row, and
6//! after the walk, and the core's walk is stopped at each point it reaches
7//! while another thread makes the load. In each, the other file replaces a
8//! CAB a scene file registered, or two (`RaceScene`'s docs).
9
10use super::named;
11use super::revisit::preload_revisits_after_load;
12use crate::env::{Bundle, DepScene, Obj, RaceScene, Scene, bundle, row, serialized};
13
14/// Two `SerializedFile`s, each with one container row naming its own
15/// object: `p` (object 10, `assets/a.prefab`) and `q` (object 30,
16/// `assets/b.prefab`). A plain scene ([`super::scenes`]): the core's unit
17/// test `env::race_tests` loads them on two threads, the first stopped
18/// between its registration and its `files` entry while the second loads
19/// whole, under these names and both under `x`, against UnityPy's two
20/// orders of each (`tools/fixtures/env_race.py`; review round 16: `files`
21/// took the order the threads listed in, the registry the loads' order),
22/// and three loads, `p` under `x` and `y` and then `q` under `x`, the
23/// first stopped while the other two load whole, against UnityPy's order
24/// of their numbers (a key listed by a later load before the first lists
25/// moves to the first's number).
26#[must_use]
27pub fn listings_raced() -> Scene {
28 let file = |id: i64, path: &str| {
29 serialized(
30 &[],
31 &[
32 Obj::named(id, "o", &[]),
33 Obj::asset_bundle(
34 2,
35 Bundle {
36 rows: vec![row(path, (0, 0), (0, id))],
37 ..Bundle::default()
38 },
39 ),
40 ],
41 )
42 };
43 Scene {
44 files: vec![
45 named("p", file(10, "assets/a.prefab")),
46 named("q", file(30, "assets/b.prefab")),
47 ],
48 resolver: Vec::new(),
49 }
50}
51
52/// The six listings the core's unit test `env::listing_tests` makes in
53/// every order, each load's number its index: `x`, `y`, `X`, `x`, `y` and
54/// `x`, the last as a dependency. Each file is a `SerializedFile` holding
55/// one named object whose path id is its load's number + 1, so a listing's
56/// file and object tell its load. A key is listed again by a later load and
57/// by an earlier one, after it moved, two keys lower to one name, and the
58/// last `x` is a dependency's, which `objects` skips. Not a scene of
59/// [`super::scenes`]: `tools/fixtures/env_race.py` records UnityPy's
60/// `env.files` after every set of these loads, made in the order of their
61/// numbers (review round 16's follow-up: the test's expected values were a
62/// hand-written model of a Python dict).
63#[must_use]
64pub fn listings() -> DepScene {
65 let keys = ["x", "y", "X", "x", "y", "x"];
66 let files = keys
67 .iter()
68 .zip(1_i64..)
69 .map(|(key, id)| named(key, serialized(&[], &[Obj::named(id, "o", &[])])))
70 .collect();
71 DepScene {
72 scene: Scene {
73 files,
74 resolver: Vec::new(),
75 },
76 dependencies: vec![5],
77 }
78}
79
80/// `c.bundle` with `CAB-A` holding object 4 only, then `f.bundle`, whose
81/// `CAB-F` has `externals` and the preload table `preload`, and the rows
82/// `assets/<k>.prefab` spanning `spans` in turn.
83fn walked(externals: &[&str], preload: Vec<(i32, i64)>, spans: &[(i32, i32)]) -> Scene {
84 let rows = spans
85 .iter()
86 .enumerate()
87 .map(|(k, &span)| row(&format!("assets/{k}.prefab"), span, (0, 1)))
88 .collect();
89 let f = serialized(
90 externals,
91 &[
92 Obj::named(1, "f1", &[]),
93 Obj::asset_bundle(
94 2,
95 Bundle {
96 preload,
97 rows,
98 ..Bundle::default()
99 },
100 ),
101 ],
102 );
103 let caller = serialized(&[], &[Obj::named(4, "caller4", &[])]);
104 Scene {
105 files: vec![
106 named("c.bundle", bundle(&[("CAB-A", caller)])),
107 named("f.bundle", bundle(&[("CAB-F", f)])),
108 ],
109 resolver: Vec::new(),
110 }
111}
112
113/// `d.bundle`, whose `CAB-<cab>` holds `objects` (path id, name).
114fn other(cab: &str, objects: &[(i64, &str)]) -> (Vec<u8>, Vec<u8>) {
115 let objects: Vec<Obj> = objects
116 .iter()
117 .map(|&(id, n)| Obj::named(id, n, &[]))
118 .collect();
119 named(
120 "d.bundle",
121 bundle(&[(&format!("CAB-{cab}"), serialized(&[], &objects))]),
122 )
123}
124
125/// A change another thread makes is seen at a later row by an index the
126/// walk dereferenced before it: the table is `CAB-A`'s 5 and 6, row 0
127/// spans the first, row 1 the second, row 2 the first. With the other
128/// file's `CAB-A` (5 and 6) loaded before row 1, UnityPy's row 1 gives 6
129/// its path and row 2 gives 5 its own (the walk had kept its row-0 miss of
130/// 5 and dereferenced it no more).
131#[must_use]
132pub fn race_seen_at_a_later_row() -> RaceScene {
133 RaceScene {
134 scene: walked(
135 &["archive:/CAB-A/CAB-A"],
136 vec![(1, 5), (1, 6)],
137 &[(0, 1), (1, 1), (0, 1)],
138 ),
139 other: other("A", &[(5, "other5"), (6, "other6")]),
140 }
141}
142
143/// Another thread's change of a key, then the walk's own (review round 14,
144/// area d's probe): the table is `CAB-A`'s 5, `t`'s 1 and `a`'s 9, row 0
145/// spans all three, row 1 the first. `t` is found nowhere; `a` is matched
146/// by suffix in `env.path` (`environment.py:345-354`), whose `cab-a` (5
147/// and 9) takes the key, so UnityPy's row 1 finds its 5 whatever the other
148/// file (`CAB-A` with 7) replaced before (the walk lost its index to the
149/// other thread's change, and put back nothing at its own).
150#[must_use]
151pub fn race_before_the_walks_own_load() -> RaceScene {
152 let mut scene = walked(
153 &["archive:/CAB-A/CAB-A", "t", "a"],
154 vec![(1, 5), (2, 1), (3, 9)],
155 &[(0, 3), (0, 1)],
156 );
157 let found = serialized(
158 &[],
159 &[Obj::named(5, "found5", &[]), Obj::named(9, "found9", &[])],
160 );
161 scene.resolver = vec![named("cab-a", found)];
162 RaceScene {
163 scene,
164 other: other("A", &[(7, "other7")]),
165 }
166}
167
168/// Two externals of one name, so their lookups read one key: the table is
169/// the first's 5, the second's 5 and the first's 6, in one row. With the
170/// other file's `CAB-A` (5 and 6) loaded before the second element,
171/// UnityPy's second and third elements find it (the walk's second lookup
172/// found the change while the first external's kept miss still held, its
173/// flag set only after the change was published).
174#[must_use]
175pub fn race_two_externals_one_key() -> RaceScene {
176 RaceScene {
177 scene: walked(
178 &["archive:/CAB-A/CAB-A", "archive:/CAB-A/CAB-A"],
179 vec![(1, 5), (2, 5), (1, 6)],
180 &[(0, 3)],
181 ),
182 other: other("A", &[(5, "other5"), (6, "other6")]),
183 }
184}
185
186/// The scene `preload_revisits_after_load` with another copy of `CAB-Q`
187/// (5 and 6) loaded at each point (review round 14, area x's probe): which
188/// copy row `b` finds depends only on whether the other load comes before
189/// or after the walk's own load of `env.path`'s `cab-q`.
190#[must_use]
191pub fn race_around_the_walks_own_load() -> RaceScene {
192 RaceScene {
193 scene: preload_revisits_after_load(),
194 other: other("Q", &[(5, "c2_5"), (6, "c2_6")]),
195 }
196}
197
198/// A miss, and a change another thread makes while the walk asks the
199/// resolver for the next element: the table is `CAB-A`'s 5 and `t`'s 1,
200/// row 0 spans both, row 1 the first. UnityPy's row 1 finds the other
201/// file's 5 (the walk dereferenced the first element no more).
202#[must_use]
203pub fn race_in_a_lookup() -> RaceScene {
204 RaceScene {
205 scene: walked(
206 &["archive:/CAB-A/CAB-A", "t"],
207 vec![(1, 5), (2, 1)],
208 &[(0, 2), (0, 1)],
209 ),
210 other: other("A", &[(5, "other5")]),
211 }
212}
213
214/// A load that replaces a CAB with a file whose own preload table the
215/// next container pass walks (review round 15, area d's probe): the table
216/// is `CAB-A`'s 5, in one row; the other file's `CAB-A` holds 5, 7 and an
217/// AssetBundle whose row `assets/x.prefab` names its 5 and spans its own 7,
218/// so only a walk of that table gives 7 a path. UnityPy's `register_cab`
219/// clears the built flag in the step after the one that sets the key
220/// (`environment.py:263-264`), so once a lookup finds the new `CAB-A`, its
221/// 7's `container` walks the new table (the core started the new container
222/// index generation after the registry's lock, so a thread that found the
223/// new `CAB-A` in between read the old generation's built index, and 7 no
224/// path).
225#[must_use]
226pub fn race_replaced_by_a_table_of_its_own() -> RaceScene {
227 let own = serialized(
228 &[],
229 &[
230 Obj::named(5, "other5", &[]),
231 Obj::named(7, "other7", &[]),
232 Obj::asset_bundle(
233 2,
234 Bundle {
235 preload: vec![(0, 7)],
236 rows: vec![row("assets/x.prefab", (0, 1), (0, 5))],
237 ..Bundle::default()
238 },
239 ),
240 ],
241 );
242 RaceScene {
243 scene: walked(&["archive:/CAB-A/CAB-A"], vec![(1, 5)], &[(0, 1)]),
244 other: named("d.bundle", bundle(&[("CAB-A", own)])),
245 }
246}
247
248/// A load that changes two keys, publishing one at a time (review round
249/// 15, area d's probe; plan section 3.16 item 6): `c.bundle` holds `CAB-A`
250/// (5) and `CAB-B` (6), and the table is `CAB-A`'s 5 and `CAB-B`'s 6, in one
251/// row; the other file holds a new `CAB-A` (5) and `CAB-B` (6). A load
252/// stopped right after it published its first key gives what UnityPy's
253/// walk gives with that key changed at the point it was published and the
254/// other after the walk, a split no whole load at one point gives.
255#[must_use]
256pub fn race_two_keys() -> RaceScene {
257 let mut scene = walked(
258 &["archive:/CAB-A/CAB-A", "archive:/CAB-B/CAB-B"],
259 vec![(1, 5), (2, 6)],
260 &[(0, 2)],
261 );
262 let c = bundle(&[
263 ("CAB-A", serialized(&[], &[Obj::named(5, "c5", &[])])),
264 ("CAB-B", serialized(&[], &[Obj::named(6, "c6", &[])])),
265 ]);
266 if let Some(first) = scene.files.first_mut() {
267 *first = named("c.bundle", c);
268 }
269 let d = bundle(&[
270 ("CAB-A", serialized(&[], &[Obj::named(5, "d5", &[])])),
271 ("CAB-B", serialized(&[], &[Obj::named(6, "d6", &[])])),
272 ]);
273 RaceScene {
274 scene,
275 other: named("d.bundle", d),
276 }
277}
278
279/// Every race scene, by name: what `tools/fixtures/env.py` records.
280#[must_use]
281pub fn race_scenes() -> Vec<(&'static str, RaceScene)> {
282 vec![
283 ("race_seen_at_a_later_row", race_seen_at_a_later_row()),
284 (
285 "race_before_the_walks_own_load",
286 race_before_the_walks_own_load(),
287 ),
288 ("race_two_externals_one_key", race_two_externals_one_key()),
289 (
290 "race_around_the_walks_own_load",
291 race_around_the_walks_own_load(),
292 ),
293 ("race_in_a_lookup", race_in_a_lookup()),
294 (
295 "race_replaced_by_a_table_of_its_own",
296 race_replaced_by_a_table_of_its_own(),
297 ),
298 ("race_two_keys", race_two_keys()),
299 ]
300}