Struct valence::ecs::world::unsafe_world_cell::UnsafeWorldCell

pub struct UnsafeWorldCell<'w>(/* private fields */);

Variant of the World where resource and component accesses take &self, and the responsibility to avoid aliasing violations are given to the caller instead of being checked at compile-time by rust’s unique XOR shared rule.

Rationale

In rust, having a &mut World means that there are absolutely no other references to the safe world alive at the same time, without exceptions. Not even unsafe code can change this.

But there are situations where careful shared mutable access through a type is possible and safe. For this, rust provides the UnsafeCell escape hatch, which allows you to get a *mut T from a &UnsafeCell<T> and around which safe abstractions can be built.

Access to resources and components can be done uniquely using World::resource_mut and World::entity_mut, and shared using World::resource and World::entity. These methods use lifetimes to check at compile time that no aliasing rules are being broken.

This alone is not enough to implement bevy systems where multiple systems can access disjoint parts of the world concurrently. For this, bevy stores all values of resources and components (and ComponentTicks) in UnsafeCells, and carefully validates disjoint access patterns using APIs like System::component_access.

A system then can be executed using System::run_unsafe with a &World and use methods with interior mutability to access resource values.

Example Usage

UnsafeWorldCell can be used as a building block for writing APIs that safely allow disjoint access into the world. In the following example, the world is split into a resource access half and a component access half, where each one can safely hand out mutable references.

use bevy_ecs::world::World;
use bevy_ecs::change_detection::Mut;
use bevy_ecs::system::Resource;
use bevy_ecs::world::unsafe_world_cell::UnsafeWorldCell;

// INVARIANT: existence of this struct means that users of it are the only ones being able to access resources in the world
struct OnlyResourceAccessWorld<'w>(UnsafeWorldCell<'w>);
// INVARIANT: existence of this struct means that users of it are the only ones being able to access components in the world
struct OnlyComponentAccessWorld<'w>(UnsafeWorldCell<'w>);

impl<'w> OnlyResourceAccessWorld<'w> {
    fn get_resource_mut<T: Resource>(&mut self) -> Option<Mut<'_, T>> {
        // SAFETY: resource access is allowed through this UnsafeWorldCell
        unsafe { self.0.get_resource_mut::<T>() }
    }
}
// impl<'w> OnlyComponentAccessWorld<'w> {
//     ...
// }

// the two `UnsafeWorldCell`s borrow from the `&mut World`, so it cannot be accessed while they are live
fn split_world_access(world: &mut World) -> (OnlyResourceAccessWorld<'_>, OnlyComponentAccessWorld<'_>) {
    let unsafe_world_cell = world.as_unsafe_world_cell();
    let resource_access = OnlyResourceAccessWorld(unsafe_world_cell);
    let component_access = OnlyComponentAccessWorld(unsafe_world_cell);
    (resource_access, component_access)
}

Implementations

impl<'w> UnsafeWorldCell<'w>

pub unsafe fn into_deferred(self) -> DeferredWorld<'w>

Turn self into a DeferredWorld

Safety

Caller must ensure there are no outstanding mutable references to world and no outstanding references to the world’s command queue, resource or component data

impl<'w> UnsafeWorldCell<'w>

pub unsafe fn world_mut(self) -> &'w mut World

Gets a mutable reference to the World this UnsafeWorldCell belongs to. This is an incredibly error-prone operation and is only valid in a small number of circumstances.

Safety

• self must have been obtained from a call to World::as_unsafe_world_cell (not as_unsafe_world_cell_readonly or any other method of construction that does not provide mutable access to the entire world).
  • This means that if you have an UnsafeWorldCell that you didn’t create yourself, it is likely unsound to call this method.
• The returned &mut World must be unique: it must never be allowed to exist at the same time as any other borrows of the world or any accesses to its data. This includes safe ways of accessing world data, such as UnsafeWorldCell::archetypes.
  • Note that the &mut World may exist at the same time as instances of UnsafeWorldCell, so long as none of those instances are used to access world data in any way while the mutable borrow is active.

// Make an UnsafeWorldCell.
let world_cell = world.as_unsafe_world_cell();

// SAFETY: `world_cell` was originally created from `&mut World`.
// We must be sure not to access any world data while `world_mut` is active.
let world_mut = unsafe { world_cell.world_mut() };

// We can still use `world_cell` so long as we don't access the world with it.
store_but_dont_use(world_cell);

// !!This is unsound!! Even though this method is safe, we cannot call it until
// `world_mut` is no longer active.
let tick = world_cell.change_tick();

// Use mutable access to spawn an entity.
world_mut.spawn(Player);

// Since we never use `world_mut` after this, the borrow is released
// and we are once again allowed to access the world using `world_cell`.
let archetypes = world_cell.archetypes();

pub unsafe fn world(self) -> &'w World

Gets a reference to the &World this UnsafeWorldCell belongs to. This can be used for arbitrary shared/readonly access.

Safety

• must have permission to access the whole world immutably
• there must be no live exclusive borrows on world data
• there must be no live exclusive borrow of world

pub unsafe fn world_metadata(self) -> &'w World

Gets a reference to the World this UnsafeWorldCell belong to. This can be used for arbitrary read only access of world metadata

