1scheduler(3)               Erlang Module Definition               scheduler(3)
2
3
4

NAME

6       scheduler - Measure scheduler utilization
7

DESCRIPTION

9       This  module contains utility functions for easy measurement and calcu‐
10       lation of scheduler utilization. It act as a wrapper  around  the  more
11       primitive API erlang:statistics(scheduler_wall_time).
12
13       The  simplest  usage is to call the blocking scheduler:utilization(Sec‐
14       onds).
15
16       For non blocking and/or continuous calculation  of  scheduler  utiliza‐
17       tion, the recommended usage is:
18
19         * First  call  erlang:system_flag(scheduler_wall_time,true) to enable
20           scheduler wall time measurements.
21
22         * Call get_sample/0 to collect samples with some time in between.
23
24         * Call utilization/2 to calculate the scheduler  utilization  in  the
25           interval between two samples.
26
27         * When  done  call  erlang:system_flag(scheduler_wall_time,false)  to
28           disable scheduler wall time measurements and avoid  unecessary  cpu
29           overhead.
30
31       To  get  correct values from utilization/2, it is important that sched‐
32       uler_wall_time is kept enabled during the entire interval  between  the
33       two  samples.  To  ensure  this,  the  process  that called erlang:sys‐
34       tem_flag(scheduler_wall_time,true)  must  be  kept  alive,  as   sched‐
35       uler_wall_time will automatically be disabled if it terminates.
36

DATA TYPES

38       sched_sample()
39
40       sched_type() = normal | cpu | io
41
42       sched_id() = integer()
43
44       sched_util_result() =
45           [{sched_type(), sched_id(), float(), string()} |
46            {total, float(), string()} |
47            {weighted, float(), string()}]
48
49              A list of tuples containing results for individual schedulers as
50              well as aggregated averages. Util is the  scheduler  utilization
51              as  a  floating  point value between 0.0 and 1.0. Percent is the
52              same utilization as a more human readable  string  expressed  in
53              percent.
54
55                {normal, SchedulerId, Util, Percent}:
56                  Scheduler  utilization  of  a  normal  scheduler with number
57                  SchedulerId. Schedulers that are not online will also be in‐
58                  cluded. Online schedulers have the lowest SchedulerId.
59
60                {cpu, SchedulerId, Util, Percent}:
61                  Scheduler  utilization  of a dirty-cpu scheduler with number
62                  SchedulerId.
63
64                {io, SchedulerId, Util, Percent}:
65                  Scheduler utilization of a dirty-io  scheduler  with  number
66                  SchedulerId. This tuple will only exist if both samples were
67                  taken with sample_all/0.
68
69                {total, Util, Percent}:
70                  Total utilization of all normal and dirty-cpu schedulers.
71
72                {weighted, Util, Percent}:
73                  Total utilization of all normal  and  dirty-cpu  schedulers,
74                  weighted against maximum amount of available CPU time.
75

EXPORTS

77       get_sample() -> sched_sample() | undefined
78
79              Returns  a scheduler utilization sample for normal and dirty-cpu
80              schedulers. Returns undefined if system flag scheduler_wall_time
81              has not been enabled.
82
83       get_sample_all() -> sched_sample() | undefined
84
85              Return  a  scheduler  utilization sample for all schedulers, in‐
86              cluding dirty-io schedulers. Returns undefined  if  system  flag
87              scheduler_wall_time has not been enabled.
88
89       sample() -> sched_sample()
90
91              Return  a  scheduler utilization sample for normal and dirty-cpu
92              schedulers.      Will       call       erlang:system_flag(sched‐
93              uler_wall_time,true) first if not already already enabled.
94
95          Note:
96              This function is not recommended as there is no way to detect if
97              scheduler_wall_time  already  was  enabled  or  not.  If  sched‐
98              uler_wall_time  has  been  disabled between two samples, passing
99              them to utilization/2 will yield invalid results.
100
101              Instead use get_sample/0 together with erlang:system_flag(sched‐
102              uler_wall_time,_).
103
104
105       sample_all() -> sched_sample()
106
107              Return  a  scheduler  utilization sample for all schedulers, in‐
108              cluding dirty-io schedulers. Will call erlang:system_flag(sched‐
109              uler_wall_time,true) first if not already already enabled.
110
111          Note:
112              This  function  is  not recommended for same reason as sample/0.
113              Instead   use   get_sample_all/0   together   with   erlang:sys‐
114              tem_flag(scheduler_wall_time,_).
115
116
117       utilization(Seconds) -> sched_util_result()
118
119              Types:
120
121                 Seconds = integer() >= 1
122
123              Measure  utilization  for normal and dirty-cpu schedulers during
124              Seconds seconds, and then return the result.
125
126              Will  automatically  first  enable  and  then   disable   sched‐
127              uler_wall_time.
128
129       utilization(Sample) -> sched_util_result()
130
131              Types:
132
133                 Sample = sched_sample()
134
135              Calculate scheduler utilizations for the time interval from when
136              Sample was taken and "now". The same as  calling  scheduler:uti‐
137              lization(Sample, scheduler:sample_all()).
138
139          Note:
140              This  function is not recommended as it's so easy to get invalid
141              results without noticing. In particular do not do this:
142
143              scheduler:utilization(scheduler:sample()). % DO NOT DO THIS!
144
145
146              The above example takes two samples in rapid succession and cal‐
147              culates  the  scheduler  utilization between them. The resulting
148              values will probably be more misleading than informative.
149
150              Instead use scheduler:utilization/2 and call get_sample/0 to get
151              samples with some time in between.
152
153
154       utilization(Sample1, Sample2) -> sched_util_result()
155
156              Types:
157
158                 Sample1 = Sample2 = sched_sample()
159
160              Calculates  scheduler utilizations for the time interval between
161              the two samples obtained from calling get_sample/0  or  get_sam‐
162              ple_all/0.
163
164              This  function  itself,  does not need scheduler_wall_time to be
165              enabled. However, for a correct result, scheduler_wall_time must
166              have  been  enabled  during  the entire interval between the two
167              samples.
168
169
170
171Ericsson AB                   runtime_tools 1.19                  scheduler(3)
Impressum