Per world access lists and utils

[ElliottjPierce]

Objective

Fixes #16933

Note

This PR proposes a direct solution to #16933. The issue is technically still in design phase, and while there may be better solutions, I wanted to get the conversation going. This is the least complex solution I could think of.

Since this PR is sort of a base-line implementation to create some discussion, I haven't done mush polish. If the community thinks this sort of implementation is worth pursuing, I would want to put more time into polishing it up with more documentation, tests, and maybe an example.

Solution

I made four main changes to facilitate this. These could be split into smaller PRs later.

First, I added universal access lists. See crates/bevy_ecs/src/query/access.rs UniversalAccess. This stores multiple Accesss, one per relevant world. This lets access be tracked over multiple worlds. I used a SmallVec instead of a HashMap for pairing worlds to accesses because I suspect it will perform better, but this could always be changed.

Second, I converted SystemMeta and FilteredAccessSet to use UniversalAccess. I also updated the relevant references. This formed the backbone for the feature since it allows systems to be parallelized across multiple world accesses.

Third, I created an abstraction in crates/bevy_ecs/src/world/links.rs that makes it easy to nest or reference worlds in each other. This is what makes the feature useful.

Fourth, I added SystemParam::update_meta. I needed a way to notify nested parameters of archetype changes. This needed to be within the scope of System::update_archetype_component_access, otherwise SystemMeta may be changed in a way that conflicts with the scheduler or the nested param my not have been fully updated. Using this new interface, I was able to fully connect nested params.

As a note, the Link abstraction uses some sneaky privacy rules to safely access a resource in a way that is traditionally unsafe. Although I don't see any issues with it, I encourage it to be very carefully reviewed in particular.

Testing

I have done minimal testing myself. If the community likes this sort of implementation, I would want more tests for sure. If anyone has any requests for more tests, I'd be happy to add them.

The current CI passes for me. I'm on a M2 Mac.

As far as I can tell, though not polished, the current state of the PR is safe, so please try to break it.

---

Showcase

The following is an excerpt of the test I wrote for a proof on concept. See crates/bevy_ecs/src/world/links.rs for full context and refer to #16933 for the long-term vision.

let mut main = World::new();
main.insert_resource(MyRes);
main.link(NestedWorld(World::new()));
main.peek_link::<NestedWorld>()
    .unwrap()
    .deref_mut()
    .0
    .insert_resource(MyRes);

fn my_system(
    main_res: ResMut<MyRes>,
    main_query: Query<&mut MyComponent>,
    nested_res: Linked<NestedWorld, ResMut<MyRes>>,
    nested_query: Linked<NestedWorld, Query<&'static mut MyComponent>>,
) {
    // would do stuff here
}

main.run_system_once(my_system).unwrap();

let mut schedule = Schedule::default();
schedule.add_systems(my_system);
schedule.run(&mut main);

This kind of interface could make sub app extraction much much easier to work with (and likely faster from parallelization). In the long run, it may also enable multiple sub apps' extractions to be run in parallel. This would be huge for performance of projects with multiple big sub apps, like those using avian physics.

Migration Guide

Most notably, SystemMeta's access data types have changed. If the community is in favor of this kind of implementation, I can work on a more complete migration guide.

Final Note:

This is my first time contributing to bevy or open source in general, so I am extremely open to feedback. I have done my best to follow the contributing guidelines, but let me know if anything needs to be done differently. I'm very excited about this feature, so any feedback or requests are very welcome.

[github-actions]

Welcome, new contributor!

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

[ElliottjPierce]

@PPakalns I would appreciate your input here too since you expressed interest in #16933. I want to walk away from this PR (merged or not) with a solid plan for implementing the feature.