# Entities

> Entity handles, updates, notify, events and weak handles.

An `Entity<T>` is a handle to state of type `T` owned by the application.
State lives in the app, not in your struct, so handles are cheap to clone and
can be shared between views.

```rust
let counter: Entity<Counter> = cx.new(|_cx| Counter { value: 0 });

counter.read(cx).value;                       // &T
counter.update(cx, |counter, cx| {            // &mut T plus Context<Counter>
    counter.value += 1;
    cx.notify();                              // re-render views observing it
});
```

Rules that matter in practice:

- Updating an entity that is already being updated panics. Structure code so
  one `update` finishes before another begins on the same entity.
- `cx.notify()` marks the entity dirty. Views re-render and `cx.observe`
  callbacks fire. Forgetting it is the usual reason a view does not refresh.
- `cx.emit(event)` sends a typed event; the entity declares
  `impl EventEmitter<MyEvent> for MyEntity {}`. Listeners use `cx.subscribe`
  and keep the returned `Subscription` in a `_subscriptions: Vec<Subscription>`
  field, since dropping it unsubscribes.
- `entity.downgrade()` gives a `WeakEntity<T>` whose `update` and `read_with`
  return `anyhow::Result`. Use weak handles in long-lived tasks and in any
  structure where two entities reference each other, or neither is dropped.