PreviousUpNext

15.3.297  src/lib/core/init/runtime.api

## runtime.api
#
#####################################
#            BLACK MAGIC!
#
# This file interfaces with C and assembly
# in odd ways -- modify at your peril!
#####################################


# This file defines the interface to a few globals
# exported by the (C-coded) runtime system -- see
#
#     src/c/main/construct-runtime-package.c
#
# The BOXED version is supposed to correspond to the assembly and
# the C code that implement the functions using the boxed calling 
# conventions.
#
# Right now, we tried hard to eliminate the typeagnostic type
# in the BOXED version because they are interpreted differently across 
# different versions of the compilers.
#
# In
#     src/lib/core/init/core.pkg
# we use the magic (and "dirty") cast to force them into the right
# Mythryl types. (ZHONG)



###                   "A surgeon must have the courage to cut."
###                                    -- Jerrold D. Prothero


# This api is implemented in:
#
#     src/lib/core/init/core.pkg

api Runtime {

    Chunk;

    Null_Or(X) =  NULL  |  THE X;

    # Assembly language functions callable directly from Mythryl.
    # Depending on the platform, these are found in one of the files:
    #
    #     src/c/machine-dependent/prim.pwrpc32.asm
    #     src/c/machine-dependent/prim.sparc32.asm
    #     src/c/machine-dependent/prim.intel32.asm
    #     src/c/machine-dependent/prim.intel32.masm
    #
    # Those functions may then set up one of the requestcodes from
    # 
    #     src/c/h/asm-to-c-request-codes.h
    #
    # and transfer control to
    #
    #     src/c/main/run-mythryl-code-and-runtime-eventloop.c
    #
    # for further processing at the C level.
    #
    package asm:  api {
                   Cfunction;
                   eqtype Unt8_Rw_Vector;
                   eqtype Float64_Rw_Vector;
                   Spin_Lock;
                   #
                   make_typeagnostic_rw_vector:  (Int, X) -> Rw_Vector(X);                                      # Construct and return read-write typeagnostic vector initialized to given value.
                   find_cfun:  (String, String) -> Cfunction;                                                   # Find a Mythryl-callable C library fn registered via   src/c/lib/mythryl-callable-c-libraries-list.h
                   call_cfun:  (Cfunction, X) -> Z;                                                             # Call a Mythryl-callable C library fn obtained from    find_cfun.
                   #                                                                                            # find_cfun and call_cfun are used in:                  src/lib/std/src/unsafe/mythryl-callable-c-library-interface.pkg
                   make_unt8_rw_vector:         Int             -> Unt8_Rw_Vector;                              # Construct and return uninitialized Un8     vector with given number of slots.
                   make_float64_rw_vector:      Int             -> Float64_Rw_Vector;                           # Construct and return uninitialized Float64 vector with given number of slots.
                   make_string:                 Int             -> String;
                   make_typeagnostic_ro_vector: (Int, List(X))  -> Vector(X);                                   # Construct and return read-only typeagnostic vector initialized from given list.
                    #
                   floor:  Float -> Int;
                   logb:   Float -> Int;
                   scalb:  (Float, Int) -> Float;
                   try_lock:  Spin_Lock -> Bool;
                   unlock:    Spin_Lock -> Void;
                }; 

    exception DIVIDE_BY_ZERO;
    exception OVERFLOW;
    exception RUNTIME_EXCEPTION  (String, Null_Or(Int));                                                        # C-level runtime errno.h/strerror() (or such) errors. See src/c/lib/raise-error.c

    # Global C variables used to communicate
    # with the C runtime:
    #   
    this_fn_profiling_hook_refcell__global:                     Ref( Int  );                                    # THIS_FN_PROFILING_HOOK_REFCELL__GLOBAL                        in src/c/main/construct-runtime-package.c
    software_generated_periodic_events_switch_refcell__global:  Ref( Bool );                                    # SOFTWARE_GENERATED_PERIODIC_EVENTS_SWITCH_REFCELL__GLOBAL     in src/c/main/construct-runtime-package.c
    software_generated_periodic_event_interval_refcell__global: Ref( Int  );                                    # SOFTWARE_GENERATED_PERIODIC_EVENT_INTERVAL_REFCELL__GLOBAL    in src/c/main/construct-runtime-package.c
    software_generated_periodic_event_handler_refcell__global:  Ref( Fate(Void) -> Fate(Void) );                # SOFTWARE_GENERATED_PERIODIC_EVENTS_HANDLER_REFCELL__GLOBAL    in src/c/main/construct-runtime-package.c
    microthread_switch_lock_refcell__global:                    Ref( Int  );                                    # MICROTHREAD_SWITCH_LOCK_REFCELL__GLOBAL                       in src/c/main/construct-runtime-package.c   Documented in   src/c/h/runtime-globals.h
    pervasive_package_pickle_list__global:                      Ref( Chunk );                                   # PERVASIVE_PACKAGE_PICKLE_LIST_REFCELL__GLOBAL                 in src/c/main/construct-runtime-package.c
    posix_interprocess_signal_handler_refcell__global:          Ref( (Int, Int, Fate(Void)) -> Fate(Void) );    # POSIX_INTERPROCESS_SIGNAL_HANDLER_REFCELL__GLOBAL             in src/c/main/construct-runtime-package.c
    zero_length_vector__global:                                 Vector(X);                                      # ZERO_LENGTH_VECTOR__GLOBAL                                    in src/c/main/construct-runtime-package.c
        #
        # Renaming? See note [1].
};


