factor/library/continuations.facts

USING: errors help kernel kernel-internals ;

HELP: catchstack*
{ $values { "catchstack" "a vector" } }
{ $description "Outputs the current catchstack." } ;

HELP: catchstack
{ $values { "catchstack" "a vector" } }
{ $description "Outputs a copy of the current catchstack." } ;

HELP: set-catchstack
{ $values { "catchstack" "a vector" } }
{ $description "Replaces the catchstack with a copy of the given vector." } ;

HELP: continuation
{ $values { "continuation" "a continuation" } }
{ $description "Reifies the current continuation from the point immediately after which the caller returns." } ;

HELP: >continuation<
{ $values { "continuation" "a continuation" } { "data" "a vector" } { "retain" "a vector" } { "call" "a vector" } { "name" "a vector" } { "catch" "a vector" } }
{ $description "Takes a continuation apart into its four constituents." } ;

HELP: ifcc
{ $values { "terminator" "a quotation with stack effect " { $snippet "( continuation -- )" } } { "balance" "a quotation" } }
{ $description "Reifies a continuation from the point immediately after which the caller returns, and passes it to " { $snippet "terminator" } ". When the continuation is restored, execution resumes; " { $snippet "terminator" } " is still on the stack and "{ $snippet "balance" } " is called." }
{ $see-also callcc0 callcc1 } ;

HELP: callcc0
{ $values { "quot" "a quotation with stack effect " { $snippet "( continuation -- )" } } }
{ $description "Applies the quotation to the current continuation, which is reified from the point immediately after which the caller returns. The " { $link continue } " word resumes the continuation." }
{ $see-also ifcc callcc1 continue } ;

HELP: callcc1
{ $values { "quot" "a quotation with stack effect " { $snippet "( continuation -- )" } } { "obj" "an object provided when resuming the continuation" } }
{ $description "Applies the quotation to the current continuation, which is reified from the point immediately after which the caller returns. The " { $link continue-with } " word resumes the continuation, passing a value back to the original execution context." }
{ $see-also ifcc callcc0 continue-with } ;

HELP: continue
{ $values { "continuation" "a continuation" } }
{ $description "Resumes a continuation reified by " { $link callcc0 } "." } ;

HELP: continue-with
{ $values { "obj" "an object to pass to the continuation's execution context" } { "continuation" "a continuation" } }
{ $description "Resumes a continuation reified by " { $link callcc1 } ". The object remains on the stack when the continuation resumes executing." } ;