d4985af7cb
# Objective - move SyncCell and SyncUnsafeCell to bevy_platform ## Solution - move SyncCell and SyncUnsafeCell to bevy_platform ## Testing - cargo clippy works
76 lines
2.5 KiB
Rust
76 lines
2.5 KiB
Rust
//! Resources are unique, singleton-like data types that can be accessed from systems and stored in the [`World`](crate::world::World).
|
|
|
|
// The derive macro for the `Resource` trait
|
|
pub use bevy_ecs_macros::Resource;
|
|
|
|
/// A type that can be inserted into a [`World`] as a singleton.
|
|
///
|
|
/// You can access resource data in systems using the [`Res`] and [`ResMut`] system parameters
|
|
///
|
|
/// Only one resource of each type can be stored in a [`World`] at any given time.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// # let mut world = World::default();
|
|
/// # let mut schedule = Schedule::default();
|
|
/// # use bevy_ecs::prelude::*;
|
|
/// #[derive(Resource)]
|
|
/// struct MyResource { value: u32 }
|
|
///
|
|
/// world.insert_resource(MyResource { value: 42 });
|
|
///
|
|
/// fn read_resource_system(resource: Res<MyResource>) {
|
|
/// assert_eq!(resource.value, 42);
|
|
/// }
|
|
///
|
|
/// fn write_resource_system(mut resource: ResMut<MyResource>) {
|
|
/// assert_eq!(resource.value, 42);
|
|
/// resource.value = 0;
|
|
/// assert_eq!(resource.value, 0);
|
|
/// }
|
|
/// # schedule.add_systems((read_resource_system, write_resource_system).chain());
|
|
/// # schedule.run(&mut world);
|
|
/// ```
|
|
///
|
|
/// # `!Sync` Resources
|
|
/// A `!Sync` type cannot implement `Resource`. However, it is possible to wrap a `Send` but not `Sync`
|
|
/// type in [`SyncCell`] or the currently unstable [`Exclusive`] to make it `Sync`. This forces only
|
|
/// having mutable access (`&mut T` only, never `&T`), but makes it safe to reference across multiple
|
|
/// threads.
|
|
///
|
|
/// This will fail to compile since `RefCell` is `!Sync`.
|
|
/// ```compile_fail
|
|
/// # use std::cell::RefCell;
|
|
/// # use bevy_ecs::resource::Resource;
|
|
///
|
|
/// #[derive(Resource)]
|
|
/// struct NotSync {
|
|
/// counter: RefCell<usize>,
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// This will compile since the `RefCell` is wrapped with `SyncCell`.
|
|
/// ```
|
|
/// # use std::cell::RefCell;
|
|
/// # use bevy_ecs::resource::Resource;
|
|
/// use bevy_platform::cell::SyncCell;
|
|
///
|
|
/// #[derive(Resource)]
|
|
/// struct ActuallySync {
|
|
/// counter: SyncCell<RefCell<usize>>,
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// [`Exclusive`]: https://doc.rust-lang.org/nightly/std/sync/struct.Exclusive.html
|
|
/// [`World`]: crate::world::World
|
|
/// [`Res`]: crate::system::Res
|
|
/// [`ResMut`]: crate::system::ResMut
|
|
/// [`SyncCell`]: bevy_platform::cell::SyncCell
|
|
#[diagnostic::on_unimplemented(
|
|
message = "`{Self}` is not a `Resource`",
|
|
label = "invalid `Resource`",
|
|
note = "consider annotating `{Self}` with `#[derive(Resource)]`"
|
|
)]
|
|
pub trait Resource: Send + Sync + 'static {}
|