Add system.map(...) for transforming the output of a system

[JoJoJet]

Objective

Any time we wish to transform the output of a system, we currently use system piping to do so:

my_system.pipe(|In(x)| do_something(x))

Unfortunately, system piping is not a zero cost abstraction. Each call to .pipe requires allocating two extra access sets: one for the second system and one for the combined accesses of both systems. This also adds extra work to each call to update_archetype_component_access, which stacks as one adds multiple layers of system piping.

Solution

Add the AdapterSystem abstraction: similar to CombinatorSystem, this allows you to implement a trait to generically control how a system is run and how its inputs and outputs are processed. Unlike CombinatorSystem, this does not have any overhead when computing world accesses which makes it ideal for simple operations such as inverting or ignoring the output of a system.

Add the extension method .map(...): this is similar to .pipe(...), only it accepts a closure as an argument instead of an In<T> system.

my_system.map(do_something)

This has the added benefit of making system names less messy: a system that ignores its output will just be called my_system, instead of Pipe(my_system, ignore)

---

Changelog

TODO

Migration Guide

The system_adapter functions have been deprecated: use .map instead, which is a lightweight alternative to .pipe.

// Before:
my_system.pipe(system_adapter::ignore)
my_system.pipe(system_adapter::unwrap)
my_system.pipe(system_adapter::new(T::from))

// After:
my_system.map(std::mem::drop)
my_system.map(Result::unwrap)
my_system.map(T::from)

// Before:
my_system.pipe(system_adapter::info)
my_system.pipe(system_adapter::dbg)
my_system.pipe(system_adapter::warn)
my_system.pipe(system_adapter::error)

// After:
my_system.map(bevy_utils::info)
my_system.map(bevy_utils::dbg)
my_system.map(bevy_utils::warn)
my_system.map(bevy_utils::error)

[alice-i-cecile]

Clever: I like being able to deprecate these.

[cart]

Seems like a good complement to pipe. Simpler interface (avoids In<T>). .map is a common rust convention. Saves on some expenses.

I think in a world where we find a way to remove In<T> (in favor of just T) I might advocate for removing map, as I'm not sure avoiding the startup allocations for name() is worth "duplicate" abstractions. We could probably make name lazily computed if that is a concern as most games won't even need system names at runtime.

[JoJoJet]

I've fixed the type_id method, and I added an API that lets system adapters change the system name. Now, calling not(resource_exists<T>) will correctly result in a system called !resource_exists<T>.
Using .map() will not change the name of the inner system -- IMO this is cleaner, but I'm willing to change it if you guys think it's important for the system name to include the mapping function.

Also, I'm going to temporarily mark this as a draft. I want to see if I can make this abstraction usable for #8705 -- this will require giving the system adapter access to the system's name, but I don't have time to experiment with that at the moment.

[JoJoJet]

Alright, I've simplified the API for system names which will make it easier to use this in the aforementioned PR (and makes it consistent with CombinatorSystem.

I believe I have addressed all of the concerns raised :).

[ItsDoot]

What's the status on this PR? Interesting in using .map.

[TimJentzsch]

Is it intentional that the changelog is still "TODO"?

[JoJoJet]

I don't think we still do changelogs. Not sure why it's still in the PR template.

[cart]

We do still do changelogs, we just lean on auto-generation more. Including changelogs in PRs is still welcome and encouraged as it will make the auto-generated changelog better.