Merge branch 'egil/redocument-scheduler_wall_time/OTP-9858' into maint

* egil/redocument-scheduler_wall_time/OTP-9858:
  doc: Enhance wording and remove typos
  doc: Move examples and notes into tag-lists
  doc: Rewording of scheduler_wall_time
  doc: Change variable name to 'A' to reflect Active
  doc: Rewording of scheduler busy
  Update scheduler_wall_time documentation

1 files changed, 82 insertions, 26 deletions

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index fbe7b36163..8c438b0bd7 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -4881,6 +4881,7 @@ true</pre>
         <v>Type, Res -- see below</v>
       </type>
       <desc>
+	        <p>All times are in milliseconds unless otherwise specified.</p>
         <p>Returns information about the system as specified by
           <c>Type</c>:</p>
         <taglist>
@@ -4894,15 +4895,20 @@ true</pre>
           <item>
             <p>Returns
               <c>{Total_Exact_Reductions, Exact_Reductions_Since_Last_Call}</c>.</p>
-            <p><em>NOTE:</em><c>statistics(exact_reductions)</c> is
-              a more expensive operation than
-              <seealso marker="#statistics_reductions">statistics(reductions)</seealso>
-              especially on an Erlang machine with SMP support.</p>
+		  <note><p><c>statistics(exact_reductions)</c> is
+				  a more expensive operation than
+				  <seealso marker="#statistics_reductions">statistics(reductions)</seealso>
+				  especially on an Erlang machine with SMP support.</p>
+		  </note>
           </item>
           <tag><c>garbage_collection</c></tag>
           <item>
             <p>Returns <c>{Number_of_GCs, Words_Reclaimed, 0}</c>. This
               information may not be valid for all implementations.</p>
+			<pre>
+> <input>statistics(garbage_collection).</input>
+{85,23961,0}
+</pre>
           </item>
           <tag><c>io</c></tag>
           <item>
@@ -4914,12 +4920,18 @@ true</pre>
           <tag><marker id="statistics_reductions"><c>reductions</c></marker></tag>
           <item>
             <p>Returns
-              <c>{Total_Reductions, Reductions_Since_Last_Call}</c>.</p>
-            <p><em>NOTE:</em> From erts version 5.5 (OTP release R11B)
-              this value does not include reductions performed in current
-              time slices of currently scheduled processes. If an
-              exact value is wanted, use
-              <seealso marker="#statistics_exact_reductions">statistics(exact_reductions)</seealso>.</p>
+				<c>{Total_Reductions, Reductions_Since_Last_Call}</c>.</p>
+			<note>
+				<p>From erts version 5.5 (OTP release R11B)
+					this value does not include reductions performed in current
+					time slices of currently scheduled processes. If an
+					exact value is wanted, use
+					<seealso marker="#statistics_exact_reductions">statistics(exact_reductions)</seealso>.</p>
+			</note>
+        <pre>
+> <input>statistics(reductions).</input>
+{2046,11}
+</pre>
           </item>
           <tag><c>run_queue</c></tag>
           <item>
@@ -4932,20 +4944,72 @@ true</pre>
 	    Note that the run-time is the sum of the run-time for all
 	    threads in the Erlang run-time system and may therefore be greater
 	    than the wall-clock time.</p>
+        <pre>
+> <input>statistics(runtime).</input>
+{1690,1620}
+</pre>
           </item>
           <tag><marker id="statistics_scheduler_wall_time"><c>scheduler_wall_time</c></marker></tag>
           <item>
-            <p>Returns
-	    <c>[{Scheduler_Id, Scheduler_Worked_Time, Scheduler_Total_Time}]</c>, time lapses are since the
-	    the system flag <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso>
-	    was set to true.
+            <p>Returns a list of tuples with 
+	    <c>{SchedulerId, ActiveTime, TotalTime}</c>, where <c>SchedulerId</c> is an integer id of the scheduler, <c>ActiveTime</c> is
+		 the duration the scheduler has been busy, <c>TotalTime</c> is the total time duration since 
+	    <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso>
+		activation. The time unit is not defined and may be subject to change
+		between releases, operating systems and system restarts.
+		<c>scheduler_wall_time</c> should only be used to calculate relative
+		values for scheduler-utilization. <c>ActiveTime</c> can never exceed <c>TotalTime</c>.
+		</p>
+
+		<p>The definition of a busy scheduler is when it is not idle or not
+			scheduling (selecting) a process or port, meaning; executing process
+			code, executing linked-in-driver or NIF code, executing
+			built-in-functions or any other runtime handling, garbage collecting
+			or handling any other memory management. Note, a scheduler may also be
+			busy even if the operating system has scheduled out the scheduler
+			thread.
+		</p>
+
+		<p>
 	    Returns <c>undefined</c> if the system flag <seealso marker="#system_flag_scheduler_wall_time">
-	    scheduler_wall_time</seealso> is set to false.
+	    scheduler_wall_time</seealso> is turned off.
 	    </p>
-	    <p>The list of scheduler information is unsorted and may come in different order
-	    between calls. The time unit is undefined and may be changed and should only be used
-	    to calculate relative utilization.
+
+	    <p>The list of scheduler information is unsorted and may appear in different order
+	    between calls. 
 	    </p>
+		<p>Using <c>scheduler_wall_time</c> to calculate scheduler utilization.</p>
+<pre>
+> <input>erlang:system_flag(scheduler_wall_time, true).</input>
+false
+> <input>Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.</input>
+ok
+</pre>
+		<p>Some time later we will take another snapshot and calculate scheduler-utilization per scheduler.</p>
+<pre>
+> <input>Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.</input>
+ok
+> <input>lists:map(fun({{I, A0, T0}, {I, A1, T1}}) ->
+	{I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).</input>
+[{1,0.9743474730177548},
+ {2,0.9744843782751444},
+ {3,0.9995902361669045},
+ {4,0.9738012596572161},
+ {5,0.9717956667018103},
+ {6,0.9739235846420741},
+ {7,0.973237033077876},
+ {8,0.9741297293248656}]
+</pre>
+		<p>Using the same snapshots to calculate a total scheduler-utilization.</p>
+<pre>
+> <input>{A, T} = lists:foldl(fun({{_, A0, T0}, {_, A1, T1}}, {Ai,Ti}) ->
+	{Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), A/T.</input>
+0.9769136803764825
+</pre>
+ 
+        <note>
+          <p><c>scheduler_wall_time</c> is by default disabled. Use <c>erlang:system_flag(scheduler_wall_time, true)</c> to enable it. </p>
+        </note>
           </item>
 
           <tag><c>wall_clock</c></tag>
@@ -4957,14 +5021,6 @@ true</pre>
               opposed to runtime or CPU time.</p>
           </item>
         </taglist>
-        <p>All times are in milliseconds.</p>
-        <pre>
-> <input>statistics(runtime).</input>
-{1690,1620}
-> <input>statistics(reductions).</input>
-{2046,11}
-> <input>statistics(garbage_collection).</input>
-{85,23961,0}</pre>
       </desc>
     </func>
     <func>