forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Small Commands error handling cleanup (#17904)

Browse Source 
- Remove references to the short-lived `CommandError` type.
- Add a sentence to the explanation of error handlers.
- Clean up spacing/linebreaks.
- Use `where` notation for command-related trait `impl`s to make the big
ones easier to parse.
This commit is contained in:
JaySpruce 2025-02-23 16:41:43 -06:00 committed by GitHub
parent 726d8ac4b0
commit 283654cf4d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 57 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
crates/bevy_ecs/src/system/commands/command.rs
View File

@ -79,7 +79,11 @@ pub trait HandleError<Out = ()> {
}
}
impl<C: Command<Result<T, E>>, T, E: Into<Error>> HandleError<Result<T, E>> for C {
impl<C, T, E> HandleError<Result<T, E>> for C
where
C: Command<Result<T, E>>,
E: Into<Error>,
{
fn handle_error_with(self, error_handler: fn(&mut World, Error)) -> impl Command {
move |world: &mut World| match self.apply(world) {
Ok(_) => {}
@ -88,7 +92,10 @@ impl<C: Command<Result<T, E>>, T, E: Into<Error>> HandleError<Result<T, E>> for
}
}
impl<C: Command> HandleError for C {
impl<C> HandleError for C
where
C: Command,
{
#[inline]
fn handle_error_with(self, _error_handler: fn(&mut World, Error)) -> impl Command {
self

23
crates/bevy_ecs/src/system/commands/entity_command.rs
View File

@ -5,6 +5,7 @@
//! [`EntityCommands`](crate::system::EntityCommands).
use alloc::vec::Vec;
use core::fmt;
use log::info;
use crate::{
@ -79,8 +80,7 @@ use bevy_ptr::OwningPtr;
/// }
/// ```
pub trait EntityCommand<Out = ()>: Send + 'static {
/// Executes this command for the given [`Entity`] and
/// returns a [`Result`] for error handling.
/// Executes this command for the given [`Entity`].
fn apply(self, entity: EntityWorldMut) -> Out;
}
/// Passes in a specific entity to an [`EntityCommand`], resulting in a [`Command`] that
@ -96,7 +96,10 @@ pub trait CommandWithEntity<Out> {
fn with_entity(self, entity: Entity) -> impl Command<Out> + HandleError<Out>;
}
impl<C: EntityCommand> CommandWithEntity<Result<(), EntityMutableFetchError>> for C {
impl<C> CommandWithEntity<Result<(), EntityMutableFetchError>> for C
where
C: EntityCommand,
{
fn with_entity(
self,
entity: Entity,
@ -110,11 +113,10 @@ impl<C: EntityCommand> CommandWithEntity<Result<(), EntityMutableFetchError>> fo
}
}
impl<
C: EntityCommand<Result<T, Err>>,
T,
Err: core::fmt::Debug + core::fmt::Display + Send + Sync + 'static,
> CommandWithEntity<Result<T, EntityCommandError<Err>>> for C
impl<C, T, Err> CommandWithEntity<Result<T, EntityCommandError<Err>>> for C
where
C: EntityCommand<Result<T, Err>>,
Err: fmt::Debug + fmt::Display + Send + Sync + 'static,
{
fn with_entity(
self,
@ -245,8 +247,9 @@ pub fn retain<T: Bundle>() -> impl EntityCommand {
///
/// # Note
///
/// This will also despawn any [`Children`](crate::hierarchy::Children) entities, and any other [`RelationshipTarget`](crate::relationship::RelationshipTarget) that is configured
/// to despawn descendants. This results in "recursive despawn" behavior.
/// This will also despawn any [`Children`](crate::hierarchy::Children) entities,
/// and any other [`RelationshipTarget`](crate::relationship::RelationshipTarget) that is configured to despawn descendants.
/// This results in "recursive despawn" behavior.
#[track_caller]
pub fn despawn() -> impl EntityCommand {
let caller = MaybeLocation::caller();

53
crates/bevy_ecs/src/system/commands/mod.rs
View File

@ -89,14 +89,19 @@ use crate::{
///
/// # Error handling
///
/// Commands can return a [`Result`](crate::result::Result), which can be passed to
/// an error handler. Error handlers are functions/closures of the form
/// `fn(&mut World, CommandError)`.
/// A [`Command`] can return a [`Result`](crate::result::Result),
/// which will be passed to an error handler if the `Result` is an error.
///
/// The default error handler panics. It can be configured by enabling the `configurable_error_handler`
/// cargo feature, then setting the `GLOBAL_ERROR_HANDLER`.
/// Error handlers are functions/closures of the form `fn(&mut World, Error)`.
/// They are granted exclusive access to the [`World`], which enables them to
/// respond to the error in whatever way is necessary.
///
/// Alternatively, you can customize the error handler for a specific command by calling [`Commands::queue_handled`].
/// The [default error handler](error_handler::default) panics.
/// It can be configured by enabling the `configurable_error_handler` cargo feature,
/// then setting the `GLOBAL_ERROR_HANDLER`.
///
/// Alternatively, you can customize the error handler for a specific command
/// by calling [`Commands::queue_handled`].
///
/// The [`error_handler`] module provides some simple error handlers for convenience.
///
@ -546,7 +551,8 @@ impl<'w, 's> Commands<'w, 's> {
/// Pushes a generic [`Command`] to the command queue.
///
/// If the [`Command`] returns a [`Result`], it will be handled using the [default error handler](error_handler::default).
/// If the [`Command`] returns a [`Result`],
/// it will be handled using the [default error handler](error_handler::default).
///
/// To use a custom error handler, see [`Commands::queue_handled`].
///
@ -589,8 +595,11 @@ impl<'w, 's> Commands<'w, 's> {
pub fn queue<C: Command<T> + HandleError<T>, T>(&mut self, command: C) {
self.queue_internal(command.handle_error());
}
/// Pushes a generic [`Command`] to the command queue. If the command returns a [`Result`] the given
/// `error_handler` will be used to handle error cases.
/// Pushes a generic [`Command`] to the command queue.
///
/// If the [`Command`] returns a [`Result`],
/// the given `error_handler` will be used to handle error cases.
///
/// To implicitly use the default error handler, see [`Commands::queue`].
///
@ -1137,7 +1146,7 @@ impl<'w, 's> Commands<'w, 's> {
/// Most [`Commands`] (and thereby [`EntityCommands`]) are deferred: when you call the command,
/// if it requires mutable access to the [`World`] (that is, if it removes, adds, or changes something),
/// it's not executed immediately. Instead, the command is added to a "command queue."
/// The command queue is applied between [`Schedules`](bevy_ecs::schedule::Schedule), one by one,
/// The command queue is applied between [`Schedules`](crate::schedule::Schedule), one by one,
/// so that each command can have exclusive access to the World.
///
/// # Fallible
@ -1148,14 +1157,19 @@ impl<'w, 's> Commands<'w, 's> {
///
/// # Error handling
///
/// [`EntityCommands`] can return a [`Result`](crate::result::Result), which can be passed to
/// an error handler. Error handlers are functions/closures of the form
/// `fn(&mut World, CommandError)`.
/// An [`EntityCommand`] can return a [`Result`](crate::result::Result),
/// which will be passed to an error handler if the `Result` is an error.
///
/// The default error handler panics. It can be configured by enabling the `configurable_error_handler`
/// cargo feature, then setting the `GLOBAL_ERROR_HANDLER`.
/// Error handlers are functions/closures of the form `fn(&mut World, Error)`.
/// They are granted exclusive access to the [`World`], which enables them to
/// respond to the error in whatever way is necessary.
///
/// Alternatively, you can customize the error handler for a specific command by calling [`EntityCommands::queue_handled`].
/// The [default error handler](error_handler::default) panics.
/// It can be configured by enabling the `configurable_error_handler` cargo feature,
/// then setting the `GLOBAL_ERROR_HANDLER`.
///
/// Alternatively, you can customize the error handler for a specific command
/// by calling [`EntityCommands::queue_handled`].
///
/// The [`error_handler`] module provides some simple error handlers for convenience.
pub struct EntityCommands<'a> {
@ -1754,7 +1768,8 @@ impl<'a> EntityCommands<'a> {
/// Pushes an [`EntityCommand`] to the queue, which will get executed for the current [`Entity`].
///
/// If the [`EntityCommand`] returns a [`Result`], it will be handled using the [default error handler](error_handler::default).
/// If the [`EntityCommand`] returns a [`Result`],
/// it will be handled using the [default error handler](error_handler::default).
///
/// To use a custom error handler, see [`EntityCommands::queue_handled`].
///
@ -1788,7 +1803,9 @@ impl<'a> EntityCommands<'a> {
}
/// Pushes an [`EntityCommand`] to the queue, which will get executed for the current [`Entity`].
/// If the command returns a [`Result`] the given `error_handler` will be used to handle error cases.
///
/// If the [`EntityCommand`] returns a [`Result`],
/// the given `error_handler` will be used to handle error cases.
///
/// To implicitly use the default error handler, see [`EntityCommands::queue`].
///