NAME

       scheduler - Measure scheduler utilization

DESCRIPTION

       This  module contains utility functions for easy measurement and calculation of scheduler utilization. It
       act as a wrapper around the more primitive API erlang:statistics(scheduler_wall_time).

       The simplest usage is to call the blocking scheduler:utilization(Seconds).

       For non blocking and/or continuous calculation of scheduler utilization, the recommended usage is:

         * First call erlang:system_flag(scheduler_wall_time,true) to enable scheduler wall time measurements.

         * Call get_sample/0 to collect samples with some time in between.

         * Call utilization/2 to calculate the scheduler utilization in the interval between two samples.

         * When  done  call  erlang:system_flag(scheduler_wall_time,false)  to  disable  scheduler   wall   time
           measurements and avoid unecessary cpu overhead.

       To get correct values from utilization/2, it is important that scheduler_wall_time is kept enabled during
       the   entire   interval   between   the   two   samples.   To   ensure  this,  the  process  that  called
       erlang:system_flag(scheduler_wall_time,true)  must   be   kept   alive,   as   scheduler_wall_time   will
       automatically be disabled if it terminates.

DATA TYPES

       sched_sample()

       sched_type() = normal | cpu | io

       sched_id() = integer()

       sched_util_result() =
           [{sched_type(), sched_id(), float(), string()} |
            {total, float(), string()} |
            {weighted, float(), string()}]

              A list of tuples containing results for individual schedulers as well as aggregated averages. Util
              is  the  scheduler  utilization as a floating point value between 0.0 and 1.0. Percent is the same
              utilization as a more human readable string expressed in percent.

                {normal, SchedulerId, Util, Percent}:
                  Scheduler utilization of a normal scheduler with number SchedulerId. Schedulers that  are  not
                  online will also be included. Online schedulers have the lowest SchedulerId.

                {cpu, SchedulerId, Util, Percent}:
                  Scheduler utilization of a dirty-cpu scheduler with number SchedulerId.

                {io, SchedulerId, Util, Percent}:
                  Scheduler  utilization  of  a dirty-io scheduler with number SchedulerId. This tuple will only
                  exist if both samples were taken with sample_all/0.

                {total, Util, Percent}:
                  Total utilization of all normal and dirty-cpu schedulers.

                {weighted, Util, Percent}:
                  Total utilization of all normal and dirty-cpu schedulers, weighted against maximum  amount  of
                  available CPU time.

EXPORTS

       get_sample() -> sched_sample() | undefined

              Returns  a  scheduler utilization sample for normal and dirty-cpu schedulers. Returns undefined if
              system flag scheduler_wall_time has not been enabled.

       get_sample_all() -> sched_sample() | undefined

              Return a scheduler utilization sample for all schedulers, including dirty-io  schedulers.  Returns
              undefined if system flag scheduler_wall_time has not been enabled.

       sample() -> sched_sample()

              Return   a   scheduler   utilization  sample  for  normal  and  dirty-cpu  schedulers.  Will  call
              erlang:system_flag(scheduler_wall_time,true) first if not already already enabled.

          Note:
              This function is not recommended as there is no way to detect if scheduler_wall_time  already  was
              enabled  or  not.  If  scheduler_wall_time  has been disabled between two samples, passing them to
              utilization/2 will yield invalid results.

              Instead use get_sample/0 together with erlang:system_flag(scheduler_wall_time,_).

       sample_all() -> sched_sample()

              Return a scheduler utilization sample for all schedulers, including dirty-io schedulers. Will call
              erlang:system_flag(scheduler_wall_time,true) first if not already already enabled.

          Note:
              This function is not recommended  for  same  reason  as  sample/0.  Instead  use  get_sample_all/0
              together with erlang:system_flag(scheduler_wall_time,_).

       utilization(Seconds) -> sched_util_result()

              Types:

                 Seconds = integer() >= 1

              Measure  utilization  for  normal and dirty-cpu schedulers during Seconds seconds, and then return
              the result.

              Will automatically first enable and then disable scheduler_wall_time.

       utilization(Sample) -> sched_util_result()

              Types:

                 Sample = sched_sample()

              Calculate scheduler utilizations for the time interval from when Sample was taken and  "now".  The
              same as calling scheduler:utilization(Sample, scheduler:sample_all()).

          Note:
              This  function  is  not  recommended  as  it's so easy to get invalid results without noticing. In
              particular do not do this:

              scheduler:utilization(scheduler:sample()). % DO NOT DO THIS!

              The above example takes two samples in rapid succession and calculates the  scheduler  utilization
              between them. The resulting values will probably be more misleading than informative.

              Instead  use  scheduler:utilization/2  and  call  get_sample/0  to  get  samples with some time in
              between.

       utilization(Sample1, Sample2) -> sched_util_result()

              Types:

                 Sample1 = Sample2 = sched_sample()

              Calculates scheduler utilizations for the time interval between  the  two  samples  obtained  from
              calling get_sample/0 or get_sample_all/0.

              This  function  itself,  does  not  need scheduler_wall_time to be enabled. However, for a correct
              result, scheduler_wall_time must have been enabled during the  entire  interval  between  the  two
              samples.

Ericsson AB                                    runtime_tools 1.19                                scheduler(3erl)