File 1433-runtime_tools-Add-scheduler-get_sample-0-a... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 1433-runtime_tools-Add-scheduler-get_sample-0-and-get_sam.patch of Package erlang (Revision 57cf7c87cb80e2aaaf3f20327bf57529)

Currently displaying revision 57cf7c87cb80e2aaaf3f20327bf57529 , Show latest

From 3ebb48c8c8e37987f71d02633ce8020af8d3ea9e Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Tue, 23 Nov 2021 21:29:13 +0100
Subject: [PATCH 3/3] runtime_tools: Add scheduler:get_sample/0 and
 get_sample_all/0

And clarify documentation,
especially regarding erlang:system_flag(scheduler_wall_time,_).
---
 lib/runtime_tools/doc/src/scheduler.xml    | 153 +++++++++++++++++----
 lib/runtime_tools/src/scheduler.erl        |  32 ++++-
 lib/runtime_tools/test/scheduler_SUITE.erl |   9 ++
 3 files changed, 165 insertions(+), 29 deletions(-)

diff --git a/lib/runtime_tools/doc/src/scheduler.xml b/lib/runtime_tools/doc/src/scheduler.xml
index d539ccb1c6..7e18503d0f 100644
--- a/lib/runtime_tools/doc/src/scheduler.xml
+++ b/lib/runtime_tools/doc/src/scheduler.xml
@@ -35,12 +35,52 @@
 <module since="OTP 21.0">scheduler</module>
 <modulesummary>Measure scheduler utilization</modulesummary>
 <description>
- This module contains utility functions for easier measurement and
- calculation of scheduler utilization, otherwise obtained from calling the
- more primitive <seeerl marker="erts:erlang#statistics_scheduler_wall_time">
- <c>statistics(scheduler_wall_time)</c></seeerl>.
- The simplest usage is to call <seemfa marker="#utilization/1">
- <c>scheduler:utilization(Seconds)</c></seemfa>.
+ 
+ This module contains utility functions for easy measurement and
+ calculation of scheduler utilization. It act as a wrapper around the more
+ primitive API <seeerl marker="erts:erlang#statistics_scheduler_wall_time">
+ <c>erlang:statistics(scheduler_wall_time)</c></seeerl>.
+ 
+ 
+ The simplest usage is to call the blocking <seemfa marker="#utilization/1">
+ <c>scheduler:utilization(Seconds)</c></seemfa>.
+ 
+ 
+ For non blocking and/or continuous calculation of scheduler utilization,
+ the recommended usage is:
+ 
+ <list>
+ <item>
+	First call <seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	<c>erlang:system_flag(scheduler_wall_time,true)</c></seeerl> to enable
+	scheduler wall time measurements.
+ </item>
+ <item>
+	Call <seemfa marker="#get_sample/0"><c>get_sample/0</c></seemfa> to
+	collect samples with some time in between.
+ </item>
+ <item>
+	Call <seemfa marker="#utilization/2"><c>utilization/2</c></seemfa> to
+	calculate the scheduler utilization in the interval between two
+	samples.
+ </item>
+ <item>
+	When done call
+	<seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	<c>erlang:system_flag(scheduler_wall_time,false)</c></seeerl> to disable
+	scheduler wall time measurements and avoid unecessary cpu overhead.
+ </item>
+ </list>
+ 
+ To get correct values from
+ <seemfa marker="#utilization/2"><c>utilization/2</c></seemfa>, it is
+ important that <c>scheduler_wall_time</c> is kept enabled during the
+ entire interval between the two samples. To ensure this, the process
+ that called <seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	<c>erlang:system_flag(scheduler_wall_time,true)</c></seeerl> must be
+ kept alive, as <c>scheduler_wall_time</c> will automatically be disabled
+ if it terminates.
+ 
 </description>
 
 <datatypes>
@@ -86,12 +126,54 @@
 
 <funcs>
 
