Implement System::system_metas(&self) and System::system_metas_mut(&mut self) for system exploration and configuration

[Rajveer100]

Part of #16168

Objective

Implement System::system_metas(&self) and System::system_metas_mut(&mut self) for system exploration and configuration.

Solution

Introduce System::system_metas(&self) and System::system_metas_mut(&mut self) which would return iterator/vector/slice that we can work with.

[github-actions]

Welcome, new contributor!

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

[Rajveer100]

@alice-i-cecile
I am not quite sure if this is in the right direction.

[alice-i-cecile]

@MiniaczQ, opinions?

[alice-i-cecile]

In all of the cases other than for piped systems, this method should return a vector with one element :)

[MiniaczQ]

Yeah, I didn't want to tackle this, because it's actually pretty technical.
I'd say the actual scope of this issue can be split into 3 steps.
If you can get the first one down, the rest is relatively easy as follow-up PRs.

Step 1

We definitely need a trait that has system_metas(&self) -> Vec<&SystemMeta> and system_metas_mut(&mut self) -> Vec<&mut SystemMeta>.
Implement it for all of the system types, sort of like what you did, just as a trait instead.

Now, to make this actually work, we need another set of methods (in that trait): extend_with_system_metas(&self, &mut Vec<&SystemMeta>) and extend_with_system_metas_mut(&mut self, &mut Vec<&mut SystemMeta>).
The original two methods will create a new Vec and fill it using the new methods.
Non-primitive systems like adapters and combinators will call the new methods on their sub-systems, while primitive systems will just append their own meta.
I'm not sure if the borrow checker will freak out here or not with the &mut.

Step 2

Then there is the matter of in-lining it.
This is not very appealing:

let mut my_system = IntoSystem::into_system(my_system);
my_system.system_metas_mut()[0].name = "abba".into();
app.add_systems(Update, my_system);

so we want a map_system_metas method (again, in the trait) that can do the same thing inline.

app.add_systems(Update, my_system.map_system_metas(|metas| { metas[0].name = "abba".into(); }));

no need for immutable variant.

Step 3

Sadly this isn't the end for this issue, we also should expose SystemMetas for schedule-configuration wrappers as well.
So implementing aforementioned trait on I believe SystemConfig and SystemSetConfig, I'd need to look it up to be sure.
This would allow us to do my_system.after(other_system).map_system_metas(...).

[Rajveer100]

Thanks for the detailed overview :)

[Rajveer100]

@MiniaczQ
Let me know if the latest changes is the intended way. I think only the non-primitive systems remain:

• AdapterSystems
• CombinatorSystems
• PipeSystems

[MiniaczQ]

Looks good!
Looking through CI there seem to be no issues with borrow checker so far, hopefully it stays that way 🤞

[Rajveer100]

Done with non-primitive systems, if this looks fine we can work with the next steps.

[hymm]

it might be better for these to take an impl Extend instead of a Vec. https://doc.rust-lang.org/core/iter/trait.Extend.html

[MiniaczQ]

It's neat, but I don't think it's appropriate to implement it here
Unless I don't understand your point

[hymm]

I was saying to change the function signature to fn extend_with_system_metas<'a>(&'a self, extendable: impl Extend<&'a SystemMeta>), which would allow the methods to take a bunch of the other std collections and not be limited to just a Vec.

[MiniaczQ]

I completely missed the point then :)
I'm down for it

[chescock]

Another option is to take impl FnMut(&'a SystemMeta). That way, users that are just going to iterate over the result won't even have to allocate a Vec.

[Rajveer100]

So you recommend going with extend first?

[MiniaczQ]

Yup

[chescock]

Just to clarify, my point was that FnOnce is more general than Extend here. You'd still offer the version that returns a Vec!

fn for_each_system_meta<'a>(&'a self, f: impl FnOnce(&'a SystemMeta));

fn system_metas(&self) -> Vec<&SystemMeta> {
    let mut result = Vec::new();
    self.for_each_system_meta(|meta| result.push(meta));
    result
}

If someone wants to populate another type of collection, they can pass a closure that calls the relevant push method. But if they were just going to do for meta in system.system_metas() { ... } then they can avoid an allocation by calling system.for_each_system_meta(|meta| ...).

[MiniaczQ]

Can't be FnOnce since we use it many times, besides that makes sense, I voice no preference then

[Rajveer100]

Idea seems reasonable.