bevy_utils/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![doc(
3    html_logo_url = "https://bevy.org/assets/icon.png",
4    html_favicon_url = "https://bevy.org/assets/icon.png"
5)]
6#![no_std]
7
8//! General utilities for first-party [Bevy] engine crates.
9//!
10//! [Bevy]: https://bevy.org/
11
12/// Configuration information for this crate.
13pub mod cfg {
14    pub(crate) use bevy_platform::cfg::*;
15
16    pub use bevy_platform::cfg::{alloc, std};
17
18    define_alias! {
19        #[cfg(feature = "parallel")] => {
20            /// Indicates the `Parallel` type is available.
21            parallel
22        }
23        #[cfg(feature = "buffered_channel")] => {
24            /// Indicates the `BufferedChannel` type is available.
25            buffered_channel
26        }
27    }
28}
29
30cfg::std! {
31    extern crate std;
32}
33
34cfg::alloc! {
35    extern crate alloc;
36
37    mod map;
38    pub use map::*;
39}
40
41cfg::parallel! {
42    mod parallel_queue;
43    pub use parallel_queue::*;
44}
45
46cfg::buffered_channel! {
47    mod buffered_channel;
48    pub use buffered_channel::*;
49}
50
51/// The utilities prelude.
52///
53/// This includes the most common types in this crate, re-exported for your convenience.
54pub mod prelude {
55    pub use crate::debug_info::DebugName;
56    pub use crate::default;
57    pub use disqualified::ShortName;
58}
59
60mod atomic_id;
61mod bloom_filter;
62pub use bloom_filter::*;
63mod debug_info;
64mod default;
65pub mod memory_size;
66mod once;
67
68#[doc(hidden)]
69pub use once::OnceFlag;
70
71pub use debug_info::DebugName;
72pub use default::default;
73
74use core::mem::ManuallyDrop;
75
76/// A type which calls a function when dropped.
77/// This can be used to ensure that cleanup code is run even in case of a panic.
78///
79/// Note that this only works for panics that [unwind](https://doc.rust-lang.org/nomicon/unwinding.html)
80/// -- any code within `OnDrop` will be skipped if a panic does not unwind.
81/// In most cases, this will just work.
82///
83/// # Examples
84///
85/// ```
86/// # use bevy_utils::OnDrop;
87/// # fn test_panic(do_panic: bool, log: impl FnOnce(&str)) {
88/// // This will print a message when the variable `_catch` gets dropped,
89/// // even if a panic occurs before we reach the end of this scope.
90/// // This is similar to a `try ... catch` block in languages such as C++.
91/// let _catch = OnDrop::new(|| log("Oops, a panic occurred and this function didn't complete!"));
92///
93/// // Some code that may panic...
94/// // ...
95/// # if do_panic { panic!() }
96///
97/// // Make sure the message only gets printed if a panic occurs.
98/// // If we remove this line, then the message will be printed regardless of whether a panic occurs
99/// // -- similar to a `try ... finally` block.
100/// core::mem::forget(_catch);
101/// # }
102/// #
103/// # test_panic(false, |_| unreachable!());
104/// # let mut did_log = false;
105/// # std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
106/// #   test_panic(true, |_| did_log = true);
107/// # }));
108/// # assert!(did_log);
109/// ```
110pub struct OnDrop<F: FnOnce()> {
111    callback: ManuallyDrop<F>,
112}
113
114impl<F: FnOnce()> OnDrop<F> {
115    /// Returns an object that will invoke the specified callback when dropped.
116    pub fn new(callback: F) -> Self {
117        Self {
118            callback: ManuallyDrop::new(callback),
119        }
120    }
121}
122
123impl<F: FnOnce()> Drop for OnDrop<F> {
124    fn drop(&mut self) {
125        #![expect(
126            unsafe_code,
127            reason = "Taking from a ManuallyDrop requires unsafe code."
128        )]
129        // SAFETY: We may move out of `self`, since this instance can never be observed after it's dropped.
130        let callback = unsafe { ManuallyDrop::take(&mut self.callback) };
131        callback();
132    }
133}
bevy_utils/lib.rs

bevy_utils/
lib.rs
