aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erlang.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erlang.xml')
-rw-r--r--erts/doc/src/erlang.xml242
1 files changed, 123 insertions, 119 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index fa13e4c142..6289f033b2 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -4361,86 +4361,86 @@ os_prompt% </pre>
<marker id="process_flag_max_heap_size"/>
<func>
<name name="process_flag" arity="2" clause_i="5"/>
- <type name="max_heap_size"/>
<fsummary>Sets process flag <c>max_heap_size</c> for the calling process.</fsummary>
+ <type name="max_heap_size"/>
<desc>
<p>
This flag sets the maximum heap size for the calling process.
If <c><anno>MaxHeapSize</anno></c> is an integer, the system default
values for <c>kill</c> and <c>error_logger</c> are used.
- <taglist>
- <tag><c>size</c></tag>
- <item>
- <p>
- The maximum size in words of the process. If set to zero, the
- heap size limit is disabled. Badarg will be thrown if the value is
- smaller than
- <seealso marker="#process_flag_min_heap_size"><c>min_heap_size</c></seealso>.
- The size check is only done when a garbage collection is triggered.
- </p>
- <p>
- <c>size</c> is the entire heap of the process when garbage collection
- is triggered, this includes all generational heaps, the process stack,
- any <seealso marker="#process_flag_message_queue_data">
- messages that are considered to be part of the heap</seealso> and any
- extra memory that the garbage collector needs during collection.
- </p>
- <p>
- <c>size</c> is the same as can be retrieved using
- <seealso marker="#process_info_total_heap_size">
- <c>erlang:process_info(Pid, total_heap_size)</c></seealso>,
- or by adding <c>heap_block_size</c>, <c>old_heap_block_size</c>
- and <c>mbuf_size</c> from <seealso marker="#process_info_garbage_collection_info">
- <c>erlang:process_info(Pid, garbage_collection_info)</c></seealso>.
- </p>
- </item>
- <tag><c>kill</c></tag>
- <item>
- <p>
- When set to <c>true</c> the runtime system will send an
- untrappable exit signal with reason <c>kill</c> to the process
- if the maximum heap size is reached. The garbage collection
- that triggered the <c>kill</c> will not be completed, instead the
- process will exit as soon as is possible. When set to <c>false</c>
- no exit signal will be sent to the process, instead it will
- continue executing.
- </p>
- <p>
- If <c>kill</c> is not defined in the map
- the system default will be used. The default system default
- is <c>true</c>. It can be changed by either the erl
- <seealso marker="erl#+hmaxk">+hmaxk</seealso> option,
- or <seealso marker="#system_flag_max_heap_size"><c>
- erlang:system_flag(max_heap_size, MaxHeapSize)</c></seealso>.
- </p>
- </item>
- <tag><c>error_logger</c></tag>
- <item>
- <p>
- When set to <c>true</c> the runtime system will send a
- message to the current <seealso marker="kernel:error_logger"><c>error_logger</c></seealso>
- containing details about the process when the maximum
- heap size is reached. One <c>error_logger</c> report will
- be sent each time the limit is reached.
- </p>
- <p>
- If <c>error_logger</c> is not defined in the map the system
- default will be used. The default system default is <c>true</c>.
- It can be changed by either the erl <seealso marker="erl#+hmaxel">+hmaxel</seealso>
- option, or <seealso marker="#system_flag_max_heap_size"><c>
- erlang:system_flag(max_heap_size, MaxHeapSize)</c></seealso>.
- </p>
- </item>
+ </p>
+ <taglist>
+ <tag><c>size</c></tag>
+ <item>
+ <p>
+ The maximum size in words of the process. If set to zero, the
+ heap size limit is disabled. Badarg will be thrown if the value is
+ smaller than
+ <seealso marker="#process_flag_min_heap_size"><c>min_heap_size</c></seealso>.
+ The size check is only done when a garbage collection is triggered.
+ </p>
+ <p>
+ <c>size</c> is the entire heap of the process when garbage collection
+ is triggered, this includes all generational heaps, the process stack,
+ any <seealso marker="#process_flag_message_queue_data">
+ messages that are considered to be part of the heap</seealso> and any
+ extra memory that the garbage collector needs during collection.
+ </p>
+ <p>
+ <c>size</c> is the same as can be retrieved using
+ <seealso marker="#process_info_total_heap_size">
+ <c>erlang:process_info(Pid, total_heap_size)</c></seealso>,
+ or by adding <c>heap_block_size</c>, <c>old_heap_block_size</c>
+ and <c>mbuf_size</c> from <seealso marker="#process_info_garbage_collection_info">
+ <c>erlang:process_info(Pid, garbage_collection_info)</c></seealso>.
+ </p>
+ </item>
+ <tag><c>kill</c></tag>
+ <item>
+ <p>
+ When set to <c>true</c> the runtime system will send an
+ untrappable exit signal with reason <c>kill</c> to the process
+ if the maximum heap size is reached. The garbage collection
+ that triggered the <c>kill</c> will not be completed, instead the
+ process will exit as soon as is possible. When set to <c>false</c>
+ no exit signal will be sent to the process, instead it will
+ continue executing.
+ </p>
<p>
- The heap size of a process is quite hard to predict, especially the
- amount of memory that is used during the garbage collection. When
- contemplating using this option, it is recommended to first run
- it in production with <c>kill</c> set to <c>false</c> and inspect
- the <c>error_logger</c> reports to see what the normal peak sizes
- of the processes in the system is and then tune the value
- accordingly.
+ If <c>kill</c> is not defined in the map
+ the system default will be used. The default system default
+ is <c>true</c>. It can be changed by either the erl
+ <seealso marker="erl#+hmaxk">+hmaxk</seealso> option,
+ or <seealso marker="#system_flag_max_heap_size"><c>
+ erlang:system_flag(max_heap_size, MaxHeapSize)</c></seealso>.
</p>
- </taglist>
+ </item>
+ <tag><c>error_logger</c></tag>
+ <item>
+ <p>
+ When set to <c>true</c> the runtime system will send a
+ message to the current <seealso marker="kernel:error_logger"><c>error_logger</c></seealso>
+ containing details about the process when the maximum
+ heap size is reached. One <c>error_logger</c> report will
+ be sent each time the limit is reached.
+ </p>
+ <p>
+ If <c>error_logger</c> is not defined in the map the system
+ default will be used. The default system default is <c>true</c>.
+ It can be changed by either the erl <seealso marker="erl#+hmaxel">+hmaxel</seealso>
+ option, or <seealso marker="#system_flag_max_heap_size"><c>
+ erlang:system_flag(max_heap_size, MaxHeapSize)</c></seealso>.
+ </p>
+ </item>
+ </taglist>
+ <p>
+ The heap size of a process is quite hard to predict, especially the
+ amount of memory that is used during the garbage collection. When
+ contemplating using this option, it is recommended to first run
+ it in production with <c>kill</c> set to <c>false</c> and inspect
+ the <c>error_logger</c> reports to see what the normal peak sizes
+ of the processes in the system is and then tune the value
+ accordingly.
</p>
</desc>
</func>
@@ -4797,8 +4797,10 @@ os_prompt% </pre>
The content of <c><anno>GCInfo</anno></c> can be changed without
prior notice.</p>
</item>
- <marker id="process_info_garbage_collection_info"/>
- <tag><c>{garbage_collection_info, <anno>GCInfo</anno>}</c></tag>
+ <tag>
+ <marker id="process_info_garbage_collection_info"/>
+ <c>{garbage_collection_info, <anno>GCInfo</anno>}</c>
+ </tag>
<item>
<p><c><anno>GCInfo</anno></c> is a list containing miscellaneous
detailed information about garbage collection for this process.
@@ -4986,8 +4988,10 @@ os_prompt% </pre>
total suspend count on <c><anno>Suspendee</anno></c>,
only the parts contributed by <c><anno>Pid</anno></c>.</p>
</item>
- <marker id="process_info_total_heap_size"/>
- <tag><c>{total_heap_size, <anno>Size</anno>}</c></tag>
+ <tag>
+ <marker id="process_info_total_heap_size"/>
+ <c>{total_heap_size, <anno>Size</anno>}</c>
+ </tag>
<item>
<p><c><anno>Size</anno></c> is the total size, in words, of all heap
fragments of the process. This includes the process stack and
@@ -6631,8 +6635,8 @@ ok
<marker id="system_flag_max_heap_size"></marker>
<func>
<name name="system_flag" arity="2" clause_i="8"/>
- <type name="max_heap_size"/>
<fsummary>Sets system flag <c>max_heap_size</c></fsummary>
+ <type name="max_heap_size"/>
<desc>
<p>
Sets the default maximum heap size settings for processes.
@@ -7136,9 +7140,9 @@ ok
<name name="system_info" arity="1" clause_i="37"/>
<name name="system_info" arity="1" clause_i="38"/>
<name name="system_info" arity="1" clause_i="39"/>
+ <fsummary>Information about the default process heap settings.</fsummary>
<type name="message_queue_data"/>
<type name="max_heap_size"/>
- <fsummary>Information about the default process heap settings.</fsummary>
<desc>
<taglist>
<tag><c>fullsweep_after</c></tag>
@@ -7183,7 +7187,7 @@ ok
where <c><anno>MinHeapSize</anno></c> is the current
system-wide minimum heap size for spawned processes.</p>
</item>
- <tag><marker id="system_info_message_queue_data"><c>message_queue_data</c></marker></tag>
+ <tag><marker id="system_info_message_queue_data"/><c>message_queue_data</c></tag>
<item>
<p>Returns the default value of the <c>message_queue_data</c>
process flag which is either <c>off_heap</c>, or <c>on_heap</c>.
@@ -7664,7 +7668,7 @@ ok
and
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
</item>
- <tag><marker id="system_info_otp_release"><c>otp_release</c></marker></tag>
+ <tag><marker id="system_info_otp_release"/><c>otp_release</c></tag>
<item>
<marker id="system_info_otp_release"></marker>
<p>Returns a string containing the OTP release number of the
@@ -8617,21 +8621,21 @@ timestamp() ->
<tag><c>send</c></tag>
<item>
<p>Traces sending of messages.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_send">send</seealso></c> and
- <c><seealso marker="#trace_3_trace_messages_send_to_non_existing_process">send_to_non_existing_process</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_send"><c>send</c></seealso> and
+ <seealso marker="#trace_3_trace_messages_send_to_non_existing_process"><c>send_to_non_existing_process</c></seealso>.</p>
</item>
<tag><c>'receive'</c></tag>
<item>
<p>Traces receiving of messages.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_receive">'receive'</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_receive"><c>'receive'</c></seealso>.</p>
</item>
<tag><c>call</c></tag>
<item>
<p>Traces certain function calls. Specify which function
calls to trace by calling
<seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_call">call</seealso></c> and
- <c><seealso marker="#trace_3_trace_messages_return_from">return_from</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_call"><c>call</c></seealso> and
+ <seealso marker="#trace_3_trace_messages_return_from"><c>return_from</c></seealso>.</p>
</item>
<tag><c>silent</c></tag>
<item>
@@ -8649,9 +8653,9 @@ timestamp() ->
specification function <c>{silent,Bool}</c>, giving
a high degree of control of which functions with which
arguments that trigger the trace.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_call">call</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_return_from">return_from</seealso></c>, and
- <c><seealso marker="#trace_3_trace_messages_return_to">return_to</seealso></c>. Or rather, the absence of.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_call"><c>call</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_return_from"><c>return_from</c></seealso>, and
+ <seealso marker="#trace_3_trace_messages_return_to"><c>return_to</c></seealso>. Or rather, the absence of.</p>
</item>
<tag><c>return_to</c></tag>
<item>
@@ -8672,43 +8676,43 @@ timestamp() ->
<p>To get trace messages containing return values from
functions, use the <c>{return_trace}</c> match
specification action instead.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_return_to">return_to</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_return_to"><c>return_to</c></seealso>.</p>
</item>
<tag><c>procs</c></tag>
<item>
<p>Traces process-related events.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_spawn">spawn</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_spawned">spawned</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_exit">exit</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_register">register</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_unregister">unregister</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_link">link</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_unlink">unlink</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_getting_linked">getting_linked</seealso></c>, and
- <c><seealso marker="#trace_3_trace_messages_getting_unlinked">getting_unlinked</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_spawn"><c>spawn</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_spawned"><c>spawned</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_exit"><c>exit</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_register"><c>register</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_unregister"><c>unregister</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_link"><c>link</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_unlink"><c>unlink</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_getting_linked"><c>getting_linked</c></seealso>, and
+ <seealso marker="#trace_3_trace_messages_getting_unlinked"><c>getting_unlinked</c></seealso>.</p>
</item>
<tag><c>ports</c></tag>
<item>
<p>Traces port-related events.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_open">open</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_closed">closed</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_register">register</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_unregister">unregister</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_getting_linked">getting_linked</seealso></c>, and
- <c><seealso marker="#trace_3_trace_messages_getting_unlinked">getting_unlinked</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_open"><c>open</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_closed"><c>closed</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_register"><c>register</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_unregister"><c>unregister</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_getting_linked"><c>getting_linked</c></seealso>, and
+ <seealso marker="#trace_3_trace_messages_getting_unlinked"><c>getting_unlinked</c></seealso>.</p>
</item>
<tag><c>running</c></tag>
<item>
<p>Traces scheduling of processes.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_in_proc">in</seealso></c> and
- <c><seealso marker="#trace_3_trace_messages_out_proc">out</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_in_proc"><c>in</c></seealso> and
+ <seealso marker="#trace_3_trace_messages_out_proc"><c>out</c></seealso>.</p>
</item>
<tag><c>exiting</c></tag>
<item>
<p>Traces scheduling of exiting processes.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_in_exiting_proc">in_exiting</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_out_exiting_proc">out_exiting</seealso></c>, and
- <c><seealso marker="#trace_3_trace_messages_out_exited_proc">out_exited</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_in_exiting_proc"><c>in_exiting</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_out_exiting_proc"><c>out_exiting</c></seealso>, and
+ <seealso marker="#trace_3_trace_messages_out_exited_proc"><c>out_exited</c></seealso>.</p>
</item>
<tag><c>running_procs</c></tag>
<item>
@@ -8716,21 +8720,21 @@ timestamp() ->
However this option also includes schedule events when the
process executes within the context of a port without
being scheduled out itself.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_in_proc">in</seealso></c> and
- <c><seealso marker="#trace_3_trace_messages_out_proc">out</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_in_proc"><c>in</c></seealso> and
+ <seealso marker="#trace_3_trace_messages_out_proc"><c>out</c></seealso>.</p>
</item>
<tag><c>running_ports</c></tag>
<item>
<p>Traces scheduling of ports.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_in_port">in</seealso></c> and
- <c><seealso marker="#trace_3_trace_messages_out_port">out</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_in_port"><c>in</c></seealso> and
+ <seealso marker="#trace_3_trace_messages_out_port"><c>out</c></seealso>.</p>
</item>
<tag><c>garbage_collection</c></tag>
<item>
<p>Traces garbage collections of processes.</p>
- <p>Message tags: <c><seealso marker="#trace_3_trace_messages_gc_minor_start">gc_minor_start</seealso></c>,
- <c><seealso marker="#trace_3_trace_messages_gc_max_heap_size">gc_max_heap_size</seealso></c> and
- <c><seealso marker="#trace_3_trace_messages_gc_minor_end">gc_minor_end</seealso></c>.</p>
+ <p>Message tags: <seealso marker="#trace_3_trace_messages_gc_minor_start"><c>gc_minor_start</c></seealso>,
+ <seealso marker="#trace_3_trace_messages_gc_max_heap_size"><c>gc_max_heap_size</c></seealso> and
+ <seealso marker="#trace_3_trace_messages_gc_minor_end"><c>gc_minor_end</c></seealso>.</p>
</item>
<tag><c>timestamp</c></tag>
<item>
@@ -8758,7 +8762,7 @@ timestamp() ->
<seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
monotonic time</seealso> time-stamp in all trace messages. The
time-stamp (Ts) has the same format and value as produced by
- <c><seealso marker="#monotonic_time-1">erlang:monotonic_time(nano_seconds)</seealso></c>.
+ <seealso marker="#monotonic_time-1"><c>erlang:monotonic_time(nano_seconds)</c></seealso>.
This flag overrides the <c>cpu_timestamp</c> flag.</p>
</item>
<tag><c>strict_monotonic_timestamp</c></tag>
@@ -8768,8 +8772,8 @@ timestamp() ->
monotonic time</seealso> and a monotonically increasing
integer in all trace messages. The time-stamp (Ts) has the
same format and value as produced by
- <c>{<seealso marker="#monotonic_time-1">erlang:monotonic_time(nano_seconds)</seealso>,
- <seealso marker="#unique_integer-1">erlang:unique_integer([monotonic])</seealso>}</c>.
+ <c>{</c><seealso marker="#monotonic_time-1"><c>erlang:monotonic_time(nano_seconds)</c></seealso><c>,</c>
+ <seealso marker="#unique_integer-1"><c>erlang:unique_integer([monotonic])</c></seealso><c>}</c>.
This flag overrides the <c>cpu_timestamp</c> flag.</p>
</item>
<tag><c>arity</c></tag>