[Merged by Bors] - Add a SystemParam primitive for deferred mutations; allow #[derive]ing more types of SystemParam

[JoJoJet]

Objective

One pattern to increase parallelism is deferred mutation: instead of directly mutating the world (and preventing other systems from running at the same time), you queue up operations to be applied to the world at the end of the stage. The most common example of this pattern uses the Commands SystemParam.

In order to avoid the overhead associated with commands, some power users may want to add their own deferred mutation behavior. To do this, you must implement the unsafe trait SystemParam, which interfaces with engine internals in a way that we'd like users to be able to avoid.

Solution

Add the Deferred<T> primitive SystemParam, which encapsulates the deferred mutation pattern.
This can be combined with other types of SystemParam to safely and ergonomically create powerful custom types.

Essentially, this is just a variant of Local<T> which can run code at the end of the stage.

This type is used in the engine to derive Commands and ParallelCommands, which removes a bunch of unsafe boilerplate.

Example

use bevy_ecs::system::{Deferred, SystemBuffer};

/// Sends events with a delay, but may run in parallel with other event writers.
#[derive(SystemParam)]
pub struct BufferedEventWriter<'s, E: Event> {
    queue: Deferred<'s, EventQueue<E>>,
}

struct EventQueue<E>(Vec<E>);

impl<'s, E: Event> BufferedEventWriter<'s, E> {
    /// Queues up an event to be sent at the end of this stage.
    pub fn send(&mut self, event: E) {
        self.queue.0.push(event);
    }
}

// The `SystemBuffer` trait controls how [`Deferred`] gets applied at the end of the stage.
impl<E: Event> SystemBuffer for EventQueue<E> {
    fn apply(&mut self, world: &mut World) {
        let mut events = world.resource_mut::<Events<E>>();
        for e in self.0.drain(..) {
            events.send(e);
        }
    }
}

---

Changelog

• Added the SystemParam type Deferred<T>, which can be used to defer World mutations. Powered by the new trait SystemBuffer.

[alice-i-cecile]

Lovely idea: I really like generalizing and exposing this. Especially when it saves us on unsafe code.

I would like to see a worked example as a doc test in the docs for Buffer: it's hard to piece together exactly how this should work , even when diving into the source.

[alice-i-cecile]

That's a lovely example, thank you.

[alice-i-cecile]

Once we have one-shot systems (#2192), I think we should try to use those as our API, rather than always requiring &mut World.

[JoJoJet]

I haven't reviewed this in detail yet, but if I queue a series of mutations on the same data, I would expect that each mutation observes the result of the previous one. Is that what will happen?

That depends on how the SystemBuffer trait is implemented for your type. For BufferedEventWriter (example in the PR desc), multiple operations will get queued up in order. But for AlarmFlag (doc example for Deferred), "queuing up" a mutation is idempotent.

[alice-i-cecile]

bors r+

[bors]

Build failed (retrying...):

• run-examples

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-and-install-on-iOS
• build-android
• build (macos-latest)
• build (ubuntu-latest)
• build-wasm
• build (windows-latest)
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• check-compiles
• check-doc
• check-missing-examples-in-docs
• ci
• markdownlint
• msrv
• run-examples
• run-examples-on-wasm
• run-examples-on-windows-dx12