1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
use bevy_utils::tracing::error;

use crate::{
    archetype::ArchetypeComponentId,
    event::{Event, Events},
    storage::SparseSet,
    system::Resource,
    world::{Mut, World},
};
use std::{
    any::TypeId,
    cell::RefCell,
    ops::{Deref, DerefMut},
    rc::Rc,
};

use super::unsafe_world_cell::UnsafeWorldCell;

/// Exposes safe mutable access to multiple resources at a time in a World. Attempting to access
/// World in a way that violates Rust's mutability rules will panic thanks to runtime checks.
pub struct WorldCell<'w> {
    pub(crate) world: UnsafeWorldCell<'w>,
    pub(crate) access: Rc<RefCell<ArchetypeComponentAccess>>,
}

pub(crate) struct ArchetypeComponentAccess {
    access: SparseSet<ArchetypeComponentId, usize>,
}

impl Default for ArchetypeComponentAccess {
    fn default() -> Self {
        Self {
            access: SparseSet::new(),
        }
    }
}

const UNIQUE_ACCESS: usize = 0;
const BASE_ACCESS: usize = 1;
impl ArchetypeComponentAccess {
    const fn new() -> Self {
        Self {
            access: SparseSet::new(),
        }
    }

    fn read(&mut self, id: ArchetypeComponentId) -> bool {
        let id_access = self.access.get_or_insert_with(id, || BASE_ACCESS);
        if *id_access == UNIQUE_ACCESS {
            false
        } else {
            *id_access += 1;
            true
        }
    }

    fn drop_read(&mut self, id: ArchetypeComponentId) {
        let id_access = self.access.get_or_insert_with(id, || BASE_ACCESS);
        *id_access -= 1;
    }

    fn write(&mut self, id: ArchetypeComponentId) -> bool {
        let id_access = self.access.get_or_insert_with(id, || BASE_ACCESS);
        if *id_access == BASE_ACCESS {
            *id_access = UNIQUE_ACCESS;
            true
        } else {
            false
        }
    }

    fn drop_write(&mut self, id: ArchetypeComponentId) {
        let id_access = self.access.get_or_insert_with(id, || BASE_ACCESS);
        *id_access = BASE_ACCESS;
    }
}

impl<'w> Drop for WorldCell<'w> {
    fn drop(&mut self) {
        let mut access = self.access.borrow_mut();

        {
            // SAFETY: `WorldCell` does not hand out `UnsafeWorldCell` to anywhere else so this is the only
            // `UnsafeWorldCell` and we have exclusive access to it.
            let world = unsafe { self.world.world_mut() };
            let world_cached_access = &mut world.archetype_component_access;

            // give world ArchetypeComponentAccess back to reuse allocations
            std::mem::swap(world_cached_access, &mut *access);
        }
    }
}

/// A read-only borrow of some data stored in a [`World`]. This type is returned by [`WorldCell`],
/// which uses run-time checks to ensure that the borrow does not violate Rust's aliasing rules.
pub struct WorldBorrow<'w, T> {
    value: &'w T,
    archetype_component_id: ArchetypeComponentId,
    access: Rc<RefCell<ArchetypeComponentAccess>>,
}

impl<'w, T> WorldBorrow<'w, T> {
    fn try_new(
        value: impl FnOnce() -> Option<&'w T>,
        archetype_component_id: ArchetypeComponentId,
        access: Rc<RefCell<ArchetypeComponentAccess>>,
    ) -> Option<Self> {
        assert!(
            access.borrow_mut().read(archetype_component_id),
            "Attempted to immutably access {}, but it is already mutably borrowed",
            std::any::type_name::<T>(),
        );
        let value = value()?;
        Some(Self {
            value,
            archetype_component_id,
            access,
        })
    }
}

impl<'w, T> Deref for WorldBorrow<'w, T> {
    type Target = T;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self.value
    }
}

impl<'w, T> Drop for WorldBorrow<'w, T> {
    fn drop(&mut self) {
        let mut access = self.access.borrow_mut();
        access.drop_read(self.archetype_component_id);
    }
}

/// A mutable borrow of some data stored in a [`World`]. This type is returned by [`WorldCell`],
/// which uses run-time checks to ensure that the borrow does not violate Rust's aliasing rules.
pub struct WorldBorrowMut<'w, T> {
    value: Mut<'w, T>,
    archetype_component_id: ArchetypeComponentId,
    access: Rc<RefCell<ArchetypeComponentAccess>>,
}

impl<'w, T> WorldBorrowMut<'w, T> {
    fn try_new(
        value: impl FnOnce() -> Option<Mut<'w, T>>,
        archetype_component_id: ArchetypeComponentId,
        access: Rc<RefCell<ArchetypeComponentAccess>>,
    ) -> Option<Self> {
        assert!(
            access.borrow_mut().write(archetype_component_id),
            "Attempted to mutably access {}, but it is already mutably borrowed",
            std::any::type_name::<T>(),
        );
        let value = value()?;
        Some(Self {
            value,
            archetype_component_id,
            access,
        })
    }
}

