Skip to content

Commit ffeb61c

Browse files
committed
Tutorial: improve section on ThreadSafeFlag.
1 parent c300516 commit ffeb61c

File tree

1 file changed

+15
-11
lines changed

1 file changed

+15
-11
lines changed

v3/docs/TUTORIAL.md

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -895,12 +895,9 @@ following key differences:
895895
* It is self-clearing.
896896
* Only one task may wait on the flag.
897897

898-
The latter limitation may be addressed by having a task wait on a
899-
`ThreadSafeFlag` before setting an `Event`. Multiple tasks may wait on that
900-
`Event`.
901-
902898
Synchronous method:
903899
* `set` Triggers the flag. Like issuing `set` then `clear` to an `Event`.
900+
904901
Asynchronous method:
905902
* `wait` Wait for the flag to be set. If the flag is already set then it
906903
returns immediately.
@@ -925,7 +922,7 @@ tim = Timer(1, freq=1, callback=cb)
925922

926923
asyncio.run(foo())
927924
```
928-
Another example (posted by [Damien](https://github.com/micropython/micropython/pull/6886#issuecomment-779863757)):
925+
Another example ([posted by Damien](https://github.com/micropython/micropython/pull/6886#issuecomment-779863757)):
929926
```python
930927
class AsyncPin:
931928
def __init__(self, pin, trigger):
@@ -939,16 +936,23 @@ class AsyncPin:
939936
You then call `await async_pin.wait_edge()`.
940937

941938
The current implementation provides no performance benefits against polling the
942-
hardware. The `ThreadSafeFlag` uses the I/O mechanism. There are plans to
943-
reduce the latency such that I/O is polled every time the scheduler acquires
944-
control. This would provide the highest possible level of performance as
945-
discussed in
939+
hardware: other pending tasks may be granted execution first in round-robin
940+
fashion. However the `ThreadSafeFlag` uses the I/O mechanism. There is a plan
941+
to provide a means to reduce the latency such that selected I/O devices are
942+
polled every time the scheduler acquires control. This will provide the highest
943+
possible level of performance as discussed in
946944
[Polling vs Interrupts](./TUTORIAL.md#9-polling-vs-interrupts).
947945

948946
Regardless of performance issues, a key use for `ThreadSafeFlag` is where a
949947
hardware device requires the use of an ISR for a μs level response. Having
950-
serviced the device, it then flags an asynchronous routine, for example to
951-
process data received.
948+
serviced the device, the ISR flags an asynchronous routine, say to process
949+
received data.
950+
951+
The fact that only one task may wait on a `ThreadSafeFlag` may be addressed by
952+
having the task that waits on the `ThreadSafeFlag` set an `Event`. Multiple
953+
tasks may wait on that `Event`. As an alternative to explicitly coding this,
954+
the [Message class](./TUTORIAL.md#39-message) uses this approach to provide an
955+
`Event`-like object which can be triggered from an ISR.
952956

953957
###### [Contents](./TUTORIAL.md#contents)
954958

0 commit comments

Comments
 (0)