15.3.512  src/lib/std/src/nj/save-heap-to-disk.api

## save-heap-to-disk.api
#
# We use this to generate "stand-alone" "executable" Mythryl
# apps, and also the Mythryl compiler.
#
# In both cases these "executables" actually consist of heap dumps
# with a shebang line at the top that invokes the C-coded Mythryl runtime,
# but the casual use will not know or care that they are not
# "real" os-specific executables.
#
# (The main difference is that Linux doesn't allow a script to be
# interpreted by another script.  Since Linux thinks Mythryl
# "executables" are scripts, a Mythryl executable cannot directly
# be used as a script interpreter.  This limitation is easily
# evaded by using a trivial C program to exec() the Mythryl
# "executable".)

# Compiled by:
#     src/lib/std/src/standard-core.sublib


stipulate
    package wt  =  winix_types;                                                         # winix_types                           is from   src/lib/std/src/posix/winix-types.pkg
herein

    # This api is implemented in:
    #
    #     src/lib/std/src/nj/save-heap-to-disk.pkg
    #
    api Save_Heap_To_Disk {
        #

        spawn_to_disk
            :
            ( String,                                                                   # This argument provides the filename for the saved heap image.
              #
              ( (String, List(String))                                                  # This argument provides the function to run when the saved     
                ->                                                                      # heap image is run.
                winix_types::process::Status
              )
            )
            ->
            Void;
            #
            # Export the current Mythryl heap to the given file
            # and then exit.  When the heap is run, execution
            # will appear to start (and end) with the given fn.
            #
            # This is the call used to generate all Mythryl
            # "executable" heap images except the compiler;
            # in practice it is almost always invoked via the
            # wrapper script
            #
            #       sh/_build-an-executable-mythryl-heap-image
            # aka   bin/build-an-executable-mythryl-heap-image
            #
            # which in turn is usually invoked via a script like
            #
            #     src/app/yacc/build-yacc-app
            #
            # in response to "make rest" or such.


        Fork_Result = AM_PARENT | AM_CHILD;

        fork_to_disk:     String -> Fork_Result;
            #
            # Export the current Mythryl heap to the given file
            # and then continue execution, returning AM_PARENT
            # to caller.
            #
            # When the saved heap image is run, it will appear
            # to resume execution at the return from thie call,
            # except with a return value of AM_CHILD instead
            # of AM_PARENT.
            #
            # Note that in the latter case various kernel-dependent
            # resources such as open file descriptors and running
            # subprocesses will have been lost -- this call must
            # be used cautiously.
            #
            # In practice this call is used only to generate the
            # "executable" heap image for the Mythryl compiler.
    };
end;



## COPYRIGHT (c) 1995 AT&T Bell Laboratories.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.