TUTORIAL.md: Document task group.

Author: peterhinch

v3/docs/TUTORIAL.md

@@ -27,7 +27,9 @@ REPL.
  3. [Synchronisation](./TUTORIAL.md#3-synchronisation)  
   3.1 [Lock](./TUTORIAL.md#31-lock)  
   3.2 [Event](./TUTORIAL.md#32-event)  
-  3.3 [gather](./TUTORIAL.md#33-gather)  
+  3.3 [Coordinating multiple tasks](./TUTORIAL.md#33-coordinating-multiple-tasks)  
+       3.3.1 [gather](./TUTORIAL.md#331-gather)  
+       3.3.2 [TaskGroups](./TUTORIAL.md#332-taskgroups)  
   3.4 [Semaphore](./TUTORIAL.md#34-semaphore)  
        3.4.1 [BoundedSemaphore](./TUTORIAL.md#341-boundedsemaphore)  
   3.5 [Queue](./TUTORIAL.md#35-queue)  
@@ -701,7 +703,15 @@ constant creation of tasks. Arguably the `Barrier` class is the best approach.
 
 ###### [Contents](./TUTORIAL.md#contents)
 
-## 3.3 gather
+## 3.3 Coordinating multiple tasks
+
+Several tasks may be launched together with the launching task pausing until
+all have completed. The `gather` mechanism is supported by CPython and
+MicroPython. CPython 3.11 adds a `TaskGroup` class which is particularly
+suited to applications where runtime exceptions may be encountered. It is not
+yet officially supported by MicroPython.
+
+### 3.3.1 gather
 
 This official `uasyncio` asynchronous method causes a number of tasks to run,
 pausing until all have either run to completion or been terminated by
@@ -714,7 +724,7 @@ res = await asyncio.gather(*tasks, return_exceptions=True)
 The keyword-only boolean arg `return_exceptions` determines the behaviour in
 the event of a cancellation or timeout of tasks. If `False` the `gather`
 terminates immediately, raising the relevant exception which should be trapped
-by the caller. If `True` the `gather` continues to block until all have either
+by the caller. If `True` the `gather` continues to pause until all have either
 run to completion or been terminated by cancellation or timeout. In this case
 tasks which have been terminated will return the exception object in the list
 of return values.
@@ -767,6 +777,73 @@ async def main():
         print('Cancelled')
     print('Result: ', res)
 
+asyncio.run(main())
+```
+### 3.3.2 TaskGroups
+
+The `TaskGroup` class is unofficially provided by
+[this PR](https://github.com/micropython/micropython/pull/8791). It is well
+suited to applications where one or more of a group of tasks is subject to
+runtime exceptions. A `TaskGroup` is instantiated in an asynchronous context
+manager. The `TaskGroup` instantiates member tasks. When all have run to
+completion the context manager terminates. Return values from member tasks
+cannot be retrieved. Results should be passed in other ways such as via bound
+variables, queues etc.
+
+An exception in a member task not trapped by that task is propagated to the
+task that created the `TaskGroup`. All tasks in the `TaskGroup` then terminate
+in an orderly fashion: cleanup code in any `finally` clause will run. When all
+cleanup code has completed, the context manager completes, and execution passes
+to an exception handler in an outer scope.
+
+If a member task is cancelled in code, that task terminates in an orderly way
+but the other members continue to run.
+
+The following illustrates the basic salient points of using a `TaskGroup`:
+```python
+import uasyncio as asyncio
+async def foo(n):
+    for x in range(10 + n):
+        print(f"Task {n} running.")
+        await asyncio.sleep(1 + n/10)
+    print(f"Task {n} done")
+
+async def main():
+    async with asyncio.TaskGroup() as tg:  # Context manager pauses until members terminate
+        for n in range(4):
+            tg.create_task(foo(n))  # tg.create_task() creates a member task
+    print("TaskGroup done")  # All tasks have terminated
+
+asyncio.run(main())
+```
+This more complete example illustrates an exception which is not trapped by the
+member task. Cleanup code on all members runs when the exception occurs,
+followed by exception handling code in `main()`.
+```python
+import uasyncio as asyncio
+fail = True  # Set False to demo normal completion
+async def foo(n):
+    print(f"Task {n} running...")
+    try:
+        for x in range(10 + n):
+            await asyncio.sleep(1 + n/10)
+            if n==0 and x==5 and fail:
+                raise OSError("Uncaught exception in task.")
+        print(f"Task {n} done")
+    finally:
+        print(f"Task {n} cleanup")
+
+async def main():
+    try:
+        async with asyncio.TaskGroup() as tg:
+            for n in range(4):
+                tg.create_task(foo(n))
+        print("TaskGroup done")  # Does not get here if a task throws exception
+    except Exception as e:
+        print(f'TaskGroup caught exception: "{e}"')
+    finally:
+        print("TaskGroup finally")
+
 asyncio.run(main())
 ```