Tracked one-shot systems by ItsDoot · Pull Request #24165 · bevyengine/bevy

ItsDoot · 2026-05-07T03:04:34Z

Objective

#24087 introduces scene templating for SystemIds, however it can result in a memory leak if a scene is re-constructed multiple times:

#24087 (comment)

This was proposed basically 1:1 in #24026 (this was later changed though). The issue is that it's unclear who owns these systems, that is who is responsible for unregistering them once they are no longer needed. Given that recreating the template will spawn the system again this basically becomes a memory leak.

#24087 (comment)

Hm, are you sure this is the case even tho in build_template it only registers the system the first time its called, switching over to storing the SystemId after the first call?

If you recreate the template (e.g. you call my_scene() again) then you will create a new instance of the system. And since the system is not scoped to the scene once the scene is despawned the system entity will be leaked.

Essentially, we need a way to connect the lifetime of the registered system to the lifetime of the scene.

Solution

This is a purely additive / opt-in / backwards-compatible version of #24114

Introducing: SystemHandles

pub enum SystemHandle<I: SystemInput = (), O = ()> {
    /// A strong handle keeps the system entity alive as long as the handle
    /// (and any clones of it) exist.
    Strong(Arc<StrongSystemHandle>),
    /// A weak handle does not keep the system entity alive.
    Weak(SystemId<I, O>),
}

pub struct StrongSystemHandle {
    entity: Entity,
    drop_queue: Arc<ConcurrentQueue<<Entity>>,
}

Similar to bevy_asset::Handles,SystemHandle's custom Drop implementation enqueues the registered system entity into a concurrent queue. The system despawn_unused_registered_systems pulls from the other end of this queue and despawns the registered system entities.

World::register_tracked_system and World::register_tracked_boxed_system are the only functions that return SystemHandles.

Testing

Added a test to ensure that despawn_unused_registered_systems does its job
Added a test to ensure that the default app will automatically call despawn_unused_registered_systems

Future work

SystemId scene templating #24087 will use this PR as a base

chescock

Looks good! I left some comments, but they're just style nits.

chescock · 2026-05-07T15:13:05Z

        I: SystemInput + 'static,
        O: 'static,
    {
+        let id = id.into();


Do we need to worry about this monomorphizing two versions of this function?

Maybe! Would be good to check how much of a difference the codegen is

Co-authored-by: Chris Russell <8494645+chescock@users.noreply.github.com>

bytemuck · 2026-05-17T02:32:34Z

+}
+
+// A manual impl is used because the trait bounds should ignore the `I` and `O` phantom parameters,
+// and so that the handle can be hashed based on its entity not its handle type.


Is there a typo? (maybe there is not, english is my second language)
// and so that the handle can be hashed based on its entity {instead of, and not} its handle type

it would work with a "," before "not"

hxYuki · 2026-06-02T04:28:09Z

    }

+    /// Registers a system and returns a tracked [`SystemHandle`] so it can later
+    /// be called by [`World::run_system`]. The system entity will be automatically


I didn't see a conversion defined for from SystemHandle into SystemId. Maybe From<&SystemHandle> is needed, too.

And I think Command::run_system* should also accept a SystemHandle.

# Objective - The `SystemHandle` was introduced in bevyengine#24165. But it didn't come with full `run_system` support. ## Solution - Implement `From<SystemHandle<I, O>>` and `From<&SystemHandle<I, O>>` for `SystemId<I, O>` to make it available for `run_system`. Using `SystemHandle::entity()` and `SystemId::from_entity()`. - Let `Commands::run_system*` and `commands::command::run_system*` to accept `impl Into<SystemId>` ## Testing - Add a test `system::system_registry::tests::run_system_with_owned_system_handle`, to run a `SystemHandle`. --- ## Showcase ```rust world.run_system(handle) // or borrowing from a reference world.run_system(&handle) ```

