aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc')
-rw-r--r--system/doc/design_principles/statem.xml6
-rw-r--r--system/doc/efficiency_guide/advanced.xml2
-rw-r--r--system/doc/efficiency_guide/profiling.xml171
-rw-r--r--system/doc/efficiency_guide/xmlfiles.mk4
-rw-r--r--system/doc/getting_started/seq_prog.xml13
-rw-r--r--system/doc/reference_manual/errors.xml47
-rw-r--r--system/doc/reference_manual/expressions.xml32
-rw-r--r--system/doc/reference_manual/xmlfiles.mk5
-rw-r--r--system/doc/top/Makefile6
9 files changed, 212 insertions, 74 deletions
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index a0611a46da..5be2981f62 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2016</year><year>2017</year>
+ <year>2016</year><year>2018</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -1679,8 +1679,8 @@ handle_event(
{next_state, {open,LockButton}, Data,
[{reply,From,ok}]};
[Digit|Rest] -> % Incomplete
- {keep_state, Data#{remaining := Rest, 30000},
- [{reply,From,ok}]};
+ {keep_state, Data#{remaining := Rest},
+ [{reply,From,ok}, 30000]};
[_|_] -> % Wrong
{keep_state, Data#{remaining := Code},
[{reply,From,ok}]}
diff --git a/system/doc/efficiency_guide/advanced.xml b/system/doc/efficiency_guide/advanced.xml
index 896eda5f1c..245e7d3674 100644
--- a/system/doc/efficiency_guide/advanced.xml
+++ b/system/doc/efficiency_guide/advanced.xml
@@ -151,7 +151,7 @@
<row>
<cell>Processes</cell>
<cell>The maximum number of simultaneously alive Erlang processes
- is by default 32,768. This limit can be configured at startup.
+ is by default 262,144. This limit can be configured at startup.
For more information, see the
<seealso marker="erts:erl#max_processes"><c>+P</c></seealso>
command-line flag in the
diff --git a/system/doc/efficiency_guide/profiling.xml b/system/doc/efficiency_guide/profiling.xml
index bf50a03fa6..f185456158 100644
--- a/system/doc/efficiency_guide/profiling.xml
+++ b/system/doc/efficiency_guide/profiling.xml
@@ -41,30 +41,87 @@
<p>Erlang/OTP contains several tools to help finding bottlenecks:</p>
<list type="bulleted">
- <item><c>fprof</c> provides the most detailed information about
- where the program time is spent, but it significantly slows down the
- program it profiles.</item>
-
- <item><p><c>eprof</c> provides time information of each function
- used in the program. No call graph is produced, but <c>eprof</c> has
- considerable less impact on the program it profiles.</p>
- <p>If the program is too large to be profiled by <c>fprof</c> or
- <c>eprof</c>, the <c>cover</c> and <c>cprof</c> tools can be used
- to locate code parts that are to be more thoroughly profiled using
- <c>fprof</c> or <c>eprof</c>.</p></item>
-
- <item><c>cover</c> provides execution counts per line per
- process, with less overhead than <c>fprof</c>. Execution counts
- can, with some caution, be used to locate potential performance
- bottlenecks.</item>
-
- <item><c>cprof</c> is the most lightweight tool, but it only
- provides execution counts on a function basis (for all processes,
- not per process).</item>
+ <item><p><seealso marker="tools:fprof"><c>fprof</c></seealso> provides
+ the most detailed information about where the program time is spent,
+ but it significantly slows down the program it profiles.</p></item>
+
+ <item><p><seealso marker="tools:eprof"><c>eprof</c></seealso> provides
+ time information of each function used in the program. No call graph is
+ produced, but <c>eprof</c> has considerable less impact on the program it
+ profiles.</p>
+ <p>If the program is too large to be profiled by <c>fprof</c> or
+ <c>eprof</c>, <c>cprof</c> can be used to locate code parts that
+ are to be more thoroughly profiled using <c>fprof</c> or <c>eprof</c>.</p></item>
+
+ <item><p><seealso marker="tools:cprof"><c>cprof</c></seealso> is the
+ most lightweight tool, but it only provides execution counts on a
+ function basis (for all processes, not per process).</p></item>
+
+ <item><p><seealso marker="runtime_tools:dbg"><c>dbg</c></seealso> is the
+ generic erlang tracing frontend. By using the <c>timestamp</c> or
+ <c>cpu_timestamp</c> options it can be used to time how long function
+ calls in a live system take.</p></item>
+
+ <item><p><seealso marker="tools:lcnt"><c>lcnt</c></seealso> is used
+ to find contention points in the Erlang Run-Time System's internal
+ locking mechanisms. It is useful when looking for bottlenecks in
+ interaction between process, port, ets tables and other entities
+ that can be run in parallel.</p></item>
+
</list>
<p>The tools are further described in
<seealso marker="#profiling_tools">Tools</seealso>.</p>
+
+ <p>There are also several open source tools outside of Erlang/OTP
+ that can be used to help profiling. Some of them are:</p>
+
+ <list type="bulleted">
+ <item><url href="https://github.com/isacssouza/erlgrind">erlgrind</url>
+ can be used to visualize fprof data in kcachegrind.</item>
+ <item><url href="https://github.com/proger/eflame">eflame</url>
+ is an alternative to fprof that displays the profiling output as a flamegraph.</item>
+ <item><url href="https://ferd.github.io/recon/index.html">recon</url>
+ is a collection of Erlang profiling and debugging tools.
+ This tool comes with an accompanying E-book called
+ <url href="https://www.erlang-in-anger.com/">Erlang in Anger</url>.</item>
+ </list>
+ </section>
+
+ <section>
+ <title>Memory profiling</title>
+ <pre>eheap_alloc: Cannot allocate 1234567890 bytes of memory (of type "heap").</pre>
+ <p>The above slogan is one of the more common reasons for Erlang to terminate.
+ For unknown reasons the Erlang Run-Time System failed to allocate memory to
+ use. When this happens a crash dump is generated that contains information
+ about the state of the system as it ran out of mmeory. Use the
+ <seealso marker="observer:cdv"><c>crashdump_viewer</c></seealso> to get a
+ view of the memory is being used. Look for processes with large heaps or
+ many messages, large ets tables, etc.</p>
+ <p>When looking at memory usage in a running system the most basic function
+ to get information from is <seealso marker="erts:erlang#memory/0"><c>
+ erlang:memory()</c></seealso>. It returns the current memory usage
+ of the system. <seealso marker="tools:instrument"><c>instrument(3)</c></seealso>
+ can be used to get a more detailed breakdown of where memory is used.</p>
+ <p>Processes, ports and ets tables can then be inspecting using their
+ respective info functions, i.e.
+ <seealso marker="erts:erlang#process_info_memory"><c>erlang:process_info/2
+ </c></seealso>,
+ <seealso marker="erts:erlang#port_info_memory"><c>erlang:port_info/2
+ </c></seealso> and
+ <seealso marker="stdlib:ets#info/1"><c>ets:info/1</c></seealso>.
+ </p>
+ <p>Sometimes the system can enter a state where the reported memory
+ from <c>erlang:memory(total)</c> is very different from the
+ memory reported by the OS. This can be because of internal
+ fragmentation within the Erlang Run-Time System. Data about
+ how memory is allocated can be retrieved using
+ <seealso marker="erts:erlang#system_info_allocator">
+ <c>erlang:system_info(allocator)</c></seealso>.
+ The data you get from that function is very raw and not very plesant to read.
+ <url href="http://ferd.github.io/recon/recon_alloc.html">recon_alloc</url>
+ can be used to extract useful information from system_info
+ statistics counters.</p>
</section>
<section>
@@ -80,6 +137,22 @@
tools on the whole system. Instead you want to concentrate on
central processes and modules, which contribute for a big part
of the execution.</p>
+
+ <p>There are also some tools that can be used to get a view of the
+ whole system with more or less overhead.</p>
+ <list type="bulleted">
+ <item><seealso marker="observer:observer"><c>observer</c></seealso>
+ is a GUI tool that can connect to remote nodes and display a
+ variety of information about the running system.</item>
+ <item><seealso marker="observer:etop"><c>etop</c></seealso>
+ is a command line tool that can connect to remote nodes and
+ display information similar to what the UNIX tool top shows.</item>
+ <item><seealso marker="runtime_tools:msacc"><c>msacc</c></seealso>
+ allows the user to get a view of what the Erlang Run-Time system
+ is spending its time doing. Has a very low overhead, which makes it
+ useful to run in heavily loaded systems to get some idea of where
+ to start doing more granular profiling.</item>
+ </list>
</section>
<section>
@@ -128,7 +201,7 @@
performance impact. Using <c>fprof</c> is just a matter of
calling a few library functions, see the
<seealso marker="tools:fprof">fprof</seealso> manual page in
- Tools .<c>fprof</c> was introduced in R8.</p>
+ Tools.</p>
</section>
<section>
@@ -142,20 +215,6 @@
</section>
<section>
- <title>cover</title>
- <p>The primary use of <c>cover</c> is coverage analysis to verify
- test cases, making sure that all relevant code is covered.
- <c>cover</c> counts how many times each executable line of code
- is executed when a program is run, on a per module basis.</p>
- <p>Clearly, this information can be used to determine what
- code is run very frequently and can therefore be subject for
- optimization. Using <c>cover</c> is just a matter of calling a
- few library functions, see the
- <seealso marker="tools:cover">cover</seealso> manual page in
- Tools.</p>
- </section>
-
- <section>
<title>cprof</title>
<p><c>cprof</c> is something in between <c>fprof</c> and
<c>cover</c> regarding features. It counts how many times each
@@ -202,16 +261,6 @@
<cell>No</cell>
</row>
<row>
- <cell><c>cover</c></cell>
- <cell>Per module to screen/file</cell>
- <cell>Small</cell>
- <cell>Moderate slowdown</cell>
- <cell>Yes, per line</cell>
- <cell>No</cell>
- <cell>No</cell>
- <cell>No</cell>
- </row>
- <row>
<cell><c>cprof</c></cell>
<cell>Per module to caller</cell>
<cell>Small</cell>
@@ -224,6 +273,37 @@
<tcaption>Tool Summary</tcaption>
</table>
</section>
+
+ <section>
+ <title>dbg</title>
+ <p><c>dbg</c> is a generic Erlang trace tool. By using the
+ <c>timestamp</c> or <c>cpu_timestamp</c> options it can be used
+ as a precision instrument to profile how long time a function
+ call takes for a specific process. This can be very useful when
+ trying to understand where time is spent in a heavily loaded
+ system as it is possible to limit the scope of what is profiled
+ to be very small.
+ For more information, see the
+ <seealso marker="runtime_tools:dbg">dbg</seealso> manual page in
+ Runtime Tools.</p>
+ </section>
+
+ <section>
+ <title>lcnt</title>
+ <p><c>lcnt</c> is used to profile interactions inbetween
+ entities that run in parallel. For example if you have
+ a process that all other processes in the system needs
+ to interact with (maybe it has some global configuration),
+ then <c>lcnt</c> can be used to figure out if the interaction
+ with that process is a problem.</p>
+ <p>In the Erlang Run-time System entities are only run in parallel
+ when there are multiple schedulers. Therefore <c>lcnt</c> will
+ show more contention points (and thus be more useful) on systems
+ using many schedulers on many cores.</p>
+ <p>For more information, see the
+ <seealso marker="tools:lcnt">lcnt</seealso> manual page in Tools.</p>
+ </section>
+
</section>
<section>
@@ -282,4 +362,3 @@
</list>
</section>
</chapter>
-
diff --git a/system/doc/efficiency_guide/xmlfiles.mk b/system/doc/efficiency_guide/xmlfiles.mk
index 88df9417f5..23c0d991b4 100644
--- a/system/doc/efficiency_guide/xmlfiles.mk
+++ b/system/doc/efficiency_guide/xmlfiles.mk
@@ -29,5 +29,5 @@ EFF_GUIDE_CHAPTER_FILES = \
processes.xml \
profiling.xml \
tablesDatabases.xml \
- drivers.xml
-
+ drivers.xml \
+ retired_myths.xml
diff --git a/system/doc/getting_started/seq_prog.xml b/system/doc/getting_started/seq_prog.xml
index 6b7e1cd24f..2b0750ff80 100644
--- a/system/doc/getting_started/seq_prog.xml
+++ b/system/doc/getting_started/seq_prog.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2016</year>
+ <year>2003</year><year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -271,11 +271,12 @@ convert(N, centimeter) ->
{'EXIT',{function_clause,[{tut2,convert,
[3,miles],
[{file,"tut2.erl"},{line,4}]},
- {erl_eval,do_apply,5,[{file,"erl_eval.erl"},{line,482}]},
- {shell,exprs,7,[{file,"shell.erl"},{line,666}]},
- {shell,eval_exprs,7,[{file,"shell.erl"},{line,621}]},
- {shell,eval_loop,3,[{file,"shell.erl"},{line,606}]}]}}</pre>
-
+ {erl_eval,do_apply,6,
+ [{file,"erl_eval.erl"},{line,677}]},
+ {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
+ {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
+ {shell,eval_loop,3,
+ [{file,"shell.erl"},{line,627}]}]}}</pre>
</section>
<section>
diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml
index b16c5da6eb..16d3e7590e 100644
--- a/system/doc/reference_manual/errors.xml
+++ b/system/doc/reference_manual/errors.xml
@@ -108,14 +108,55 @@
(see <seealso marker="#exit_reasons">Exit Reason</seealso>),
and a stack trace (which aids in finding the code location of
the exception).</p>
- <p>The stack trace can be retrieved using
- <c>erlang:get_stacktrace/0</c>
- from within a <c>try</c> expression, and is returned for
+ <p>The stack trace can be be bound to a variable from within
+ a <c>try</c> expression, and is returned for
exceptions of class <c>error</c> from a <c>catch</c> expression.</p>
<p>An exception of class <c>error</c> is also known as a run-time
error.</p>
+
+ <section>
+ <title>The call-stack back trace (stacktrace)</title>
+ <p>The stack back-trace (<em>stacktrace</em>) is a list of
+ <c>{Module,Function,Arity,Location}</c>
+ tuples. The field <c>Arity</c> in the first tuple can be the
+ argument list of that function call instead of an arity integer,
+ depending on the exception.</p>
+
+ <p><c>Location</c> is a (possibly empty) list of two-tuples
+ that can indicate the location in the source code of the
+ function. The first element is an atom describing the type of
+ information in the second element. The following items can
+ occur:</p>
+ <taglist>
+ <tag><c>file</c></tag>
+ <item>The second element of the tuple is a string (list of
+ characters) representing the filename of the source file
+ of the function.
+ </item>
+ <tag><c>line</c></tag>
+ <item>The second element of the tuple is the line number
+ (an integer &gt; 0) in the source file
+ where the exception occurred or the function was called.
+ </item>
+ </taglist>
+ <warning><p>Developers should rely on stacktrace entries only for
+ debugging purposes.</p>
+ <p>The VM performs tail call optimization, which
+ does not add new entries to the stacktrace, and also limits stacktraces
+ to a certain depth. Furthermore, compiler options, optimizations and
+ future changes may add or remove stacktrace entries, causing any code
+ that expects the stacktrace to be in a certain order or contain specific
+ items to fail.</p>
+ <p>The only exception to this rule is the class <c>error</c> with the
+ reason <c>undef</c> which is guaranteed to include the <c>Module</c>,
+ <c>Function</c> and <c>Arity</c> of the attempted
+ function as the first stacktrace entry.</p>
+ </warning>
+ </section>
+
</section>
+
<section>
<title>Handling of Run-time Errors in Erlang</title>
diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index cf2d5034aa..94e40dd077 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -1340,9 +1340,9 @@ hello</pre>
<code type="none">
try Exprs
catch
- [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] ->
+ Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
ExceptionBody1;
- [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] ->
+ ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
ExceptionBodyN
end</code>
<p>This is an enhancement of
@@ -1362,10 +1362,12 @@ end</code>
the evaluation. In that case the exception is caught and
the patterns <c>ExceptionPattern</c> with the right exception
class <c>Class</c> are sequentially matched against the caught
- exception. An omitted <c>Class</c> is shorthand for <c>throw</c>.
- If a match succeeds and the optional guard sequence
+ exception. If a match succeeds and the optional guard sequence
<c>ExceptionGuardSeq</c> is true, the corresponding
<c>ExceptionBody</c> is evaluated to become the return value.</p>
+ <p><c>Stacktrace</c>, if specified, must be the name of a variable
+ (not a pattern). The stack trace is bound to the variable when
+ the corresponding <c>ExceptionPattern</c> matches.</p>
<p>If an exception occurs during evaluation of <c>Exprs</c> but
there is no matching <c>ExceptionPattern</c> of the right
<c>Class</c> with a true guard sequence, the exception is passed
@@ -1373,6 +1375,18 @@ end</code>
expression.</p>
<p>If an exception occurs during evaluation of <c>ExceptionBody</c>,
it is not caught.</p>
+ <p>It is allowed to omit <c>Class</c> and <c>Stacktrace</c>.
+ An omitted <c>Class</c> is shorthand for <c>throw</c>:</p>
+
+ <code type="none">
+try Exprs
+catch
+ ExceptionPattern1 [when ExceptionGuardSeq1] ->
+ ExceptionBody1;
+ ExceptionPatternN [when ExceptionGuardSeqN] ->
+ ExceptionBodyN
+end</code>
+
<p>The <c>try</c> expression can have an <c>of</c>
section:
</p>
@@ -1384,10 +1398,10 @@ try Exprs of
PatternN [when GuardSeqN] ->
BodyN
catch
- [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] ->
+ Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
ExceptionBody1;
...;
- [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] ->
+ ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
ExceptionBodyN
end</code>
<p>If the evaluation of <c>Exprs</c> succeeds without an exception,
@@ -1408,10 +1422,10 @@ try Exprs of
PatternN [when GuardSeqN] ->
BodyN
catch
- [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] ->
+ Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
ExceptionBody1;
...;
- [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] ->
+ ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
ExceptionBodyN
after
AfterBody
@@ -1470,7 +1484,7 @@ try Expr
catch
throw:Term -> Term;
exit:Reason -> {'EXIT',Reason}
- error:Reason -> {'EXIT',{Reason,erlang:get_stacktrace()}}
+ error:Reason:Stk -> {'EXIT',{Reason,Stk}}
end</code>
</section>
diff --git a/system/doc/reference_manual/xmlfiles.mk b/system/doc/reference_manual/xmlfiles.mk
index 61637ae701..fffcbdd911 100644
--- a/system/doc/reference_manual/xmlfiles.mk
+++ b/system/doc/reference_manual/xmlfiles.mk
@@ -30,5 +30,6 @@ REF_MAN_CHAPTER_FILES = \
processes.xml \
distributed.xml \
code_loading.xml \
- ports.xml
-
+ ports.xml \
+ character_set.xml \
+ typespec.xml
diff --git a/system/doc/top/Makefile b/system/doc/top/Makefile
index 116ec688fa..b6a80aadf5 100644
--- a/system/doc/top/Makefile
+++ b/system/doc/top/Makefile
@@ -50,6 +50,8 @@ include ../tutorial/xmlfiles.mk
include ../design_principles/xmlfiles.mk
include ../oam/xmlfiles.mk
+BOOK_FILES = book.xml
+
XML_FILES = \
$(INST_GUIDE_CHAPTER_FILES:%=../installation_guide/%) \
$(SYSTEM_PRINCIPLES_CHAPTER_FILES:%=../system_principles/%) \
@@ -70,9 +72,9 @@ XML_FILES = \
../efficiency_guide/part.xml \
../tutorial/part.xml \
../design_principles/part.xml \
- ../oam/part.xml
+ ../oam/part.xml \
+ $(BOOK_FILES)
-BOOK_FILES = book.xml
XMLLINT_SRCDIRS= ../installation_guide:../system_principles:../embedded:../getting_started:../reference_manual:../programming_examples:../efficiency_guide:../tutorial:../design_principles:../oam
HTMLDIR= ../html
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-17 19:44:45 +0000