From a22bd9dba264e70ee7ea7dc2027af4b076890e43 Mon Sep 17 00:00:00 2001 From: Zee Date: Fri, 8 Jan 2021 21:04:01 +0800 Subject: [PATCH] doc: Update usage.md --- doc/usage.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/usage.md b/doc/usage.md index cb0d1929..dbfc42d6 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -54,7 +54,9 @@ Handle to cothread. Handle must be of type `void*`. -A value of `null` (0) indicates an uninitialized or invalid handle, whereas a non-zero value indicates a valid handle. +A value of null (0) indicates an uninitialized or invalid handle, whereas a +non-zero value indicates a valid handle. A valid handle is backed by execution +state to which the execution can be co_switch()ed to. ## co_active ```c @@ -62,7 +64,12 @@ cothread_t co_active(); ``` Return handle to current cothread. -Always returns a valid handle, even when called from the main program thread. +Note that the handle is valid even if the function is called from a non-cothread +context. To achieve this, we save the execution state in an internal buffer, +instead of using the user-provided memory. Since this handle is valid, it can +be used to co_switch to this context from another cothread. In multi-threaded +applications, make sure to not switch non-cothread context across CPU cores, +to prevent any possible conflicts with the OS scheduler. ## co_derive ```c