Mutate Observer

[pyhinox]

Objective

• Adopts Add OnMutate observer and demonstrate how to use it for UI reactivity #14520 and adds OnMutate observers.
• Provide a mechanism for immediate changes in response to mutate event.

Solution

A EntityChanges which stores the change list is added to World. When Mut::set_changed is called, a change record will be added to the EntityChanges.
When World::flush is called, EntityChanges will be clear and trigger OnMutate event to each relative entity.

Example

world.observe(|trigger: Trigger<OnMutate, Transform>, query: Query<&Transform>| {
    let transform = query.get(trigger.entity()).unwrap();
});

Testing

• Did you test these changes? If so, how?
  Just test for the base function, I don't know which test i should do.
• Are there any parts that need more testing?
  Query::iter and Query::get_mut's benchmark
• How can other people (reviewers) test your changes? Is there anything specific they need to know?
  Just treat the OnMutate as a common observer. Nothing is specific.
• If relevant, what platforms did you test these changes on, and are there any important ones you can't test?
  Mac

Possible Follow-ups

1. Add an OnMutate hook

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[pyhinox]

@alice-i-cecile Hi alice, i thought this pr is ready to review now. What should I do next?

[BenjaminBrienen]

@pyhinox there are some merge conflicts, but I'll go ahead and mark it for review to start getting eyes on it. 🙂

[mockersf]

Could you use core::cell::RefCell instead of std::cell::RefCell?

CI is failing for a few invalid links in documentation, mostly things that are not in scope for automatic doc links

[BenjaminBrienen]

I thought we had a lint enabled to catch that as well. Good eye.

[alice-i-cecile]

I think that we can use #16208 to remove the need for this. If certain components can't be mutated, we can do all of our reactive logic in the insertion / removal stage 🎉

[bushrat011899]

I thought we had a lint enabled to catch that as well. Good eye.

I don't believe clippy lints apply to documentation sadly. I got bit by that when adding the lints!

[JMS55]

@alice-i-cecile how does #16208 remove the need for this? What happens if you want to observe a component changing?

[bushrat011899]

@alice-i-cecile how does #16208 remove the need for this? What happens if you want to observe a component changing?

I believe the idea was if you want to watch a component, make that component immutable so that the current hooks can capture all state changes. It doesn't cover the case where you want to observe a component which isn't immutable though.

[alice-i-cecile]

I believe the idea was if you want to watch a component, make that component immutable so that the current hooks can capture all state changes.

Precisely.

It doesn't cover the case where you want to observe a component which isn't immutable though.

Yeah. Ultimately, virtually all of the same drawbacks apply to both the OnMutate and the immutable components approaches to this problem:

• can only be safely mutated during exclusive world access to ensure side effects are processed immediately
• changes are relatively expensive
• must be opted in (otherwise the current design would incur an unacceptable global perf penalty)

I'd like to see if we can get away with only using a single new concept to achieve these benefits, and then re-evaluate once we have a clearer picture of the final performance and ergonomics.

EDIT: on reflection, I think that this is probably still useful, because it allows users to do reactivity things with any arbitrary component, which is really valuable for UI. I suspect that we should have on-mutate observers fill a "not very strict + deferred reactions" niche, while reserving immutable components + hooks for really critical invariants that must be constantly upheld.

[cart]

on reflection, I think that this is probably still useful, because it allows users to do reactivity things with any arbitrary component, which is really valuable for UI. I suspect that we should have on-mutate observers fill a "not very strict + deferred reactions" niche, while reserving immutable components + hooks for really critical invariants that must be constantly upheld.

Yeah I'm starting to want something like this as part of our reactivity solution, over less event driven / poll based approaches (tbd though).

But yeah the current unconditional impl should not be merged. If we land this, we can't affect the default Mut path. That is hot / costly enough as it is.

The Option also appears to exist to accommodate resources. But I'd rather stop using Mut with resources (in favor of ResMut or alternatives) than pay the unnecessary size cost of the Option for resources and the unnecessary branching cost of the option for components.