|
| 1 | +use super::Command; |
| 2 | +use crate::world::World; |
| 3 | + |
| 4 | +struct CommandMeta { |
| 5 | + offset: usize, |
| 6 | + func: unsafe fn(value: *mut u8, world: &mut World), |
| 7 | +} |
| 8 | + |
| 9 | +/// A queue of [`Command`]s |
| 10 | +// |
| 11 | +// NOTE: [`CommandQueue`] is implemented via a `Vec<u8>` over a `Vec<Box<dyn Command>>` |
| 12 | +// as an optimization. Since commands are used frequently in systems as a way to spawn |
| 13 | +// entities/components/resources, and it's not currently possible to parallelize these |
| 14 | +// due to mutable [`World`] access, maximizing performance for [`CommandQueue`] is |
| 15 | +// preferred to simplicity of implementation. |
| 16 | +#[derive(Default)] |
| 17 | +pub struct CommandQueue { |
| 18 | + bytes: Vec<u8>, |
| 19 | + metas: Vec<CommandMeta>, |
| 20 | +} |
| 21 | + |
| 22 | +// SAFE: All commands [`Command`] implement [`Send`] |
| 23 | +unsafe impl Send for CommandQueue {} |
| 24 | + |
| 25 | +// SAFE: `&CommandQueue` never gives access to the inner commands. |
| 26 | +unsafe impl Sync for CommandQueue {} |
| 27 | + |
| 28 | +impl CommandQueue { |
| 29 | + /// Push a [`Command`] onto the queue. |
| 30 | + #[inline] |
| 31 | + pub fn push<C>(&mut self, command: C) |
| 32 | + where |
| 33 | + C: Command, |
| 34 | + { |
| 35 | + /// SAFE: This function is only every called when the `command` bytes is the associated |
| 36 | + /// [`Commands`] `T` type. Also this only reads the data via `read_unaligned` so unaligned |
| 37 | + /// accesses are safe. |
| 38 | + unsafe fn write_command<T: Command>(command: *mut u8, world: &mut World) { |
| 39 | + let command = command.cast::<T>().read_unaligned(); |
| 40 | + command.write(world); |
| 41 | + } |
| 42 | + |
| 43 | + let size = std::mem::size_of::<C>(); |
| 44 | + let old_len = self.bytes.len(); |
| 45 | + |
| 46 | + self.metas.push(CommandMeta { |
| 47 | + offset: old_len, |
| 48 | + func: write_command::<C>, |
| 49 | + }); |
| 50 | + |
| 51 | + if size > 0 { |
| 52 | + self.bytes.reserve(size); |
| 53 | + |
| 54 | + // SAFE: The internal `bytes` vector has enough storage for the |
| 55 | + // command (see the call the `reserve` above), and the vector has |
| 56 | + // its length set appropriately. |
| 57 | + // Also `command` is forgotten at the end of this function so that |
| 58 | + // when `apply` is called later, a double `drop` does not occur. |
| 59 | + unsafe { |
| 60 | + std::ptr::copy_nonoverlapping( |
| 61 | + &command as *const C as *const u8, |
| 62 | + self.bytes.as_mut_ptr().add(old_len), |
| 63 | + size, |
| 64 | + ); |
| 65 | + self.bytes.set_len(old_len + size); |
| 66 | + } |
| 67 | + } |
| 68 | + |
| 69 | + std::mem::forget(command); |
| 70 | + } |
| 71 | + |
| 72 | + /// Execute the queued [`Command`]s in the world. |
| 73 | + /// This clears the queue. |
| 74 | + #[inline] |
| 75 | + pub fn apply(&mut self, world: &mut World) { |
| 76 | + // flush the previously queued entities |
| 77 | + world.flush(); |
| 78 | + |
| 79 | + // SAFE: In the iteration below, `meta.func` will safely consume and drop each pushed command. |
| 80 | + // This operation is so that we can reuse the bytes `Vec<u8>`'s internal storage and prevent |
| 81 | + // unnecessary allocations. |
| 82 | + unsafe { self.bytes.set_len(0) }; |
| 83 | + |
| 84 | + let byte_ptr = if self.bytes.as_mut_ptr().is_null() { |
| 85 | + // SAFE: If the vector's buffer pointer is `null` this mean nothing has been pushed to its bytes. |
| 86 | + // This means either that: |
| 87 | + // |
| 88 | + // 1) There are no commands so this pointer will never be read/written from/to. |
| 89 | + // |
| 90 | + // 2) There are only zero-sized commands pushed. |
| 91 | + // According to https://doc.rust-lang.org/std/ptr/index.html |
| 92 | + // "The canonical way to obtain a pointer that is valid for zero-sized accesses is NonNull::dangling" |
| 93 | + // therefore it is safe to call `read_unaligned` on a pointer produced from `NonNull::dangling` for |
| 94 | + // zero-sized commands. |
| 95 | + unsafe { std::ptr::NonNull::dangling().as_mut() } |
| 96 | + } else { |
| 97 | + self.bytes.as_mut_ptr() |
| 98 | + }; |
| 99 | + |
| 100 | + for meta in self.metas.drain(..) { |
| 101 | + // SAFE: The implementation of `write_command` is safe for the according Command type. |
| 102 | + // The bytes are safely cast to their original type, safely read, and then dropped. |
| 103 | + unsafe { |
| 104 | + (meta.func)(byte_ptr.add(meta.offset), world); |
| 105 | + } |
| 106 | + } |
| 107 | + } |
| 108 | +} |
| 109 | + |
| 110 | +#[cfg(test)] |
| 111 | +mod test { |
| 112 | + use super::*; |
| 113 | + use std::{ |
| 114 | + panic::AssertUnwindSafe, |
| 115 | + sync::{ |
| 116 | + atomic::{AtomicU32, Ordering}, |
| 117 | + Arc, |
| 118 | + }, |
| 119 | + }; |
| 120 | + |
| 121 | + struct DropCheck(Arc<AtomicU32>); |
| 122 | + |
| 123 | + impl DropCheck { |
| 124 | + fn new() -> (Self, Arc<AtomicU32>) { |
| 125 | + let drops = Arc::new(AtomicU32::new(0)); |
| 126 | + (Self(drops.clone()), drops) |
| 127 | + } |
| 128 | + } |
| 129 | + |
| 130 | + impl Drop for DropCheck { |
| 131 | + fn drop(&mut self) { |
| 132 | + self.0.fetch_add(1, Ordering::Relaxed); |
| 133 | + } |
| 134 | + } |
| 135 | + |
| 136 | + impl Command for DropCheck { |
| 137 | + fn write(self, _: &mut World) {} |
| 138 | + } |
| 139 | + |
| 140 | + #[test] |
| 141 | + fn test_command_queue_inner_drop() { |
| 142 | + let mut queue = CommandQueue::default(); |
| 143 | + |
| 144 | + let (dropcheck_a, drops_a) = DropCheck::new(); |
| 145 | + let (dropcheck_b, drops_b) = DropCheck::new(); |
| 146 | + |
| 147 | + queue.push(dropcheck_a); |
| 148 | + queue.push(dropcheck_b); |
| 149 | + |
| 150 | + assert_eq!(drops_a.load(Ordering::Relaxed), 0); |
| 151 | + assert_eq!(drops_b.load(Ordering::Relaxed), 0); |
| 152 | + |
| 153 | + let mut world = World::new(); |
| 154 | + queue.apply(&mut world); |
| 155 | + |
| 156 | + assert_eq!(drops_a.load(Ordering::Relaxed), 1); |
| 157 | + assert_eq!(drops_b.load(Ordering::Relaxed), 1); |
| 158 | + } |
| 159 | + |
| 160 | + struct SpawnCommand; |
| 161 | + |
| 162 | + impl Command for SpawnCommand { |
| 163 | + fn write(self, world: &mut World) { |
| 164 | + world.spawn(); |
| 165 | + } |
| 166 | + } |
| 167 | + |
| 168 | + #[test] |
| 169 | + fn test_command_queue_inner() { |
| 170 | + let mut queue = CommandQueue::default(); |
| 171 | + |
| 172 | + queue.push(SpawnCommand); |
| 173 | + queue.push(SpawnCommand); |
| 174 | + |
| 175 | + let mut world = World::new(); |
| 176 | + queue.apply(&mut world); |
| 177 | + |
| 178 | + assert_eq!(world.entities().len(), 2); |
| 179 | + |
| 180 | + // The previous call to `apply` cleared the queue. |
| 181 | + // This call should do nothing. |
| 182 | + queue.apply(&mut world); |
| 183 | + assert_eq!(world.entities().len(), 2); |
| 184 | + } |
| 185 | + |
| 186 | + // This has an arbitrary value `String` stored to ensure |
| 187 | + // when then command gets pushed, the `bytes` vector gets |
| 188 | + // some data added to it. |
| 189 | + struct PanicCommand(String); |
| 190 | + impl Command for PanicCommand { |
| 191 | + fn write(self, _: &mut World) { |
| 192 | + panic!("command is panicking"); |
| 193 | + } |
| 194 | + } |
| 195 | + |
| 196 | + #[test] |
| 197 | + fn test_command_queue_inner_panic_safe() { |
| 198 | + std::panic::set_hook(Box::new(|_| {})); |
| 199 | + |
| 200 | + let mut queue = CommandQueue::default(); |
| 201 | + |
| 202 | + queue.push(PanicCommand("I panic!".to_owned())); |
| 203 | + queue.push(SpawnCommand); |
| 204 | + |
| 205 | + let mut world = World::new(); |
| 206 | + |
| 207 | + let _ = std::panic::catch_unwind(AssertUnwindSafe(|| { |
| 208 | + queue.apply(&mut world); |
| 209 | + })); |
| 210 | + |
| 211 | + // even though the first command panicking. |
| 212 | + // the `bytes`/`metas` vectors were cleared. |
| 213 | + assert_eq!(queue.bytes.len(), 0); |
| 214 | + assert_eq!(queue.metas.len(), 0); |
| 215 | + |
| 216 | + // Even though the first command panicked, it's still ok to push |
| 217 | + // more commands. |
| 218 | + queue.push(SpawnCommand); |
| 219 | + queue.push(SpawnCommand); |
| 220 | + queue.apply(&mut world); |
| 221 | + assert_eq!(world.entities().len(), 2); |
| 222 | + } |
| 223 | + |
| 224 | + // NOTE: `CommandQueue` is `Send` because `Command` is send. |
| 225 | + // If the `Command` trait gets reworked to be non-send, `CommandQueue` |
| 226 | + // should be reworked. |
| 227 | + // This test asserts that Command types are send. |
| 228 | + fn assert_is_send_impl(_: impl Send) {} |
| 229 | + fn assert_is_send(command: impl Command) { |
| 230 | + assert_is_send_impl(command); |
| 231 | + } |
| 232 | + |
| 233 | + #[test] |
| 234 | + fn test_command_is_send() { |
| 235 | + assert_is_send(SpawnCommand); |
| 236 | + } |
| 237 | +} |
0 commit comments