From cdf9c8648f81dd4f2795a71b075aab75f01a9f1f Mon Sep 17 00:00:00 2001
From: Jim Mussared <jim.mussared@gmail.com>
Date: Mon, 15 Feb 2021 17:28:15 +1100
Subject: [PATCH] docs/library/uasyncio.rst: Add docs for ThreadSafeFlag.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
---
 docs/library/uasyncio.rst | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/library/uasyncio.rst b/docs/library/uasyncio.rst
index 3316f908d6..1efee56e96 100644
--- a/docs/library/uasyncio.rst
+++ b/docs/library/uasyncio.rst
@@ -125,6 +125,9 @@ class Event
 
     Set the event.  Any tasks waiting on the event will be scheduled to run.
 
+    Note: This must be called from within a task. It is not safe to call this
+    from an IRQ, scheduler callback, or other thread. See `ThreadSafeFlag`.
+
 .. method:: Event.clear()
 
     Clear the event.
@@ -136,6 +139,29 @@ class Event
 
     This is a coroutine.
 
+class ThreadSafeFlag
+--------------------
+
+.. class:: ThreadSafeFlag()
+
+    Create a new flag which can be used to synchronise a task with code running
+    outside the asyncio loop, such as other threads, IRQs, or scheduler
+    callbacks.  Flags start in the cleared state.
+
+.. method:: ThreadSafeFlag.set()
+
+    Set the flag.  If there is a task waiting on the event, it will be scheduled
+    to run.
+
+.. method:: ThreadSafeFlag.wait()
+
+    Wait for the flag to be set.  If the flag is already set then it returns
+    immediately.
+
+    A flag may only be waited on by a single task at a time.
+
+    This is a coroutine.
+
 class Lock
 ----------
 
@@ -188,7 +214,7 @@ TCP stream connections
     This is a coroutine.
 
 .. class:: Stream()
-    
+
     This represents a TCP stream connection.  To minimise code this class implements
     both a reader and a writer, and both ``StreamReader`` and ``StreamWriter`` alias to
     this class.