1//! In GPUI, every model or view in the application is actually owned by a single top-level object called the `App`. When a new entity or view is created (referred to collectively as _entities_), the application is given ownership of their state to enable their participation in a variety of app services and interaction with other entities.
  2//!
  3//! To illustrate, consider the trivial app below. We start the app by calling `run` with a callback, which is passed a reference to the `App` that owns all the state for the application. This `App` is our gateway to all application-level services, such as opening windows, presenting dialogs, etc. It also has an `insert_entity` method, which is called below to create an entity and give ownership of it to the application.
  4//!
  5//! ```no_run
  6//! # use gpui::{App, AppContext, Application, Entity};
  7//! # struct Counter {
  8//! #     count: usize,
  9//! # }
 10//! Application::new().run(|cx: &mut App| {
 11//!     let _counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
 12//!     // ...
 13//! });
 14//! ```
 15//!
 16//! The call to `new_entity` returns an _entity handle_, which carries a type parameter based on the type of object it references. By itself, this `Entity<Counter>` handle doesn't provide access to the entity's state. It's merely an inert identifier plus a compile-time type tag, and it maintains a reference counted pointer to the underlying `Counter` object that is owned by the app.
 17//!
 18//! Much like an `Rc` from the Rust standard library, this reference count is incremented when the handle is cloned and decremented when it is dropped to enable shared ownership over the underlying model, but unlike an `Rc` it only provides access to the model's state when a reference to an `App` is available. The handle doesn't truly _own_ the state, but it can be used to access the state from its true owner, the `App`. Stripping away some of the setup code for brevity:
 19//!
 20//! ```no_run
 21//! # use gpui::{App, AppContext, Application, Context, Entity};
 22//! # struct Counter {
 23//! #     count: usize,
 24//! # }
 25//! Application::new().run(|cx: &mut App| {
 26//!     let counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
 27//!     // Call `update` to access the model's state.
 28//!     counter.update(cx, |counter: &mut Counter, _cx: &mut Context<Counter>| {
 29//!         counter.count += 1;
 30//!     });
 31//! });
 32//! ```
 33//!
 34//! To update the counter, we call `update` on the handle, passing the context reference and a callback. The callback is yielded a mutable reference to the counter, which can be used to manipulate state.
 35//!
 36//! The callback is also provided a second `Context<Counter>` reference. This reference is similar to the `App` reference provided to the `run` callback. A `Context` is actually a wrapper around the `App`, including some additional data to indicate which particular entity it is tied to; in this case the counter.
 37//!
 38//! In addition to the application-level services provided by `App`, a `Context` provides access to entity-level services. For example, it can be used it to inform observers of this entity that its state has changed. Let's add that to our example, by calling `cx.notify()`.
 39//!
 40//! ```no_run
 41//! # use gpui::{App, AppContext, Application, Entity};
 42//! # struct Counter {
 43//! #     count: usize,
 44//! # }
 45//! Application::new().run(|cx: &mut App| {
 46//!     let counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
 47//!     counter.update(cx, |counter, cx| {
 48//!         counter.count += 1;
 49//!         cx.notify(); // Notify observers
 50//!     });
 51//! });
 52//! ```
 53//!
 54//! Next, these notifications need to be observed and reacted to. Before updating the counter, we'll construct a second counter that observes it. Whenever the first counter changes, twice its count is assigned to the second counter. Note how `observe` is called on the `Context` belonging to our second counter to arrange for it to be notified whenever the first counter notifies. The call to `observe` returns a `Subscription`, which is `detach`ed to preserve this behavior for as long as both counters exist. We could also store this subscription and drop it at a time of our choosing to cancel this behavior.
 55//!
 56//! The `observe` callback is passed a mutable reference to the observer and a _handle_ to the observed counter, whose state we access with the `read` method.
 57//!
 58//! ```no_run
 59//!  # use gpui::{App, AppContext, Application, Entity, prelude::*};
 60//!  # struct Counter {
 61//!  #     count: usize,
 62//!  # }
 63//!  Application::new().run(|cx: &mut App| {
 64//!      let first_counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
 65//!
 66//!      let second_counter = cx.new(|cx: &mut Context<Counter>| {
 67//!          // Note we can set up the callback before the Counter is even created!
 68//!          cx.observe(
 69//!              &first_counter,
 70//!              |second: &mut Counter, first: Entity<Counter>, cx| {
 71//!                  second.count = first.read(cx).count * 2;
 72//!              },
 73//!          )
 74//!          .detach();
 75//!
 76//!          Counter { count: 0 }
 77//!      });
 78//!
 79//!      first_counter.update(cx, |counter, cx| {
 80//!          counter.count += 1;
 81//!          cx.notify();
 82//!      });
 83//!
 84//!      assert_eq!(second_counter.read(cx).count, 2);
 85//!  });
 86//! ```
 87//!
 88//! After updating the first counter, it can be noted that the observing counter's state is maintained according to our subscription.
 89//!
 90//! In addition to `observe` and `notify`, which indicate that an entity's state has changed, GPUI also offers `subscribe` and `emit`, which enables entities to emit typed events. To opt into this system, the emitting object must implement the `EventEmitter` trait.
 91//!
 92//! Let's introduce a new event type called `CounterChangeEvent`, then indicate that `Counter` can emit this type of event:
 93//!
 94//! ```no_run
 95//! use gpui::EventEmitter;
 96//! # struct Counter {
 97//! #     count: usize,
 98//! # }
 99//! struct CounterChangeEvent {
100//!     increment: usize,
101//! }
102//!
103//! impl EventEmitter<CounterChangeEvent> for Counter {}
104//! ```
105//!
106//! Next, the example should be updated, replacing the observation with a subscription. Whenever the counter is incremented, a `Change` event is emitted to indicate the magnitude of the increase.
107//!
108//! ```no_run
109//! # use gpui::{App, AppContext, Application, Context, Entity, EventEmitter};
110//! # struct Counter {
111//! #     count: usize,
112//! # }
113//! # struct CounterChangeEvent {
114//! #     increment: usize,
115//! # }
116//! # impl EventEmitter<CounterChangeEvent> for Counter {}
117//! Application::new().run(|cx: &mut App| {
118//!     let first_counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
119//!
120//!     let second_counter = cx.new(|cx: &mut Context<Counter>| {
121//!         // Note we can set up the callback before the Counter is even created!
122//!         cx.subscribe(&first_counter, |second: &mut Counter, _first: Entity<Counter>, event, _cx| {
123//!             second.count += event.increment * 2;
124//!         })
125//!         .detach();
126//!
127//!         Counter {
128//!             count: first_counter.read(cx).count * 2,
129//!         }
130//!     });
131//!
132//!     first_counter.update(cx, |first, cx| {
133//!         first.count += 2;
134//!         cx.emit(CounterChangeEvent { increment: 2 });
135//!         cx.notify();
136//!     });
137//!
138//!     assert_eq!(second_counter.read(cx).count, 4);
139//! });
140//! ```