## runtime-profiling-control.api
#
# Profiling support.
# At present this mainly means counting
# how many times functions are called,
# and how much time is spent in them.
#
# For background see:
#
# src/A.TRACE-DEBUG-PROFILE.OVERVIEW
#
# See also:
#
# src/lib/compiler/debugging-and-profiling/profiling/profiling-control.api# Compiled by:
# src/lib/std/src/standard-core.sublib# This package implements the interface to the run-time system's profiling
# support library. It is not meant for general use. For general use see:
#
# src/lib/compiler/debugging-and-profiling/profiling/profiling-control-g.pkgstipulate
package rwv = rw_vector; # rw_vector is from src/lib/std/src/rw-vector.pkgherein
# This api is implemented in:
#
# src/lib/std/src/nj/runtime-profiling-control.pkg #
api Runtime_Profiling_Control {
#
add_per_fun_call_counters_to_deep_syntax: Ref( Bool ); # Controls profile instrumentation.
#
# This is the on/off switch for add_per_fun_call_counters_to_deep_syntax # add_per_fun_call_counters_to_deep_syntax is from src/lib/compiler/debugging-and-profiling/profiling/add-per-fun-call-counters-to-deep-syntax.pkg #
# If this refcell holds TRUE during a compile
# then the compiler will insert call-counting code
# at the start of each function.
get_time_profiling_rw_vector: Void -> Rw_Vector( Int ); # Get the timer count rw_vector
#
# Fetch the timing vector. This has one slot for
# every Mythryl function being time-profiled, containing
# a count of how many times SIGVTALRM hit while we were
# executing that function.
this_fn_profiling_hook_refcell__global: Ref( Int );
#
# UNSAFE!! This is used internally to communicate
# the currently-running Mythryl function to sigvtalrm_handler. # sigvtalrm_handler def in src/c/lib/space-and-time-profiling/libmythryl-space-and-time-profiling.c
# If you change this to an out-of-range value
# sigvtalrm_handler() will blithely trash heap
# memory, probably coredumping the system eventually.
start_sigvtalrm_time_profiler: Void -> Void;
stop_sigvtalrm_time_profiler: Void -> Void;
#
# The first of these does two things:
#
# o Enables the SIGVTALRM handler sigvtalrm_handler(),
# which will at each call increment the appropriate
# slot in the time_profiling_rw_vector.
#
# o Tells the kernel to send us SIGVTALRM signals
# every 1/100 of a second.
#
# The second call reverses those two operations.
sigvtalrm_time_profiler_is_running: Void -> Bool;
#
# Which of the above two fns was most recently called?
get_sigvtalrm_interval_in_microseconds: Void -> Int;
Profiled_Package # Technically these track compilation units, not packages but 99% of the time we're compiling a package.
=
PROFILED_PACKAGE
{
fun_names: String, # Names of all funs being profiled, in order. This is conceptually a list or vector of strings; to save space we pack them into a single string, terminated by newlines.
# This string gets generated by the instrumentation logic in src/lib/compiler/debugging-and-profiling/profiling/add-per-fun-call-counters-to-deep-syntax.pkg fun_count: Int, # Number of functions being time-profiled in this package. (Same as number of newlines in fun_names, and in fact that is how we generate this value.)
first_slot_in_time_profiling_rw_vector: Int, # This package has 'fun_count' slots in time_profiling_rw_vector starting at this offset.
per_fun_call_counts: rwv::Rw_Vector( Int ) # Length 'fun_count', holds the call-counts for all functions in this package.
};
#
# We maintain one of these records for each
# package being time-profiled.
#
# Our primary job is to track, for each profiled user function,
# the number of times it is called and the number of seconds spent
# in it. But we also track the number of seconds spent in the
# runtime, in the major and minor garbage collectors, in the
# compiler, and in "other". We reserve the first five slots in
# the time_profiling_rw_vector for this purpose, and here publish
# these special five offsets into them:
#
in_runtime__cpu_user_index: Int; # 0
in_minor_heapcleaner__cpu_user_index: Int; # 1
in_major_heapcleaner__cpu_user_index: Int; # 2
in_other_code__cpu_user_index: Int; # 3
in_compiler__cpu_user_index: Int; # 4
number_of_predefined_indices: Int; # 5
get_profiled_packages_list: Void -> List(Profiled_Package);
zero_profiling_counts: Void -> Void;
# Space profiling hooks: THIS FUNCTIONALITY IS COMPLETELY BROKEN.
#
space_profiling: Ref( Bool );
space_prof_register: Ref ((unsafe::unsafe_chunk::Chunk, String) -> unsafe::unsafe_chunk::Chunk);
};
end;
## COPYRIGHT (c) 1996 AT&T Research.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.