diff options
Diffstat (limited to 'lib/tools/doc')
| -rw-r--r-- | lib/tools/doc/src/cover.xml | 4 | ||||
| -rw-r--r-- | lib/tools/doc/src/cprof_chapter.xml | 149 | ||||
| -rw-r--r-- | lib/tools/doc/src/eprof.xml | 4 | ||||
| -rw-r--r-- | lib/tools/doc/src/fprof.xml | 6 | ||||
| -rw-r--r-- | lib/tools/doc/src/fprof_chapter.xml | 4 | ||||
| -rw-r--r-- | lib/tools/doc/src/instrument.xml | 50 | ||||
| -rw-r--r-- | lib/tools/doc/src/lcnt_chapter.xml | 4 | ||||
| -rw-r--r-- | lib/tools/doc/src/notes.xml | 16 | ||||
| -rw-r--r-- | lib/tools/doc/src/notes_history.xml | 4 |
9 files changed, 142 insertions, 99 deletions
diff --git a/lib/tools/doc/src/cover.xml b/lib/tools/doc/src/cover.xml index 9bcaa9227d..c9c7d2e6fc 100644 --- a/lib/tools/doc/src/cover.xml +++ b/lib/tools/doc/src/cover.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2001</year> - <year>2020</year> + <year>2022</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -110,7 +110,7 @@ <p>If the connection to a remote node goes down, the main node will mark it as lost. If the node comes back it will be added again. If the remote node was alive during the disconnected - periode, cover data from before and during this periode will be + period, cover data from before and during this period will be included in the analysis.</p> </description> <funcs> diff --git a/lib/tools/doc/src/cprof_chapter.xml b/lib/tools/doc/src/cprof_chapter.xml index af13b8d8d7..671f9717a6 100644 --- a/lib/tools/doc/src/cprof_chapter.xml +++ b/lib/tools/doc/src/cprof_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2002</year><year>2021</year> + <year>2002</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -37,7 +37,7 @@ </p> <p><c>cprof</c> uses breakpoints similar to local call trace, but containing counters, to collect profiling - data. Therfore there is no need for special compilation of any + data. Therefore there is no need for special compilation of any module to be profiled. </p> <p><c>cprof</c> presents all profiled modules in decreasing total @@ -96,33 +96,38 @@ <p>From the Erlang shell:</p> <pre> 1> <input>cprof:start(), cprof:pause(). % Stop counters just after start</input> -3476 +8492 2> <input>cprof:analyse().</input> -{30, - [{erl_eval,11, - [{{erl_eval,expr,3},3}, - {{erl_eval,'-merge_bindings/2-fun-0-',2},2}, - {{erl_eval,expand_module_name,2},1}, - {{erl_eval,merge_bindings,2},1}, - {{erl_eval,binding,2},1}, - {{erl_eval,expr_list,5},1}, - {{erl_eval,expr_list,3},1}, - {{erl_eval,exprs,4},1}]}, - {orddict,8, - [{{orddict,find,2},6}, - {{orddict,dict_to_list,1},1}, - {{orddict,to_list,1},1}]}, - {packages,7,[{{packages,is_segmented_1,1},6}, - {{packages,is_segmented,1},1}]}, - {lists,4,[{{lists,foldl,3},3},{{lists,reverse,1},1}]}]} +{539, + [{shell,155, + [{{shell,prep_check,1},55}, + {{shell,used_records,4},45}, + {{shell,used_records,1},45}, + {{shell,used_record_defs,2},1}, + {{shell,record_defs,2},1}, + {{shell,record_bindings,2},1}, + {{shell,exprs,7},1}, + {{shell,expr,4},1}, + {{shell,expand_records,2},1}, + {{shell,check_command,2},1}, + {{shell,apply_fun,3},1}, + {{shell,'-exprs/7-lc$^0/1-0-',1},1}, + {{shell,'-eval_loop/3-fun-0-',3},1}]}, + %% Information about many modules omitted. + . + . + . + %% Here is the last part. + {erts_internal,2,[{{erts_internal,trace_pattern,3},2}]}, + {otp_internal,1,[{{otp_internal,obsolete,3},1}]}, + {maps,1,[{{maps,from_list,1},1}]}, + {erl_internal,1,[{{erl_internal,bif,3},1}]}]} 3> <input>cprof:analyse(cprof).</input> {cprof,3,[{{cprof,tr,2},2},{{cprof,pause,0},1}]} 4> <input>cprof:stop().</input> -3476</pre> - <p>The example showed the background work that the shell performs - just to interpret the first command line. Most work is done by - <c>erl_eval</c> and <c>orddict</c>. - </p> +8586</pre> + <p>The example showed some of the background work that the shell + performs just to interpret the first command line.</p> <p>What is captured in this example is the part of the work the shell does while interpreting the command line that occurs between the actual calls to <c>cprof:start()</c> and @@ -138,17 +143,17 @@ 1 2> <input>cprof:analyse(calendar).</input> {calendar,9, - [{{calendar,df,2},1}, - {{calendar,dm,1},1}, - {{calendar,dy,1},1}, - {{calendar,last_day_of_the_month1,2},1}, + [{{calendar,last_day_of_the_month1,2},1}, {{calendar,last_day_of_the_month,2},1}, {{calendar,is_leap_year1,1},1}, {{calendar,is_leap_year,1},1}, + {{calendar,dy,1},1}, + {{calendar,dm,1},1}, + {{calendar,df,2},1}, {{calendar,day_of_the_week,3},1}, {{calendar,date_to_gregorian_days,3},1}]} 3> <input>cprof:stop().</input> -3271</pre> +8648</pre> <p>The example tells us that "Aktiebolaget LM Ericsson & Co" was registered on a Monday (since the return value of the first command is 1), and that the <c>calendar</c> module @@ -164,66 +169,70 @@ <p>Write a module:</p> <pre> -module(sort). - -export([do/1]). - + do(N) -> cprof:stop(), cprof:start(), do(N, []). - + do(0, L) -> R = lists:sort(L), cprof:pause(), R; do(N, L) -> - do(N-1, [random:uniform(256)-1 | L]).</pre> + do(N-1, [rand:uniform(256)-1 | L]).</pre> <p>From the Erlang shell:</p> <pre> 1> <input>c(sort).</input> {ok,sort} -2> <input>l(random).</input> -{module,random} +2> <input>rand:seed(default, 42), ok.</input> +ok. 3> <input>sort:do(1000).</input> -[0,0,1,1,1,1,1,1,2,2,2,3,3,3,3,3,4,4,4,5,5,5,5,6,6,6,6,6,6|...] +[0,0,0,1,1,1,1,2,2,3,3,4,4,4,4,5,5,5,6,6,6,6,7,7,7,7,7,8,8|...] 4> <input>cprof:analyse().</input> -{9050, - [{lists_sort,6047, - [{{lists_sort,merge3_2,6},923}, - {{lists_sort,merge3_1,6},879}, - {{lists_sort,split_2,5},661}, - {{lists_sort,rmerge3_1,6},580}, - {{lists_sort,rmerge3_2,6},543}, - {{lists_sort,merge3_12_3,6},531}, - {{lists_sort,merge3_21_3,6},383}, - {{lists_sort,split_2_1,6},338}, - {{lists_sort,rmerge3_21_3,6},299}, - {{lists_sort,rmerge3_12_3,6},205}, - {{lists_sort,rmerge2_2,4},180}, - {{lists_sort,rmerge2_1,4},171}, - {{lists_sort,merge2_1,4},127}, - {{lists_sort,merge2_2,4},121}, - {{lists_sort,mergel,2},79}, - {{lists_sort,rmergel,2},27}]}, - {random,2001, - [{{random,uniform,1},1000}, - {{random,uniform,0},1000}, - {{random,seed0,0},1}]}, +{13180, + [{lists,6173, + [{{lists,rmerge3_1,6},1045}, + {{lists,rmerge3_2,6},977}, + {{lists,split_1,5},652}, + {{lists,merge3_1,6},579}, + {{lists,merge3_2,6},577}, + {{lists,rmerge3_12_3,6},511}, + {{lists,split_1_1,6},347}, + {{lists,merge3_12_3,6},310}, + {{lists,rmerge3_21_3,6},282}, + {{lists,merge3_21_3,6},221}, + {{lists,merge2_1,4},154}, + {{lists,merge2_2,5},138}, + {{lists,reverse,2},106}, + {{lists,rmerge2_2,5},87}, + {{lists,rmergel,2},81}, + {{lists,rmerge2_1,4},75}, + {{lists,mergel,2},28}, + {{lists,keyfind,3},2}, + {{lists,sort,1},1}]}, + {rand,5000, + [{{rand,uniform_s,2},1000}, + {{rand,uniform,1},1000}, + {{rand,seed_put,1},1000}, + {{rand,seed_get,0},1000}, + {{rand,exsss_uniform,2},1000}]}, + {erlang,1004, + [{{erlang,put,2},1000}, + {{erlang,trace_pattern,3},2}, + {{erlang,ensure_tracer_module_loaded,2},2}]}, {sort,1001,[{{sort,do,2},1001}]}, - {lists,1,[{{lists,sort,1},1}]}]} + {erts_internal,2,[{{erts_internal,trace_pattern,3},2}]}]} 5> <input>cprof:stop().</input> -5369</pre> +12625</pre> <p>The example shows some details of how <c>lists:sort/1</c> - works. It used 6047 function calls in the module - <c>lists_sort</c> to complete the work. - </p> - <p>This time, since the shell was not involved, no other work was - done in the system during the profiling. If you retry the same - example with a freshly started Erlang emulator, but omit the - command <c>l(random)</c>, the analysis will show a lot more - function calls done by <c>code_server</c> and others to - automatically load the module <c>random</c>. + works. It used 6173 function calls in the module + <c>lists</c> to complete the work. </p> + <p>This time, since the shell was not involved in starting and + stopping <c>cprof</c>, no other work was done in the system during + the profiling.</p> </section> </chapter> diff --git a/lib/tools/doc/src/eprof.xml b/lib/tools/doc/src/eprof.xml index b10624751f..a1e25b5505 100644 --- a/lib/tools/doc/src/eprof.xml +++ b/lib/tools/doc/src/eprof.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2020</year> + <year>1996</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -74,7 +74,7 @@ <p>Stops profiling started with <seemfa marker="#start_profiling/1"><c>start_profiling/1</c></seemfa> or - <seemfa marker="#profile/1"><c>prifile/1</c></seemfa>.</p> + <seemfa marker="#profile/1"><c>profile/1</c></seemfa>.</p> </desc> </func> <func> diff --git a/lib/tools/doc/src/fprof.xml b/lib/tools/doc/src/fprof.xml index e7e7ad69f3..4e4e466fc7 100644 --- a/lib/tools/doc/src/fprof.xml +++ b/lib/tools/doc/src/fprof.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2001</year><year>2021</year> + <year>2001</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -485,7 +485,7 @@ <item>Includes a section containing call statistics for all calls regardless of process, in the analysis.</item> <tag><c>{totals, false}</c></tag> - <item>Supresses the totals section in the analysis, which is + <item>Suppresses the totals section in the analysis, which is the default.</item> <tag><c>details</c> | <c>{details, true}</c></tag> <item>Prints call statistics for each process in the @@ -686,7 +686,7 @@ create_file_slow(FD, M, N) -> {{fprof,apply_start_stop,4}, 1, 0.000, 0.000}], { suspend, 299, 32.002, 0.000}, % [ ]}.</pre> - <p>We find no particulary long suspend times, so no function seems + <p>We find no particularly long suspend times, so no function seems to have waited in a receive statement. Actually, <c>prim_file:drv_command/4</c> contains a receive statement, but in this test program, the message lies in the process receive diff --git a/lib/tools/doc/src/fprof_chapter.xml b/lib/tools/doc/src/fprof_chapter.xml index 65ffcede1a..b07eef2637 100644 --- a/lib/tools/doc/src/fprof_chapter.xml +++ b/lib/tools/doc/src/fprof_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2001</year><year>2021</year> + <year>2001</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -37,7 +37,7 @@ processes. </p> <p><c>fprof</c> uses tracing with timestamps to collect profiling - data. Therfore there is no need for special compilation of any + data. Therefore there is no need for special compilation of any module to be profiled. </p> <p><c>fprof</c> presents wall clock times from the host machine OS, diff --git a/lib/tools/doc/src/instrument.xml b/lib/tools/doc/src/instrument.xml index 4305bad599..80a5e8c3ba 100644 --- a/lib/tools/doc/src/instrument.xml +++ b/lib/tools/doc/src/instrument.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1998</year><year>2021</year> + <year>1998</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -36,11 +36,12 @@ <modulesummary>Analysis and Utility Functions for Instrumentation</modulesummary> <description> <p>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.</p> + usage in an Erlang runtime system. Currently, only the allocation of + memory can be studied.</p> <note> - <p>Note that this whole module is experimental, and the representations - used as well as the functionality is likely to change in the future.</p> + <p>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.</p> </note> </description> <datatypes> @@ -52,6 +53,13 @@ <p>The upper bound of the first interval is provided by the function that returned the histogram, and the last interval has no upper bound.</p> + <p>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.</p> + <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 @@ <p><c><anno>Origin</anno></c> is generally which NIF or driver that allocated the blocks, or 'system' if it could not be determined.</p> <p><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>.</p> + 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>.</p> <p>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.</p> @@ -78,7 +89,10 @@ <p><c><anno>TotalSize</anno></c> is the total size of the carrier, including its header.</p> <p><c><anno>Allocations</anno></c> is a summary of the allocated blocks - in the carrier.</p> + 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).</p> <p><c><anno>FreeBlocks</anno></c> is a histogram of the free block sizes in the carrier.</p> <p>If the carrier could not be scanned in full without harming the @@ -115,11 +129,13 @@ <taglist> <tag><c>allocator_types</c></tag> <item> - <p>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.</p> + <p>The allocator types that will be searched.</p> + <p>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.</p> <p>Defaults to all <c>alloc_util</c> allocators.</p> </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> diff --git a/lib/tools/doc/src/lcnt_chapter.xml b/lib/tools/doc/src/lcnt_chapter.xml index c8afd7063d..a9628525c9 100644 --- a/lib/tools/doc/src/lcnt_chapter.xml +++ b/lib/tools/doc/src/lcnt_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2009</year><year>2021</year> + <year>2009</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -42,7 +42,7 @@ completed its access to the resource and unlocked it. The <c>lcnt</c> tool measures these lock conflicts. </p> <p> - Locks have an inherent cost in execution time and memory space. It takes time initialize, destroy, aquiring or releasing locks. To decrease lock contention it + Locks have an inherent cost in execution time and memory space. It takes time initialize, destroy, acquiring or releasing locks. To decrease lock contention it some times necessary to use finer grained locking strategies. This will usually also increase the locking overhead and hence there is a tradeoff between lock contention and overhead. In general, lock contention increases with the number of threads running concurrently. The <c>lcnt</c> tool does not measure locking overhead. </p> diff --git a/lib/tools/doc/src/notes.xml b/lib/tools/doc/src/notes.xml index 0680f28f71..84a6019e57 100644 --- a/lib/tools/doc/src/notes.xml +++ b/lib/tools/doc/src/notes.xml @@ -31,6 +31,22 @@ </header> <p>This document describes the changes made to the Tools application.</p> +<section><title>Tools 3.5.3</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Removed the previously undocumented and unsupported + <c>emem</c> tool.</p> + <p> + Own Id: OTP-17892 Aux Id: PR-5591 </p> + </item> + </list> + </section> + +</section> + <section><title>Tools 3.5.2</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/tools/doc/src/notes_history.xml b/lib/tools/doc/src/notes_history.xml index d955cbde69..7ef93d6fbf 100644 --- a/lib/tools/doc/src/notes_history.xml +++ b/lib/tools/doc/src/notes_history.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2016</year> + <year>2006</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -91,7 +91,7 @@ <p>Own Id: OTP-4594</p> </item> <item> - <p>Improvments for support of Emacs 21 contributed by Dave + <p>Improvements for support of Emacs 21 contributed by Dave Love. The bulk of the changes are actually cosmetic commentary/doc fixes. The significant ones make it play better with Emacs 21 with up-to-date facilities. In |