## fate.api
#
# Support for call/cc type stuff.
#
# NB: The literature refers to "continuations";
# for brevity we call them "fates".
#
#
# Overview
# ========
#
# call/cc (which we call "call_with_current_fate")
# is powerful because in essence it lets us swap callstacks,
# which lets us implement things like co-routines, generators
# and concurrent threads of execution.
#
# call/cc was introduced by the Scheme dialect of Lisp.
# One major difference between the Scheme and Mythryl
# versions is that Scheme fates can be invoked like
# functions, but Mythryl fates must be invoked via
# switch_to_fate().
#
#
#
# In more detail
# ==============
#
# At any given time a program is evaluating the "current expression",
# whose result will be handed to the "current fate", which will
# accept that result and perform all remaining computations needed
# to complete the program run.
#
# The current fate can be thought of as the contents of the callstack,
# upon which are pushed all the nested function calls remaining
# to be completed. (This understanding should not be taken too
# literally. For one thing, Mythryl does not in fact use callstacks,
# at all. The stackless implementation makes call_with_current_fate
# very very fast -- about as fast as a function call.)
#
# A fate is like a function in that it accepts an argument and
# does a computation based upon that value; the critical difference
# is that a function returns some value of some type (be it only Void)
# but a fate never returns at all, and consequently has no return value
# or return type.
#
# Thus, the type of a function is Input_Type -> Result_Type
# but the type of a fate is just Fate( Input_Type )
#
# For a longer introduction to call/cc generally, see:
#
# http://en.wikipedia.org/wiki/Call-with-current-continuation
# or http://community.schemewiki.org/?call-with-current-continuation-for-C-programmers
# Compiled by:
# src/lib/std/src/standard-core.sublib# This api is implemented in:
#
# src/lib/std/src/nj/fate.pkg#
api Fate {
#
Fate(X); # ``The type of fates which accept arguments of type X.'' -- http://www.smlnj.org/doc/SMLofNJ/pages/cont.html
#
call_with_current_fate # ``Apply f to the "current fate". If f invokes this fate with argument x, it is as if (call_with_current_fate f) had returned x as a result.''
: # -- http://www.smlnj.org/doc/SMLofNJ/pages/cont.html
(Fate(X) -> X) -> X; # Never returns -- the return type is essentially a fiction.
switch_to_fate # Switch to executing given fate with given argument.
: #
Fate(X) -> X -> Y; # Never returns -- the return type is essentially a fiction.
# A function for creating an isolated fate from a function.
# This is a specialized fn called (only) in:
#
# src/lib/std/src/hostthread.pkg # src/lib/std/src/unsafe/unsafe.pkg # src/lib/src/lib/thread-kit/src/core-thread-kit/microthread.pkg # src/lib/src/lib/thread-kit/src/core-thread-kit/microthread-preemptive-scheduler.pkg # src/lib/src/lib/thread-kit/src/glue/thread-scheduler-control-g.pkg # src/lib/src/lib/thread-kit/src/glue/threadkit-base-for-os-g.pkg #
make_isolated_fate # ``Discard all live data from the calling context (except what is reachable from f or x), then call f(x), then exit.
: # This may use much less memory then something like f(x) then exit().''
(X -> Void) -> Fate(X); # -- http://www.smlnj.org/doc/SMLofNJ/pages/cont.html
# Versions of the fate operations that do not
# capture/restore the exception handler context.
#
# These are speed kludges:
# Avoid using them unless absolutely necessary.
#
Control_Fate(X);
#
call_with_current_control_fate: (Control_Fate(X) -> X) -> X;
switch_to_control_fate: Control_Fate(X) -> X -> Y;
};
## COPYRIGHT (c) 1995 AT&T Bell Laboratories.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.