aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorBenoit Germain <benoit.germain@ubisoft.com>2024-07-04 09:47:12 +0200
committerBenoit Germain <benoit.germain@ubisoft.com>2024-07-04 09:47:12 +0200
commitdc55ffcf9cf3592b822bbdb90b63c72ed61ec668 (patch)
treee3d3aa7dc8abc028146a13961821a26fd224dbcc /docs
parentf3b7facea8de585dda1d4f5bd1d9716b40b1ce94 (diff)
downloadlanes-dc55ffcf9cf3592b822bbdb90b63c72ed61ec668.tar.gz
lanes-dc55ffcf9cf3592b822bbdb90b63c72ed61ec668.tar.bz2
lanes-dc55ffcf9cf3592b822bbdb90b63c72ed61ec668.zip
Documentation for coroutine lanes
Diffstat (limited to 'docs')
-rw-r--r--docs/index.html70
1 files changed, 60 insertions, 10 deletions
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 @@
777 Change <tt>HAVE_DECODA_SUPPORT()</tt> in <tt>lanesconf.h</tt> to enable the Decoda support, that sets a special global variable <tt>decoda_name</tt> in the lane's state.<br /> 777 Change <tt>HAVE_DECODA_SUPPORT()</tt> in <tt>lanesconf.h</tt> to enable the Decoda support, that sets a special global variable <tt>decoda_name</tt> in the lane's state.<br />
778 The name is stored inside the Lua state registry so that it is available for error reporting. Changing <tt>decoda_name</tt> doesn't affect this hidden name or the OS thread name reported by MSVC.<br /> 778 The name is stored inside the Lua state registry so that it is available for error reporting. Changing <tt>decoda_name</tt> doesn't affect this hidden name or the OS thread name reported by MSVC.<br />
779 When Lanes is initialized by the first <a href="#initialization"><tt>lanes.configure()</tt></a> call, <tt>"main"</tt> is stored in the registry in the same fashion (but <tt>decoda_name</tt> and the OS thread name are left unchanged).<br /> 779 When Lanes is initialized by the first <a href="#initialization"><tt>lanes.configure()</tt></a> call, <tt>"main"</tt> is stored in the registry in the same fashion (but <tt>decoda_name</tt> and the OS thread name are left unchanged).<br />
780 The lane also has a method <tt>lane:get_debug_threadname()</tt> that gives access to that name from the caller side (returns <tt>"&lt;unnamed&gt;"</tt> if unset, <tt>"&lt;closed&gt;"</tt> if the internal Lua state is closed).<br /> 780 The lane also has a method <tt>lane:get_threadname()</tt> that gives access to that name from the caller side (returns <tt>"&lt;unnamed&gt;"</tt> if unset, <tt>"&lt;closed&gt;"</tt> if the internal Lua state is closed).<br />
781 With Lua 5.4, Lanes have a <tt>__close</tt> metamethod, meaning they can be declared to-be-closed. <tt>__close</tt> calls <tt>lane:join(nil)</tt>. 781 With Lua 5.4, Lanes have a <tt>__close</tt> metamethod, meaning they can be declared to-be-closed. <tt>__close</tt> calls <tt>lane:join(nil)</tt>.
782</p> 782</p>
783 783
@@ -794,6 +794,32 @@
794 </table> 794 </table>
795</p> 795</p>
796 796
797<h3 id="coroutines">Coroutine lanes</h3>
798
799<p>
800 It is possible to have the Lane body run inside the lane as a coroutine. For this, just use <tt>lanes.coro()</tt> instead of <tt>lanes.gen()</tt>.
801
802 <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
803 <tr>
804 <td>
805 <pre> local lane_h = lanes.coro(...)(...)</pre>
806 </td>
807 </tr>
808 </table>
809
810 Coroutine lanes function mostly like regular coroutines. They can use <tt>coroutine.yield()</tt> normally, in which case the yielded values can be obtained with regular lane indexing (see <a href="#results">Results and errors</a>).<br />
811 A yielded coroutine Lane has a <tt>"suspended"</tt> status. It can be resumed with <tt>lane_h:resume(values...)</tt>.
812 <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
813 <tr>
814 <td>
815 <pre> local yielded_values = lane_h:resume(reply_values...)</pre>
816 </td>
817 </tr>
818 </table>
819
820 The reply values are returned to the lane body at the <tt>coroutine.yield()</tt> point.<br />
821 If the yielded values were previously obtained by lane indexing, <tt>resume()</tt> returns <tt>nil</tt>.
822</p>
797<h3>Free running lanes</h3> 823<h3>Free running lanes</h3>
798 824
799<p> 825<p>
@@ -873,7 +899,7 @@
873 </table> 899 </table>
874 900
875<p> 901<p>
876 The current execution state of a lane can be read via its <tt>status</tt> member, providing one of these values: <sup>(<a href="#2">2</a>)</sup> 902 The current execution state of a lane can be read via its <tt>status</tt> member, providing one of these values:
877 903
878 <table style="width:100%"> 904 <table style="width:100%">
879 <tr> 905 <tr>
@@ -895,7 +921,31 @@
895 </td> 921 </td>
896 <td /> 922 <td />
897 <td> 923 <td>
898 running, not suspended on a <a href="#lindas">Linda</a> call. 924 Running, not suspended on a <a href="#lindas">Linda</a> call, or yielded on a <tt>coroutine.yield()</tt> call.
925 </td>
926 </tr>
927 <tr>
928 <td />
929 <td>
930 <tt>
931 "suspended"
932 </tt>
933 </td>
934 <td />
935 <td>
936 Coroutine lane stopped at a <tt>coroutine.yield()</tt> point.
937 </td>
938 </tr>
939 <tr>
940 <td />
941 <td>
942 <tt>
943 "resuming"
944 </tt>
945 </td>
946 <td />
947 <td>
948 Parent state called <tt>lane_h:resume()</tt> on a suspended <a href="#coroutines">coroutine</a> lane, but the lane hasn't yet actually resumed execution.
899 </td> 949 </td>
900 </tr> 950 </tr>
901 <tr> 951 <tr>
@@ -905,7 +955,7 @@
905 </td> 955 </td>
906 <td /> 956 <td />
907 <td> 957 <td>
908 waiting at a <a href="#lindas">Linda</a> <tt>:receive()</tt> or <tt>:send()</tt> 958 Waiting at a <a href="#lindas">Linda</a> <tt>:receive()</tt> or <tt>:send()</tt>
909 </td> 959 </td>
910 </tr> 960 </tr>
911 <tr> 961 <tr>
@@ -915,7 +965,7 @@
915 </td> 965 </td>
916 <td /> 966 <td />
917 <td> 967 <td>
918 finished executing (results are ready) 968 Finished executing (results are ready)
919 </td> 969 </td>
920 </tr> 970 </tr>
921 <tr> 971 <tr>
@@ -925,7 +975,7 @@
925 </td> 975 </td>
926 <td /> 976 <td />
927 <td> 977 <td>
928 met an error (reading results will propagate it) 978 Met an error (reading results will propagate it)
929 </td> 979 </td>
930 </tr> 980 </tr>
931 <tr> 981 <tr>
@@ -935,7 +985,7 @@
935 </td> 985 </td>
936 <td /> 986 <td />
937 <td> 987 <td>
938 received <a href="#cancelling">cancellation</a> and finished itself. 988 Received <a href="#cancelling">cancellation</a> and finished itself.
939 </td> 989 </td>
940 </tr> 990 </tr>
941 </table> 991 </table>
@@ -982,7 +1032,7 @@
982</pre></td></tr></table> 1032</pre></td></tr></table>
983 1033
984<p> 1034<p>
985 Makes sure lane has finished, and gives its first (maybe only) return value. Other return values will be available in other <tt>lane_h</tt> indices. 1035 Makes sure lane has finished or yielded, and gives its first (maybe only) return value. Other return values will be available in other <tt>lane_h</tt> indices.
986 <br /> 1036 <br />
987 If the lane ended in an error, it is propagated to master state at this place. 1037 If the lane ended in an error, it is propagated to master state at this place.
988</p> 1038</p>
@@ -992,7 +1042,7 @@
992</pre></td></tr></table> 1042</pre></td></tr></table>
993 1043
994<p> 1044<p>
995 Waits until the lane finishes, or <tt>timeout</tt> seconds have passed (forever if <tt>nil</tt>).<br /> 1045 Waits until the lane finishes/yields, or <tt>timeout</tt> seconds have passed (forever if <tt>nil</tt>).<br />
996 Unlike in reading the results in table fashion, errors are not propagated.<br /> 1046 Unlike in reading the results in table fashion, errors are not propagated.<br />
997 Possible return values are: 1047 Possible return values are:
998 <ul> 1048 <ul>
@@ -1109,7 +1159,7 @@
1109</p> 1159</p>
1110 1160
1111<p> 1161<p>
1112 Lanes registers a function <tt>set_finalizer</tt> in the lane's Lua state for doing this. 1162 Lanes registers a function <tt>set_finalizer()</tt> in the lane's Lua state for doing this.
1113 Any functions given to it will be called in the lane Lua state, just prior to closing it. It is possible to set more than one finalizer. They are not called in any particular order. 1163 Any functions given to it will be called in the lane Lua state, just prior to closing it. It is possible to set more than one finalizer. They are not called in any particular order.
1114</p> 1164</p>
1115 1165