impl<'w, T> Deref for WorldBorrowMut<'w, T> {
    type Target = T;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self.value.deref()
    }
}

impl<'w, T> DerefMut for WorldBorrowMut<'w, T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.value
    }
}

impl<'w, T> Drop for WorldBorrowMut<'w, T> {
    fn drop(&mut self) {
        let mut access = self.access.borrow_mut();
        access.drop_write(self.archetype_component_id);
    }
}

impl<'w> WorldCell<'w> {
    pub(crate) fn new(world: &'w mut World) -> Self {
        // this is cheap because ArchetypeComponentAccess::new() is const / allocation free
        let access = std::mem::replace(
            &mut world.archetype_component_access,
            ArchetypeComponentAccess::new(),
        );
        // world's ArchetypeComponentAccess is recycled to cut down on allocations
        Self {
            world: world.as_unsafe_world_cell(),
            access: Rc::new(RefCell::new(access)),
        }
    }

    /// Gets a reference to the resource of the given type
    pub fn get_resource<T: Resource>(&self) -> Option<WorldBorrow<'_, T>> {
        let component_id = self.world.components().get_resource_id(TypeId::of::<T>())?;

        let archetype_component_id = self
            .world
            .get_resource_archetype_component_id(component_id)?;

        WorldBorrow::try_new(
            // SAFETY: access is checked by WorldBorrow
            || unsafe { self.world.get_resource::<T>() },
            archetype_component_id,
            self.access.clone(),
        )
    }

    /// Gets a reference to the resource of the given type
    ///
    /// # Panics
    ///
    /// Panics if the resource does not exist. Use [`get_resource`](WorldCell::get_resource) instead
    /// if you want to handle this case.
    pub fn resource<T: Resource>(&self) -> WorldBorrow<'_, T> {
        match self.get_resource() {
            Some(x) => x,
            None => panic!(
                "Requested resource {} does not exist in the `World`. 
                Did you forget to add it using `app.insert_resource` / `app.init_resource`? 
                Resources are also implicitly added via `app.add_event`,
                and can be added by plugins.",
                std::any::type_name::<T>()
            ),
        }
    }

    /// Gets a mutable reference to the resource of the given type
    pub fn get_resource_mut<T: Resource>(&self) -> Option<WorldBorrowMut<'_, T>> {
        let component_id = self.world.components().get_resource_id(TypeId::of::<T>())?;

        let archetype_component_id = self
            .world
            .get_resource_archetype_component_id(component_id)?;
        WorldBorrowMut::try_new(
            // SAFETY: access is checked by WorldBorrowMut
            || unsafe { self.world.get_resource_mut::<T>() },
            archetype_component_id,
            self.access.clone(),
        )
    }

    /// Gets a mutable reference to the resource of the given type
    ///
    /// # Panics
    ///
    /// Panics if the resource does not exist. Use [`get_resource_mut`](WorldCell::get_resource_mut)
    /// instead if you want to handle this case.
    pub fn resource_mut<T: Resource>(&self) -> WorldBorrowMut<'_, T> {
        match self.get_resource_mut() {
            Some(x) => x,
            None => panic!(
                "Requested resource {} does not exist in the `World`. 
                Did you forget to add it using `app.insert_resource` / `app.init_resource`? 
                Resources are also implicitly added via `app.add_event`,
                and can be added by plugins.",
                std::any::type_name::<T>()
            ),
        }
    }

    /// Gets an immutable reference to the non-send resource of the given type, if it exists.
    pub fn get_non_send_resource<T: 'static>(&self) -> Option<WorldBorrow<'_, T>> {
        let component_id = self.world.components().get_resource_id(TypeId::of::<T>())?;

        let archetype_component_id = self
            .world
            .get_non_send_archetype_component_id(component_id)?;
        WorldBorrow::try_new(
            // SAFETY: access is checked by WorldBorrowMut
            || unsafe { self.world.get_non_send_resource::<T>() },
            archetype_component_id,
            self.access.clone(),
        )
    }

    /// Gets an immutable reference to the non-send resource of the given type, if it exists.
    ///
    /// # Panics
    ///
    /// Panics if the resource does not exist. Use
    /// [`get_non_send_resource`](WorldCell::get_non_send_resource) instead if you want to handle
    /// this case.
    pub fn non_send_resource<T: 'static>(&self) -> WorldBorrow<'_, T> {
        match self.get_non_send_resource() {
            Some(x) => x,
            None => panic!(
                "Requested non-send resource {} does not exist in the `World`. 
                Did you forget to add it using `app.insert_non_send_resource` / `app.init_non_send_resource`? 
                Non-send resources can also be be added by plugins.",
                std::any::type_name::<T>()
            ),
        }
    }

    /// Gets a mutable reference to the non-send resource of the given type, if it exists.
    pub fn get_non_send_resource_mut<T: 'static>(&self) -> Option<WorldBorrowMut<'_, T>> {
        let component_id = self.world.components().get_resource_id(TypeId::of::<T>())?;

        let archetype_component_id = self
            .world
            .get_non_send_archetype_component_id(component_id)?;
        WorldBorrowMut::try_new(
            // SAFETY: access is checked by WorldBorrowMut
            || unsafe { self.world.get_non_send_resource_mut::<T>() },
            archetype_component_id,
            self.access.clone(),
        )
    }

    /// Gets a mutable reference to the non-send resource of the given type, if it exists.
    ///
    /// # Panics
    ///
    /// Panics if the resource does not exist. Use
    /// [`get_non_send_resource_mut`](WorldCell::get_non_send_resource_mut) instead if you want to
    /// handle this case.
    pub fn non_send_resource_mut<T: 'static>(&self) -> WorldBorrowMut<'_, T> {
        match self.get_non_send_resource_mut() {
            Some(x) => x,
            None => panic!(
                "Requested non-send resource {} does not exist in the `World`. 
                Did you forget to add it using `app.insert_non_send_resource` / `app.init_non_send_resource`? 
                Non-send resources can also be be added by plugins.",
                std::any::type_name::<T>()
            ),
        }
    }

    /// Sends an [`Event`].
    #[inline]
    pub fn send_event<E: Event>(&self, event: E) {
        self.send_event_batch(std::iter::once(event));
    }

    /// Sends the default value of the [`Event`] of type `E`.
    #[inline]
    pub fn send_event_default<E: Event + Default>(&self) {
        self.send_event_batch(std::iter::once(E::default()));
    }

    /// Sends a batch of [`Event`]s from an iterator.
    #[inline]
    pub fn send_event_batch<E: Event>(&self, events: impl Iterator<Item = E>) {
        match self.get_resource_mut::<Events<E>>() {
            Some(mut events_resource) => events_resource.extend(events),
            None => error!(
                    "Unable to send event `{}`\n\tEvent must be added to the app with `add_event()`\n\thttps://docs.rs/bevy/*/bevy/app/struct.App.html#method.add_event ",
                    std::any::type_name::<E>()
                ),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::BASE_ACCESS;
    use crate as bevy_ecs;
    use crate::{system::Resource, world::World};
    use std::any::TypeId;

    #[derive(Resource)]
    struct A(u32);

    #[derive(Resource)]
    struct B(u64);

    #[test]
    fn world_cell() {
        let mut world = World::default();
        world.insert_resource(A(1));
        world.insert_resource(B(1));
        let cell = world.cell();
        {
            let mut a = cell.resource_mut::<A>();
            assert_eq!(1, a.0);
            a.0 = 2;
        }
        {
            let a = cell.resource::<A>();
            assert_eq!(2, a.0, "ensure access is dropped");

            let a2 = cell.resource::<A>();
            assert_eq!(
                2, a2.0,
                "ensure multiple immutable accesses can occur at the same time"
            );
        }
        {
            let a = cell.resource_mut::<A>();
            assert_eq!(
                2, a.0,
                "ensure both immutable accesses are dropped, enabling a new mutable access"
            );

            let b = cell.resource::<B>();
            assert_eq!(
                1, b.0,
                "ensure multiple non-conflicting mutable accesses can occur at the same time"
            );
        }
    }

    #[test]
    fn world_access_reused() {
        let mut world = World::default();
        world.insert_resource(A(1));
        {
            let cell = world.cell();
            {
                let mut a = cell.resource_mut::<A>();
                assert_eq!(1, a.0);
                a.0 = 2;
            }
        }

        let u32_component_id = world.components.get_resource_id(TypeId::of::<A>()).unwrap();
        let u32_archetype_component_id = world
            .get_resource_archetype_component_id(u32_component_id)
            .unwrap();
        assert_eq!(world.archetype_component_access.access.len(), 1);
        assert_eq!(
            world
                .archetype_component_access
                .access
                .get(u32_archetype_component_id),
            Some(&BASE_ACCESS),
            "reused access count is 'base'"
        );
    }

    #[test]
    #[should_panic]
    fn world_cell_double_mut() {
        let mut world = World::default();
        world.insert_resource(A(1));
        let cell = world.cell();
        let _value_a = cell.resource_mut::<A>();
        let _value_b = cell.resource_mut::<A>();
    }

    #[test]
    #[should_panic]
    fn world_cell_ref_and_mut() {
        let mut world = World::default();
        world.insert_resource(A(1));
        let cell = world.cell();
        let _value_a = cell.resource::<A>();
        let _value_b = cell.resource_mut::<A>();
    }

    #[test]
    #[should_panic]
    fn world_cell_mut_and_ref() {
        let mut world = World::default();
        world.insert_resource(A(1));
        let cell = world.cell();
        let _value_a = cell.resource_mut::<A>();
        let _value_b = cell.resource::<A>();
    }

    #[test]
    fn world_cell_ref_and_ref() {
        let mut world = World::default();
        world.insert_resource(A(1));
        let cell = world.cell();
        let _value_a = cell.resource::<A>();
        let _value_b = cell.resource::<A>();
    }
}