# This api is implemented in:
#
#     src/lib/core/init/runtime.pkg

api Runtime_Boxed {

    Chunk;

    Null_Or(X) =   NULL | THE X;

    # See above comments re package asm:
    #
    package asm:  api {
                    #
                    Cfunction;
                    #
                    eqtype Unt8_Rw_Vector;
                    eqtype Float64_Rw_Vector;
                    #
                    Spin_Lock;
                    #
                    make_typeagnostic_rw_vector: Chunk -> Chunk;
                    find_cfun:                  Chunk -> Chunk;
                    call_cfun:                  Chunk -> Chunk;
                    #
                    make_unt8_rw_vector:        Chunk -> Unt8_Rw_Vector;
                    make_float64_rw_vector:     Chunk -> Float64_Rw_Vector;
                    make_string:                Chunk -> String;
                    make_typeagnostic_ro_vector:        Chunk -> Chunk;
                    #
                    floor:      Chunk -> Chunk;
                    logb:       Chunk -> Chunk;
                    scalb:      Chunk -> Chunk;
                    try_lock:   Spin_Lock -> Chunk;
                    unlock:     Spin_Lock -> Chunk;
                }; 

    exception DIVIDE_BY_ZERO;
    exception OVERFLOW;
    exception RUNTIME_EXCEPTION  (String, Null_Or(Int));                                        # C-level runtime errno.h/strerror() (or such) errors. See src/c/lib/raise-error.c

    # Global variables used to communicate
    # with the C runtime -- see
    #
    #     src/c/main/construct-runtime-package.c
    #
    this_fn_profiling_hook_refcell__global:                     Ref( Int   );
    software_generated_periodic_events_switch_refcell__global:  Ref( Bool  );                                           # Set FALSE to prevent handler from being called.
    software_generated_periodic_event_interval_refcell__global: Ref( Int   );
    software_generated_periodic_event_handler_refcell__global:  Ref( Fate(Void) -> Fate(Void) );
    microthread_switch_lock_refcell__global:                            Ref( Int   );
    pervasive_package_pickle_list__global:                      Ref( Chunk );
    posix_interprocess_signal_handler_refcell__global:          Ref( (Int, Int, Fate(Void)) -> Fate(Void) );            # (signal_id, signal_count, fate) -> fate
    zero_length_vector__global:                                 Vector(Chunk);                                          # Renaming? See note [1].
};

###############################################################################################
#                                  Notes
#
# Note [1]:   The name "zero_length_vector__global" is hardwired into

#                 src/lib/compiler/back/top/translate/translate-deep-syntax-to-lambdacode.pkg
#
#             so a straightforward attempt to rename will crash you with
#
#                 WARNING: no Core access
#
#             messages.  One workaround is to rename in three steps:
#
#                 1)  Create a synonym "length_zero_vector__global" or whatever
#                     with the desired new name and do a full
#                         make compiler
#                         make rest
#                         sudo make install; make check
#                         make tart
#                     compile cycle to establish it.
#
#                 2)  Replace all "zero_length_vector__global" references
#                     with "length_zero_vector__global" references and do a
#                     full compile cycle.
#
#                 3)  Remove the now-unneeded "length_zero_vector__global" and do a
#                     full compile cycle.


## Copyright 1996 by 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