Merge PR-1639 from sverker/scheduler_utilization OTP-14904

runtime_tools: Add scheduler module

4 files changed, 144 insertions, 1 deletions

diff --git a/lib/runtime_tools/doc/src/Makefile b/lib/runtime_tools/doc/src/Makefile
index ec19a4ce59..a9b0056a93 100644
--- a/lib/runtime_tools/doc/src/Makefile
+++ b/lib/runtime_tools/doc/src/Makefile
@@ -41,7 +41,13 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
 # Target Specs
 # ----------------------------------------------------
 XML_APPLICATION_FILES = ref_man.xml
-XML_REF3_FILES = dbg.xml dyntrace.xml erts_alloc_config.xml system_information.xml msacc.xml
+XML_REF3_FILES = \
+	dbg.xml \
+	dyntrace.xml \
+	erts_alloc_config.xml \
+	system_information.xml \
+	msacc.xml \
+	scheduler.xml
 XML_REF6_FILES = runtime_tools_app.xml
 
 XML_PART_FILES = part.xml
diff --git a/lib/runtime_tools/doc/src/ref_man.xml b/lib/runtime_tools/doc/src/ref_man.xml
index d2fb7a29af..eb3a6f0f5c 100644
--- a/lib/runtime_tools/doc/src/ref_man.xml
+++ b/lib/runtime_tools/doc/src/ref_man.xml
@@ -37,6 +37,7 @@
   <xi:include href="dyntrace.xml"/>
   <xi:include href="erts_alloc_config.xml"/>
   <xi:include href="msacc.xml"/>
+  <xi:include href="scheduler.xml"/>
   <xi:include href="system_information.xml"/>
 </application>
 
diff --git a/lib/runtime_tools/doc/src/scheduler.xml b/lib/runtime_tools/doc/src/scheduler.xml
new file mode 100644
index 0000000000..dd8bf73bae
--- /dev/null
+++ b/lib/runtime_tools/doc/src/scheduler.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2018</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+
+    </legalnotice>
+
+    <title></title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno>1</docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
+    <file>scheduler.xml</file>
+  </header>
+  <module>scheduler</module>
+  <modulesummary>Measure scheduler utilization</modulesummary>
+  <description>
+    <p>This module contains utility functions for easier measurement and
+    calculation of scheduler utilization, otherwise obtained from calling the
+    more primitive <seealso marker="erts:erlang#statistics_scheduler_wall_time">
+    <c>statistics(scheduler_wall_time)</c></seealso>.</p>
+    <p>The simplest usage is to call <seealso marker="#utilization-1">
+    <c>scheduler:utilization(Seconds)</c></seealso>.</p>
+  </description>
+
+  <datatypes>
+    <datatype>
+      <name name="sched_sample"/>
+    </datatype>
+    <datatype>
+      <name name="sched_type"/>
+    </datatype>
+    <datatype>
+      <name name="sched_id"/>
+    </datatype>
+    <datatype>
+      <name name="sched_util_result"/>
+      <desc>
+	<p>A list of tuples containing results for individual schedulers
+	as well as aggregated averages. <c>Util</c> is the scheduler utilization
+	as a floating point value between 0.0 and 1.0. <c>Percent</c> is the
+	same utilization as a more human readable string expressed in percent.</p>
+	<taglist>
+	  <tag><c>{normal, SchedulerId, Util, Percent}</c></tag>
+	  <item>Scheduler utilization of a normal scheduler with number
+	    <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>
+	  <tag><c>{io, SchedulerId, Util, Percent}</c></tag>
+	  <item>Scheduler utilization of a dirty-io scheduler with number
+	    <c>SchedulerId</c>. This tuple will only exist if both samples were
+	    taken with <seealso marker="#sample_all-0"><c>sample_all/0</c></seealso>.</item>
+	  <tag><c>{total, Util, Percent}</c></tag>
+	  <item>Total utilization of all normal and dirty-cpu schedulers.</item>
+	  <tag><c>{weighted, Util, Percent}</c></tag>
+	  <item>Total utilization of all normal and dirty-cpu schedulers,
+	  weighted against maximum amount of available CPU time.</item>
+	</taglist>
+      </desc>
+    </datatype>
+  </datatypes>
+
+  <funcs>
+
+    <func>
+      <name name="sample" arity="0"/>
+      <fsummary>Get scheduler utilization sample.</fsummary>
+      <desc>
+        <p>Return a scheduler utilization sample for normal and dirty-cpu
+	schedulers.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="sample_all" arity="0"/>
+      <fsummary>Get scheduler utilization sample.</fsummary>
+      <desc>
+        <p>Return a scheduler utilization sample for all schedulers,
+	including dirty-io schedulers.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="utilization" arity="1" clause_i="1"/>
+      <fsummary>Measure scheduler utilizations during a period of time.</fsummary>
+      <desc>
+        <p>Measure utilization for normal and dirty-cpu schedulers during
+	<c><anno>Seconds</anno></c> seconds, and then return the result.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="utilization" arity="1" clause_i="2"/>
+      <fsummary>Measure scheduler utilizations since sample.</fsummary>
+      <desc>
+        <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>
+      </desc>
+    </func>
+
+    <func>
+      <name name="utilization" arity="2"/>
+      <fsummary>Measure scheduler utilizations between two samples.</fsummary>
+      <desc>
+	<p>Calculates scheduler utilizations for the time interval between
+	the two samples obtained from calling
+	<seealso marker="#sample-0"><c>sample/0</c></seealso> or
+	<seealso marker="#sample_all-0"><c>sample_all/0</c></seealso>.</p>
+      </desc>
+    </func>
+
+  </funcs>
+ </erlref>
diff --git a/lib/runtime_tools/doc/src/specs.xml b/lib/runtime_tools/doc/src/specs.xml
index 978bd39e55..33fe7fa370 100644
--- a/lib/runtime_tools/doc/src/specs.xml
+++ b/lib/runtime_tools/doc/src/specs.xml
@@ -2,4 +2,5 @@
 <specs xmlns:xi="http://www.w3.org/2001/XInclude">
   <xi:include href="../specs/specs_system_information.xml"/>
   <xi:include href="../specs/specs_msacc.xml"/>
+  <xi:include href="../specs/specs_scheduler.xml"/>
 </specs>