From 5107b78ae59c289a1cd5897ac7cdf5aed84d4d86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= Date: Sat, 31 Oct 2020 19:00:46 +0100 Subject: [PATCH] add warning and yield docs to readme --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 4bc30fe..d9d4665 100644 --- a/README.md +++ b/README.md @@ -342,6 +342,11 @@ The coroutine is blocked until the value is consumed by someone. To consume a yi (ld r0 @r5) ; read a yielded value ``` +**Caution!!!** Due to the way this is implemented, the instruction that tries to use a yielded value might partially execute +before detecting that it is blocked, and will be retried when the thread is next scheduled to run. This has the consequence +that if something like a object handle is read by the same instruction, it may be read multiple times while waiting for the +yielded value. It is recommended to *never combine reads of a yielded value with reads of other object handles*. + ### Joining a coroutine Use the `join` instruction with a coroutine object handle to wait for its completion. @@ -480,6 +485,15 @@ Jumping to a label is always safer than a manual skip. ; Exit the current routine (or coroutine) with return values (ret Rd...) +; Yield control from a coroutine (use when waiting for a mutex to give control early to +; other coroutines that might be holding it) +(yield) + +; Yield a value generated by a coroutine. Gives up control and blocks until the value is consumed. +; Conversely, an instruction that tries to read a yielded value using the object handle is blocked +; until such value becomes available. +(yield Rd'value) + ; Wait for a coroutine to complete, read its return values and delete it. (join @Obj)