# Objective #24087 introduces scene templating for `SystemId`s, however it can result in a memory leak if a scene is re-constructed multiple times: #24087 (comment) > This was proposed basically 1:1 in #24026 (this was later changed though). The issue is that it's unclear who owns these systems, that is who is responsible for unregistering them once they are no longer needed. Given that recreating the template will spawn the system again this basically becomes a memory leak. #24087 (comment) > > Hm, are you sure this is the case even tho in `build_template` it only registers the system the first time its called, switching over to storing the SystemId after the first call? > > If you recreate the template (e.g. you call `my_scene()` again) then you will create a new instance of the system. And since the system is not scoped to the scene once the scene is despawned the system entity will be leaked. Essentially, we need a way to connect the lifetime of the registered system to the lifetime of the scene. ## Solution This is a purely additive / opt-in / backwards-compatible version of #24114 Introducing: `SystemHandle`s ```rust pub enum SystemHandle<I: SystemInput = (), O = ()> { /// A strong handle keeps the system entity alive as long as the handle /// (and any clones of it) exist. Strong(Arc<StrongSystemHandle>), /// A weak handle does not keep the system entity alive. Weak(SystemId<I, O>), } pub struct StrongSystemHandle { entity: Entity, drop_queue: Arc<ConcurrentQueue<<Entity>>, } ``` Similar to `bevy_asset::Handle`s,`SystemHandle`'s custom `Drop` implementation enqueues the registered system entity into a concurrent queue. The system `despawn_unused_registered_systems` pulls from the other end of this queue and despawns the registered system entities. `World::register_tracked_system` and `World::register_tracked_boxed_system` are the only functions that return `SystemHandle`s. ## Testing - Added a test to ensure that `despawn_unused_registered_systems` does its job - Added a test to ensure that the default app will automatically call `despawn_unused_registered_systems` ## Future work - #24087 will use this PR as a base --------- Co-authored-by: Chris Russell <8494645+chescock@users.noreply.github.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>

# Objective - The `SystemHandle` was introduced in #24165. But it didn't come with full `run_system` support. ## Solution - Implement `From<SystemHandle<I, O>>` and `From<&SystemHandle<I, O>>` for `SystemId<I, O>` to make it available for `run_system`. Using `SystemHandle::entity()` and `SystemId::from_entity()`. - Let `Commands::run_system*` and `commands::command::run_system*` to accept `impl Into<SystemId>` ## Testing - Add a test `system::system_registry::tests::run_system_with_owned_system_handle`, to run a `SystemHandle`. --- ## Showcase ```rust world.run_system(handle) // or borrowing from a reference world.run_system(&handle) ```

Tracked one-shot systems

2074dc8

ItsDoot mentioned this pull request May 7, 2026

Automatic cleanup of one-shot systems #24114

Closed

github-project-automation Bot added this to ECS May 7, 2026

github-project-automation Bot moved this to Needs SME Triage in ECS May 7, 2026

ItsDoot requested a review from chescock May 7, 2026 03:41

chescock approved these changes May 7, 2026

View reviewed changes

ItsDoot and others added 3 commits May 9, 2026 02:15

address feedback

edb93fa

Apply suggestions from code review

7144d67

Co-authored-by: Chris Russell <8494645+chescock@users.noreply.github.com>

cargo fmt

d666be0

chescock approved these changes May 9, 2026

View reviewed changes

Comment thread crates/bevy_ecs/src/system/system_registry.rs Outdated

Update crates/bevy_ecs/src/system/system_registry.rs

0f050c7

Co-authored-by: Chris Russell <8494645+chescock@users.noreply.github.com>

cookie1170 approved these changes May 17, 2026

View reviewed changes

bytemuck approved these changes May 17, 2026

View reviewed changes

ItsDoot added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels May 17, 2026

mockersf approved these changes May 22, 2026

View reviewed changes

mockersf added this pull request to the merge queue May 22, 2026

mockersf removed this pull request from the merge queue due to a manual request May 22, 2026

mockersf reviewed May 22, 2026

View reviewed changes

Comment thread crates/bevy_ecs/src/system/system_registry.rs Outdated

Apply suggestion from @mockersf

e1dc7c4

mockersf enabled auto-merge May 22, 2026 10:40

mockersf added this pull request to the merge queue May 22, 2026

Merged via the queue into bevyengine:main with commit b5f5a42 May 22, 2026
38 checks passed

github-project-automation Bot moved this from Needs SME Triage to Done in ECS May 22, 2026

alice-i-cecile added this to the 0.19 milestone Jun 1, 2026

hxYuki reviewed Jun 2, 2026

View reviewed changes

hxYuki mentioned this pull request Jun 4, 2026

add missing run support for SystemHandle #24527

Merged

Navigation Menu

Uh oh!

Uh oh!

Tracked one-shot systems - #24165

Tracked one-shot systems#24165
mockersf merged 6 commits into
bevyengine:mainfrom
ItsDoot:ecs/optinoneshothandle

ItsDoot commented May 7, 2026 •

edited

Loading

Uh oh!

chescock left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chescock May 7, 2026

Uh oh!

ItsDoot May 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bytemuck May 17, 2026

Uh oh!

mockersf May 22, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hxYuki Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Uh oh!

Uh oh!

Conversation

ItsDoot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Testing

Future work

Uh oh!

chescock left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chescock May 7, 2026

Choose a reason for hiding this comment

Uh oh!

ItsDoot May 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bytemuck May 17, 2026

Choose a reason for hiding this comment

Uh oh!

mockersf May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hxYuki Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

ItsDoot commented May 7, 2026 •

edited

Loading

mockersf May 22, 2026 •

edited

Loading