## software-generated-periodic-events.api
#
# This API defines access to a facility which supports having
# a user-specified function called every time a certain number
# of instructions have been executed. This functionality is
# similar to that possible via the POSIX SIGALRM signal, but
# is implemented entirely in software courtesy of support and
# cooperation from the Mythryl compiler and runtime.
#
# Relative to SIGALRM, this facility has the advantage of not
# interrupting system calls (which can break many C libraries)
# and of having extremely low overhead (it is piggybacked on
# the heapcleaner's heaplimit check mechanism, whereas one
# SIGALRM may take 10,000 -> 100,000 instructions just to do
# the process context switch) but the disadvantage of being
# less precise and predictable.
#
# Call
#
# platform_properties::has_software_polling ()
#
# to determine whether support for this facility has been compiled
# into the Mythryl runtime.
#
# REGISTERING A USER-SPECIFIED EVENT HANDLEDR:
#
# The user sets a handler by doing
#
# set_software_generated_periodic_event_handler (THE my_handler);
#
# This can be undone by doing
#
# set_software_generated_periodic_event_handler NULL;
#
# HANDLER ARGUMENT:
# The 'my_handler' function will be called with the fate
# ("continuation") which would otherwise have been executing
# at that point.
#
# HANDLER RETURN VALUE:
# Upon return, the Mythryl runtime runs whatever fate
# the 'my_handler' function returns; this allows the
# handler to implement pre-emptive thread concurrency
# by regularly switching fates. If this functionality
# is not needed, the handler can simply return its
# argument fate unchanged.
# Compiled by:
# src/lib/std/src/standard-core.sublibapi Software_Generated_Periodic_Events {
#
exception BAD_SOFTWARE_GENERATED_PERIODIC_EVENT_INTERVAL;
# Setting this refcell to FALSE will prevent the
# user-supplied handler from being called:
#
software_generated_periodic_events_switch_refcell__global: Ref( Bool ); # Ultimately from src/c/main/construct-runtime-package.c
set_software_generated_periodic_event_handler: Null_Or ( fate::Fate (Void) -> fate::Fate (Void)) -> Void;
get_software_generated_periodic_event_handler: Void -> Null_Or ( fate::Fate (Void) -> fate::Fate (Void));
# Intervals are expressed in terms of units
# of 1024 instructions as measured in the
# machine-independent fate-passing-style
# phase of the compiler. That is, setting
# the interval to 1024 requests that the
# handler be called roughly every 1024
# machine instructions. (A very bad idea!)
#
set_software_generated_periodic_event_interval: Null_Or( Int ) -> Void;
get_software_generated_periodic_event_interval: Void -> (Null_Or( Int ));
};
## COPYRIGHT (c) 1997 Bell Labs, Lucent Technologies.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.