diff options
Diffstat (limited to 'erts/doc')
| -rw-r--r-- | erts/doc/src/absform.xml | 4 | ||||
| -rw-r--r-- | erts/doc/src/erl.xml | 31 | ||||
| -rw-r--r-- | erts/doc/src/erl_driver.xml | 4 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 79 | ||||
| -rw-r--r-- | erts/doc/src/erl_tracer.xml | 96 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 494 | ||||
| -rw-r--r-- | erts/doc/src/init.xml | 15 |
7 files changed, 384 insertions, 339 deletions
diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index bfabb7f042..0b04f8f70e 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -152,9 +152,11 @@ <list type="bulleted"> <item>If L is an atom literal, then Rep(L) = <c>{atom,LINE,L}</c>.</item> + <item>If L is a character literal, then + Rep(L) = <c>{char,LINE,L}</c>.</item> <item>If L is a float literal, then Rep(L) = <c>{float,LINE,L}</c>.</item> - <item>If L is an integer or character literal, then + <item>If L is an integer literal, then Rep(L) = <c>{integer,LINE,L}</c>.</item> <item>If L is a string literal consisting of the characters <c>C_1</c>, ..., <c>C_k</c>, then diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 1bbde7f1e0..7b90a1ccca 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -338,7 +338,8 @@ <seealso marker="kernel:net_kernel">net_kernel(3)</seealso>. It is also ensured that <c><![CDATA[epmd]]></c> runs on the current host before Erlang is started. See - <seealso marker="epmd">epmd(1)</seealso>.</p> + <seealso marker="epmd">epmd(1)</seealso> and the + <seealso marker="#start_epmd"><c>-start_epmd</c></seealso> option.</p> <p>The name of the node will be <c><![CDATA[Name@Host]]></c>, where <c><![CDATA[Host]]></c> is the fully qualified host name of the current host. For short names, use the <c><![CDATA[-sname]]></c> flag instead.</p> @@ -463,6 +464,21 @@ flag and those running with the <c><![CDATA[-name]]></c> flag, as node names must be unique in distributed Erlang systems.</p> </item> + <tag><marker id="start_epmd"/><c>-start_epmd true | false</c></tag> + <item> + + <p>Specifies whether Erlang should start + <seealso marker="epmd">epmd</seealso> on startup. By default + this is <c>true</c>, but if you prefer to start epmd + manually, set this to <c>false</c>.</p> + + <p>This only applies if Erlang is started as a distributed node, + i.e. if <c>-name</c> or <c>-sname</c> is specified. Otherwise, + epmd is not started even if <c>-start_epmd true</c> is given.</p> + + <p>Note that a distributed node will fail to start if epmd is + not running.</p> + </item> <tag><marker id="smp"/><c><![CDATA[-smp [enable|auto|disable]]]></c></tag> <item> <p><c>-smp enable</c> and <c>-smp</c> starts the Erlang runtime @@ -627,8 +643,7 @@ <p>Sets the default binary virtual heap size of processes to the size <c><![CDATA[Size]]></c>.</p> </item> - <marker id="+hmax"/> - <tag><c><![CDATA[+hmax Size]]></c></tag> + <tag><marker id="+hmax"/><c><![CDATA[+hmax Size]]></c></tag> <item> <p>Sets the default maximum heap size of processes to the size <c><![CDATA[Size]]></c>. If <c>+hmax</c> is not given, the default is <c>0</c> @@ -637,8 +652,7 @@ <seealso marker="erlang#process_flag_max_heap_size"> <c>process_flag(max_heap_size, MaxHeapSize)</c></seealso>.</p> </item> - <marker id="+hmaxel"/> - <tag><c><![CDATA[+hmaxel true|false]]></c></tag> + <tag><marker id="+hmaxel"/><c><![CDATA[+hmaxel true|false]]></c></tag> <item> <p>Sets whether to send an error logger message for processes that reach the maximum heap size or not. If <c>+hmaxel</c> is not given, the default is <c>true</c>. @@ -646,8 +660,7 @@ <seealso marker="erlang#process_flag_max_heap_size"> <c>process_flag(max_heap_size, MaxHeapSize)</c></seealso>.</p> </item> - <marker id="+hmaxk"/> - <tag><c><![CDATA[+hmaxk true|false]]></c></tag> + <tag><marker id="+hmaxk"/><c><![CDATA[+hmaxk true|false]]></c></tag> <item> <p>Sets whether to kill processes that reach the maximum heap size or not. If <c>+hmaxk</c> is not given, the default is <c>true</c>. For more information, @@ -660,11 +673,11 @@ <p>Sets the initial process dictionary size of processes to the size <c><![CDATA[Size]]></c>.</p> </item> - <tag><marker id="+hmqd"><c>+hmqd off_heap|on_heap|mixed</c></marker></tag> + <tag><marker id="+hmqd"/><c>+hmqd off_heap|on_heap</c></tag> <item><p> Sets the default value for the process flag <c>message_queue_data</c>. If <c>+hmqd</c> is not - passed, <c>mixed</c> will be the default. For more information, + passed, <c>on_heap</c> will be the default. For more information, see the documentation of <seealso marker="erlang#process_flag_message_queue_data"><c>process_flag(message_queue_data, MQD)</c></seealso>. diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 175b7f6bfb..82215ead46 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -348,14 +348,14 @@ all will work as before.</p> </item> <tag><marker id="time_measurement"/>Time Measurement</tag> - <item><p>Support for time measurement in drivers: + <item><p>Support for time measurement in drivers:</p> <list> <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> <item><seealso marker="#erl_drv_monotonic_time"><c>erl_drv_monotonic_time()</c></seealso></item> <item><seealso marker="#erl_drv_time_offset"><c>erl_drv_time_offset()</c></seealso></item> <item><seealso marker="#erl_drv_convert_time_unit"><c>erl_drv_convert_time_unit()</c></seealso></item> - </list></p> + </list> </item> </taglist> </section> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 33a4fee182..8b02b3bae1 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -295,14 +295,14 @@ ok </p></item> <tag><marker id="time_measurement"/>Time Measurement</tag> - <item><p>Support for time measurement in NIF libraries: + <item><p>Support for time measurement in NIF libraries:</p> <list> <item><seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso></item> <item><seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso></item> <item><seealso marker="#enif_monotonic_time"><c>enif_monotonic_time()</c></seealso></item> <item><seealso marker="#enif_time_offset"><c>enif_time_offset()</c></seealso></item> <item><seealso marker="#enif_convert_time_unit"><c>enif_convert_time_unit()</c></seealso></item> - </list></p> + </list> </item> <tag><marker id="lengthy_work"/>Long-running NIFs</tag> @@ -322,13 +322,13 @@ ok <p>The <seealso marker="#enif_consume_timeslice">enif_consume_timeslice()</seealso> - function can be used to inform the runtime system about the lenght of the + function can be used to inform the runtime system about the length of the NIF call. It should typically always be used unless the NIF executes very quickly.</p> - <p>If the NIF call is too lenghty one needs to handle this in one of the + <p>If the NIF call is too lengthy one needs to handle this in one of the following ways in order to avoid degraded responsiveness, scheduler load - balancing problems, and other strange behaviours:</p> + balancing problems, and other strange behaviors:</p> <taglist> <tag>Yielding NIF</tag> @@ -410,14 +410,14 @@ ok <seealso marker="erlang#system_flag_multi_scheduling"><c>erlang:system_flag(multi_scheduling, block)</c></seealso>, might also take a very long time to complete. This since all ongoing dirty operations on all - dirty schedulers need to complete before the the block + dirty schedulers need to complete before the block operation can complete. </p> <p> A lot of operations communicating with a process executing a dirty NIF can, however, complete while it is executing the - dirty NIF. For example, retreiving information about it via + dirty NIF. For example, retrieving information about it via <c>process_info()</c>, setting its group leader, register/unregister its name, etc. </p> @@ -425,10 +425,10 @@ ok <p> Termination of a process executing a dirty NIF can only be completed up to a certain point while it is executing the - dirty NIF. All Erlang resources such as registered names, - ETS tables, etc will be released. All links and monitors + dirty NIF. All Erlang resources such as its registered name, + its ETS tables, etc will be released. All links and monitors will be triggered. The actual execution of the NIF will - however <em>not</em> be stopped. The NIF can safely contiue + however <em>not</em> be stopped. The NIF can safely continue execution, allocate heap memory, etc, but it is of course better to stop executing as soon as possible. The NIF can check whether current process is alive or not using @@ -450,8 +450,8 @@ ok collect a process in order to determine if it has references to the module, a process executing a dirty NIF might delay purging for a very long time. Delaying - a purge operatin implies delaying <em>all</em> code - loding operations which might cause severe problems for + a purge operation implies delaying <em>all</em> code + loading operations which might cause severe problems for the system as a whole. </p> </item> @@ -518,13 +518,15 @@ ok </item> <tag><marker id="reload"/>int (*reload)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)</tag> - <note><p>The reload mechanism is <em>deprecated</em>. It was only intended - as a development feature. Do not use it as an upgrade method for - live production systems. It might be removed in future releases. Be sure - to pass <c>reload</c> as <c>NULL</c> to <seealso marker="#ERL_NIF_INIT">ERL_NIF_INIT</seealso> - to disable it when not used.</p> - </note> - <item><p><c>reload</c> is called when the NIF library is loaded + + <item> + <note><p>The reload mechanism is <em>deprecated</em>. It was only intended + as a development feature. Do not use it as an upgrade method for + live production systems. It might be removed in future releases. Be sure + to pass <c>reload</c> as <c>NULL</c> to <seealso marker="#ERL_NIF_INIT">ERL_NIF_INIT</seealso> + to disable it when not used.</p> + </note> + <p><c>reload</c> is called when the NIF library is loaded and there is already a previously loaded library for this module code.</p> <p>Works the same as <c>load</c>. The only difference is that @@ -583,9 +585,9 @@ ok <p/> <code type="none"> typedef struct { - const char* <em>name</em>; - unsigned <em>arity</em>; - ERL_NIF_TERM (*<em>fptr</em>)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); + const char* name; + unsigned arity; + ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); unsigned flags; } ErlNifFunc; </code> @@ -618,8 +620,8 @@ typedef struct { <p/> <code type="none"> typedef struct { - unsigned <em>size</em>; - unsigned char* <em>data</em>; + unsigned size; + unsigned char* data; } ErlNifBinary; </code> <p><c>ErlNifBinary</c> contains transient information about an @@ -1101,15 +1103,6 @@ typedef enum { Erlang operators <c>=:=</c> and <c>=/=</c>.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_is_on_dirty_scheduler(ErlNifEnv* env)</nametext></name> - <fsummary>Check to see if executing on a dirty scheduler thread</fsummary> - <desc> - <p>Check to see if the current NIF is executing on a dirty scheduler thread. If - executing on a dirty scheduler thread true returned; otherwise false.</p> - <p>This function can only be used from a NIF-calling thread, and with an - environment corresponding to currently executing processes.</p> - </desc> - </func> <func><name><ret>int</ret><nametext>enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is a pid</fsummary> <desc><p>Return true if <c>term</c> is a pid.</p></desc> @@ -1820,7 +1813,25 @@ enif_map_iterator_destroy(env, &iter); <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_self">erl_drv_thread_self</seealso>. </p></desc> </func> - + <func><name><ret>int</ret><nametext>enif_thread_type(void)</nametext></name> + <fsummary>Determine type of current thread</fsummary> + <desc> + <p>Determine the type of currently executing thread. A positive value + indicates a scheduler thread while a negative value or zero indicates + another type of thread. Currently the following specific types exist + (which may be extended in the future):</p> + <taglist> + <tag><c>ERL_NIF_THR_UNDEFINED</c></tag> + <item><p>Undefined thread that is not a scheduler thread.</p></item> + <tag><c>ERL_NIF_THR_NORMAL_SCHEDULER</c></tag> + <item><p>A normal scheduler thread.</p></item> + <tag><c>ERL_NIF_THR_DIRTY_CPU_SCHEDULER</c></tag> + <item><p>A dirty CPU scheduler thread.</p></item> + <tag><c>ERL_NIF_THR_DIRTY_IO_SCHEDULER</c></tag> + <item><p>A dirty I/O scheduler thread.</p></item> + </taglist> + </desc> + </func> <func> <name><ret>ErlNifTime</ret><nametext>enif_time_offset(ErlNifTimeUnit time_unit)</nametext></name> <fsummary>Get current Time Offset</fsummary> diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml index d4c8bbad31..7841fdfd63 100644 --- a/erts/doc/src/erl_tracer.xml +++ b/erts/doc/src/erl_tracer.xml @@ -67,7 +67,7 @@ <desc> <p>The different trace tags that the tracer will be called with. Each trace tag is described in greater detail in - <seealso marker="#Module:trace/6">Module:trace/6</seealso> + <seealso marker="#Module:trace/5">Module:trace/5</seealso> </p> </desc> </datatype> @@ -84,14 +84,18 @@ <p>The options for the tracee.</p> <taglist> <tag><c>timestamp</c></tag> - <item>If not set to <c>undefined</c>, the tracer has been requested to - include a timestamp.</item> + <item>If set the tracer has been requested to include a timestamp.</item> + <tag><c>extra</c></tag> + <item>If set the tracepoint has included additonal data about + the trace event. What the additional data is depends on which + <c>TraceTag</c> has been triggered. The <c>extra</c> trace data + corresponds to the fifth elemnt in the trace tuples described in + <seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>.</item> <tag><c>match_spec_result</c></tag> - <item>If not set to <c>true</c>, the tracer has been requested to - include the output of a match specification that was run.</item> + <item>If set the tracer has been requested to include the output + of a match specification that was run.</item> <tag><c>scheduler_id</c></tag> - <item>Set to a number if the scheduler id is to be included by the tracer. - Otherwise it is set to <c>undefined</c>.</item> + <item>Set the scheduler id is to be included by the tracer.</item> </taglist> </desc> </datatype> @@ -115,23 +119,23 @@ <taglist> <tag><seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso></tag> <item>Mandatory</item> - <tag><seealso marker="#Module:trace/6"><c>Module:trace/6</c></seealso></tag> + <tag><seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso></tag> <item>Mandatory</item> <tag><seealso marker="#Module:enabled_procs/3"><c>Module:enabled_procs/3</c></seealso></tag> <item>Optional</item> - <tag><seealso marker="#Module:trace_procs/6"><c>Module:trace_procs/6</c></seealso></tag> + <tag><seealso marker="#Module:trace_procs/5"><c>Module:trace_procs/5</c></seealso></tag> <item>Optional</item> <tag><seealso marker="#Module:enabled_ports/3"><c>Module:enabled_ports/3</c></seealso></tag> <item>Optional</item> - <tag><seealso marker="#Module:trace_ports/6"><c>Module:trace_ports/6</c></seealso></tag> + <tag><seealso marker="#Module:trace_ports/5"><c>Module:trace_ports/5</c></seealso></tag> <item>Optional</item> <tag><seealso marker="#Module:enabled_running_ports/3"><c>Module:enabled_running_ports/3</c></seealso></tag> <item>Optional</item> - <tag><seealso marker="#Module:trace_running_ports/6"><c>Module:trace_running_ports/6</c></seealso></tag> + <tag><seealso marker="#Module:trace_running_ports/5"><c>Module:trace_running_ports/5</c></seealso></tag> <item>Optional</item> <tag><seealso marker="#Module:enabled_running_procs/3"><c>Module:enabled_running_procs/3</c></seealso></tag> <item>Optional</item> - <tag><seealso marker="#Module:trace_running_procs/6"><c>Module:trace_running_procs/6</c></seealso></tag> + <tag><seealso marker="#Module:trace_running_procs/5"><c>Module:trace_running_procs/5</c></seealso></tag> <item>Optional</item> </taglist> @@ -166,14 +170,13 @@ </desc> </func> <func> - <name>Module:trace(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -182,17 +185,17 @@ the <seealso marker="#Module:enabled/3">Module:enabled/3</seealso> callback returned <c>trace</c>. In it any side effects needed by the tracer should be done. The tracepoint payload is located in - the <c>FirstTraceTerm</c> and <c>SecondTraceTerm</c>. The content - of the TraceTerms depends on which <c>TraceTag</c> has been triggered. - The <c>FirstTraceTerm</c> and <c>SecondTraceTerm</c> correspond to the - fourth and fifth slot in the trace tuples described in + the <c>TraceTerm</c>. The content of the TraceTerm depends on which + <c>TraceTag</c> has been triggered. + The <c>TraceTerm</c> corresponds to the + fourth element in the trace tuples described in <seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>. - If the tuple only has four elements, <c>SecondTraceTerm</c> will be - <c>undefined</c>.</p> + If the trace tuple has five elements, the fifth element will be sent as + the <c>extra</c> value in the <c>Opts</c> maps.</p> </desc> </func> <func> - <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, undefined, Opts) -> Result</name> + <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result</name> <fsummary>Check if a sequence trace event should be generated.</fsummary> <type> <v>TracerState = term()</v> @@ -228,14 +231,13 @@ </func> <func> - <name>Module:trace_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_procs">trace_tag()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -243,7 +245,7 @@ <p>This callback will be called when a tracepoint is triggered and the <seealso marker="#Module:enabled_procs/3">Module:enabled_procs/3</seealso> callback returned <c>trace</c>.</p> - <p>If <c>trace_procs/6</c> is not defined <c>trace/6</c> will be called instead.</p> + <p>If <c>trace_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p> </desc> </func> @@ -265,14 +267,13 @@ </func> <func> - <name>Module:trace_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_ports">trace_tag()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -280,7 +281,7 @@ <p>This callback will be called when a tracepoint is triggered and the <seealso marker="#Module:enabled_ports/3">Module:enabled_ports/3</seealso> callback returned <c>trace</c>.</p> - <p>If <c>trace_ports/6</c> is not defined <c>trace/6</c> will be called instead.</p> + <p>If <c>trace_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p> </desc> </func> @@ -302,14 +303,13 @@ </func> <func> - <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_running_procs">trace_tag_running_procs()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -317,7 +317,7 @@ <p>This callback will be called when a tracepoint is triggered and the <seealso marker="#Module:enabled_running_procs/3">Module:enabled_running_procs/3</seealso> callback returned <c>trace</c>.</p> - <p>If <c>trace_running_procs/6</c> is not defined <c>trace/6</c> will be called instead.</p> + <p>If <c>trace_running_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p> </desc> </func> @@ -339,14 +339,13 @@ </func> <func> - <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_running_ports">trace_tag_running_ports()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -354,7 +353,7 @@ <p>This callback will be called when a tracepoint is triggered and the <seealso marker="#Module:enabled_running_ports/3">Module:enabled_running_ports/3</seealso> callback returned <c>trace</c>.</p> - <p>If <c>trace_running_ports/6</c> is not defined <c>trace/6</c> will be called instead.</p> + <p>If <c>trace_running_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p> </desc> </func> @@ -376,14 +375,13 @@ </func> <func> - <name>Module:trace_call(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_call">trace_tag_call()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -391,7 +389,7 @@ <p>This callback will be called when a tracepoint is triggered and the <seealso marker="#Module:enabled_call/3">Module:enabled_call/3</seealso> callback returned <c>trace</c>.</p> - <p>If <c>trace_call/6</c> is not defined <c>trace/6</c> will be called instead.</p> + <p>If <c>trace_call/5</c> is not defined <c>trace/5</c> will be called instead.</p> </desc> </func> @@ -413,14 +411,13 @@ </func> <func> - <name>Module:trace_send(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_send">trace_tag_send()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -428,7 +425,7 @@ <p>This callback will be called when a tracepoint is triggered and the <seealso marker="#Module:enabled_send/3">Module:enabled_send/3</seealso> callback returned <c>trace</c>.</p> - <p>If <c>trace_send/6</c> is not defined <c>trace/6</c> will be called instead.</p> + <p>If <c>trace_send/5</c> is not defined <c>trace/5</c> will be called instead.</p> </desc> </func> @@ -450,14 +447,13 @@ </func> <func> - <name>Module:trace_receive(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_receive">trace_tag_receive()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -465,7 +461,7 @@ <p>This callback will be called when a tracepoint is triggered and the <seealso marker="#Module:enabled_receive/3">Module:enabled_receive/3</seealso> callback returned <c>trace</c>.</p> - <p>If <c>trace_receive/6</c> is not defined <c>trace/6</c> will be called instead.</p> + <p>If <c>trace_receive/5</c> is not defined <c>trace/5</c> will be called instead.</p> </desc> </func> @@ -487,14 +483,13 @@ </func> <func> - <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name> + <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event should be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_gc">trace_tag_gc()</seealso></v> <v>TracerState = term()</v> <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> <v>FirstTraceTerm = term()</v> - <v>SecondTraceTerm = term() | undefined</v> <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> <v>Result = ok</v> </type> @@ -502,7 +497,7 @@ <p>This callback will be called when a tracepoint is triggered and the <seealso marker="#Module:enabled_garbage_collection/3">Module:enabled_garbage_collection/3</seealso> callback returned <c>trace</c>.</p> - <p>If <c>trace_garbage_collection/6</c> is not defined <c>trace/6</c> will be called instead.</p> + <p>If <c>trace_garbage_collection/5</c> is not defined <c>trace/5</c> will be called instead.</p> </desc> </func> @@ -543,7 +538,7 @@ ok <pre> -module(erl_msg_tracer). --export([enabled/3, trace/6, load/0]). +-export([enabled/3, trace/5, load/0]). load() -> erlang:load_nif("erl_msg_tracer", []). @@ -551,7 +546,7 @@ load() -> enabled(_, _, _) -> error. -trace(_, _, _,_, _, _) -> +trace(_, _, _,_, _) -> error. </pre> <p>erl_msg_tracer.c</p> @@ -569,7 +564,7 @@ static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); static ErlNifFunc nif_funcs[] = { {"enabled", 3, enabled}, - {"trace", 6, trace} + {"trace", 5, trace} }; ERL_NIF_INIT(erl_msg_tracer, nif_funcs, load, NULL, upgrade, unload) @@ -632,9 +627,8 @@ static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) * argv[0]: TraceTag, should only be 'send' * argv[1]: TracerState, process to send {argv[2], argv[4]} to * argv[2]: Tracee - * argv[3]: Message, ignored - * argv[4]: Recipient - * argv[5]: Options, ignored + * argv[3]: Recipient + * argv[4]: Options, ignored */ static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) { diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 9287b32fec..6289f033b2 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -1802,6 +1802,8 @@ os_prompt% </pre> <tag>string()</tag> <item>An Erlang crash dump is produced with <c><anno>Status</anno></c> as slogan. Then the runtime system exits with status code <c>1</c>. + Note that only code points in the range 0-255 may be used + and the string will be truncated if longer than 200 characters. </item> <tag><c>abort</c></tag> <item> @@ -2914,107 +2916,105 @@ os_prompt% </pre> <func> <name name="monitor" arity="2" clause_i="1"/> <name name="monitor" arity="2" clause_i="2"/> + <name name="monitor" arity="2" clause_i="3"/> <fsummary>Starts monitoring.</fsummary> <type name="registered_name"/> <type name="registered_process_identifier"/> <type name="monitor_process_identifier"/> + <type name="monitor_port_identifier"/> <desc> - <p>Send a monitor request of type <c><anno>Type</anno></c> to the - entity identified by <c><anno>Item</anno></c>. The caller of - <c>monitor/2</c> will later be notified by a monitor message on the - following format if the monitored state is changed:</p> + <p>Sends a monitor request of type <c><anno>Type</anno></c> to the + entity identified by <c><anno>Item</anno></c>. If the monitored entity + does not exist or when it dies, the caller of <c>monitor/2</c> will + be notified by a message on the following format:</p> <code type="none">{Tag, <anno>MonitorRef</anno>, <anno>Type</anno>, Object, Info}</code> <note><p>The monitor request is an asynchronous signal. That is, it takes time before the signal reaches its destination.</p></note> - <p>Valid <c><anno>Type</anno></c>s:</p> - <taglist> - <tag><marker id="monitor_process"/><c>process</c></tag> - <item> - <p>Monitor the existence of the process identified by - <c><anno>Item</anno></c>. Valid - <c><anno>Item</anno></c>s in combination with the - <c>process <anno>Type</anno></c> can be any of the following:</p> - <taglist> - <tag><c>pid()</c></tag> - <item> - <p>The process identifier of the process to monitor.</p> - </item> - <tag><c>{RegisteredName, Node}</c></tag> - <item> - <p>A tuple consisting of a registered name of a process and - a node name. The process residing on the node <c>Node</c> - with the registered name <c>{RegisteredName, Node}</c> will - be monitored.</p> - </item> - <tag><c>RegisteredName</c></tag> - <item> - <p>The process locally registered as <c>RegisteredName</c> - will become monitored.</p> - </item> - </taglist> - <note><p>When a registered name is used, the - process that has the registered name when the - monitor request reach its destination will be monitored. - The monitor is not effected if the registered name is - unregistered, or unregistered and later registered on another - process.</p></note> - <p>The monitor is triggered either when the monitored process - terminates, is non existing, or if the connection to it is - lost. In the case the connection to it is lost, we do not know - if it still exist or not. After this type of monitor has been - triggered, the monitor is automatically removed.</p> - <p>When the monitor is triggered a <c>'DOWN'</c> message is - sent to the monitoring process. A <c>'DOWN'</c> message has - the following pattern:</p> - <code type="none">{'DOWN', MonitorRef, Type, Object, Info}</code> - <p>Here <c>MonitorRef</c> and <c>Type</c> are the same as - described earlier, and:</p> - <taglist> - <tag><c>Object</c></tag> - <item> - <p>equals:</p> - <taglist> - <tag><c><anno>Item</anno></c></tag> - <item>If <c><anno>Item</anno></c> is specified by a - process identifier.</item> - <tag><c>{RegisteredName, Node}</c></tag> - <item>If <c><anno>Item</anno></c> is specified as - <c>RegisteredName</c>, or <c>{RegisteredName, Node}</c> - where <c>Node</c> corresponds to the node that the - monitored process resides on.</item> - </taglist> - </item> - <tag><c>Info</c></tag> - <item> - <p>Either the exit reason of the process, <c>noproc</c> - (non-existing process), or <c>noconnection</c> (no - connection to the node where the monitored process - resides).</p></item> - </taglist> - <p>The monitoring is turned off when the <c>'DOWN'</c> - message is sent or when - <seealso marker="#demonitor/1">demonitor/1</seealso> - is called.</p> - <p>If an attempt is made to monitor a process on an older node - (where remote process monitoring is not implemented or - where remote process monitoring by registered name is not - implemented), the call fails with <c>badarg</c>.</p> - <note> - <p>The format of the <c>'DOWN'</c> message changed in ERTS - version 5.2 (OTP R9B) for monitoring - <em>by registered name</em>. Element <c>Object</c> of - the <c>'DOWN'</c> message could in earlier versions - sometimes be the process identifier of the monitored process and sometimes - be the registered name. Now element <c>Object</c> is - always a tuple consisting of the registered name and - the node name. Processes on new nodes (ERTS version 5.2 - or higher) always get <c>'DOWN'</c> messages on - the new format even if they are monitoring processes on old - nodes. Processes on old nodes always get <c>'DOWN'</c> - messages on the old format.</p> - </note> - </item> - <tag><marker id="monitor_time_offset"/><c>time_offset</c></tag> + + <p><c><anno>Type</anno></c> can be one of the following atoms: + <c>process</c>, <c>port</c> or <c>time_offset</c>.</p> + + <p>A monitor is triggered only once, after that it is removed from + both monitoring process and the monitored entity. + Monitors are fired when the monitored process or port terminates, + does not exist at the moment of creation, or if the connection to + it is lost. In the case with connection, we lose knowledge about + the fact if it still exists or not. The monitoring is also turned off + when <seealso marker="#demonitor/1">demonitor/1</seealso> + is called.</p> + + <p>When monitoring by name please note, that the <c>RegisteredName</c> + is resolved to <c>pid()</c> or <c>port()</c> only once + at the moment of monitor instantiation, later changes to the name + registration will not affect the existing monitor.</p> + + <p>When a monitor is triggered, a <c>'DOWN'</c> message that has the + following pattern <c>{'DOWN', MonitorRef, Type, Object, Info}</c> + is sent to the monitoring process.</p> + + <p>In monitor message <c>MonitorRef</c> and <c>Type</c> are the same as + described earlier, and:</p> + <taglist> + <tag><c>Object</c></tag> + <item> + <p>The monitored entity, which triggered the event. When monitoring + a local process or port, <c>Object</c> will be equal to the + <c>pid()</c> or <c>port()</c> that was being monitored. When + monitoring process or port by name, <c>Object</c> will have format + <c>{RegisteredName, Node}</c> where <c>RegisteredName</c> is the + name which has been used with <c>monitor/2</c> call and + <c>Node</c> is local or remote node name (for ports monitored by + name, <c>Node</c> is always local node name).</p> + </item> + <tag><c>Info</c></tag> + <item> + <p>Either the exit reason of the process, <c>noproc</c> + (process or port did not exist at the time of monitor creation), + or <c>noconnection</c> (no connection to the node where the + monitored process resides). </p></item> + </taglist> + + <p>If an attempt is made to monitor a process on an older node + (where remote process monitoring is not implemented or + where remote process monitoring by registered name is not + implemented), the call fails with <c>badarg</c>.</p> + <note> + <p>The format of the <c>'DOWN'</c> message changed in ERTS + version 5.2 (OTP R9B) for monitoring + <em>by registered name</em>. Element <c>Object</c> of + the <c>'DOWN'</c> message could in earlier versions + sometimes be the process identifier of the monitored process and sometimes + be the registered name. Now element <c>Object</c> is + always a tuple consisting of the registered name and + the node name. Processes on new nodes (ERTS version 5.2 + or higher) always get <c>'DOWN'</c> messages on + the new format even if they are monitoring processes on old + nodes. Processes on old nodes always get <c>'DOWN'</c> + messages on the old format.</p> + </note> + + <taglist> + <tag>Monitoring a <marker id="monitor_process"/><c>process</c></tag> + <item> + <p>Creates monitor between the current process and another + process identified by <c><anno>Item</anno></c>, which can be a + <c>pid()</c> (local or remote), an atom <c>RegisteredName</c> or + a tuple <c>{RegisteredName, Node}</c> for a registered process, + located elsewhere.</p> + </item> + + <tag>Monitoring a <marker id="monitor_port"/><c>port</c></tag> + <item> + <p>Creates monitor between the current process and a port + identified by <c><anno>Item</anno></c>, which can be a + <c>port()</c> (only local), an atom <c>RegisteredName</c> or + a tuple <c>{RegisteredName, Node}</c> for a registered port, + located on this node. Note, that attempt to monitor a remote port + will result in <c>badarg</c>.</p> + </item> + + <tag>Monitoring a + <marker id="monitor_time_offset"/><c>time_offset</c></tag> <item> <p>Monitor changes in <seealso marker="#time_offset/0">time offset</seealso> @@ -3070,15 +3070,17 @@ os_prompt% </pre> Note that you can observe the change of the time offset when calling <c>erlang:time_offset()</c> before you get the <c>'CHANGE'</c> message.</p> - </item> </taglist> + <p>Making several calls to <c>monitor/2</c> for the same - <c><anno>Item</anno></c> and/or <c><anno>Type</anno></c> is not - an error; it results in as many independent monitoring instances.</p> + <c><anno>Item</anno></c> and/or <c><anno>Type</anno></c> is not + an error; it results in as many independent monitoring instances.</p> + <p>The monitor functionality is expected to be extended. That is, - other <c><anno>Type</anno></c>s and <c><anno>Item</anno></c>s - are expected to be supported in a future release.</p> + other <c><anno>Type</anno></c>s and <c><anno>Item</anno></c>s + are expected to be supported in a future release.</p> + <note> <p>If or when <c>monitor/2</c> is extended, other possible values for <c>Tag</c>, <c>Object</c> and @@ -4148,6 +4150,22 @@ os_prompt% </pre> <func> <name name="port_info" arity="2" clause_i="8"/> + <fsummary>Which processes are monitoring this port.</fsummary> + <desc> + <p>Returns list of pids that are monitoring given port at the + moment.</p> + <p>If the port identified by <c><anno>Port</anno></c> is not open, + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> + <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local + port identifier, or an atom.</p> + </desc> + </func> + + <func> + <name name="port_info" arity="2" clause_i="9"/> <fsummary>Information about the name of a port.</fsummary> <desc> <p><c><anno>Name</anno></c> is the command name set by @@ -4163,7 +4181,7 @@ os_prompt% </pre> </func> <func> - <name name="port_info" arity="2" clause_i="9"/> + <name name="port_info" arity="2" clause_i="10"/> <fsummary>Information about the OS pid of a port.</fsummary> <desc> <p><c><anno>OsPid</anno></c> is the process identifier (or equivalent) @@ -4182,7 +4200,7 @@ os_prompt% </pre> </func> <func> - <name name="port_info" arity="2" clause_i="10"/> + <name name="port_info" arity="2" clause_i="11"/> <fsummary>Information about the output of a port.</fsummary> <desc> <p><c><anno>Bytes</anno></c> is the total number of bytes written @@ -4201,7 +4219,7 @@ os_prompt% </pre> </func> <func> - <name name="port_info" arity="2" clause_i="11"/> + <name name="port_info" arity="2" clause_i="12"/> <fsummary>Information about the parallelism hint of a port.</fsummary> <desc> <p><c><anno>Boolean</anno></c> corresponds to the port parallelism @@ -4212,7 +4230,7 @@ os_prompt% </pre> </func> <func> - <name name="port_info" arity="2" clause_i="12"/> + <name name="port_info" arity="2" clause_i="13"/> <fsummary>Information about the queue size of a port.</fsummary> <desc> <p><c><anno>Bytes</anno></c> is the total number @@ -4229,7 +4247,7 @@ os_prompt% </pre> </func> <func> - <name name="port_info" arity="2" clause_i="13"/> + <name name="port_info" arity="2" clause_i="14"/> <fsummary>Information about the registered name of a port.</fsummary> <desc> <p><c><anno>RegisteredName</anno></c> is the registered name of @@ -4343,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> - 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. + 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> - </taglist> + <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> + </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> @@ -4449,11 +4467,6 @@ os_prompt% </pre> off heap. This is how messages always have been stored up until ERTS version 8.0. </p></item> - <tag><c>mixed</c></tag> - <item><p> - Messages may be placed either on the heap or outside - of the heap. - </p></item> </taglist> <p> The default <c>message_queue_data</c> process flag is determined @@ -4784,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. @@ -4868,16 +4883,25 @@ os_prompt% </pre> <p>A list of monitors (started by <c>monitor/2</c>) that are active for the process. For a local process monitor or a remote process monitor by a process - identifier, the list item is <c>{process, <anno>Pid</anno>}</c>. - For a remote process - monitor by name, the list item is - <c>{process, {<anno>RegName</anno>, <anno>Node</anno>}}</c>.</p> + identifier, the list consists of:</p> + <taglist> + <tag><c>{process, <anno>Pid</anno>}</c></tag> + <item>Process is monitored by pid.</item> + <tag><c>{process, {<anno>RegName</anno>, <anno>Node</anno>}}</c></tag> + <item>Local or remote process is monitored by name.</item> + <tag><c>{port, PortId}</c></tag> + <item>Local port is monitored by port id.</item> + <tag><c>{port, {<anno>RegName</anno>, <anno>Node</anno>}}</c></tag> + <item>Local port is monitored by name. Please note, that + remote port monitors are not supported, so <c>Node</c> will + always be the local node name.</item> + </taglist> </item> <tag><c>{message_queue_data, <anno>MQD</anno>}</c></tag> <item> <p>Returns the current state of the <c>message_queue_data</c> process flag. <c><anno>MQD</anno></c> is either <c>off_heap</c>, - <c>on_heap</c>, or <c>mixed</c>. For more information, see the + or <c>on_heap</c>. For more information, see the documentation of <seealso marker="#process_flag_message_queue_data"><c>process_flag(message_queue_data, MQD)</c></seealso>.</p> @@ -4964,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 @@ -5808,7 +5834,7 @@ true</pre> <item> <p>Sets the state of the <c>message_queue_data</c> process flag. <c><anno>MQD</anno></c> should be either <c>off_heap</c>, - <c>on_heap</c>, or <c>mixed</c>. The default + or <c>on_heap</c>. The default <c>message_queue_data</c> process flag is determined by the <seealso marker="erl#+hmqd"><c>+hmqd</c></seealso> <c>erl</c> command line argument. For more information, see the @@ -6609,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. @@ -7114,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> @@ -7161,10 +7187,10 @@ 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>, <c>on_heap</c>, or <c>mixed</c>. + process flag which is either <c>off_heap</c>, or <c>on_heap</c>. This default is set by the <c>erl</c> command line argument <seealso marker="erl#+hmqd"><c>+hmqd</c></seealso>. For more information on the <c>message_queue_data</c> process flag, see documentation of @@ -7642,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 @@ -8595,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> @@ -8627,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> @@ -8650,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> @@ -8694,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> @@ -8736,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> @@ -8746,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> diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml index 84a5aea335..a88a815ef6 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -178,14 +178,8 @@ <name name="stop" arity="0"/> <fsummary>Take down an Erlang node smoothly</fsummary> <desc> - <p>All applications are taken down smoothly, all code is - unloaded, and all ports are closed before the system - terminates. If the <c>-heart</c> command line flag was given, - the <c>heart</c> program is terminated before the Erlang node - terminates. Refer to <c>heart(3)</c> for more information.</p> - <p>To limit the shutdown time, the time <c>init</c> is allowed - to spend taking down applications, the <c>-shutdown_time</c> - command line flag should be used.</p> + <p>The same as + <seealso marker="#stop/1"><c>stop(0)</c></seealso>.</p> </desc> </func> <func> @@ -241,6 +235,11 @@ marker="kernel:code">code(3)</seealso>.</p> </item> + <tag><c>-epmd_module Module</c></tag> + <item> + <p>Specifies the module to use for registration and lookup of + node names. Defaults to <c>erl_epmd</c>.</p> + </item> <tag><c>-eval Expr</c></tag> <item> <p>Scans, parses and evaluates an arbitrary expression |