[Merged by Bors] - Make `RunOnce` a non-manual `System` impl #3922

DJMcNab · 2022-02-12T17:36:25Z

Objective

RunOnce was a manual System implementation.
Adding run criteria to stages was yet to be systemyoten

Solution

Make it a normal function
yeet

Changelog

Replaced RunOnce with ShouldRun::once

Migration guide

The run criterion RunOnce, which would make the controlled systems run only once, has been replaced with a new run criterion function ShouldRun::once. Replace all instances of RunOnce with ShouldRun::once.

cart · 2022-04-08T20:40:27Z

I do really like simplifying this impl + the general progression we've had toward consolidating system logic under "system functions". But I'm also not particularly happy with "functions returning closure systems" as our public interface.

I don't think its possible with IntoSystem as it stands (because it requires a "nameable type" to assign the returned system type), but I rather like the idea of:

struct RunOnce;
// maybe IntoSystem could default to () for its generics to enable this
impl IntoSystem for RunOnce {
    // this should work if/when "impl trait in associated types" lands.
    type System = impl System<In = (), Out = RunCriteria>;

    fn into_system(self) -> Self::System {
        let mut ran = false;
        (move || {
            if ran {
                ShouldRun::No
            } else {
                ran = true;
                ShouldRun::Yes
            }
        }).system()
    }
}

This would allow users to transform arbitrary structs (and use their fields) to construct closure function systems. Slightly more boilerplate, but it has the benefit of allowing stuff like:

app
  .add_system(foo.with_run_criteria(FixedTimestep::from_seconds(2.0)))
  .add_system(bar.with_run_criteria(FixedTimestep::from_duration(Duration::from_secs_f64(1.0))))

Compared to stuff like:

app
  .add_system(foo.with_run_criteria(fixed_timestep_from_seconds(2.0)))
  .add_system(bar.with_run_criteria(fixed_timestep_from_duration(Duration::from_secs_f64(1.0))))

The former is much more discoverable, documentable, and "rusty" in my personal opinion.

I'm down to discuss this, but if we agree thats what we should be aiming for ultimately, maybe we should adopt something like this in the interim?

impl RunOnce {
    pub fn new() -> impl FnMut() -> ShouldRun {
        let mut ran = false;
        move || {
            if ran {
                ShouldRun::No
            } else {
                ran = true;
                ShouldRun::Yes
            }
        }
    }
}

Heck, maybe thats better than an IntoSystem impl?

cart · 2022-04-10T19:41:32Z

crates/bevy_ecs/src/schedule/run_criteria.rs

@@ -44,6 +41,17 @@ pub enum ShouldRun {
    NoAndCheckAgain,
 }

