## profiling-control.api
#
# User interface for controling profiling.
# At present this primarily means counting calls to functions
# and measuring time spent in functions.
#
# See also:
#
# src/lib/std/src/nj/runtime-profiling-control.api# Compiled by:
# src/lib/compiler/debugging-and-profiling/debugprof.sublib# User interface for controlling profiling.
### "Every program starts off with bugs.
### Many programs end up with bugs as well.
### There are two corollaries to this:
### First, you must test all your
### programs straight away.
### And second, there's no point in
### losing your temper every time they
### don't work."
###
### -- Z80 Users Manual
stipulate
package fil = file__premicrothread; # file__premicrothread is from src/lib/std/src/posix/file--premicrothread.pkgherein
# This api is implemented in:
#
# src/lib/compiler/debugging-and-profiling/profiling/profiling-control-g.pkg #
api Profiling_Control {
#
set_compiler_to_add_per_fun_call_counters_to_deep_syntax: Void -> Void; # Enable call-counter insertion.
set_compiler_to_not_add_per_fun_call_counters_to_deep_syntax: Void -> Void; # Disable call-counter insertion. (The default.)
compiler_is_set_to_add_per_fun_call_counters_to_deep_syntax: Void -> Bool; # Which of the previous two was most recently called?
#
# These three dis/able operation of 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 # Set this compiler switch before compiling code to be profiled.
start_sigvtalrm_time_profiler: Void -> Void;
stop_sigvtalrm_time_profiler: Void -> Void;
sigvtalrm_time_profiler_is_running: Void -> Bool; # Which of the previous two was most recently called?
#
# These start/stop the SIGVTALRM signal which actually
# drives time profiling statistics collection at runtime.
zero_profiling_counts: Void -> Void; # Reset all profiling times and counts to zero.
get_per_fun_timing_stats_sorted_by_cpu_time_then_callcount # Return raw timing data for client-package processing.
:
Void
->
List
{ fun_name: String, # "foo::bar": Package-qualified name of some function compiled while profiling_control::compiler_is_set_to_add_per_fun_call_counters_to_deep_syntax() was TRUE.
call_count: Int, # Number of times the function was called.
cpu_seconds: Float # From number of times SIGVTALRM was handled while this function was executing. We generate SIGVTALRM at 100Hz, so we tally these as 0.01 CPU second each.
}; # NB: SIGVTALRM measures only userspace cpu time, not wallclock time and not kernel cpu time.
write_per_fun_time_profile_report0 # Write profiling report to stream.
: # This is just the data returned by above call, formatted as text.
fil::Output_Stream -> Void; # file is from src/lib/std/src/posix/file.pkg write_per_fun_time_profile_report # Same as above, except we ignore uncalled functions.
: #
fil::Output_Stream -> Void;
};
end;
## COPYRIGHT (c) 1995 AT&T Bell Laboratories.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.