PreviousUpNext

15.3.502  src/lib/std/src/nj/fate.api

## 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.


Comments and suggestions to: bugs@mythryl.org

PreviousUpNext