From acfbf952bceb728ae9a7a659500b1e846c5e0592 Mon Sep 17 00:00:00 2001
From: Layl Bongers <3094382+LaylBongers@users.noreply.github.com>
Date: Wed, 23 Aug 2023 22:10:16 +0200
Subject: [PATCH] Update actor explanation

---
 docs/src/actors-theory.md | 51 ++++++++++++++++++++++++++-------------
 1 file changed, 34 insertions(+), 17 deletions(-)

diff --git a/docs/src/actors-theory.md b/docs/src/actors-theory.md
index 34cf81d..be453c1 100644
--- a/docs/src/actors-theory.md
+++ b/docs/src/actors-theory.md
@@ -1,24 +1,41 @@
 # Actors Theory
 
-Stewart is built around the "actor" pattern.
-This pattern is implemented in different ways at different levels.
-It's good to understand the theoretical concept of "actors", to understand how to use them.
-This theory primer gives a quick *heavily generalized* explanations of what actors are.
+Functions are great!
+When you need to "abstract" something you want your code to do, you simply wrap it in a name with
+some parameters.
+This makes it a lot easier to reason around what you're making, and what your code is doing.
 
-Actors are a method of organizing "asynchronous" components of software.
-Actor systems typically, but not always, have the following traits:
+Sometimes, however, you need to create a task that needs to 'wait' on something.
+Maybe you have to wait for a network adapter to receive a packet, or wait for another task to be
+done performing some intensive calculations.
 
-- Maintain a persistent state.
-- Communicate with other actors, and the outside world, through messages.
-- 'Suspended' execution, until new messages arrive.
+While it's perfectly *possible* to use OS threads for this, and 'block' the current one until you
+get what you need, this is very resource-intensive.
+Additionally, OS threads usually don't expect to be rapidly switching between a lot of different
+threads in more complex programs.
 
-This is very similar to the idea of "futures" or "promises".
-This "async-await" model of futures is used to 'suspend' a function until the response it's waiting
-for is available.
+## `async-await`
 
-In contrast to futures, actors are an ongoing 'process'.
-Actors don't suspend on another function's result, rather they *reactively* respond to incoming
-messages.
+One approach to solving this instead is using the "async-await" pattern.
+With this pattern you can still write your functions as normal, but additionally you can 'await' on
+something before continuing.
 
-In Rust, futures are implemented very similar to the actor model, even if typically you use them
-with the `async` and `await` keywords.
+How this is implemented depends on the language.
+Rust for example, will 'generate' a state machine for your function.
+This is nice, as it can track a lot of guarantees about memory and ownership semantics.
+
+There are a few downsides to this approach.
+A lot of complexity happens behind the scenes, making it a lot harder to reason about your code.
+As well, while this pattern is well suited to a linear set of steps, it doesn't model ongoing
+processes as well.
+
+## The Actor Pattern
+
+Enter, the "Actor Pattern".
+Conceptually, actors are cooperative multitasking tasks, that communicate through messages.
+This is, of course, highly simplifying and generalizing the concept.
+The computer science of actors is however outside the scope of this guide.
+
+In contrast to `async-await`, actors hide very little in how they work.
+An actor maintains its internal state manually.
+Its handler function returns when it is done processing, yielding back to the runtime.