Skip to main content

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}