You should attempt to use various safe methods on UnsafeWorldCell for metadata access before using this method.

Safety

• must only be used to access world metadata

pub fn id(self) -> WorldId

Retrieves this world’s unique ID.

pub fn entities(self) -> &'w Entities

Retrieves this world’s Entities collection.

pub fn archetypes(self) -> &'w Archetypes

Retrieves this world’s Archetypes collection.

pub fn components(self) -> &'w Components

Retrieves this world’s Components collection.

pub fn removed_components(self) -> &'w RemovedComponentEvents

Retrieves this world’s collection of removed components.

pub fn bundles(self) -> &'w Bundles

Retrieves this world’s Bundles collection.

pub fn change_tick(self) -> Tick

Gets the current change tick of this world.

pub fn last_change_tick(self) -> Tick

Returns the Tick indicating the last time that World::clear_trackers was called.

If this UnsafeWorldCell was created from inside of an exclusive system (a System that takes &mut World as its first parameter), this will instead return the Tick indicating the last time the system was run.

See World::last_change_tick().

pub fn increment_change_tick(self) -> Tick

Increments the world’s current change tick and returns the old value.

pub unsafe fn storages(self) -> &'w Storages

Provides unchecked access to the internal data stores of the World.

Safety

The caller must ensure that this is only used to access world data that this UnsafeWorldCell is allowed to. As always, any mutable access to a component must not exist at the same time as any other accesses to that same component.

pub fn get_entity(self, entity: Entity) -> Option<UnsafeEntityCell<'w>>

Retrieves an UnsafeEntityCell that exposes read and write operations for the given entity. Similar to the UnsafeWorldCell, you are in charge of making sure that no aliasing rules are violated.

pub unsafe fn get_resource<R>(self) -> Option<&'w R>

where R: Resource,

Gets a reference to the resource of the given type if it exists

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource
• no mutable reference to the resource exists at the same time

pub unsafe fn get_resource_ref<R>(self) -> Option<Res<'w, R>>

where R: Resource,

Gets a reference including change detection to the resource of the given type if it exists.

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource
• no mutable reference to the resource exists at the same time

pub unsafe fn get_resource_by_id( self, component_id: ComponentId, ) -> Option<Ptr<'w>>

Gets a pointer to the resource with the id ComponentId if it exists. The returned pointer must not be used to modify the resource, and must not be dereferenced after the borrow of the World ends.

You should prefer to use the typed API UnsafeWorldCell::get_resource where possible and only use this in cases where the actual types are not known at compile time.

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource
• no mutable reference to the resource exists at the same time

pub unsafe fn get_non_send_resource<R>(self) -> Option<&'w R>

where R: 'static,

Gets a reference to the non-send resource of the given type if it exists

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource
• no mutable reference to the resource exists at the same time

pub unsafe fn get_non_send_resource_by_id( self, component_id: ComponentId, ) -> Option<Ptr<'w>>

Gets a !Send resource to the resource with the id ComponentId if it exists. The returned pointer must not be used to modify the resource, and must not be dereferenced after the immutable borrow of the World ends.

You should prefer to use the typed API UnsafeWorldCell::get_non_send_resource where possible and only use this in cases where the actual types are not known at compile time.

Panics

This function will panic if it isn’t called from the same thread that the resource was inserted from.

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource
• no mutable reference to the resource exists at the same time

pub unsafe fn get_resource_mut<R>(self) -> Option<Mut<'w, R>>

where R: Resource,

Gets a mutable reference to the resource of the given type if it exists

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource mutably
• no other references to the resource exist at the same time

pub unsafe fn get_resource_mut_by_id( self, component_id: ComponentId, ) -> Option<MutUntyped<'w>>

Gets a pointer to the resource with the id ComponentId if it exists. The returned pointer may be used to modify the resource, as long as the mutable borrow of the UnsafeWorldCell is still valid.

You should prefer to use the typed API UnsafeWorldCell::get_resource_mut where possible and only use this in cases where the actual types are not known at compile time.

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource mutably
• no other references to the resource exist at the same time

pub unsafe fn get_non_send_resource_mut<R>(self) -> Option<Mut<'w, R>>

where R: 'static,

Gets a mutable reference to the non-send resource of the given type if it exists

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource mutably
• no other references to the resource exist at the same time

pub unsafe fn get_non_send_resource_mut_by_id( self, component_id: ComponentId, ) -> Option<MutUntyped<'w>>

Gets a !Send resource to the resource with the id ComponentId if it exists. The returned pointer may be used to modify the resource, as long as the mutable borrow of the World is still valid.

You should prefer to use the typed API UnsafeWorldCell::get_non_send_resource_mut where possible and only use this in cases where the actual types are not known at compile time.

Panics

This function will panic if it isn’t called from the same thread that the resource was inserted from.

Safety

It is the callers responsibility to ensure that

• the UnsafeWorldCell has permission to access the resource mutably
• no other references to the resource exist at the same time

Trait Implementations

impl<'w> Clone for UnsafeWorldCell<'w>

fn clone(&self) -> UnsafeWorldCell<'w>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnsafeWorldCell<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'w> Copy for UnsafeWorldCell<'w>

impl Send for UnsafeWorldCell<'_>

impl Sync for UnsafeWorldCell<'_>