+ <func>
+ <name name="get_sample" arity="0" since="OTP @OTP-17830@"/>
+ <fsummary>Get scheduler utilization sample.</fsummary>
+ <desc>
+ Returns a scheduler utilization sample for normal and dirty-cpu
+	schedulers. Returns <c>undefined</c> if system flag
+	<seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	<c>scheduler_wall_time</c></seeerl> has not been enabled.
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_sample_all" arity="0" since="OTP @OTP-17830@"/>
+ <fsummary>Get scheduler utilization sample.</fsummary>
+ <desc>
+ Return a scheduler utilization sample for all schedulers,
+	including dirty-io schedulers. Returns <c>undefined</c> if system flag
+	<seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	<c>scheduler_wall_time</c></seeerl> has not been enabled.
+ </desc>
+ </func>
+
 <func>
 <name name="sample" arity="0" since="OTP 21.0"/>
 <fsummary>Get scheduler utilization sample.</fsummary>
 <desc>
- Return a scheduler utilization sample for normal and dirty-cpu
-	schedulers.
+ 
+	 Return a scheduler utilization sample for normal and dirty-cpu
+	 schedulers. Will call
+	 <seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	 <c>erlang:system_flag(scheduler_wall_time,true)</c></seeerl> first if
+	 not already already enabled.
+	
+	<note>
+	 
+	 This function is not recommended as there is no way to detect if
+	 <c>scheduler_wall_time</c> already was enabled or not. If
+	 <c>scheduler_wall_time</c> has been disabled between two samples,
+	 passing them to <seemfa marker="#utilization/1"><c>utilization/2</c></seemfa>
+	 will yield invalid results.
+	 
+	 
+	 Instead use <seemfa marker="#get_sample/0">
+	 <c>get_sample/0</c></seemfa> together with
+	 <seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	 <c>erlang:system_flag(scheduler_wall_time,_)</c></seeerl>.
+	 
+	</note>
 </desc>
 </func>
 
@@ -99,8 +181,22 @@
 <name name="sample_all" arity="0" since="OTP 21.0"/>
 <fsummary>Get scheduler utilization sample.</fsummary>
 <desc>
- Return a scheduler utilization sample for all schedulers,
-	including dirty-io schedulers.
+ 
+	 Return a scheduler utilization sample for all schedulers,
+	 including dirty-io schedulers. Will call
+	 <seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	 <c>erlang:system_flag(scheduler_wall_time,true)</c></seeerl> first if
+	 not already already enabled.
+	
+	<note>
+	 
+	 This function is not recommended for same reason as <c>sample/0</c>.
+	 Instead use <seemfa marker="#get_sample_all/0">
+	 <c>get_sample_all/0</c></seemfa> together with
+	 <seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	 <c>erlang:system_flag(scheduler_wall_time,_)</c></seeerl>.
+	 
+	</note>
 </desc>
 </func>
 
@@ -108,8 +204,15 @@
 <name name="utilization" arity="1" clause_i="1" since="OTP 21.0"/>
 <fsummary>Measure scheduler utilizations during a period of time.</fsummary>
 <desc>
- Measure utilization for normal and dirty-cpu schedulers during
-	<c><anno>Seconds</anno></c> seconds, and then return the result.
+ 
+	 Measure utilization for normal and dirty-cpu schedulers during
+	 <c><anno>Seconds</anno></c> seconds, and then return the result.
+	
+	
+	 Will automatically first enable and then disable
+	 <seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	 <c>scheduler_wall_time</c></seeerl>.
+	
 </desc>
 </func>
 
@@ -122,11 +225,8 @@
 	<c>scheduler:utilization(Sample, scheduler:sample_all())</c>.
 	<note>
 	 
-	 Scheduler utilization is measured as an average value over a time
-	 interval, calculated as the difference between two samples. To get
-	 good useful utilization values at least a couple of seconds should
-	 have passed between the two samples. For this reason, you should not
-	 do
+	 This function is not recommended as it's so easy to get invalid
+	 results without noticing. In particular do not do this:
 	 
 <pre>
 scheduler:utilization(scheduler:sample()). % DO NOT DO THIS!
@@ -137,10 +237,10 @@ scheduler:utilization(scheduler:sample()). % DO NOT DO THIS!
 	 probably be more misleading than informative.
 	 
 	 
