<ppdoc>
<copyright>
Copyright (c) 2001 by Addison Wesley Longman, Inc. This material may
be distributed only subject to the terms and conditions set forth in
the Open Publication License, v1.0 or later (the latest version is
presently available at http://www.opencontent.org/openpub/).
<p/>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<p/>
Distribution of the work or derivative of the work in any standard
(paper) book form is prohibited unless prior permission is obtained
from the copyright holder.
</copyright>
<class name="Continuation" super="Object" type="class" ref="xref-000001">
<p/>
  <classname>Continuation</classname> objects are generated by
  <mim><file>kernel</file><front>Kernel</front><back>callcc</back><mref>callcc</mref></mim>. They hold a return address and execution
  context, allowing a nonlocal return to the end of the <tt>callcc</tt>
  block from anywhere within a program. Continuations are somewhat
  analogous to a structured version of C's <tt>setjmp/longjmp</tt>
  (although they contain more state, so you might consider them closer
  to threads).
<p/>
  For instance:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[    arr = [ "Freddie", "Herbie", "Ron", "Max", "Ringo" ]
    callcc{|$cc|}
    puts(message = arr.shift)
    $cc.call unless message =~ /Max/
]]></fullcode>
arr<nbsp/>=<nbsp/>[<nbsp/>"Freddie",<nbsp/>"Herbie",<nbsp/>"Ron",<nbsp/>"Max",<nbsp/>"Ringo"<nbsp/>]
callcc{|$cc|}
puts(message<nbsp/>=<nbsp/>arr.shift)
$cc.call<nbsp/>unless<nbsp/>message<nbsp/>=~<nbsp/>/Max/
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Freddie
Herbie
Ron
Max
</alltt>
</codefragment>
<p/>
  This (somewhat contrived) example  allows the inner loop to abandon
  processing early:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[    callcc {|cont|
      for i in 0..4
        print "\n#{i}: "
        for j in i*5...(i+1)*5
          cont.call() if j == 17
          printf "%3d", j
        end
      end
    }
    print "\n"
]]></fullcode>
callcc<nbsp/>{|cont|
<nbsp/><nbsp/>for<nbsp/>i<nbsp/>in<nbsp/>0..4
<nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"\n#{i}:<nbsp/>"
<nbsp/><nbsp/><nbsp/><nbsp/>for<nbsp/>j<nbsp/>in<nbsp/>i*5...(i+1)*5
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>cont.call()<nbsp/>if<nbsp/>j<nbsp/>==<nbsp/>17
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>printf<nbsp/>"%3d",<nbsp/>j
<nbsp/><nbsp/><nbsp/><nbsp/>end
<nbsp/><nbsp/>end
}
print<nbsp/>"\n"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
<p/>
0:<nbsp/><nbsp/><nbsp/>0<nbsp/><nbsp/>1<nbsp/><nbsp/>2<nbsp/><nbsp/>3<nbsp/><nbsp/>4
1:<nbsp/><nbsp/><nbsp/>5<nbsp/><nbsp/>6<nbsp/><nbsp/>7<nbsp/><nbsp/>8<nbsp/><nbsp/>9
2:<nbsp/><nbsp/>10<nbsp/>11<nbsp/>12<nbsp/>13<nbsp/>14
3:<nbsp/><nbsp/>15<nbsp/>16
</alltt>
</codefragment>
<p/>
  <methods type="instance">
        <method name="call" ref="call">
      <callseq>
        <obj>cont</obj>.call( <optz><obj>args</obj></optz> )
      </callseq>
      <desc>
<p/>
      Invokes the continuation. The program continues from the end of
      the <tt>callcc</tt> block. If no arguments are given, the original
      <meth>callcc</meth> returns <const>nil</const>. If one argument is given,
      <meth>callcc</meth> returns it. Otherwise, an array containing
      <obj>args</obj> is returned.
<p/>
<codefragment>
<fullcode><![CDATA[      callcc {|cont|  cont.call }
      callcc {|cont|  cont.call 1 }
      callcc {|cont|  cont.call 1, 2, 3 }
]]></fullcode><rubycode>
<tr>
  <td><tt>callcc<nbsp/>{|cont|<nbsp/><nbsp/>cont.call<nbsp/>}</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>callcc<nbsp/>{|cont|<nbsp/><nbsp/>cont.call<nbsp/>1<nbsp/>}</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>callcc<nbsp/>{|cont|<nbsp/><nbsp/>cont.call<nbsp/>1,<nbsp/>2,<nbsp/>3<nbsp/>}</tt></td>
  <td>&#187;</td>
  <td><tt>[1,<nbsp/>2,<nbsp/>3]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
