[Merged by Bors] - Separate Extract from Sub App Schedule

[hymm]

Objective

• This pulls out some of the changes to Plugin setup and sub apps from [Merged by Bors] - Pipelined Rendering #6503 to make that PR easier to review.
• Separate the extract stage from running the sub app's schedule to allow for them to be run on separate threads in the future
• Fixes render app: Added stages get ignored #6990

Solution

• add a run method to SubApp that runs the schedule
• change the name of sub_app_runner to extract to make it clear that this function is only for extracting data between the main app and the sub app
• remove the extract stage from the sub app schedule so it can be run separately. This is done by adding a setup method to the Plugin trait that runs after all plugin build methods run. This is required to allow the extract stage to be removed from the schedule after all the plugins have added their systems to the stage. We will also need the setup method for pipelined rendering to setup the render thread. See

  bevy/crates/bevy_render/src/pipelined_rendering.rs

  Lines 57 to 98 in e326796

  	fn setup(&self, app: &mut App) {
  	// skip setting up when headless
  	if app.get_sub_app(RenderExtractApp).is_err() {
  	return;
  	}
  	let (app_to_render_sender, app_to_render_receiver) = async_channel::bounded::<SubApp>(1);
  	let (render_to_app_sender, render_to_app_receiver) = async_channel::bounded::<SubApp>(1);
  	let mut render_app = app
  	.remove_sub_app(RenderApp)
  	.expect("Unable to get RenderApp. Another plugin may have remove the RenderApp before PipelinedRenderingPlugin");
  	// clone main thread executor to render world
  	let executor = app.world.get_resource::<MainThreadExecutor>().unwrap();
  	render_app.app.world.insert_resource(executor.clone());
  	render_to_app_sender.send_blocking(render_app).unwrap();
  	app.insert_resource(MainToRenderAppSender(app_to_render_sender));
  	app.insert_resource(RenderToMainAppReceiver(render_to_app_receiver));
  	std::thread::spawn(move || {
  	#[cfg(feature = "trace")]
  	let _span = bevy_utils::tracing::info_span!("render thread").entered();
  	loop {
  	// run a scope here to allow main world to use this thread while it's waiting for the render app
  	let mut render_app = ComputeTaskPool::get()
  	.scope(|s| {
  	s.spawn(async { app_to_render_receiver.recv().await.unwrap() });
  	})
  	.pop()
  	.unwrap();
  	#[cfg(feature = "trace")]
  	let _span = bevy_utils::tracing::info_span!("render app").entered();
  	render_app.run();
  	render_to_app_sender.send_blocking(render_app).unwrap();
  	}
  	});
  	}

Changelog

• Separate SubApp Extract stage from running the sub app schedule.

Migration Guide

SubApp runner has conceptually been changed to an extract function.

The runner no longer is in charge of running the sub app schedule. It's only concern is now moving data between the main world and the sub app. The sub_app.app.schedule is now run for you after the provided function is called.

// before
fn main() {
    let sub_app = App::empty();
    sub_app.add_stage(MyStage, SystemStage::parallel());
    
    App::new().add_sub_app(MySubApp, sub_app, move |main_world, sub_app| {
        extract(app_world, render_app);
        render_app.app.schedule.run();
    });
}

// after
fn main() {
        let sub_app = App::empty();
    sub_app.add_stage(MyStage, SystemStage::parallel());
    
    App::new().add_sub_app(MySubApp, sub_app, move |main_world, sub_app| {
        extract(app_world, render_app);
        // schedule is automatically called for you after extract is run
    });
}

[hymm]

It felt like these changes had merit on their own separate from pipelined rendering, so they could be reviewed separately.

[james7132]

LGTM. My only concern is how this will work when stageless lands, but something like a dedicated schedule in Schedules works just fine.

[hymm]

something like a dedicated schedule in Schedules works just fine.

I think that's my current preference. A separate extract schedule should work.

[recatek]

Correct me if I'm wrong, but the switch to having only an extract method removes the authority of the sub app function to decide whether or not to update the sub-app at all, right? Do sub apps have run criteria to fill this gap? If not, could they?

[hymm]

Correct me if I'm wrong, but the switch to having only an extract method removes the authority of the sub app function to decide whether or not to update the sub-app at all, right? Do sub apps have run criteria to fill this gap? If not, could they?

The way I would do this is to conditionally run a schedule from inside an exclusive system. This requires a bit of boilerplate right now, but should be significantly easier once stageless is merged.

I could add support for a runner function that would be default run the schedule, but be replaceable. Though the use case for this is if you can't do what you need with just world and need direct access to the sub app. I thought most use cases for this would be taken care of by the extract function, but if there are other use cases that aren't covered I wouldn't mind adding this.

[recatek]

The lost use case here isn't major, but I think it could be useful. That is, if you only want the SubApp to run sometimes (e.g. on a fixed update), and only want to perform the extract if it has run. You can do that under this setup by adding a resource with a frame counter on the SubApp and skipping the extract if that counter hasn't incremented, so it isn't a big deal, but it might be a nice ergonomics add to add a run criteria to the SubApp that also determines whether extract is called.

In summary:
Run condition on SubApp = Controls schedule and extract call.
Run condition on just SubApp's schedule = Controls schedule only, extract still called each time the parent app loops.

Having that distinction has value IMO.

EDIT: I think I had the ordering backwards here. This only calls extract before the SubApp runs its next loop and is intended to bring data from the main app into the sub app, right? What if we want to do the opposite -- have something called after the SubApp runs in order to get its data populated back into the main app?

[alice-i-cecile]

bors r+

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-and-install-on-iOS
• build-android
• build (macos-latest)
• build (ubuntu-latest)
• build-wasm
• build (windows-latest)
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• check-compiles
• check-doc
• check-missing-examples-in-docs
• ci
• markdownlint
• run-examples
• run-examples-on-wasm
• run-examples-on-windows-dx12