Skip to content

Commit 179f886

Browse files
committed
THREADING.md: Fix broken link, add installation notes.
1 parent 9c8d45a commit 179f886

File tree

1 file changed

+15
-5
lines changed

1 file changed

+15
-5
lines changed

v3/docs/THREADING.md

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ is fixed.
3232
2.1 [A pool](./THREADING.md#21-a-pool) Sharing a set of variables.
3333
2.2 [ThreadSafeQueue](./THREADING.md#22-threadsafequeue)
3434
     2.2.1 [Blocking](./THREADING.md#221-blocking)
35-
     2.2.3 [Object ownership](./THREADING.md#223-object-ownership)
35+
     2.2.2 [Object ownership](./THREADING.md#222-object-ownership)
36+
     2.2.3 [A complete example](./THREADING.md#223-a-complete-example)
3637
3. [Synchronisation](./THREADING.md#3-synchronisation)
3738
3.1 [Threadsafe Event](./THREADING.md#31-threadsafe-event)
3839
3.2 [Message](./THREADING.md#32-message) A threadsafe event with data payload.
@@ -192,6 +193,8 @@ Globals are implemented as a `dict`. Adding or deleting an entry is unsafe in
192193
the main program if there is a context which accesses global data and does not
193194
use the GIL. This means hard ISR's and code running on another core. Given that
194195
shared global data is widely used, the following guidelines should be followed.
196+
([This pr](https://github.com/micropython/micropython/pull/11604) aims to fix
197+
this issue).
195198

196199
All globals should be declared in the main program before an ISR starts to run,
197200
and before code on another core is started. It is valid to insert placeholder
@@ -301,7 +304,9 @@ read is in progress.
301304

302305
This queue is designed to interface between one `uasyncio` task and a single
303306
thread running in a different context. This can be an interrupt service routine
304-
(ISR), code running in a different thread or code on a different core.
307+
(ISR), code running in a different thread or code on a different core. See
308+
[section 2.2.3](./THREADING.md#223-a-complete-example) for a complete usage
309+
example.
305310

306311
Any Python object may be placed on a `ThreadSafeQueue`. If bi-directional
307312
communication is required between the two contexts, two `ThreadSafeQueue`
@@ -342,7 +347,6 @@ Asynchronous methods:
342347
will block until an object is put on the queue. Normal retrieval is with
343348
`async for` but this method provides an alternative.
344349

345-
346350
In use as a data consumer the `uasyncio` code will use `async for` to retrieve
347351
items from the queue. If it is a data provider it will use `put` to place
348352
objects on the queue.
@@ -428,6 +432,8 @@ the MicroPython garbage collector delete them as per the first sample.
428432

429433
This demonstrates an echo server running on core 2. The `sender` task sends
430434
consecutive integers to the server, which echoes them back on a second queue.
435+
To install the threadsafe primitives, the `threadsafe` directory and its
436+
contents should be copied to the MicroPython target.
431437
```python
432438
import uasyncio as asyncio
433439
from threadsafe import ThreadSafeQueue
@@ -480,7 +486,9 @@ and other pending tasks have run, the waiting task resumes.
480486
The `ThreadsafeFlag` has a limitation in that only a single task can wait on
481487
it. The `ThreadSafeEvent` overcomes this. It is subclassed from `Event` and
482488
presents the same interface. The `set` method may be called from an ISR or from
483-
code running on another core. Any number of tasks may wait on it.
489+
code running on another core. Any number of tasks may wait on it. To install
490+
the threadsafe primitives, the `threadsafe` directory and its contents should
491+
be copied to the MicroPython target.
484492

485493
The following Pyboard-specific code demos its use in a hard ISR:
486494
```python
@@ -546,7 +554,9 @@ the `Message` as below. A `Message` can provide a means of communication from
546554
an interrupt handler and a task. The handler services the hardware and issues
547555
`.set()` which causes the waiting task to resume (in relatively slow time).
548556

549-
This illustrates basic usage:
557+
To install the threadsafe primitives, the `threadsafe` directory and its
558+
contents should be copied to the MicroPython target. This illustrates basic
559+
usage:
550560
```python
551561
import uasyncio as asyncio
552562
from threadsafe import Message

0 commit comments

Comments
 (0)