Observers overhaul: statically-typed multi-event-listening and safer dynamic-event-listening #14674

ItsDoot · 2024-08-09T03:20:14Z

Objective

Solution

The following presented solution is:

Safe: The previous (unsafe required) solution to statically-unknown event types now has a 100% safe alternative.
Ergonomic: Simply upgrade your observers by going from Trigger<Foo> to Trigger<(Foo, Bar)>.
Zero-abstraction overhead: Single-event observers remain as fast as they were prior, and multi-event observers have little or no additional overhead.
Backwards-compatible: All observers written for 0.14 will continue to function as expected without any code changes.

Event Sets

We introduce a new trait named EventSet that performs a role similar to WorldQuery, although with a much smaller API surface. An EventSet can be / is implemented by:

All normal Event types.
A tuple of normal Event types (up to arity =15). Supports nesting tuples inside tuples.
A DynamicEvent type that allows raw-pointer-style observation.
A SemiDynamicEvent type that allows you to first match on statically-known event types, and if none match operates like a DynamicEvent.

The most notable operations that an EventSet provides are:

unchecked_cast: Casts the raw pointer into the type of the output item.
matches: Returns true if the event set contains the provided event component ID.
init_components: Initializes all required event types to have component IDs.

Statically-known multiple-event observers

Your observers can now be upgraded from single-event observers to multiple-event observers with the simple change to a tuple for your Trigger generic parameter. If a single event type is specified in the trigger, then the returned item type remains a &Event or &mut Event. If a tuple of event types are specified in the trigger, then an enum with the same arity is the returned item type, for example: enum Or2<EventA, EventB> { A(EventA), B(EventB) }.

#[derive(Event)]
struct Foo(i32);
#[derive(Event)]
struct Bar(bool);
#[derive(Event)]
struct Baz(String);

// Also works with Commands!
world.observe(|trigger: Trigger<(Foo, Bar, Baz)> {
    match trigger.event() {
        Or3::A(Foo(v)) => { assert_eq!(5, *v); }
        Or3::B(Bar(v)) => { assert!(*v); }
        Or3::C(Baz(v)) => { assert_eq!("Hello world!", *v); }
    }
});
world.trigger(Foo(5));
world.trigger(Bar(true));
world.trigger(Baz("Hello world!".into()));

Dynamically-known event observers

The DynamicEvent type does not perform any pointer casting or type matching logic, and instead returns true when matching on ANY event type. This is most useful when you want to listen for event types that are not known at compile time. The returned items accessible with Trigger::event() and Trigger::event_mut() are Ptr and PtrMut, respectively, which are type-erased but lifetime'd pointers.

// Get our event component IDs somehow. They don't need to be statically known!
let foo_id = world.init_component::<Foo>();
let bar_id = world.init_component::<Bar>();

world.spawn(
    Observer::new(|trigger: Trigger<DynamicEvent> {
        // Called for foo and bar events
    })
    .with_event(foo_id) // This method was previously unsafe because it could result in UB.
    .with_event(bar_id) // But we don't do any casting automatically here, so we're safe! (It's on the user's side to do that)
);
// Trigger our runtime-known events dynamically:
unsafe {
    EmitDynamicTrigger::new_with_id(foo_id, Foo(10), ()).apply(&mut world);
    EmitDynamicTrigger::new_with_id(bar_id, Bar(false), ()).apply(&mut world);
}

Semi-dynamically-known event observers

For complex scenarios, we can also combine both statically-known and runtime-known event types in a single observer, using SemiDynamicEvent<Static>. This means all event types that don't match the specified statically-known event types will be returned as a Ptr/PtrMut. The returned item type for SemiDynamicEvent is Result<StaticallyKnownItems, PtrMut>.

#[derive(Event)]
struct Foo(i32);
#[derive(Event)]
struct Bar(bool);

// Get our event component IDs that are only runtime-known
let baz_id = world.init_component::<Baz>();

world.spawn(
    Observer::new(|trigger: Trigger<SemiDynamicEvent<(Foo, Bar)>>| {
        match trigger.event() {
            Ok(Or2::A(Foo(v))) => { assert_eq!(6, *v); },
            Ok(Or2::B(Bar(v))) => { assert!(*v); },
            Err(ptr) => { /* do stuff with our `Ptr` */ }
        }
    })
    .with_event(baz_id)
);

// Trigger our statically known event types
world.trigger(Foo(6));
world.trigger(Bar(true));
// Trigger our runtime-known events dynamically:
unsafe {
    EmitDynamicTrigger::new_with_id(baz_id, Baz("Hello world!".into()), ()).apply(&mut world);
}

TODO

Add a lot more docs.
Open a subsequent issue for adding a derive macro for custom EventSet types.

Testing

I've added 5 new tests:
- observer_multiple_events_static: Tests functionality of reading event data from two different statically-known event types.
- observer_multiple_events_dynamic: Tests DynamicEvent's behavior of passing pointers as-is.
- observer_multiple_events_semidynamic: Tests SemiDynamicEvent's behavior of first trying to match on statically-known event types, and falling back to DynamicEvent if none match.
- observer_propagating_multi_event_between: Tests that event sets do not interfere with current propagation code.
- observer_propagating_multi_event_all: Same as above
I've added 3 new benchmarks:
- observe_multievent: Tests the matching speed of tuple event sets from size 1 to 15 (No observed slowdowns).
  - The (A,) (size=1) tuple implementation simply forwards to A, which is equivalent to current observer code.
- observe_dynamic: Tests the matching speed of runtime known event types with DynamicEvent (No observed slowdowns).
- observe_semidynamic: Tests the matching speed of combined statically-known and runtime-known event types with SemiDynamicEvent (No observed slowdowns).

Migration Guide

Observer::with_event was renamed to Observer::with_event_unchecked. If you were using this function, consider using a new one that has been added under the old name, which isn't marked unsafe but requires your Trigger<E>'s E type to be either DynamicEvent or SemiDynamicEvent.

viridia · 2024-08-09T06:26:40Z

Don't know if this helps, but here's an example of a macro that does tuple expansion: https://github.com/viridia/quill/blob/main/crates/bevy_mod_stylebuilder/src/lib.rs#L80

…g some of the unsafe blocks. also added a safe method for adding events to an observer when it's all untyped

…t the event type matches the event set before casting

…ke it more obvious that it does the same thing

github-actions · 2024-08-10T22:31:40Z

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Could you add some context on what users should update when this change get released in a new version of Bevy?
It will be used to help writing the migration guide for the version. Putting it after a ## Migration Guide will help it get automatically picked up by our tooling.

…safely

…cEvent

cBournhonesque

(I only looked at the tests)
I like the idea, and it seems to be a big amount of work, kudos!
I wonder if there would be a way to resolve some of the ergonomics:

introducing SemiDynamicEvent and DynamicEvent is a bit confusing
the user needing to use Or2, Or3, etc.
using Err as a match branch for dynamic events

cBournhonesque · 2024-08-11T21:23:59Z