1use crate::{private::Sealed, AnyBox, AppContext, Context, Entity, ModelContext};
2use anyhow::{anyhow, Result};
3use derive_more::{Deref, DerefMut};
4use parking_lot::{RwLock, RwLockUpgradableReadGuard};
5use slotmap::{SecondaryMap, SlotMap};
6use std::{
7 any::{type_name, TypeId},
8 fmt::{self, Display},
9 hash::{Hash, Hasher},
10 marker::PhantomData,
11 mem,
12 sync::{
13 atomic::{AtomicUsize, Ordering::SeqCst},
14 Arc, Weak,
15 },
16 thread::panicking,
17};
18
19slotmap::new_key_type! { pub struct EntityId; }
20
21impl EntityId {
22 pub fn as_u64(self) -> u64 {
23 self.0.as_ffi()
24 }
25}
26
27impl Display for EntityId {
28 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
29 write!(f, "{}", self.as_u64())
30 }
31}
32
33pub(crate) struct EntityMap {
34 entities: SecondaryMap<EntityId, AnyBox>,
35 ref_counts: Arc<RwLock<EntityRefCounts>>,
36}
37
38struct EntityRefCounts {
39 counts: SlotMap<EntityId, AtomicUsize>,
40 dropped_entity_ids: Vec<EntityId>,
41}
42
43impl EntityMap {
44 pub fn new() -> Self {
45 Self {
46 entities: SecondaryMap::new(),
47 ref_counts: Arc::new(RwLock::new(EntityRefCounts {
48 counts: SlotMap::with_key(),
49 dropped_entity_ids: Vec::new(),
50 })),
51 }
52 }
53
54 /// Reserve a slot for an entity, which you can subsequently use with `insert`.
55 pub fn reserve<T: 'static>(&self) -> Slot<T> {
56 let id = self.ref_counts.write().counts.insert(1.into());
57 Slot(Model::new(id, Arc::downgrade(&self.ref_counts)))
58 }
59
60 /// Insert an entity into a slot obtained by calling `reserve`.
61 pub fn insert<T>(&mut self, slot: Slot<T>, entity: T) -> Model<T>
62 where
63 T: 'static,
64 {
65 let model = slot.0;
66 self.entities.insert(model.entity_id, Box::new(entity));
67 model
68 }
69
70 /// Move an entity to the stack.
71 #[track_caller]
72 pub fn lease<'a, T>(&mut self, model: &'a Model<T>) -> Lease<'a, T> {
73 self.assert_valid_context(model);
74 let entity = Some(
75 self.entities
76 .remove(model.entity_id)
77 .expect("Circular entity lease. Is the entity already being updated?"),
78 );
79 Lease {
80 model,
81 entity,
82 entity_type: PhantomData,
83 }
84 }
85
86 /// Return an entity after moving it to the stack.
87 pub fn end_lease<T>(&mut self, mut lease: Lease<T>) {
88 self.entities
89 .insert(lease.model.entity_id, lease.entity.take().unwrap());
90 }
91
92 pub fn read<T: 'static>(&self, model: &Model<T>) -> &T {
93 self.assert_valid_context(model);
94 self.entities[model.entity_id].downcast_ref().unwrap()
95 }
96
97 fn assert_valid_context(&self, model: &AnyModel) {
98 debug_assert!(
99 Weak::ptr_eq(&model.entity_map, &Arc::downgrade(&self.ref_counts)),
100 "used a model with the wrong context"
101 );
102 }
103
104 pub fn take_dropped(&mut self) -> Vec<(EntityId, AnyBox)> {
105 let mut ref_counts = self.ref_counts.write();
106 let dropped_entity_ids = mem::take(&mut ref_counts.dropped_entity_ids);
107
108 dropped_entity_ids
109 .into_iter()
110 .map(|entity_id| {
111 let count = ref_counts.counts.remove(entity_id).unwrap();
112 debug_assert_eq!(
113 count.load(SeqCst),
114 0,
115 "dropped an entity that was referenced"
116 );
117 (entity_id, self.entities.remove(entity_id).unwrap())
118 })
119 .collect()
120 }
121}
122
123pub struct Lease<'a, T> {
124 entity: Option<AnyBox>,
125 pub model: &'a Model<T>,
126 entity_type: PhantomData<T>,
127}
128
129impl<'a, T: 'static> core::ops::Deref for Lease<'a, T> {
130 type Target = T;
131
132 fn deref(&self) -> &Self::Target {
133 self.entity.as_ref().unwrap().downcast_ref().unwrap()
134 }
135}
136
137impl<'a, T: 'static> core::ops::DerefMut for Lease<'a, T> {
138 fn deref_mut(&mut self) -> &mut Self::Target {
139 self.entity.as_mut().unwrap().downcast_mut().unwrap()
140 }
141}
142
143impl<'a, T> Drop for Lease<'a, T> {
144 fn drop(&mut self) {
145 if self.entity.is_some() && !panicking() {
146 panic!("Leases must be ended with EntityMap::end_lease")
147 }
148 }
149}
150
151#[derive(Deref, DerefMut)]
152pub struct Slot<T>(Model<T>);
153
154pub struct AnyModel {
155 pub(crate) entity_id: EntityId,
156 pub(crate) entity_type: TypeId,
157 entity_map: Weak<RwLock<EntityRefCounts>>,
158}
159
160impl AnyModel {
161 fn new(id: EntityId, entity_type: TypeId, entity_map: Weak<RwLock<EntityRefCounts>>) -> Self {
162 Self {
163 entity_id: id,
164 entity_type,
165 entity_map,
166 }
167 }
168
169 pub fn entity_id(&self) -> EntityId {
170 self.entity_id
171 }
172
173 pub fn entity_type(&self) -> TypeId {
174 self.entity_type
175 }
176
177 pub fn downgrade(&self) -> AnyWeakModel {
178 AnyWeakModel {
179 entity_id: self.entity_id,
180 entity_type: self.entity_type,
181 entity_ref_counts: self.entity_map.clone(),
182 }
183 }
184
185 pub fn downcast<T: 'static>(self) -> Result<Model<T>, AnyModel> {
186 if TypeId::of::<T>() == self.entity_type {
187 Ok(Model {
188 any_model: self,
189 entity_type: PhantomData,
190 })
191 } else {
192 Err(self)
193 }
194 }
195}
196
197impl Clone for AnyModel {
198 fn clone(&self) -> Self {
199 if let Some(entity_map) = self.entity_map.upgrade() {
200 let entity_map = entity_map.read();
201 let count = entity_map
202 .counts
203 .get(self.entity_id)
204 .expect("detected over-release of a model");
205 let prev_count = count.fetch_add(1, SeqCst);
206 assert_ne!(prev_count, 0, "Detected over-release of a model.");
207 }
208
209 Self {
210 entity_id: self.entity_id,
211 entity_type: self.entity_type,
212 entity_map: self.entity_map.clone(),
213 }
214 }
215}
216
217impl Drop for AnyModel {
218 fn drop(&mut self) {
219 if let Some(entity_map) = self.entity_map.upgrade() {
220 let entity_map = entity_map.upgradable_read();
221 let count = entity_map
222 .counts
223 .get(self.entity_id)
224 .expect("detected over-release of a handle.");
225 let prev_count = count.fetch_sub(1, SeqCst);
226 assert_ne!(prev_count, 0, "Detected over-release of a model.");
227 if prev_count == 1 {
228 // We were the last reference to this entity, so we can remove it.
229 let mut entity_map = RwLockUpgradableReadGuard::upgrade(entity_map);
230 entity_map.dropped_entity_ids.push(self.entity_id);
231 }
232 }
233 }
234}
235
236impl<T> From<Model<T>> for AnyModel {
237 fn from(model: Model<T>) -> Self {
238 model.any_model
239 }
240}
241
242impl Hash for AnyModel {
243 fn hash<H: Hasher>(&self, state: &mut H) {
244 self.entity_id.hash(state);
245 }
246}
247
248impl PartialEq for AnyModel {
249 fn eq(&self, other: &Self) -> bool {
250 self.entity_id == other.entity_id
251 }
252}
253
254impl Eq for AnyModel {}
255
256impl std::fmt::Debug for AnyModel {
257 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
258 f.debug_struct("AnyModel")
259 .field("entity_id", &self.entity_id.as_u64())
260 .finish()
261 }
262}
263
264#[derive(Deref, DerefMut)]
265pub struct Model<T> {
266 #[deref]
267 #[deref_mut]
268 pub(crate) any_model: AnyModel,
269 pub(crate) entity_type: PhantomData<T>,
270}
271
272unsafe impl<T> Send for Model<T> {}
273unsafe impl<T> Sync for Model<T> {}
274impl<T> Sealed for Model<T> {}
275
276impl<T: 'static> Entity<T> for Model<T> {
277 type Weak = WeakModel<T>;
278
279 fn entity_id(&self) -> EntityId {
280 self.any_model.entity_id
281 }
282
283 fn downgrade(&self) -> Self::Weak {
284 WeakModel {
285 any_model: self.any_model.downgrade(),
286 entity_type: self.entity_type,
287 }
288 }
289
290 fn upgrade_from(weak: &Self::Weak) -> Option<Self>
291 where
292 Self: Sized,
293 {
294 Some(Model {
295 any_model: weak.any_model.upgrade()?,
296 entity_type: weak.entity_type,
297 })
298 }
299}
300
301impl<T: 'static> Model<T> {
302 fn new(id: EntityId, entity_map: Weak<RwLock<EntityRefCounts>>) -> Self
303 where
304 T: 'static,
305 {
306 Self {
307 any_model: AnyModel::new(id, TypeId::of::<T>(), entity_map),
308 entity_type: PhantomData,
309 }
310 }
311
312 /// Downgrade the this to a weak model reference
313 pub fn downgrade(&self) -> WeakModel<T> {
314 // Delegate to the trait implementation to keep behavior in one place.
315 // This method was included to improve method resolution in the presence of
316 // the Model's deref
317 Entity::downgrade(self)
318 }
319
320 /// Convert this into a dynamically typed model.
321 pub fn into_any(self) -> AnyModel {
322 self.any_model
323 }
324
325 pub fn read<'a>(&self, cx: &'a AppContext) -> &'a T {
326 cx.entities.read(self)
327 }
328
329 pub fn read_with<'a, R, C: Context>(
330 &self,
331 cx: &'a C,
332 f: impl FnOnce(&T, &AppContext) -> R,
333 ) -> C::Result<R> {
334 cx.read_model(self, f)
335 }
336
337 /// Update the entity referenced by this model with the given function.
338 ///
339 /// The update function receives a context appropriate for its environment.
340 /// When updating in an `AppContext`, it receives a `ModelContext`.
341 /// When updating an a `WindowContext`, it receives a `ViewContext`.
342 pub fn update<C, R>(
343 &self,
344 cx: &mut C,
345 update: impl FnOnce(&mut T, &mut ModelContext<'_, T>) -> R,
346 ) -> C::Result<R>
347 where
348 C: Context,
349 {
350 cx.update_model(self, update)
351 }
352}
353
354impl<T> Clone for Model<T> {
355 fn clone(&self) -> Self {
356 Self {
357 any_model: self.any_model.clone(),
358 entity_type: self.entity_type,
359 }
360 }
361}
362
363impl<T> std::fmt::Debug for Model<T> {
364 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
365 write!(
366 f,
367 "Model {{ entity_id: {:?}, entity_type: {:?} }}",
368 self.any_model.entity_id,
369 type_name::<T>()
370 )
371 }
372}
373
374impl<T> Hash for Model<T> {
375 fn hash<H: Hasher>(&self, state: &mut H) {
376 self.any_model.hash(state);
377 }
378}
379
380impl<T> PartialEq for Model<T> {
381 fn eq(&self, other: &Self) -> bool {
382 self.any_model == other.any_model
383 }
384}
385
386impl<T> Eq for Model<T> {}
387
388impl<T> PartialEq<WeakModel<T>> for Model<T> {
389 fn eq(&self, other: &WeakModel<T>) -> bool {
390 self.any_model.entity_id() == other.entity_id()
391 }
392}
393
394#[derive(Clone)]
395pub struct AnyWeakModel {
396 pub(crate) entity_id: EntityId,
397 entity_type: TypeId,
398 entity_ref_counts: Weak<RwLock<EntityRefCounts>>,
399}
400
401impl AnyWeakModel {
402 pub fn entity_id(&self) -> EntityId {
403 self.entity_id
404 }
405
406 pub fn is_upgradable(&self) -> bool {
407 let ref_count = self
408 .entity_ref_counts
409 .upgrade()
410 .and_then(|ref_counts| Some(ref_counts.read().counts.get(self.entity_id)?.load(SeqCst)))
411 .unwrap_or(0);
412 ref_count > 0
413 }
414
415 pub fn upgrade(&self) -> Option<AnyModel> {
416 let ref_counts = &self.entity_ref_counts.upgrade()?;
417 let ref_counts = ref_counts.read();
418 let ref_count = ref_counts.counts.get(self.entity_id)?;
419
420 // entity_id is in dropped_entity_ids
421 if ref_count.load(SeqCst) == 0 {
422 return None;
423 }
424 ref_count.fetch_add(1, SeqCst);
425
426 Some(AnyModel {
427 entity_id: self.entity_id,
428 entity_type: self.entity_type,
429 entity_map: self.entity_ref_counts.clone(),
430 })
431 }
432}
433
434impl<T> From<WeakModel<T>> for AnyWeakModel {
435 fn from(model: WeakModel<T>) -> Self {
436 model.any_model
437 }
438}
439
440impl Hash for AnyWeakModel {
441 fn hash<H: Hasher>(&self, state: &mut H) {
442 self.entity_id.hash(state);
443 }
444}
445
446impl PartialEq for AnyWeakModel {
447 fn eq(&self, other: &Self) -> bool {
448 self.entity_id == other.entity_id
449 }
450}
451
452impl Eq for AnyWeakModel {}
453
454#[derive(Deref, DerefMut)]
455pub struct WeakModel<T> {
456 #[deref]
457 #[deref_mut]
458 any_model: AnyWeakModel,
459 entity_type: PhantomData<T>,
460}
461
462unsafe impl<T> Send for WeakModel<T> {}
463unsafe impl<T> Sync for WeakModel<T> {}
464
465impl<T> Clone for WeakModel<T> {
466 fn clone(&self) -> Self {
467 Self {
468 any_model: self.any_model.clone(),
469 entity_type: self.entity_type,
470 }
471 }
472}
473
474impl<T: 'static> WeakModel<T> {
475 /// Upgrade this weak model reference into a strong model reference
476 pub fn upgrade(&self) -> Option<Model<T>> {
477 // Delegate to the trait implementation to keep behavior in one place.
478 Model::upgrade_from(self)
479 }
480
481 /// Update the entity referenced by this model with the given function if
482 /// the referenced entity still exists. Returns an error if the entity has
483 /// been released.
484 ///
485 /// The update function receives a context appropriate for its environment.
486 /// When updating in an `AppContext`, it receives a `ModelContext`.
487 /// When updating an a `WindowContext`, it receives a `ViewContext`.
488 pub fn update<C, R>(
489 &self,
490 cx: &mut C,
491 update: impl FnOnce(&mut T, &mut ModelContext<'_, T>) -> R,
492 ) -> Result<R>
493 where
494 C: Context,
495 Result<C::Result<R>>: crate::Flatten<R>,
496 {
497 crate::Flatten::flatten(
498 self.upgrade()
499 .ok_or_else(|| anyhow!("entity release"))
500 .map(|this| cx.update_model(&this, update)),
501 )
502 }
503}
504
505impl<T> Hash for WeakModel<T> {
506 fn hash<H: Hasher>(&self, state: &mut H) {
507 self.any_model.hash(state);
508 }
509}
510
511impl<T> PartialEq for WeakModel<T> {
512 fn eq(&self, other: &Self) -> bool {
513 self.any_model == other.any_model
514 }
515}
516
517impl<T> Eq for WeakModel<T> {}
518
519impl<T> PartialEq<Model<T>> for WeakModel<T> {
520 fn eq(&self, other: &Model<T>) -> bool {
521 self.entity_id() == other.any_model.entity_id()
522 }
523}
524
525#[cfg(test)]
526mod test {
527 use crate::EntityMap;
528
529 struct TestEntity {
530 pub i: i32,
531 }
532
533 #[test]
534 fn test_entity_map_slot_assignment_before_cleanup() {
535 // Tests that slots are not re-used before take_dropped.
536 let mut entity_map = EntityMap::new();
537
538 let slot = entity_map.reserve::<TestEntity>();
539 entity_map.insert(slot, TestEntity { i: 1 });
540
541 let slot = entity_map.reserve::<TestEntity>();
542 entity_map.insert(slot, TestEntity { i: 2 });
543
544 let dropped = entity_map.take_dropped();
545 assert_eq!(dropped.len(), 2);
546
547 assert_eq!(
548 dropped
549 .into_iter()
550 .map(|(_, entity)| entity.downcast::<TestEntity>().unwrap().i)
551 .collect::<Vec<i32>>(),
552 vec![1, 2],
553 );
554 }
555
556 #[test]
557 fn test_entity_map_weak_upgrade_before_cleanup() {
558 // Tests that weak handles are not upgraded before take_dropped
559 let mut entity_map = EntityMap::new();
560
561 let slot = entity_map.reserve::<TestEntity>();
562 let handle = entity_map.insert(slot, TestEntity { i: 1 });
563 let weak = handle.downgrade();
564 drop(handle);
565
566 let strong = weak.upgrade();
567 assert_eq!(strong, None);
568
569 let dropped = entity_map.take_dropped();
570 assert_eq!(dropped.len(), 1);
571
572 assert_eq!(
573 dropped
574 .into_iter()
575 .map(|(_, entity)| entity.downcast::<TestEntity>().unwrap().i)
576 .collect::<Vec<i32>>(),
577 vec![1],
578 );
579 }
580}