1scheduler(3) Erlang Module Definition scheduler(3)
2
6 scheduler - Measure scheduler utilization
7
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 The simplest usage is to call the blocking scheduler:utilization(Sec‐
14 onds).
15 For non blocking and/or continuous calculation of scheduler utiliza‐
17 tion, the recommended usage is:
18 * First call erlang:system_flag(scheduler_wall_time,true) to enable
20 scheduler wall time measurements.
21 * Call get_sample/0 to collect samples with some time in between.
23 * Call utilization/2 to calculate the scheduler utilization in the
25 interval between two samples.
26 * When done call erlang:system_flag(scheduler_wall_time,false) to
28 disable scheduler wall time measurements and avoid unecessary cpu
29 overhead.
30 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
38 sched_sample()
39 sched_type() = normal | cpu | io
41 sched_id() = integer()
43 sched_util_result() =
45 [{sched_type(), sched_id(), float(), string()} |
46 {total, float(), string()} |
47 {weighted, float(), string()}]
48 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 {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 {cpu, SchedulerId, Util, Percent}:
61 Scheduler utilization of a dirty-cpu scheduler with number
62 SchedulerId.
63 {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 {total, Util, Percent}:
70 Total utilization of all normal and dirty-cpu schedulers.
71 {weighted, Util, Percent}:
73 Total utilization of all normal and dirty-cpu schedulers,
74 weighted against maximum amount of available CPU time.
75
77 get_sample() -> sched_sample() | undefined
78 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 get_sample_all() -> sched_sample() | undefined
84 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 sample() -> sched_sample()
90 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 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 Instead use get_sample/0 together with erlang:system_flag(sched‐
102 uler_wall_time,_).
103 sample_all() -> sched_sample()
106 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 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 utilization(Seconds) -> sched_util_result()
118 Types:
120 Seconds = integer() >= 1
122 Measure utilization for normal and dirty-cpu schedulers during
124 Seconds seconds, and then return the result.
125 Will automatically first enable and then disable sched‐
127 uler_wall_time.
128 utilization(Sample) -> sched_util_result()
130 Types:
132 Sample = sched_sample()
134 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 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 scheduler:utilization(scheduler:sample()). % DO NOT DO THIS!
144 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 Instead use scheduler:utilization/2 and call get_sample/0 to get
151 samples with some time in between.
152 utilization(Sample1, Sample2) -> sched_util_result()
155 Types:
157 Sample1 = Sample2 = sched_sample()
159 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 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.
168Ericsson AB runtime_tools 1.19 scheduler(3)