aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/LuaJIT-1.1.7/jitdoc/coco_api.html
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/LuaJIT-1.1.7/jitdoc/coco_api.html')
-rw-r--r--libraries/LuaJIT-1.1.7/jitdoc/coco_api.html182
1 files changed, 182 insertions, 0 deletions
diff --git a/libraries/LuaJIT-1.1.7/jitdoc/coco_api.html b/libraries/LuaJIT-1.1.7/jitdoc/coco_api.html
new file mode 100644
index 0000000..990ac5b
--- /dev/null
+++ b/libraries/LuaJIT-1.1.7/jitdoc/coco_api.html
@@ -0,0 +1,182 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Coco API Extensions</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6<meta name="Author" content="Mike Pall">
7<meta name="Copyright" content="Copyright (C) 2005-2011, Mike Pall">
8<meta name="Language" content="en">
9<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
10<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
11</head>
12<body>
13<div id="site">
14<a href="http://luajit.org/"><span>Lua<span id="logo">JIT</span></span></a>
15</div>
16<div id="head">
17<h1>Coco API Extensions</h1>
18</div>
19<div id="nav">
20<ul><li>
21<a href="index.html">Index</a>
22</li><li>
23<a href="luajit.html">LuaJIT</a>
24<ul><li>
25<a href="luajit_features.html">Features</a>
26</li><li>
27<a href="luajit_install.html">Installation</a>
28</li><li>
29<a href="luajit_run.html">Running</a>
30</li><li>
31<a href="luajit_api.html">API Extensions</a>
32</li><li>
33<a href="luajit_intro.html">Introduction</a>
34</li><li>
35<a href="luajit_performance.html">Performance</a>
36</li><li>
37<a href="luajit_debug.html">Debugging</a>
38</li><li>
39<a href="luajit_changes.html">Changes</a>
40</li></ul>
41</li><li>
42<a href="coco.html">Coco</a>
43<ul><li>
44<a href="coco_portability.html">Portability</a>
45</li><li>
46<a class="current" href="coco_api.html">API Extensions</a>
47</li><li>
48<a href="coco_changes.html">Changes</a>
49</li></ul>
50</li><li>
51<a href="dynasm.html">DynASM</a>
52<ul><li>
53<a href="dynasm_features.html">Features</a>
54</li><li>
55<a href="dynasm_examples.html">Examples</a>
56</li></ul>
57</li><li>
58<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
59</li></ul>
60</div>
61<div id="main">
62<p>
63Coco changes the semantics of several standard API functions and
64provides a few API extensions for Lua.
65</p>
66<p>
67By default all your coroutines get an associated C&nbsp;stack.
68If you want to be more selective, see below.
69</p>
70
71<h2>Lua API extensions</h2>
72<p>
73All <tt>coroutine.*</tt> functions should be fully upwards compatible.
74</p>
75
76<h3><tt>coroutine.coco</tt></h3>
77<p>
78This field is <tt>true</tt> when Coco is present (nil otherwise).
79</p>
80
81<h3><tt>coro = coroutine.create(f [, cstacksize])<br>
82func = coroutine.wrap(f [, cstacksize])</tt></h3>
83<p>
84The optional argument <tt>cstacksize</tt> specifies the size of the
85C&nbsp;stack to allocate for the coroutine:
86</p>
87<ul>
88<li>A default stack size is used if <tt>cstacksize</tt> is not given
89or is nil or zero.</li>
90<li>No C&nbsp;stack is allocated if <tt>cstacksize</tt> is -1.</li>
91<li>Any other value is rounded up to the minimum size
92(i.e. use 1 to get the minimum size).</li>
93</ul>
94<p>
95Important notice for LuaJIT: JIT compiled functions cannot
96yield if a coroutine does not have a dedicated C&nbsp;stack.
97</p>
98
99<h3><tt>olddefault = coroutine.cstacksize([newdefault])</tt></h3>
100<p>
101Returns the current default C&nbsp;stack size (may be 0 if the
102underlying context switch method has its own default).
103Sets a new default C&nbsp;stack size if <tt>newdefault</tt> is present.
104Use 0 to reset it to the default C&nbsp;stack size. Any other
105value is rounded up to the minimum size.
106</p>
107
108<h2>C&nbsp;API extensions</h2>
109<p>
110All C&nbsp;API functions are either unchanged or upwards compatible.
111</p>
112
113<h3><tt>int lua_yield(lua_State *L, int nresults)</tt></h3>
114<p>
115The semantics for <tt>lua_yield()</tt> have changed slightly.
116Existing programs should work fine as long as they follow
117the usage conventions from the Lua manual:
118</p>
119<pre>
120return lua_yield(L, nresults);
121</pre>
122<p>
123Previously <tt>lua_yield()</tt> returned a 'magic' value (<tt>-1</tt>) that
124indicated a yield. Your C&nbsp;function had to pass this value
125on to the Lua core and was <em>not</em> called again.
126</p>
127<p>
128Now, if the current coroutine has an associated C&nbsp;stack,
129<tt>lua_yield()</tt> returns the number of arguments passed back from
130the resume. This just happens to be the right convention for
131returning them as a result from a C&nbsp;function. I.e. if you
132used the above convention, you'll never notice the change.
133</p>
134<p>
135But the results <em>are</em> on the Lua stack when <tt>lua_yield()</tt>
136returns. So the C&nbsp;function can just continue and process them
137or retry an I/O operation etc. And your whole C&nbsp;stack frame
138(local variables etc.) is still there, too. You can yield from
139anywhere in your C&nbsp;program, even several call levels deeper.
140</p>
141<p>
142Of course all of this only works with Lua+Coco and not with standard Lua.
143</p>
144
145<h3><tt>lua_State *lua_newcthread(lua_State *L, int cstacksize)</tt></h3>
146<p>
147This is an (optional) new function that allows you to create
148a coroutine with an associated C&nbsp;stack directly from the C&nbsp;API.
149Other than that it works the same as <tt>lua_newthread(L)</tt>.
150</p>
151<p>
152You have to declare this function as <tt>extern</tt>
153yourself, since it's not part of the official Lua API.
154This means that a C&nbsp;module that uses this call cannot
155be loaded with standard Lua. This may be intentional.
156</p>
157<p>
158If you want your C&nbsp;module to work with both standard Lua
159and Lua+Coco you can check whether Coco is available with:
160</p>
161<pre>
162 lua_getfield(L, LUA_GLOBALSINDEX, "coroutine");
163 lua_getfield(L, -1, "coco");
164 coco_available = lua_toboolean(L, -1);
165 lua_pop(L, 2);
166</pre>
167<p>
168You can create coroutines with a C&nbsp;stack by calling
169the Lua function <tt>coroutine.create()</tt> from C, too.
170</p>
171<br class="flush">
172</div>
173<div id="foot">
174<hr class="hide">
175Copyright &copy; 2005-2011 Mike Pall
176<span class="noprint">
177&middot;
178<a href="contact.html">Contact</a>
179</span>
180</div>
181</body>
182</html>
generated by cgit v1.1 at 2025-01-12 12:42:55 +0000