-	 Instead use <seemfa marker="#utilization/1">
-	 <c>scheduler:utilization(Seconds)</c></seemfa> or let some time pass
-	 between <c>Sample=scheduler:sample()</c> and
-	 <c>scheduler:utilization(Sample)</c>.
+	 Instead use <seemfa marker="#utilization/2">
+	 <c>scheduler:utilization/2</c></seemfa> and call
+	 <seemfa marker="#get_sample/0"><c>get_sample/0</c></seemfa> to get
+	 samples with some time in between.
 	 
 	</note>
 </desc>
@@ -152,8 +252,15 @@ scheduler:utilization(scheduler:sample()). % DO NOT DO THIS!
 <desc>
 	Calculates scheduler utilizations for the time interval between
 	the two samples obtained from calling
-	<seemfa marker="#sample/0"><c>sample/0</c></seemfa> or
-	<seemfa marker="#sample_all/0"><c>sample_all/0</c></seemfa>.
+	<seemfa marker="#sample/0"><c>get_sample/0</c></seemfa> or
+	<seemfa marker="#sample_all/0"><c>get_sample_all/0</c></seemfa>.
+	
+	 This function itself, does not need
+	 <seeerl marker="erts:erlang#system_flag_scheduler_wall_time">
+	 <c>scheduler_wall_time</c></seeerl> to be enabled. However, for
+ a correct result, <c>scheduler_wall_time</c> must have been enabled
+ during the entire interval between the two samples.
+	
 </desc>
 </func>
 
diff --git a/lib/runtime_tools/src/scheduler.erl b/lib/runtime_tools/src/scheduler.erl
index cc4f26111a..114dfa17fe 100644
--- a/lib/runtime_tools/src/scheduler.erl
+++ b/lib/runtime_tools/src/scheduler.erl
@@ -23,8 +23,8 @@
 
 -module(scheduler).
 
--export([sample/0,
- sample_all/0,
+-export([sample/0, get_sample/0,
+ sample_all/0, get_sample_all/0,
 utilization/1,
 utilization/2]).
 
@@ -54,12 +54,32 @@ sample(Stats) ->
 sample(Stats);
 
 List ->
- Sorted = lists:sort(List),
- Tagged = lists:map(fun({I, A, T}) -> {sched_tag(I), I, A, T} end,
- Sorted),
- {Stats, Tagged}
+ create_sample(Stats, List)
 end.
 
+-spec get_sample() -> sched_sample() | undefined.
+get_sample() ->
+ get_sample(scheduler_wall_time).
+
+-spec get_sample_all() -> sched_sample() | undefined.
+get_sample_all() ->
+ get_sample(scheduler_wall_time_all).
+
+get_sample(Stats) ->
+ case erlang:statistics(Stats) of
+ undefined ->
+ undefined;
+ List ->
+ create_sample(Stats, List)
+ end.
+
+create_sample(Stats, List) ->
+ Sorted = lists:sort(List),
+ Tagged = lists:map(fun({I, A, T}) -> {sched_tag(I), I, A, T} end,
+ Sorted),
+ {Stats, Tagged}.
+
+
 -type sched_util_result() ::
 [{sched_type(), sched_id(), float(), string()} |
 {total, float(), string()} |
diff --git a/lib/runtime_tools/test/scheduler_SUITE.erl b/lib/runtime_tools/test/scheduler_SUITE.erl
index 4f000c381b..fd1ec4cc8e 100644
--- a/lib/runtime_tools/test/scheduler_SUITE.erl
+++ b/lib/runtime_tools/test/scheduler_SUITE.erl
@@ -34,6 +34,15 @@ suite() -> [{ct_hooks,[ts_install_cth]}].
 
 
 basic(_Config) ->
+ undefined = scheduler:get_sample(),
+ undefined = scheduler:get_sample_all(),
+ false = erlang:system_flag(scheduler_wall_time, true),
+ GS1 = scheduler:get_sample(),
+ GS2 = scheduler:get_sample_all(),
+ check(scheduler:utilization(GS1, scheduler:get_sample())),
+ check(scheduler:utilization(GS2, scheduler:get_sample())),
+ true = erlang:system_flag(scheduler_wall_time, false),
+
 S1 = scheduler:sample(),
 S2 = scheduler:sample_all(),
 
-- 
2.31.1

Places

File 1433-runtime_tools-Add-scheduler-get_sample-0-and-get_sam.patch of Package erlang (Revision 57cf7c87cb80e2aaaf3f20327bf57529)

Places