add warning and yield docs to readme

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)