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
use ArenaContactTracker;
use crateSeqImpulseConstraintSolver;
/// Reusable temporary storage for one arena step.
///
/// Pass one value to [`crate::Arena::step_tick_with_buffers`]. The arena borrows the
/// storage for exactly one tick. Reuse the same value for each arena that a
/// worker thread steps.
///
/// Use this storage when one worker steps many arenas. Use
/// [`crate::Arena::step_tick`] for a single arena to avoid the storage exchange.
/// Speed depends on the workload. Measure both methods before you choose one.
///
/// The storage holds only temporary step data. It does not hold world state,
/// persistent manifolds, output events, contact history, or random-generator
/// state. All of those stay in the arena.
///
/// # Lifetime
///
/// The arena keeps its own storage object. The step exchanges the two storage
/// objects for one tick and then exchanges them back. This value keeps the
/// buffers used by that step. A successful step clears their contents but
/// retains their capacity. An arena that also uses [`crate::Arena::step_tick`]
/// retains its own grown buffers.
///
/// Use one buffer set for one worker thread at a time. Do not use the same
/// value from two threads at the same time.
///
/// # Panic safety
///
/// A panic inside the step cannot move temporary records into another arena.
/// The restore guard runs during unwinding. It puts the arena storage back
/// first. It then clears the records and temporary rows of the reuse storage.
/// The next call starts from empty storage. A build with `panic = "abort"`
/// stops the process, so no arena can reuse the storage.
///
/// # Example
///
/// ```no_run
/// use rocketsim::{Arena, ArenaStepBuffers, GameMode};
///
/// let mut arenas = [Arena::new(GameMode::TheVoid), Arena::new(GameMode::TheVoid)];
/// let mut buffers = ArenaStepBuffers::new();
/// for _ in 0..120 {
/// for arena in &mut arenas {
/// arena.step_tick_with_buffers(&mut buffers);
/// }
/// }
/// ```