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