factor/library/continuations.facts

USING: errors help kernel ;

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

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

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

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

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

HELP: ifcc "( terminator balance -- )"
{ $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 "( quot -- )"
{ $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 "( quot -- obj )"
{ $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 "( continuation -- )"
{ $values { "continuation" "a continuation" } }
{ $description "Resumes a continuation reified by " { $link callcc0 } "." } ;

HELP: continue-with "( obj continuation -- )"
{ $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." } ;