PreviousUpNext

15.3.215  src/lib/compiler/debugging-and-profiling/profiling/profiling-control.api

## 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.pkg
herein

    # 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-2013,
## released per terms of SMLNJ-COPYRIGHT.


Comments and suggestions to: bugs@mythryl.org

PreviousUpNext