File 0884-tools-Update-instrument-documentation.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0884-tools-Update-instrument-documentation.patch of Package erlang

From 98ddc68e28a403469d106bb4b9337bb795bffef1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20H=C3=B6gberg?= <john@erlang.org>
Date: Mon, 14 Feb 2022 16:09:09 +0100
Subject: [PATCH] tools: Update `instrument` documentation

---
 lib/tools/doc/src/instrument.xml | 48 ++++++++++++++++++++++----------
 1 file changed, 33 insertions(+), 15 deletions(-)

diff --git a/lib/tools/doc/src/instrument.xml b/lib/tools/doc/src/instrument.xml
index 4305bad599..b1b2a8339e 100644
--- a/lib/tools/doc/src/instrument.xml
+++ b/lib/tools/doc/src/instrument.xml
@@ -36,11 +36,12 @@
 <modulesummary>Analysis and Utility Functions for Instrumentation</modulesummary>
 <description>
 The module <c>instrument</c> contains support for studying the resource
- usage in an Erlang runtime system. Currently, only the allocation of memory can
- be studied.
+ usage in an Erlang runtime system. Currently, only the allocation of
+ memory can be studied.
 <note>
- Note that this whole module is experimental, and the representations
- used as well as the functionality is likely to change in the future.
+ Since this module inspects internal details of the runtime system it
+ may differ greatly from one version to another. We make no compatibility
+ guarantees in this module.
 </note>
 </description>
 <datatypes>
@@ -52,6 +53,13 @@
 The upper bound of the first interval is provided by the function
 that returned the histogram, and the last interval has no upper
 bound.
+ For example, the histogram below has 40 (<c>message</c>) blocks
+ between 256-512 bytes in size, 78 blocks between 512-1024 bytes,2
+ blocks between 1-2KB, and 2 blocks between 2-4KB.
+ <code type="none"><![CDATA[
+> instrument:allocations(#{ histogram_start => 128, histogram_width => 15 }).
+{ok, {128, 0, #{ message => {0,40,78,2,2,0,0,0,0,0,0,0,0,0,0}, ... } }}
+ ]]></code>
 </desc>
 </datatype>
 <datatype>
@@ -62,7 +70,10 @@
 <c><anno>Origin</anno></c> is generally which NIF or driver that
 allocated the blocks, or 'system' if it could not be determined.
 <c><anno>Type</anno></c> is the allocation category that the blocks
- belong to, e.g. <c>db_term</c>, <c>message</c> or <c>binary</c>.
+ belong to, e.g. <c>db_term</c>, <c>message</c> or <c>binary</c>. The
+ categories correspond to those in
+ <url href="https://github.com/erlang/otp/blob/master/erts/emulator/beam/erl_alloc.types">
+ erl_alloc.types</url>.
 If one or more carriers could not be scanned in full without harming
 the responsiveness of the system, <c><anno>UnscannedSize</anno></c>
 is the number of bytes that had to be skipped.
@@ -78,7 +89,10 @@
 <c><anno>TotalSize</anno></c> is the total size of the carrier,
 including its header.
 <c><anno>Allocations</anno></c> is a summary of the allocated blocks
- in the carrier.
+ in the carrier. Note that carriers may contain multiple different
+ block types when carrier pools are shared between different allocator
+ types (see the <seecref marker="erts:erts_alloc#M_cp"><c>erts_alloc</c>
+ </seecref> documentation for more details).
 <c><anno>FreeBlocks</anno></c> is a histogram of the free block
 sizes in the carrier.
 If the carrier could not be scanned in full without harming the
@@ -115,11 +129,13 @@
 <taglist>
 <tag><c>allocator_types</c></tag>
 <item>
- The allocator types that will be searched. Note that blocks can
- move freely between allocator types, so restricting the search to
- certain allocators may return unexpected types (e.g. process
- heaps when searching binary_alloc), or hide blocks that were
- migrated out.
+ The allocator types that will be searched.
+ Specifying a specific allocator type may lead to strange results
+ when carrier migration between different allocator types has been
+ enabled: you may see unexpected types (e.g. process heaps when
+ searching binary_alloc), or fewer blocks than expected if the
+ carriers the blocks are on have been migrated out to an allocator
+ of a different type.
 Defaults to all <c>alloc_util</c> allocators.
 </item>
 <tag><c>scheduler_ids</c></tag>
@@ -217,10 +233,12 @@
 <code type="none"><![CDATA[
 > instrument:carriers(#{ histogram_start => 512, histogram_width => 8 }).
 {ok,{512,
- [{ll_alloc,1048576,0,1048344,71,false,{0,0,0,0,0,0,0,0}},
- {binary_alloc,1048576,0,324640,13,false,{3,0,0,1,0,0,0,2}},
- {eheap_alloc,2097152,0,1037200,45,false,{2,1,1,3,4,3,2,2}},
- {fix_alloc,32768,0,29544,82,false,{22,0,0,0,0,0,0,0}},
+ [{driver_alloc,false,262144,0,
+ [{driver_alloc,1,32784}],
+ {0,0,0,0,0,0,0,1}},
+ {binary_alloc,false,32768,0,
+ [{binary_alloc,15,4304}],
+ {3,0,0,0,1,0,0,0}},
 {...}|...]}}
 ]]></code>
 </desc>
-- 
2.34.1

Places

File 0884-tools-Update-instrument-documentation.patch of Package erlang

Places