From 94a6fefedebf77d0b285ddc8ac4ed764e6a2accb Mon Sep 17 00:00:00 2001
From: Tyler Goodlet <jgbt@protonmail.com>
Date: Tue, 2 Nov 2021 15:42:19 -0400
Subject: [PATCH] Add `open_actor_cluster()` eg. to readme

---
 docs/README.rst | 60 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/docs/README.rst b/docs/README.rst
index 15abc89..0d474fd 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -313,9 +313,69 @@ real time::
 This uses no extra threads, fancy semaphores or futures; all we need
 is ``tractor``'s IPC!
 
+To be extra terse the ``tractor`` devs have started hacking some "higher
+level" APIs for managing actor trees/clusters. These interfaces should
+generally be condsidered provisional for now but we encourage you to try
+them and provide feedback. Here's a new API that let's you quickly
+spawn a flat cluster:
+
+.. code:: python
+
+    from functools import partial
+
+    import trio
+    import tractor
+
+
+    async def sleepy_jane():
+        uid = tractor.current_actor().uid
+        print(f'Yo i am actor {uid}')
+        await trio.sleep_forever()
+
+
+    async def main():
+        '''
+        Spawn a flat actor cluster, with one process per
+        detected core.
+
+        '''
+        portal_map: dict[str, tractor.Portal]
+        results: dict[str, str]
+
+        # look at this hip new syntax!
+        async with (
+
+            tractor.open_actor_cluster(
+                modules=[__name__]
+            ) as portal_map,
+
+            trio.open_nursery() as n,
+        ):
+
+            for (name, portal) in portal_map.items():
+                n.start_soon(
+                    partial(
+                        portal.run,
+                        sleepy_jane,
+                    )
+                )
+
+            await trio.sleep(0.5)
+
+            # kill the cluster with a cancel
+            raise KeyboardInterrupt
+
+
+    if __name__ == '__main__':
+        try:
+            trio.run(main)
+        except KeyboardInterrupt:
+            pass
+
 
 .. _full worker pool re-implementation: https://github.com/goodboy/tractor/blob/master/examples/parallelism/concurrent_actors_primes.py
 
+
 Install
 -------
 From PyPi::