+impl ShouldRun {
+    pub fn once(mut ran: Local<bool>) -> ShouldRun {


Ooh this is interesting. One more small consistency thing to discuss api on:

This uses "normal system" add-using-function-name syntax add_system(foo.with_run_criteria(ShouldRun::once)), which has the benefit of being exactly what you would do for a "non-closure system".

However if were were to add a theoretical ShouldRun::n_times, it would need to return a closure to store the value of n.

So we would have the inconsistent styles:

app. .add_system(foo.with_run_criteria(ShouldRun::once)) .add_system(foo.with_run_criteria(ShouldRun::n_times(42))

So the question is: is this ok? (this is not a loaded question ... i dont have strong opinions here). When using the "functions on structs" pattern for systems, what are our "rules"?
Should they be:

When using struct-functions, always use functions returning impl Fn/FnMut for consistency

When using struct-functions, prefer "normal system" style when possible and return impl Fn/FnMut only when required by the context.

When using struct-functions, prefer "normal system" style when possible, but prefer consistency across functions on the struct if there is a mismatch.

Use normal_system when possible. Only use struct-functions for closure-style systems.

~~(3)~~ (4) (edit: accidentally referenced the wrong item here ... see my correction below) loses the organizational benefits of struct style (which would be very confusing), so thats the only option I'm actively against.

Use const generics. ShouldRun::n_times::<{42}>.

I'd generally lean towards option 2. I think we need to do the same migration for FixedTimestep, but I hadn't done it yet because of stageless.

My preference is 4: I think they're clearer in general (especially in the docs), and we should have strong reasons to use struct-functions.

3 is definitely bad.

Arg sorry I inserted an extra list item, invalidating my reference to (3). Sorry for the confusion (bad cart!). I meant to say:

(4) loses the organizational benefits of struct style (which would be very confusing), so thats the only option I'm actively against.

I think this would be actively bad UX:

app .add_system(foo.with_run_criteria(should_run_once) .add_system(foo.with_run_criteria(ShouldRun::n_times(42))

Use const generics. ShouldRun::n_times::<{42}>.

Good point. There are cases where this would significantly increase the amount of internal statefullness / Local hackery required (ex: a timer that ticks down from 42 rather than up from 0 would need to have an init phase enforced with locals). But it would have the benefit of not using function calls, so its worth considering. It feels like there might be cases where closures are still required though (ex: the input is set at runtime).

This discussion shouldn't block this PR landing, right?

I think in a lot of cases, we can avoid having systems being externally configurable. At some point, we'll probably want something Local-like initialised from a const parameter. Not sure if that's possible at the moment.

My preference is option 2. Option 2 keeps the rules for struct scoped systems the same as module scoped systems.
It's worth noting that as far as I know, the _system suffix is idiomatic for functions which return system functions, which applies both when struct scoped and module scoped.

Edit: Change from option 3 to option 2, since I got it wrong.

This discussion shouldn't block this PR landing, right?

Only in that it would be a breaking change to switch from the current style to a "return FnMut for everything on a struct" style. I do think "only use FnMut when you need it" is pretty consistent with what we do today (there is already precedent for the current pattern in bevy).

So yeah Option 2 seems like a reasonable thing to default to. Lets roll with that and we can revisit later if we feel inclined.

Can we make `System` sealed please?

cart · 2022-05-04T18:41:20Z

bors r+

# Objective - `RunOnce` was a manual `System` implementation. - Adding run criteria to stages was yet to be systemyoten ## Solution - Make it a normal function - yeet ## Changelog - Replaced `RunOnce` with `ShouldRun::once` ## Migration guide The run criterion `RunOnce`, which would make the controlled systems run only once, has been replaced with a new run criterion function `ShouldRun::once`. Replace all instances of `RunOnce` with `ShouldRun::once`.

bors · 2022-05-04T18:57:38Z

Pull request successfully merged into main.

Build succeeded:

# Objective - `RunOnce` was a manual `System` implementation. - Adding run criteria to stages was yet to be systemyoten ## Solution - Make it a normal function - yeet ## Changelog - Replaced `RunOnce` with `ShouldRun::once` ## Migration guide The run criterion `RunOnce`, which would make the controlled systems run only once, has been replaced with a new run criterion function `ShouldRun::once`. Replace all instances of `RunOnce` with `ShouldRun::once`.

github-actions bot added the S-Needs-Triage This issue needs to be labelled label Feb 12, 2022

alice-i-cecile approved these changes Feb 12, 2022

View reviewed changes

DJMcNab force-pushed the runonce_and_yeet branch from 356ba65 to edd2c67 Compare February 14, 2022 16:57

alice-i-cecile requested a review from TheRawMeatball February 14, 2022 17:23

TheRawMeatball approved these changes Feb 14, 2022

View reviewed changes

alice-i-cecile added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Feb 14, 2022

DJMcNab added this to the Bevy 0.7 milestone Feb 24, 2022

DJMcNab force-pushed the runonce_and_yeet branch from edd2c67 to 4860cdf Compare April 9, 2022 09:10

DJMcNab requested review from TheRawMeatball and alice-i-cecile April 9, 2022 09:17

DJMcNab removed the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Apr 9, 2022

cart reviewed Apr 10, 2022

View reviewed changes

alice-i-cecile approved these changes Apr 10, 2022

View reviewed changes

DJMcNab added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Apr 10, 2022

DJMcNab added 3 commits April 25, 2022 16:23

Systemyeet in run criteria on stages

74f979b

Make RunOnce not a manual system implementation

cdfb980

Can we make `System` sealed please?

Rename to ShouldRun::once

2f8ae8e

DJMcNab force-pushed the runonce_and_yeet branch from 011331a to 2f8ae8e Compare April 25, 2022 15:23

Add docs

5548e56

alice-i-cecile modified the milestones: Bevy 0.7, Bevy 0.8 Apr 25, 2022

TheRawMeatball approved these changes May 4, 2022

View reviewed changes

bors bot changed the title ~~Make RunOnce a non-manual System impl~~ [Merged by Bors] - Make RunOnce a non-manual System impl May 4, 2022

bors bot closed this May 4, 2022

DJMcNab deleted the runonce_and_yeet branch May 4, 2022 18:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Merged by Bors] - Make `RunOnce` a non-manual `System` impl #3922

[Merged by Bors] - Make `RunOnce` a non-manual `System` impl #3922

DJMcNab commented Feb 12, 2022 •

edited

Loading

cart commented Apr 8, 2022

cart Apr 10, 2022 •

edited

Loading

DJMcNab Apr 10, 2022

alice-i-cecile Apr 10, 2022

cart Apr 10, 2022

cart Apr 10, 2022

cart Apr 10, 2022

DJMcNab Apr 10, 2022 •

edited

Loading

cart May 4, 2022

cart commented May 4, 2022

bors bot commented May 4, 2022

[Merged by Bors] - Make RunOnce a non-manual System impl #3922

[Merged by Bors] - Make RunOnce a non-manual System impl #3922

Conversation

DJMcNab commented Feb 12, 2022 • edited Loading

Objective

Solution

Changelog

Migration guide

cart commented Apr 8, 2022

cart Apr 10, 2022 • edited Loading

Choose a reason for hiding this comment

DJMcNab Apr 10, 2022

Choose a reason for hiding this comment

alice-i-cecile Apr 10, 2022

Choose a reason for hiding this comment

cart Apr 10, 2022

Choose a reason for hiding this comment

cart Apr 10, 2022

Choose a reason for hiding this comment

cart Apr 10, 2022

Choose a reason for hiding this comment

DJMcNab Apr 10, 2022 • edited Loading

Choose a reason for hiding this comment

cart May 4, 2022

Choose a reason for hiding this comment

cart commented May 4, 2022

bors bot commented May 4, 2022

[Merged by Bors] - Make `RunOnce` a non-manual `System` impl #3922

[Merged by Bors] - Make `RunOnce` a non-manual `System` impl #3922

DJMcNab commented Feb 12, 2022 •

edited

Loading

cart Apr 10, 2022 •

edited

Loading

DJMcNab Apr 10, 2022 •

edited

Loading