Merge pull request #273 from audionerd/docs-actor-model

actor-model.mdx: re-written and expanded

Author: davidkpiano

docs/actor-model.mdx

@@ -1,38 +1,80 @@
 ---
-title: The actor model
+title: The Actor model
 ---
 
-When you run a state machine, it becomes an actor. In the actor model, actors are “live” objects that can communicate with each other via asynchronous messages. In XState, we refer to these messages as [**events**](transitions.mdx).
+The [Actor model](https://en.wikipedia.org/wiki/Actor_model) in computer science is a mathematical model of concurrent computation in which an "actor" is the basic building block.
 
-Coming soon… what are some good examples of actors in software development?
+The actor model allows developers to build reliable message-based systems by using actors to communicate. State machines and statecharts can model the logic of actors. These actors can communicate with each other, and with other actors, in the same way.
+
+:::tip
+When you run a state machine in XState, it becomes an actor.
+:::
+
+### What Defines An "Actor"?
+
+Actors are independent "live" objects that can communicate with each other via asynchronous message passing. In XState, we refer to these messages as [_events_](transitions.mdx).
+
+- An actor has its own internal, encapsulated state that can only be updated by the actor itself. An actor may choose to update its internal state in response to a message it receives, but it cannot be updated by any other entity.
+- Actors communicate with other actors by sending and receiving events asynchronously.
+- Actors process one message at a time. They have an internal “mailbox” that acts like an event queue, processing events sequentially.
+- Internal actor state is not shared between actors. The only way for an actor to share any part of its internal state is by:
+  - Sending events to other actors
+  - Or emitting snapshots, which can be considered implicit events sent to subscribers.
+- Actors can create (spawn/invoke) new actors.
+
+You'll find strong similarities to the Actor model in software you may already be familiar with. The concept of objects encapsulating state and passing messages to each other may be familiar from Object-Oriented Programming. And actors are analagous to real-world physical concepts like cell biology, and communication in human relationships.
 
 ## State
 
-An actor has its own internal, encapsulated state that the actor itself can only update. An actor may update its internal state in response to a message it receives, but it cannot be updated by any other entity. Actors do not share state. The only way for an actor to share data is by sending events.
+An actor has its own internal, encapsulated state that only the actor itself can update. An actor may update its internal state in response to a message it receives, but it cannot be updated by any other entity. Actors do not share state. The only way for an actor to share data is by sending events.
 
-[Read more about actors and state](actors.mdx).
+[Read more about XState actors and state](actors.mdx).
 
-## Communication with events
+## Communication With Events
 
 Actors communicate with other actors by sending and receiving events asynchronously. Actors use an internal “mailbox” that acts like an event queue, processing events one at a time.
 
-[Read more about actors and events](actors.mdx).
+[Read more about XState events and transitions](transitions.mdx).
 
 ## Spawning
 
-Actors can spawn new actors. Actors will spawn new actors in situations where they need to delegate work to another actor or when they need to create a new actor to handle a new task. Spawning allows for a flexible and dynamic system where actors can be created and destroyed as needed to handle the workload efficiently.
+Actors can spawn new actors, which is useful in situations where an actor needs to delegate work to another actor. Spawning allows for a flexible and dynamic system where actors can be created and destroyed as needed to handle the workload efficiently.
+
+- [Read more about spawning actors in XState](spawn.mdx).
+- [Read about the difference between invoking and spawning actors in XState](actors.mdx#invoking-and-spawning-actors).
+
+## The Actor Model in Backend Development
 
-- [Read more about spawning actors](spawn.mdx).
-- [Read about the difference between invoking and spawning actors](actors.mdx#invoking-and-spawning-actors).
+The actor model is often used to coordinate backend systems. There are direct implementations of the Actor model, like [Akka](https://doc.akka.io/docs/akka/current/typed/guide/introduction.html) for the JVM. In [Erlang](https://www.erlang.org/docs), processes can be seen as actors, which can send and receive messages and spawn new processes. Erlang is used by massive distributed systems, like Discord and WhatsApp.
 
-## Backend development
+In [Stately Sky](https://stately.ai/docs/stately-sky-getting-started), a state machine actor be used to manage long-running backend processes like medical patient onboarding flows, inventory management, or multi-player collaborative experiences like whiteboard canvases or games.
 
-Coming soon… how do you use the actor model in backend dev?
+## The Actor Model in Frontend Development
 
-## Frontend development
+The Actor model is especially useful for coordinating the many moving parts of a front-end web application.
 
-Coming soon… how do you use the actor model in frontend dev?
+**Your front-end app is always a distributed system**, and managing distributed systems is where the actor model shines. This is because in a browser environment **you never really have a "global source of truth"**, you instead have **many independent sources of state and events**: 3rd-party components, local component state, local storage, query parameters, routers, network I/O, DOM events and their listeners, etc. 
+
+> […] there is no such thing as a single source of truth in any non-trivial application. All applications, even front-end apps, are distributed at some level. – via: [Redux is Half of a Pattern (2/2)](https://dev.to/davidkpiano/redux-is-half-of-a-pattern-2-2-4jo3)
+
+So even for simple web apps, with small app-specific state and a few known app-specific events, the actor model can be helpful. 
 
 ## XState
 
-Coming soon… how does the actor model work in XState?
+Actors in XState can:
+- **Accept messages** as [events](transitions#event-objects) passed to their own internal logic, or for state machines as received by [transitions](transitions.mdx).
+- **Create more actors** within a state machine using `spawn` in an [`assign`](actions.mdx#assign-action), or using the `spawnChild` action creator. For details, see [Spawn](spawn.mdx).
+- **Send more messages** as events using `self.send` in their own logic, or [action creators](actions.mdx) like [`sendTo`](actions#send-to-action) or [`raise`](actions#raise-action) in a state machine.
+
+Actors in XState have their own [actor logic](actors.mdx#actor-logic) which they use to:
+- **Make local decisions**
+- **Determine how to repond to the next message received**
+- **Modify their own private state** (but only affect each other via messaging)
+
+Actors in XState exist in [systems](system.mdx) and can communicate with each other within and across those systems.
+
+## Reference
+
+- [What is the actor model and when should I use it?](https://stately.ai/blog/what-is-the-actor-model)
+- [The Actor Model Explained in 5 Minutes](https://www.youtube.com/watch?v=ELwEdb_pD0k)
+- [Wikipedia: Actor model](https://en.wikipedia.org/wiki/Actor_model)

docs/actors.mdx

@@ -27,12 +27,14 @@ In the actor model, actors are objects that can communicate with each other. The
 
 - An actor has its own internal, encapsulated state that can only be updated by the actor itself. An actor may choose to update its internal state in response to a message it receives, but it cannot be updated by any other entity.
 - Actors communicate with other actors by sending and receiving events asynchronously.
-- Actors process one message at a time. They have an internal “mailbox” that acts like an event queue, processing events one at a time.
+- Actors process one message at a time. They have an internal “mailbox” that acts like an event queue, processing events sequentially.
 - Internal actor state is not shared between actors. The only way for an actor to share any part of its internal state is by:
   - Sending events to other actors
   - Or emitting snapshots, which can be considered implicit events sent to subscribers.
 - Actors can create (spawn/invoke) new actors.
 
+[Read more about the Actor model](actor-model.mdx)
+
 ## Actor logic
 
 Actor logic is the actor’s logical “model” (brain, blueprint, DNA, etc.) It describes how the actor should change behavior when receiving an event. You can create actor logic using **[actor logic creators](#actor-logic-creators)**.