From c028e03d321a10119c687e8c49d06e2b8ec9cb0d Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Sat, 27 Jun 2026 22:14:34 -0400
Subject: [PATCH] Update quickstart `we_are_processes` walkthrough

The reworked `we_are_processes.py` (now `Context`-API based) prints
different stdout, so the hardcoded expected-output block went
stale: swap the old `Yo, i'm 'worker_N'...` / "self-destruct in 1
sec" lines for the real run - "self-destruct in 2s.." then the
per-worker `Started ep-task in subactor,` / `N::'worker_N'@<pid>`
blocks.

Also retell the prose to match: subs spawn concurrently from bg
`trio` tasks, each runs a `@tractor.context` `endpoint()` that
`ctx.started()`-hands its name + pid back through
`Portal.open_context()`, then parks in `trio.sleep_forever()`
before the root crashes + the tree is reaped.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 docs/start/quickstart.rst | 45 ++++++++++++++++++++++++++-------------
 1 file changed, 30 insertions(+), 15 deletions(-)

diff --git a/docs/start/quickstart.rst b/docs/start/quickstart.rst
index db50eb7e..fabf4d8e 100644
--- a/docs/start/quickstart.rst
+++ b/docs/start/quickstart.rst
@@ -144,26 +144,41 @@ breakfast - run this while monitoring your process tree::
    ``_subactor[worker_0@<pid>]``, so ``pstree``/``htop``/
    ``pgrep -f`` can tell your actors apart at a glance.
 
-You'll see something like::
+You'll see something like (one subactor per core - 24 on this box,
+trimmed here)::
 
     $ python examples/parallelism/we_are_processes.py
-    Yo, i'm 'worker_2' running in pid 1777246
-    Yo, i'm 'worker_0' running in pid 1777244
-    Yo, i'm 'worker_3' running in pid 1777247
-    Yo, i'm 'worker_1' running in pid 1777245
-    This process tree will self-destruct in 1 sec...
+    This tree will self-destruct in 2s..
+
+    Started ep-task in subactor,
+    0::'worker_0'@218140
+
+    Started ep-task in subactor,
+    2::'worker_2'@218134
+
+    Started ep-task in subactor,
+    1::'worker_1'@218137
+
+    Started ep-task in subactor,
+    3::'worker_3'@218132
+
     Zombies Contained
 
-(The worker lines land in whatever order the OS schedules them;
-they're separate *processes*, racing, and that's the point.)
+(The ``Started ep-task`` lines land in whatever order the OS
+schedules them; they're separate *processes*, racing, and that's
+the point.)
 
-An actor is spawned per core, each parks itself in
-``trio.sleep_forever()``... and then the root *crashes on
-purpose*. The ``ActorNursery`` responds with hard ``trio``
-discipline: every child is cancelled, every process is reaped,
-the error propagates to ``trio.run()``, and your terminal prints
-``Zombies Contained``. No orphans, no ``kill -9`` archaeology in
-``htop`` afterwards.
+One subactor is spawned per core - concurrently, from background
+``trio`` tasks, so each child's cold ``import tractor`` overlaps
+instead of stacking. Each runs a ``@tractor.context``
+``endpoint()`` that ``ctx.started()``-hands its name and pid back
+through ``Portal.open_context()`` (those ``Started ep-task``
+lines), then parks in ``trio.sleep_forever()``. Then the root
+*crashes on purpose* and the ``ActorNursery`` responds with hard
+``trio`` discipline: every child is cancelled, every process is
+reaped, the error propagates to ``trio.run()``, and your terminal
+prints ``Zombies Contained``. No orphans, no ``kill -9``
+archaeology in ``htop`` afterwards.
 
 .. note::