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