From dc55ffcf9cf3592b822bbdb90b63c72ed61ec668 Mon Sep 17 00:00:00 2001 From: Benoit Germain Date: Thu, 4 Jul 2024 09:47:12 +0200 Subject: Documentation for coroutine lanes --- docs/index.html | 70 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 60 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 4fd7447..3afa7f0 100644 --- a/docs/index.html +++ b/docs/index.html @@ -777,7 +777,7 @@ Change HAVE_DECODA_SUPPORT() in lanesconf.h to enable the Decoda support, that sets a special global variable decoda_name in the lane's state.
The name is stored inside the Lua state registry so that it is available for error reporting. Changing decoda_name doesn't affect this hidden name or the OS thread name reported by MSVC.
When Lanes is initialized by the first lanes.configure() call, "main" is stored in the registry in the same fashion (but decoda_name and the OS thread name are left unchanged).
- The lane also has a method lane:get_debug_threadname() that gives access to that name from the caller side (returns "<unnamed>" if unset, "<closed>" if the internal Lua state is closed).
+ The lane also has a method lane:get_threadname() that gives access to that name from the caller side (returns "<unnamed>" if unset, "<closed>" if the internal Lua state is closed).
With Lua 5.4, Lanes have a __close metamethod, meaning they can be declared to-be-closed. __close calls lane:join(nil).

@@ -794,6 +794,32 @@

+

Coroutine lanes

+ +

+ It is possible to have the Lane body run inside the lane as a coroutine. For this, just use lanes.coro() instead of lanes.gen(). + + + + + +
+ 
	local lane_h = lanes.coro(...)(...)
+
+ + Coroutine lanes function mostly like regular coroutines. They can use coroutine.yield() normally, in which case the yielded values can be obtained with regular lane indexing (see Results and errors).
+ A yielded coroutine Lane has a "suspended" status. It can be resumed with lane_h:resume(values...). + + + + +
+ 
	local yielded_values = lane_h:resume(reply_values...)
+
+ + The reply values are returned to the lane body at the coroutine.yield() point.
+ If the yielded values were previously obtained by lane indexing, resume() returns nil. +

Free running lanes

@@ -873,7 +899,7 @@

- The current execution state of a lane can be read via its status member, providing one of these values: (2) + The current execution state of a lane can be read via its status member, providing one of these values: @@ -895,7 +921,31 @@ + + + + + + + + @@ -905,7 +955,7 @@ @@ -915,7 +965,7 @@ @@ -925,7 +975,7 @@ @@ -935,7 +985,7 @@
- running, not suspended on a Linda call. + Running, not suspended on a Linda call, or yielded on a coroutine.yield() call. +
+ + + "suspended" + + + + Coroutine lane stopped at a coroutine.yield() point. +
+ + + "resuming" + + + + Parent state called lane_h:resume() on a suspended coroutine lane, but the lane hasn't yet actually resumed execution.
- waiting at a Linda :receive() or :send() + Waiting at a Linda :receive() or :send()
- finished executing (results are ready) + Finished executing (results are ready)
- met an error (reading results will propagate it) + Met an error (reading results will propagate it)
- received cancellation and finished itself. + Received cancellation and finished itself.
@@ -982,7 +1032,7 @@

- Makes sure lane has finished, and gives its first (maybe only) return value. Other return values will be available in other lane_h indices. + Makes sure lane has finished or yielded, and gives its first (maybe only) return value. Other return values will be available in other lane_h indices.
If the lane ended in an error, it is propagated to master state at this place.

@@ -992,7 +1042,7 @@

- Waits until the lane finishes, or timeout seconds have passed (forever if nil).
+ Waits until the lane finishes/yields, or timeout seconds have passed (forever if nil).
Unlike in reading the results in table fashion, errors are not propagated.
Possible return values are: