<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Continuation - Class Continuation</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class Continuation</h1>
<p class="faldoc_brief">Intra-context suspension and resume control device. </p>
<p class="faldoc_funcdecl">
<b>class</b> Continuation( callable )
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#__call">__call()</a></td><td>Enters into or exit from a continuation. </td></tr>
<tr><td><a href="#complete">complete()</a></td><td>Indicates if the continuation has been completely executed or not. </td></tr>
<tr><td><a href="#reset">reset()</a></td><td>Clears the continuation state. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Continuation( callable )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">callable</td><td class="faldoc_paramdesc">A function or any callable item. </td></tr>
</table>
<br/>
<p class="item_brief">Intra-context suspension and resume control device. </p>
<p class="faldoc_text">This instances of this class can be used to execute some code that can be interrupted at any time and resumed later from the point they were interrupted. </p>
<p class="faldoc_text"> The function or other callable item set as the parameter in the constructor of this class will receive a special copy of the instance when this instance is called as a <i>functor</i>. For example: </p>
<pre class="faldoc_code">
function callable( cont )
> cont.toString()
end
c = Continuation( callable )
c() // will call callable( c )
</pre>
<p class="faldoc_text"> The special instance which is passed to the <b>callable</b> item is itself a functor. Calling it causes immediate suspension and return to the original frame where the continuation instance was first called. An optional value can be returned to the caller by passing it as a parameter of the continuation instance. </p>
<p class="faldoc_text">For example; the following code returns to the continuation first caller if the random number matches a dividend of a "secret" number. </p>
<pre class="faldoc_code">
c = Continuation( { secret, c =>
while true
r = random( 2, secret )
if secret % r == 0
c(r) // return "r" to our caller
end
end })
> "A random factor of 136: ", c(136)
</pre>
<p class="faldoc_text">Other than returning immediately to the first caller of the continuation, the current state of the called sequence is recorded and restored when subsequent calls are performed. In those calls, parameters are ignored (they stay the same as the first call). The following code returns the position where a given element is found in an array: </p>
<pre class="faldoc_code">
c = Continuation( { elem, array, c =>
for n in [0: array.len()]
if array[n] == elem: c(n)
end })
while (pos = c(10, [1,"a",10,5,10] ))
> "Found a '10' at pos ", pos
end
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> It is not possible to use continuations in atomic calls; for/in generators are called as atomically, so it's not possible to use continuations as generators in for/in loops. Use standard \b while loops instead. </p>
<p class="faldoc_text">Separate continuations calling the same functions have a completely different state. </p>
<p class="faldoc_text"> Also, the <a href="./class_Continuation.html#reset">Continuation.reset</a> method clears any previously existing state of a continuation, so that it can be called anew again without the need to recreate it. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="__call">__call()</a></h3>
<p class="item_brief">Enters into or exit from a continuation. </p>
<p class="faldoc_funcdecl">Continuation.__call( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">parameters passed to the callable stored in the instance, or to the return value. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The parameter passed to this method from inside the continuation. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> For the complete usage pattern, see the <a href="./class_Continuation.html">Continuation</a> class. </p>
</p>
<h3 class="faldoc_funcname"><a name="complete">complete()</a></h3>
<p class="item_brief">Indicates if the continuation has been completely executed or not. </p>
<p class="faldoc_funcdecl">Continuation.complete( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the continuation code has exited through any mean except calling the continuation. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">When the code inside the continuation calls the continuation, it means it has more operations to perform; the calling code may then decide to call the continuation to let it continue, or to reset it, or just to discard it. </p>
</p>
<h3 class="faldoc_funcname"><a name="reset">reset()</a></h3>
<p class="item_brief">Clears the continuation state. </p>
<p class="faldoc_funcdecl">Continuation.reset( )</p>
<p class="faldoc_text"><p class="faldoc_text">Allows to recycle a continuation after it is terminated, or at any moment. This must be called when the continuation has returned the control to its caller: it has no effect otherwise. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
