Add method for reborrowing SystemParam types

[ecoskey]

Objective

• Allow reborrowing for SystemParam types. The end goal here is to work towards a fast System::scope api, to run a system many times with different inputs with low overhead

Blocked on: #22025

Next steps:

• This diff would be smaller with a proc-macro for internal implementations: impl_reborrow_system_param!(...). I decided not to at least at first, though it wouldn't be too hard.
• Could also combine with ReborrowQueryData in theory, but it might be controversial:

trait EcsBorrow {
    type Item<'w, 's>;
}

trait EcsReborrow {
    pub fn reborrow(...)
}

trait SystemParam: EcsBorrow {}
trait QueryData: EcsBorrow {}

• Add System::scope

Solution

• Add a optional ReborrowSystemParam subtrait, almost identical to ReborrowQueryData

• While most system params should implement this trait, there's a few exceptions like ParamSet types with invariant lifetimes, which we can't shorten AFAICT. Maybe if we changed ParamSet::Item to shorten the inner lifetime as well?

/// A [`SystemParam`] whose lifetime can be shortened via
/// [`reborrow`](ReborrowSystemParam::reborrow)-ing. This should be implemented
/// for most system params, except in the case of non-covariant lifetimes.
pub trait ReborrowSystemParam: SystemParam {
    /// Returns a `SystemParam` item with a smaller lifetime.
    fn reborrow<'wlong: 'short, 'slong: 'short, 'short>(
        item: &'short mut Self::Item<'wlong, 'slong>,
    ) -> Self::Item<'short, 'short>;
}

[chescock]

While most system params should implement this trait, there's a few exceptions like ParamSet types with invariant lifetimes, which we can't shorten AFAICT.

I would have expected ParamSet to be reborrowable. It's invariant in T, but covariant in 'w and 's, right? What kind of error do you get? You'll have to system_meta.clone(), but that's no worse than what get_param already does.

As with QueryData, I'd vote for putting this on the main trait if we can to reduce the total number of traits.

[ecoskey]

I would have expected ParamSet to be reborrowable. It's invariant in T, but covariant in 'w and 's, right? What kind of error do you get? You'll have to system_meta.clone(), but that's no worse than what get_param already does.

It's a pretty rare exception. In custom system params a user could write my_param: ParamSet<'w, 's, Query<'w, 's, ()>> or similar, which makes 'w and 's invariant. It'd documented in an old issue and there's a regression test for it somewhere. We could remove that test and force users to write the inner lifetimes as 'static (I'd prefer that too personally) but might be contentious

[chescock]

It's a pretty rare exception. In custom system params a user could write my_param: ParamSet<'w, 's, Query<'w, 's, ()>> or similar, which makes 'w and 's invariant. It'd documented in an old issue and there's a regression test for it somewhere. We could remove that test and force users to write the inner lifetimes as 'static (I'd prefer that personally too) but might be contentious

Oh, wow, that's subtle! ... Oh, I see, and you have a conditional impl ReborrowSystemParam for ParamSet where the inner parameters are 'static, so a custom system param that does use 'static will still impl ReborrowSystemParam. Nice!

I'd personally still lean towards combining the traits. The cost of requiring 'static instead of 'w there is pretty low, since it's an unusual case and it already requires a named lifetime. So I'd count it as less expensive than having to add a new trait. But I can see the arguments either way, and I'll be happy to approve a PR with this approach (once the blocker PR is merged)!

[ecoskey]

closing these for now, will wrap into a later PR if perf looks good