File 3501-runtime_tools-Clarify-scheduler-docs.patch of Package erlang

From d9814796e4a735e4a452a11389359b1c503814b5 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Thu, 18 Feb 2021 13:38:26 +0100
Subject: [PATCH] runtime_tools: Clarify scheduler docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: José Valim <jose.valim@gmail.com>
Co-authored-by: Paulo F. Oliveira <paulo.ferraz.oliveira@gmail.com>
---
 lib/runtime_tools/doc/src/scheduler.xml | 28 ++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/lib/runtime_tools/doc/src/scheduler.xml b/lib/runtime_tools/doc/src/scheduler.xml
index 713d70548b..d539ccb1c6 100644
--- a/lib/runtime_tools/doc/src/scheduler.xml
+++ b/lib/runtime_tools/doc/src/scheduler.xml
@@ -63,7 +63,10 @@
 	<taglist>
 	  <tag><c>{normal, SchedulerId, Util, Percent}</c></tag>
 	  <item>Scheduler utilization of a normal scheduler with number
-	    <c>SchedulerId</c>.</item>
+	    <c>SchedulerId</c>. Schedulers that are not online will also be
+	    included.
+	    <seealso marker="erts:erlang#system_info_schedulers_online">Online
+	    schedulers</seealso> have the lowest <c>SchedulerId</c>.</item>
 	  <tag><c>{cpu, SchedulerId, Util, Percent}</c></tag>
 	  <item>Scheduler utilization of a dirty-cpu scheduler with number
 	    <c>SchedulerId</c>.</item>
@@ -117,6 +120,29 @@
         <p>Calculate scheduler utilizations for the time interval from when
 	<c><anno>Sample</anno></c> was taken and "now". The same as calling
 	<c>scheduler:utilization(Sample, scheduler:sample_all())</c>.</p>
+	<note>
+	  <p>
+	    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
+	  </p>
+<pre>
+scheduler:utilization(scheduler:sample()). % DO NOT DO THIS!
+</pre>
+          <p>
+            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.
+	  </p>
+	  <p>
+	    Instead use <seealso marker="#utilization/1">
+	    <c>scheduler:utilization(Seconds)</c></seealso> or let some time pass
+	    between <c>Sample=scheduler:sample()</c> and
+	    <c>scheduler:utilization(Sample)</c>.
+	  </p>
+	</note>
       </desc>
     </func>
 
-- 
2.26.2