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.xml8340
1 files changed, 4919 insertions, 3421 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 0e5909a52d..30e6751f41 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -4,20 +4,21 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2013</year>
+ <year>1996</year><year>2015</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
- The contents of this file are subject to the Erlang Public License,
- Version 1.1, (the "License"); you may not use this file except in
- compliance with the License. You should have received a copy of the
- Erlang Public License along with this software. If not, it can be
- retrieved online at http://www.erlang.org/.
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
- Software distributed under the License is distributed on an "AS IS"
- basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
- the License for the specific language governing rights and limitations
- under the License.
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
</legalnotice>
@@ -29,36 +30,107 @@
<file>erlang.xml</file>
</header>
<module>erlang</module>
- <modulesummary>The Erlang BIFs</modulesummary>
+ <modulesummary>The Erlang BIFs.</modulesummary>
<description>
- <p>By convention, most built-in functions (BIFs) are seen as being
- in the module <c>erlang</c>. A number of the BIFs are viewed more
+ <p>By convention, most Built-In Functions (BIFs) are seen as being
+ in this module. Some of the BIFs are viewed more
or less as part of the Erlang programming language and are
- <em>auto-imported</em>. Thus, it is not necessary to specify
- the module name and both the calls <c>atom_to_list(Erlang)</c> and
- <c>erlang:atom_to_list(Erlang)</c> are identical.</p>
- <p>In the text, auto-imported BIFs are listed without module prefix.
+ <em>auto-imported</em>. Thus, it is not necessary to specify the
+ module name. For example, the calls <c>atom_to_list(Erlang)</c>
+ and <c>erlang:atom_to_list(Erlang)</c> are identical.</p>
+ <p>Auto-imported BIFs are listed without module prefix.
BIFs listed with module prefix are not auto-imported.</p>
- <p>BIFs may fail for a variety of reasons. All BIFs fail with
+ <p>BIFs can fail for various reasons. All BIFs fail with
reason <c>badarg</c> if they are called with arguments of an
- incorrect type. The other reasons that may make BIFs fail are
- described in connection with the description of each individual
- BIF.</p>
- <p>Some BIFs may be used in guard tests, these are marked with
+ incorrect type. The other reasons are described in the
+ description of each individual BIF.</p>
+ <p>Some BIFs can be used in guard tests and are marked with
"Allowed in guard tests".</p>
</description>
<datatypes>
<datatype>
- <name><marker id="type-ext_binary">ext_binary()</marker></name>
+ <name>ext_binary()</name>
<desc>
+ <marker id="type-ext_binary"></marker>
<p>A binary data object, structured according to
the Erlang external term format.</p>
</desc>
</datatype>
+
<datatype>
<name name="timestamp"></name>
- <desc><p>See <seealso marker="#now/0">now/0</seealso>.</p>
+ <desc><p>See <seealso marker="#timestamp/0">erlang:timestamp/0</seealso>.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="time_unit"></name>
+ <desc><p><marker id="type_time_unit"/>
+ Supported time unit representations:</p>
+ <taglist>
+ <tag><c>PartsPerSecond :: integer() >= 1</c></tag>
+ <item><p>Time unit expressed in parts per second. That is,
+ the time unit equals <c>1/PartsPerSecond</c> second.</p></item>
+
+ <tag><c>seconds</c></tag>
+ <item><p>Symbolic representation of the time unit
+ represented by the integer <c>1</c>.</p></item>
+
+ <tag><c>milli_seconds</c></tag>
+ <item><p>Symbolic representation of the time unit
+ represented by the integer <c>1000</c>.</p></item>
+
+ <tag><c>micro_seconds</c></tag>
+ <item><p>Symbolic representation of the time unit
+ represented by the integer <c>1000000</c>.</p></item>
+
+ <tag><c>nano_seconds</c></tag>
+ <item><p>Symbolic representation of the time unit
+ represented by the integer <c>1000000000</c>.</p></item>
+
+ <tag><c>native</c></tag>
+ <item><p>Symbolic representation of the native time unit
+ used by the Erlang runtime system.</p>
+
+ <p>The <c>native</c> time unit is determined at
+ runtime system start, and remains the same until
+ the runtime system terminates. If a runtime system
+ is stopped and then started again (even on the same
+ machine), the <c>native</c> time unit of the new
+ runtime system instance can differ from the
+ <c>native</c> time unit of the old runtime system
+ instance.</p>
+
+ <p>One can get an approximation of the <c>native</c>
+ time unit by calling <c>erlang:convert_time_unit(1,
+ seconds, native)</c>. The result equals the number
+ of whole <c>native</c> time units per second. In case
+ the number of <c>native</c> time units per second does
+ not add up to a whole number, the result is rounded downwards.</p>
+
+ <note>
+ <p>The value of the <c>native</c> time unit gives
+ you more or less no information at all about the
+ quality of time values. It sets a limit for
+ the
+ <seealso marker="time_correction#Time_Resolution">resolution</seealso>
+ as well as for the
+ <seealso marker="time_correction#Time_Precision">precision</seealso>
+ of time values,
+ but it gives absolutely no information at all about the
+ <seealso marker="time_correction#Time_Accuracy">accuracy</seealso>
+ of time values. The resolution of the <c>native</c> time
+ unit and the resolution of time values can differ
+ significantly.</p>
+ </note>
+ </item>
+
+ </taglist>
+
+ <p>The <c>time_unit/0</c> type may be extended. Use
+ <seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit/3</c></seealso>
+ in order to convert time values between time units.</p>
+
</desc>
</datatype>
</datatypes>
@@ -67,12 +139,15 @@
<func>
<name name="abs" arity="1" clause_i="1"/>
<name name="abs" arity="1" clause_i="2"/>
- <type variable="Float" name_i="1"/>
- <type variable="Int" name_i="2"/>
- <fsummary>Arithmetical absolute value</fsummary>
- <desc>
- <p>Returns an integer or float which is the arithmetical
- absolute value of <c><anno>Float</anno></c> or <c><anno>Int</anno></c>.</p>
+ <fsummary>Arithmetical absolute value.</fsummary>
+ <type>
+ <v>Float = float()</v>
+ <v>Int = integer()</v>
+ </type>
+ <desc>
+ <p>Returns an integer or float that is the arithmetical
+ absolute value of <c><anno>Float</anno></c> or
+ <c><anno>Int</anno></c>, for example:</p>
<pre>
> <input>abs(-3.33).</input>
3.33
@@ -81,206 +156,214 @@
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="adler32" arity="1"/>
- <fsummary>Compute adler32 checksum</fsummary>
+ <fsummary>Computes adler32 checksum.</fsummary>
<desc>
- <p>Computes and returns the adler32 checksum for <c><anno>Data</anno></c>.</p>
+ <p>Computes and returns the adler32 checksum for
+ <c><anno>Data</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="adler32" arity="2"/>
- <fsummary>Compute adler32 checksum</fsummary>
+ <fsummary>Computes adler32 checksum.</fsummary>
<desc>
- <p>Continue computing the adler32 checksum by combining
- the previous checksum, <c><anno>OldAdler</anno></c>, with the checksum of
- <c><anno>Data</anno></c>.</p>
- <p>The following code:</p>
- <code>
- X = erlang:adler32(Data1),
- Y = erlang:adler32(X,Data2).
- </code>
- <p>- would assign the same value to <c>Y</c> as this would:</p>
- <code>
- Y = erlang:adler32([Data1,Data2]).
- </code>
+ <p>Continues computing the adler32 checksum by combining
+ the previous checksum, <c><anno>OldAdler</anno></c>, with
+ the checksum of <c><anno>Data</anno></c>.</p>
+ <p>The following code:</p>
+ <code>
+ X = erlang:adler32(Data1),
+ Y = erlang:adler32(X,Data2).</code>
+ <p>assigns the same value to <c>Y</c> as this:</p>
+ <code>
+ Y = erlang:adler32([Data1,Data2]).</code>
</desc>
</func>
+
<func>
<name name="adler32_combine" arity="3"/>
- <fsummary>Combine two adler32 checksums</fsummary>
- <desc>
- <p>Combines two previously computed adler32 checksums.
- This computation requires the size of the data object for
- the second checksum to be known.</p>
- <p>The following code:</p>
- <code>
- Y = erlang:adler32(Data1),
- Z = erlang:adler32(Y,Data2).
- </code>
- <p>- would assign the same value to <c>Z</c> as this would:</p>
- <code>
- X = erlang:adler32(Data1),
- Y = erlang:adler32(Data2),
- Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
- </code>
+ <fsummary>Combines two adler32 checksums.</fsummary>
+ <desc>
+ <p>Combines two previously computed adler32 checksums.
+ This computation requires the size of the data object for
+ the second checksum to be known.</p>
+ <p>The following code:</p>
+ <code>
+ Y = erlang:adler32(Data1),
+ Z = erlang:adler32(Y,Data2).</code>
+ <p>assigns the same value to <c>Z</c> as this:</p>
+ <code>
+ X = erlang:adler32(Data1),
+ Y = erlang:adler32(Data2),
+ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code>
</desc>
</func>
+
<func>
<name name="append_element" arity="2"/>
- <fsummary>Append an extra element to a tuple</fsummary>
- <desc>
- <p>Returns a new tuple which has one element more than
- <c><anno>Tuple1</anno></c>, and contains the elements in <c><anno>Tuple1</anno></c>
- followed by <c><anno>Term</anno></c> as the last element. Semantically
- equivalent to
- <c>list_to_tuple(tuple_to_list(<anno>Tuple1</anno>) ++ [<anno>Term</anno>])</c>, but much
- faster.</p>
+ <fsummary>Appends an extra element to a tuple.</fsummary>
+ <desc>
+ <p>Returns a new tuple that has one element more than
+ <c><anno>Tuple1</anno></c>, and contains the elements in
+ <c><anno>Tuple1</anno></c>
+ followed by <c><anno>Term</anno></c> as the last element.
+ Semantically equivalent to
+ <c>list_to_tuple(tuple_to_list(<anno>Tuple1</anno>) ++
+ [<anno>Term</anno>])</c>, but much faster.</p>
+ <p>Example:</p>
<pre>
> <input>erlang:append_element({one, two}, three).</input>
{one,two,three}</pre>
</desc>
</func>
+
<func>
<name name="apply" arity="2"/>
- <fsummary>Apply a function to an argument list</fsummary>
+ <fsummary>Applies a function to an argument list.</fsummary>
<desc>
- <p>Call a fun, passing the elements in <c><anno>Args</anno></c> as
- arguments.</p>
- <p>Note: If the number of elements in the arguments are known at
- compile-time, the call is better written as
+ <p>Calls a fun, passing the elements in <c><anno>Args</anno></c>
+ as arguments.</p>
+ <p>If the number of elements in the arguments are known at
+ compile time, the call is better written as
<c><anno>Fun</anno>(Arg1, Arg2, ... ArgN)</c>.</p>
<warning>
<p>Earlier, <c><anno>Fun</anno></c> could also be given as
<c>{Module, Function}</c>, equivalent to
- <c>apply(Module, Function, Args)</c>. This usage is
- deprecated and will stop working in a future release of
- Erlang/OTP.</p>
+ <c>apply(Module, Function, Args)</c>. This use is
+ deprecated and will stop working in a future release.</p>
</warning>
</desc>
</func>
+
<func>
<name name="apply" arity="3"/>
- <fsummary>Apply a function to an argument list</fsummary>
+ <fsummary>Applies a function to an argument list.</fsummary>
<desc>
<p>Returns the result of applying <c>Function</c> in
- <c><anno>Module</anno></c> to <c><anno>Args</anno></c>. The applied function must
+ <c><anno>Module</anno></c> to <c><anno>Args</anno></c>.
+ The applied function must
be exported from <c>Module</c>. The arity of the function is
the length of <c>Args</c>.</p>
+ <p>Example:</p>
<pre>
> <input>apply(lists, reverse, [[a, b, c]]).</input>
-[c,b,a]</pre>
- <p><c>apply</c> can be used to evaluate BIFs by using
- the module name <c>erlang</c>.</p>
- <pre>
+[c,b,a]
> <input>apply(erlang, atom_to_list, ['Erlang']).</input>
"Erlang"</pre>
- <p>Note: If the number of arguments are known at compile-time,
+ <p>If the number of arguments are known at compile time,
the call is better written as
<c><anno>Module</anno>:<anno>Function</anno>(Arg1, Arg2, ..., ArgN)</c>.</p>
<p>Failure: <c>error_handler:undefined_function/3</c> is called
if the applied function is not exported. The error handler
can be redefined (see
<seealso marker="#process_flag/2">process_flag/2</seealso>).
- If the <c>error_handler</c> is undefined, or if the user has
+ If <c>error_handler</c> is undefined, or if the user has
redefined the default <c>error_handler</c> so the replacement
module is undefined, an error with the reason <c>undef</c>
is generated.</p>
</desc>
</func>
+
<func>
<name name="atom_to_binary" arity="2"/>
- <fsummary>Return the binary representation of an atom</fsummary>
- <desc>
- <p>Returns a binary which corresponds to the text
- representation of <c><anno>Atom</anno></c>. If <c><anno>Encoding</anno></c>
- is <c>latin1</c>, there will be one byte for each character
- in the text representation. If <c><anno>Encoding</anno></c> is
- <c>utf8</c> or
- <c>unicode</c>, the characters will be encoded using UTF-8
- (meaning that characters from 16#80 up to 0xFF will be
- encoded in two bytes).</p>
-
- <note><p>Currently, <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> can
- never fail because the text representation of an atom can only contain
- characters from 0 to 16#FF. In a future release, the text representation
- of atoms might be allowed to contain any Unicode character
- and <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> will fail if the
- text representation for the <c><anno>Atom</anno></c> contains a Unicode
- character greater than 16#FF.</p></note>
-
+ <fsummary>Returns the binary representation of an atom.</fsummary>
+ <desc>
+ <p>Returns a binary corresponding to the text
+ representation of <c><anno>Atom</anno></c>.
+ If <c><anno>Encoding</anno></c>
+ is <c>latin1</c>, there is one byte for each character
+ in the text representation. If <c><anno>Encoding</anno></c> is
+ <c>utf8</c> or
+ <c>unicode</c>, the characters are encoded using UTF-8
+ (that is, characters from 128 through 255 are
+ encoded in two bytes).</p>
+ <note><p><c>atom_to_binary(<anno>Atom</anno>, latin1)</c> never
+ fails because the text representation of an atom can only
+ contain characters from 0 through 255. In a future release,
+ the text representation
+ of atoms can be allowed to contain any Unicode character and
+ <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> will then fail if the
+ text representation for <c><anno>Atom</anno></c> contains a Unicode
+ character greater than 255.</p></note>
+ <p>Example:</p>
<pre>
> <input>atom_to_binary('Erlang', latin1).</input>
&lt;&lt;"Erlang"&gt;&gt;</pre>
</desc>
</func>
+
<func>
<name name="atom_to_list" arity="1"/>
- <fsummary>Text representation of an atom</fsummary>
+ <fsummary>Text representation of an atom.</fsummary>
<desc>
- <p>Returns a string which corresponds to the text
- representation of <c><anno>Atom</anno></c>.</p>
+ <p>Returns a string corresponding to the text
+ representation of <c><anno>Atom</anno></c>, for example:</p>
<pre>
> <input>atom_to_list('Erlang').</input>
"Erlang"</pre>
</desc>
</func>
+
<func>
<name name="binary_part" arity="2"/>
- <fsummary>Extracts a part of a binary</fsummary>
+ <fsummary>Extracts a part of a binary.</fsummary>
<desc>
- <p>Extracts the part of the binary described by <c><anno>PosLen</anno></c>.</p>
-
- <p>Negative length can be used to extract bytes at the end of a binary:</p>
-
+ <p>Extracts the part of the binary described by
+ <c><anno>PosLen</anno></c>.</p>
+ <p>Negative length can be used to extract bytes at the end
+ of a binary, for example:</p>
<code>
1> Bin = &lt;&lt;1,2,3,4,5,6,7,8,9,10&gt;&gt;.
2> binary_part(Bin,{byte_size(Bin), -5}).
-&lt;&lt;6,7,8,9,10&gt;&gt;
-</code>
-
- <p>If <c><anno>PosLen</anno></c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p>
-
- <p><c><anno>Start</anno></c> is zero-based, i.e.:</p>
+&lt;&lt;6,7,8,9,10&gt;&gt;</code>
+ <p>Failure: <c>badarg</c> if <c><anno>PosLen</anno></c> in any way
+ references outside the binary.</p>
+ <p><c><anno>Start</anno></c> is zero-based, that is:</p>
<code>
1> Bin = &lt;&lt;1,2,3&gt;&gt;
2> binary_part(Bin,{0,2}).
-&lt;&lt;1,2&gt;&gt;
-</code>
-
- <p>See the STDLIB module <c>binary</c> for details about the <c><anno>PosLen</anno></c> semantics.</p>
-
+&lt;&lt;1,2&gt;&gt;</code>
+ <p>For details about the <c><anno>PosLen</anno></c> semantics, see the
+ <seealso marker="stdlib:binary">binary</seealso>
+ manual page in <c>STDLIB</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="binary_part" arity="3"/>
- <fsummary>Extracts a part of a binary</fsummary>
+ <fsummary>Extracts a part of a binary.</fsummary>
<desc>
- <p>The same as <c>binary_part(<anno>Subject</anno>, {<anno>Start</anno>, <anno>Length</anno>})</c>.</p>
-
+ <p>The same as <c>binary_part(<anno>Subject</anno>,
+ {<anno>Start</anno>, <anno>Length</anno>})</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="binary_to_atom" arity="2"/>
- <fsummary>Convert from text representation to an atom</fsummary>
+ <fsummary>Converts from text representation to an atom.</fsummary>
<desc>
<p>Returns the atom whose text representation is
- <c><anno>Binary</anno></c>. If <c><anno>Encoding</anno></c> is <c>latin1</c>, no
- translation of bytes in the binary is done. If <c><anno>Encoding</anno></c>
- is <c>utf8</c> or <c>unicode</c>, the binary must contain
- valid UTF-8 sequences; furthermore, only Unicode characters up
- to 0xFF are allowed.</p>
-
- <note><p><c>binary_to_atom(<anno>Binary</anno>, utf8)</c> will fail if
- the binary contains Unicode characters greater than 16#FF.
- In a future release, such Unicode characters might be allowed
- and <c>binary_to_atom(<anno>Binary</anno>, utf8)</c>
- will not fail in that case. For more information on Unicode support in atoms
- see <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8 encoded atoms</seealso>
- in the chapter about the external term format in the ERTS User's Guide.</p></note>
-
+ <c><anno>Binary</anno></c>.
+ If <c><anno>Encoding</anno></c> is <c>latin1</c>, no
+ translation of bytes in the binary is done.
+ If <c><anno>Encoding</anno></c>
+ is <c>utf8</c> or <c>unicode</c>, the binary must contain
+ valid UTF-8 sequences. Only Unicode characters up
+ to 255 are allowed.</p>
+ <note><p><c>binary_to_atom(<anno>Binary</anno>, utf8)</c> fails if
+ the binary contains Unicode characters greater than 255.
+ In a future release, such Unicode characters can be allowed
+ and <c>binary_to_atom(<anno>Binary</anno>, utf8)</c> does then not fail.
+ For more information on Unicode support in atoms, see the
+ <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8
+ encoded atoms</seealso>
+ in Section "External Term Format" in the User's Guide.</p></note>
+ <p>Examples:</p>
<pre>
> <input>binary_to_atom(&lt;&lt;"Erlang"&gt;&gt;, latin1).</input>
'Erlang'
@@ -290,20 +373,24 @@
called as binary_to_atom(&lt;&lt;208,128&gt;&gt;,utf8)</pre>
</desc>
</func>
+
<func>
<name name="binary_to_existing_atom" arity="2"/>
- <fsummary>Convert from text representation to an atom</fsummary>
+ <fsummary>Converts from text representation to an atom.</fsummary>
<desc>
- <p>Works like <seealso marker="#binary_to_atom/2">binary_to_atom/2</seealso>,
- but the atom must already exist.</p>
- <p>Failure: <c>badarg</c> if the atom does not already exist.</p>
+ <p>As
+ <seealso marker="#binary_to_atom/2">binary_to_atom/2</seealso>,
+ but the atom must exist.</p>
+ <p>Failure: <c>badarg</c> if the atom does not exist.</p>
</desc>
</func>
+
<func>
<name name="binary_to_float" arity="1"/>
- <fsummary>Convert from text representation to a float</fsummary>
+ <fsummary>Converts from text representation to a float.</fsummary>
<desc>
- <p>Returns the float whose text representation is <c><anno>Binary</anno></c>.</p>
+ <p>Returns the float whose text representation is
+ <c><anno>Binary</anno></c>, for example:</p>
<pre>
> <input>binary_to_float(&lt;&lt;"2.2017764e+0">>).</input>
2.2017764</pre>
@@ -311,12 +398,13 @@
representation of a float.</p>
</desc>
</func>
+
<func>
<name name="binary_to_integer" arity="1"/>
- <fsummary>Convert from text representation to an integer</fsummary>
+ <fsummary>Converts from text representation to an integer.</fsummary>
<desc>
<p>Returns an integer whose text representation is
- <c><anno>Binary</anno></c>.</p>
+ <c><anno>Binary</anno></c>, for example:</p>
<pre>
> <input>binary_to_integer(&lt;&lt;"123"&gt;&gt;).</input>
123</pre>
@@ -324,12 +412,13 @@
representation of an integer.</p>
</desc>
</func>
+
<func>
<name name="binary_to_integer" arity="2"/>
- <fsummary>Convert from text representation to an integer</fsummary>
+ <fsummary>Converts from text representation to an integer.</fsummary>
<desc>
<p>Returns an integer whose text representation in base
- <c><anno>Base</anno></c> is <c><anno>Binary</anno></c>.</p>
+ <c><anno>Base</anno></c> is <c><anno>Binary</anno></c>, for example:</p>
<pre>
> <input>binary_to_integer(&lt;&lt;"3FF"&gt;&gt;, 16).</input>
1023</pre>
@@ -337,93 +426,101 @@
representation of an integer.</p>
</desc>
</func>
+
<func>
<name name="binary_to_list" arity="1"/>
- <fsummary>Convert a binary to a list</fsummary>
+ <fsummary>Converts a binary to a list.</fsummary>
<desc>
- <p>Returns a list of integers which correspond to the bytes of
+ <p>Returns a list of integers corresponding to the bytes of
<c><anno>Binary</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="binary_to_list" arity="3"/>
- <fsummary>Convert part of a binary to a list</fsummary>
- <type_desc variable="Start">1..byte_size(<anno>Binary</anno>)</type_desc>
+ <fsummary>Converts part of a binary to a list.</fsummary>
+ <type_desc variable="Start">1..byte_size(<c><anno>Binary</anno></c>)</type_desc>
<desc>
<p>As <c>binary_to_list/1</c>, but returns a list of integers
corresponding to the bytes from position <c><anno>Start</anno></c> to
- position <c><anno>Stop</anno></c> in <c><anno>Binary</anno></c>. Positions in the
+ position <c><anno>Stop</anno></c> in <c><anno>Binary</anno></c>.
+ The positions in the
binary are numbered starting from 1.</p>
-
- <note><p>This function's indexing style of using one-based indices for
- binaries is deprecated. New code should use the functions in
- the STDLIB module <c>binary</c> instead. They consequently
- use the same (zero-based) style of indexing.</p></note>
+ <note><p>The one-based indexing for binaries used by
+ this function is deprecated. New code is to use
+ <seealso marker="stdlib:binary#bin_to_list/3">binary:bin_to_list/3</seealso>
+ in <c>STDLIB</c> instead. All functions in module
+ <c>binary</c> consistently use zero-based indexing.</p></note>
</desc>
</func>
+
<func>
<name name="bitstring_to_list" arity="1"/>
- <fsummary>Convert a bitstring to a list</fsummary>
+ <fsummary>Converts a bitstring to a list.</fsummary>
<desc>
- <p>Returns a list of integers which correspond to the bytes of
- <c><anno>Bitstring</anno></c>. If the number of bits in the binary is not
- divisible by 8, the last element of the list will be a bitstring
- containing the remaining bits (1 up to 7 bits).</p>
+ <p>Returns a list of integers corresponding to the bytes of
+ <c><anno>Bitstring</anno></c>. If the number of bits in the binary
+ is not divisible by 8, the last element of the list is a bitstring
+ containing the remaining 1-7 bits.</p>
</desc>
</func>
+
<func>
<name name="binary_to_term" arity="1"/>
- <fsummary>Decode an Erlang external term format binary</fsummary>
+ <fsummary>Decodes an Erlang external term format binary.</fsummary>
<desc>
- <p>Returns an Erlang term which is the result of decoding
- the binary object <c><anno>Binary</anno></c>, which must be encoded
+ <p>Returns an Erlang term that is the result of decoding
+ binary object <c><anno>Binary</anno></c>, which must be encoded
according to the Erlang external term format.</p>
- <warning>
- <p>When decoding binaries from untrusted sources, consider using
- <c>binary_to_term/2</c> to prevent denial of service attacks.</p>
- </warning>
- <p>See also
- <seealso marker="#term_to_binary/1">term_to_binary/1</seealso>
- and
- <seealso marker="#binary_to_term/2">binary_to_term/2</seealso>.</p>
+ <warning><p>When decoding binaries from untrusted sources,
+ consider using <c>binary_to_term/2</c> to prevent Denial
+ of Service attacks.</p></warning>
+ <p>See also
+ <seealso marker="#term_to_binary/1">term_to_binary/1</seealso>
+ and
+ <seealso marker="#binary_to_term/2">binary_to_term/2</seealso>.</p>
</desc>
</func>
+
<func>
<name name="binary_to_term" arity="2"/>
- <fsummary>Decode an Erlang external term format binary</fsummary>
+ <fsummary>Decodes an Erlang external term format binary.</fsummary>
<desc>
<p>As <c>binary_to_term/1</c>, but takes options that affect decoding
of the binary.</p>
<taglist>
<tag><c>safe</c></tag>
<item>
- <p>Use this option when receiving binaries from an untrusted
+ <p>Use this option when receiving binaries from an untrusted
source.</p>
- <p>When enabled, it prevents decoding data that may be used to
- attack the Erlang system. In the event of receiving unsafe
- data, decoding fails with a badarg error.</p>
- <p>Currently, this prevents creation of new atoms directly,
- creation of new atoms indirectly (as they are embedded in
- certain structures like pids, refs, funs, etc.), and creation of
- new external function references. None of those resources are
- currently garbage collected, so unchecked creation of them can
- exhaust available memory.</p>
+ <p>When enabled, it prevents decoding data that can be used to
+ attack the Erlang system. In the event of receiving unsafe
+ data, decoding fails with a <c>badarg</c> error.</p>
+ <p>This prevents creation of new atoms directly,
+ creation of new atoms indirectly (as they are embedded in
+ certain structures, such as process identifiers,
+ refs, and funs), and
+ creation of new external function references.
+ None of those resources are garbage collected, so unchecked
+ creation of them can exhaust available memory.</p>
</item>
</taglist>
- <p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe data
- is decoded.</p>
+ <p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe
+ data is decoded.</p>
<p>See also
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>,
<seealso marker="#binary_to_term/1">binary_to_term/1</seealso>,
- and <seealso marker="#list_to_existing_atom/1">
- list_to_existing_atom/1</seealso>.</p>
+ and
+ <seealso marker="#list_to_existing_atom/1">list_to_existing_atom/1</seealso>.</p>
</desc>
</func>
+
<func>
<name name="bit_size" arity="1"/>
- <fsummary>Return the size of a bitstring</fsummary>
+ <fsummary>Returns the size of a bitstring.</fsummary>
<desc>
- <p>Returns an integer which is the size in bits of <c><anno>Bitstring</anno></c>.</p>
+ <p>Returns an integer that is the size in bits of
+ <c><anno>Bitstring</anno></c>, for example:</p>
<pre>
> <input>bit_size(&lt;&lt;433:16,3:3&gt;&gt;).</input>
19
@@ -432,30 +529,34 @@
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="bump_reductions" arity="1"/>
- <fsummary>Increment the reduction counter</fsummary>
+ <fsummary>Increments the reduction counter.</fsummary>
<desc>
<p>This implementation-dependent function increments
the reduction counter for the calling process. In the Beam
emulator, the reduction counter is normally incremented by
- one for each function and BIF call, and a context switch is
- forced when the counter reaches the maximum number of reductions
- for a process (2000 reductions in R12B).</p>
+ one for each function and BIF call. A context switch is
+ forced when the counter reaches the maximum number of
+ reductions for a process (2000 reductions in OTP R12B).</p>
<warning>
- <p>This BIF might be removed in a future version of the Beam
+ <p>This BIF can be removed in a future version of the Beam
machine without prior warning. It is unlikely to be
implemented in other Erlang implementations.</p>
</warning>
</desc>
</func>
+
<func>
<name name="byte_size" arity="1"/>
- <fsummary>Return the size of a bitstring (or binary)</fsummary>
+ <fsummary>Returns the size of a bitstring (or binary).</fsummary>
<desc>
- <p>Returns an integer which is the number of bytes needed to contain
- <c><anno>Bitstring</anno></c>. (That is, if the number of bits in <c><anno>Bitstring</anno></c> is not
- divisible by 8, the resulting number of bytes will be rounded <em>up</em>.)</p>
+ <p>Returns an integer that is the number of bytes needed to
+ contain <c><anno>Bitstring</anno></c>. That is, if the number of bits
+ in <c><anno>Bitstring</anno></c> is not divisible by 8, the resulting
+ number of bytes is rounded <em>up</em>.</p>
+ <p>Examples:</p>
<pre>
> <input>byte_size(&lt;&lt;433:16,3:3&gt;&gt;).</input>
3
@@ -464,222 +565,319 @@
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
- <name name="cancel_timer" arity="1"/>
- <fsummary>Cancel a timer</fsummary>
- <desc>
- <p>Cancels a timer, where <c><anno>TimerRef</anno></c> was returned by
- either
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>
- or
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>.
- If the timer is there to be removed, the function returns
- the time in milliseconds left until the timer would have expired,
- otherwise <c>false</c> (which means that <c><anno>TimerRef</anno></c> was
- never a timer, that it has already been cancelled, or that it
- has already delivered its message).</p>
+ <name name="cancel_timer" arity="2"/>
+ <fsummary>Cancels a timer.</fsummary>
+ <desc>
+ <p>
+ Cancels a timer that has been created by
+ <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>,
+ or <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>.
+ <c><anno>TimerRef</anno></c> identifies the timer, and
+ was returned by the BIF that created the timer.
+ </p>
+ <p>Available <c><anno>Option</anno></c>s:</p>
+ <taglist>
+ <tag><c>{async, Async}</c></tag>
+ <item>
+ <p>
+ Asynchronous request for cancellation. <c>Async</c>
+ defaults to <c>false</c> which will cause the
+ cancellation to be performed synchronously. When
+ <c>Async</c> is set to <c>true</c>, the cancel
+ operation is performed asynchronously. That is,
+ <c>erlang:cancel_timer()</c> will send an asynchronous
+ request for cancellation to the timer service that
+ manages the timer, and then return <c>ok</c>.
+ </p>
+ </item>
+ <tag><c>{info, Info}</c></tag>
+ <item>
+ <p>
+ Request information about the <c><anno>Result</anno></c>
+ of the cancellation. <c>Info</c> defaults to <c>true</c>
+ which means the <c><anno>Result</anno></c> is
+ given. When <c>Info</c> is set to <c>false</c>, no
+ information about the result of the cancellation
+ is given. When the operation is performed</p>
+ <taglist>
+ <tag>synchronously</tag>
+ <item>
+ <p>
+ If <c>Info</c> is <c>true</c>, the <c>Result</c> is
+ returned by <c>erlang:cancel_timer()</c>; otherwise,
+ <c>ok</c> is returned.
+ </p>
+ </item>
+ <tag>asynchronously</tag>
+ <item>
+ <p>
+ If <c>Info</c> is <c>true</c>, a message on the form
+ <c>{cancel_timer, <anno>TimerRef</anno>,
+ <anno>Result</anno>}</c> is sent to the
+ caller of <c>erlang:cancel_timer()</c> when the
+ cancellation operation has been performed; otherwise,
+ no message is sent.
+ </p>
+ </item>
+ </taglist>
+ </item>
+ </taglist>
+ <p>
+ More <c><anno>Option</anno></c>s may be added in the future.
+ </p>
+ <p>If <c><anno>Result</anno></c> is an integer, it represents
+ the time in milli-seconds left until the canceled timer would
+ have expired.</p>
+ <p>
+ If <c><anno>Result</anno></c> is <c>false</c>, a
+ timer corresponding to <c><anno>TimerRef</anno></c> could not
+ be found. This can be either because the timer had expired,
+ already had been canceled, or because <c><anno>TimerRef</anno></c>
+ never corresponded to a timer. Even if the timer had expired,
+ it does not tell you whether or not the timeout message has
+ arrived at its destination yet.
+ </p>
+ <note>
+ <p>
+ The timer service that manages the timer may be co-located
+ with another scheduler than the scheduler that the calling
+ process is executing on. If this is the case, communication
+ with the timer service takes much longer time than if it
+ is located locally. If the calling process is in critical
+ path, and can do other things while waiting for the result
+ of this operation, or is not interested in the result of
+ the operation, you want to use option <c>{async, true}</c>.
+ If using option <c>{async, false}</c>, the calling
+ process blocks until the operation has been performed.
+ </p>
+ </note>
<p>See also
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>,
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
+ <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>,
+ <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>,
and
- <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
- <p>Note: Cancelling a timer does not guarantee that the message
- has not already been delivered to the message queue.</p>
+ <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="cancel_timer" arity="1"/>
+ <fsummary>Cancels a timer.</fsummary>
+ <desc>
+ <p>Cancels a timer. The same as calling
+ <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer(TimerRef,
+ [])</c></seealso>.</p>
</desc>
</func>
-
<func>
<name name="check_old_code" arity="1"/>
- <fsummary>Check if a module has old code</fsummary>
+ <fsummary>Checks if a module has old code.</fsummary>
<desc>
- <p>Returns <c>true</c> if the <c><anno>Module</anno></c> has old code,
- and <c>false</c> otherwise.</p>
+ <p>Returns <c>true</c> if <c><anno>Module</anno></c> has old code,
+ otherwise <c>false</c>.</p>
<p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
</desc>
</func>
+
<func>
<name name="check_process_code" arity="2"/>
- <fsummary>Check if a process is executing old code for a module</fsummary>
+ <fsummary>Checks if a process executes old code for a module.</fsummary>
<desc>
<p>The same as
- <seealso marker="#check_process_code/3"><c>erlang:check_process_code(<anno>Pid</anno>,
- <anno>Module</anno>, [])</c></seealso>.</p>
+ <seealso marker="#check_process_code/3"><c>erlang:check_process_code(<anno>Pid</anno>, <anno>Module</anno>, [])</c></seealso>.</p>
</desc>
</func>
+
<func>
<name name="check_process_code" arity="3"/>
- <fsummary>Check if a process is executing old code for a module</fsummary>
+ <fsummary>Checks if a process executes old code for a module.</fsummary>
<desc>
- <p>Check if the node local process identified by <c><anno>Pid</anno></c>
- is executing old code for <c><anno>Module</anno></c>.</p>
- <p>Currently available <c><anno>Option</anno>s</c>:</p>
+ <p>Checks if the node local process identified by <c><anno>Pid</anno></c>
+ executes old code for <c><anno>Module</anno></c>.</p>
+ <p>The available <c><anno>Option</anno></c>s are as follows:</p>
<taglist>
<tag><c>{allow_gc, boolean()}</c></tag>
<item>
- Determines if garbage collection is allowed when performing
- the operation. If <c>{allow_gc, false}</c> is passed, and
- a garbage collection is needed in order to determine the
- result of the operation, the operation will be aborted
- (see information on <c><anno>CheckResult</anno></c> below).
- The default is to allow garbage collection, i.e.,
- <c>{allow_gc, true}</c>.
+ <p>Determines if garbage collection is allowed when performing
+ the operation. If <c>{allow_gc, false}</c> is passed, and
+ a garbage collection is needed to determine the
+ result of the operation, the operation is aborted (see
+ information on <c><anno>CheckResult</anno></c> in the following).
+ The default is to allow garbage collection, that is,
+ <c>{allow_gc, true}</c>.</p>
</item>
<tag><c>{async, RequestId}</c></tag>
<item>
- The <c>check_process_code/3</c> function will return
- the value <c>async</c> immediately after the request
- has been sent. When the request has been processed, the
- process that called this function will be passed a
- message on the form:<br/>
- <c>{check_process_code, <anno>RequestId</anno>, <anno>CheckResult</anno>}</c>.
+ <p>The function <c>check_process_code/3</c> returns
+ the value <c>async</c> immediately after the request
+ has been sent. When the request has been processed, the
+ process that called this function is passed a
+ message on the form
+ <c>{check_process_code, <anno>RequestId</anno>, <anno>CheckResult</anno>}</c>.</p>
</item>
</taglist>
- <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and
- no <c>async</c> option has been passed, the operation will
- be performed at once. In all other cases a request for
- the operation will be sent to the process identified by
- <c><anno>Pid</anno></c>, and will be handled when
- appropriate. If no <c>async</c> option has been passed,
- the caller will block until <c><anno>CheckResult</anno></c>
- is available and can be returned.</p>
- <p><c><anno>CheckResult</anno></c> informs about the result of
- the request:</p>
+ <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and
+ no <c>async</c> option has been passed, the operation
+ is performed at once. Otherwise a request for
+ the operation is sent to the process identified by
+ <c><anno>Pid</anno></c>, and is handled when
+ appropriate. If no <c>async</c> option has been passed,
+ the caller blocks until <c><anno>CheckResult</anno></c>
+ is available and can be returned.</p>
+ <p><c><anno>CheckResult</anno></c> informs about the result of
+ the request as follows:</p>
<taglist>
<tag><c>true</c></tag>
<item>
- The process identified by <c><anno>Pid</anno></c> is
- executing old code for <c><anno>Module</anno></c>.
- That is, the current call of the process executes old
- code for this module, or the process has references
- to old code for this module, or the process contains
- funs that references old code for this module.
+ <p>The process identified by <c><anno>Pid</anno></c>
+ executes old code for <c><anno>Module</anno></c>.
+ That is, the current call of the process executes old
+ code for this module, or the process has references
+ to old code for this module, or the process contains
+ funs that references old code for this module.</p>
</item>
<tag><c>false</c></tag>
<item>
- The process identified by <c><anno>Pid</anno></c> is
- not executing old code for <c><anno>Module</anno></c>.
+ <p>The process identified by <c><anno>Pid</anno></c> does
+ not execute old code for <c><anno>Module</anno></c>.</p>
</item>
<tag><c>aborted</c></tag>
<item>
- The operation was aborted since the process needed to
- be garbage collected in order to determine the result
- of the operation, and the operation was requested
- by passing the <c>{allow_gc, false}</c> option.</item>
+ <p>The operation was aborted, as the process needed to
+ be garbage collected to determine the operation result,
+ and the operation was requested
+ by passing option <c>{allow_gc, false}</c>.</p></item>
</taglist>
<p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
- <item>
- If <c><anno>Pid</anno></c> is not a node local process identifier.
+ <item>If <c><anno>Pid</anno></c> is not a node local process identifier.
</item>
<tag><c>badarg</c></tag>
- <item>
- If <c><anno>Module</anno></c> is not an atom.
+ <item>If <c><anno>Module</anno></c> is not an atom.
</item>
<tag><c>badarg</c></tag>
- <item>
- If <c><anno>OptionList</anno></c> is not a valid list of options.
+ <item>If <c><anno>OptionList</anno></c> is an invalid list of options.
</item>
</taglist>
</desc>
</func>
+
+ <func>
+ <name name="convert_time_unit" arity="3"/>
+ <fsummary>Converts time unit of a time value.</fsummary>
+ <desc>
+ <p>Converts the <c><anno>Time</anno></c> value of time unit
+ <c><anno>FromUnit</anno></c> to the corresponding
+ <c><anno>ConvertedTime</anno></c> value of time unit
+ <c><anno>ToUnit</anno></c>. The result is rounded
+ using the floor function.</p>
+
+ <warning><p>You may lose accuracy and precision when converting
+ between time units. In order to minimize such loss, collect all
+ data at <c>native</c> time unit and do the conversion on the end
+ result.</p></warning>
+ </desc>
+ </func>
<func>
<name name="crc32" arity="1"/>
- <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
+ <fsummary>Computes crc32 (IEEE 802.3) checksum.</fsummary>
<desc>
- <p>Computes and returns the crc32 (IEEE 802.3 style) checksum for <c><anno>Data</anno></c>.</p>
+ <p>Computes and returns the crc32 (IEEE 802.3 style) checksum
+ for <c><anno>Data</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="crc32" arity="2"/>
- <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
+ <fsummary>Computes crc32 (IEEE 802.3) checksum.</fsummary>
<desc>
- <p>Continue computing the crc32 checksum by combining
- the previous checksum, <c><anno>OldCrc</anno></c>, with the checksum of
- <c><anno>Data</anno></c>.</p>
- <p>The following code:</p>
- <code>
- X = erlang:crc32(Data1),
- Y = erlang:crc32(X,Data2).
- </code>
- <p>- would assign the same value to <c>Y</c> as this would:</p>
- <code>
- Y = erlang:crc32([Data1,Data2]).
- </code>
+ <p>Continues computing the crc32 checksum by combining
+ the previous checksum, <c><anno>OldCrc</anno></c>, with the checksum of
+ <c><anno>Data</anno></c>.</p>
+ <p>The following code:</p>
+ <code>
+ X = erlang:crc32(Data1),
+ Y = erlang:crc32(X,Data2).</code>
+ <p>assigns the same value to <c>Y</c> as this:</p>
+ <code>
+ Y = erlang:crc32([Data1,Data2]).</code>
</desc>
</func>
+
<func>
<name name="crc32_combine" arity="3"/>
- <fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary>
- <desc>
- <p>Combines two previously computed crc32 checksums.
- This computation requires the size of the data object for
- the second checksum to be known.</p>
- <p>The following code:</p>
- <code>
- Y = erlang:crc32(Data1),
- Z = erlang:crc32(Y,Data2).
- </code>
- <p>- would assign the same value to <c>Z</c> as this would:</p>
+ <fsummary>Combines two crc32 (IEEE 802.3) checksums.</fsummary>
+ <desc>
+ <p>Combines two previously computed crc32 checksums.
+ This computation requires the size of the data object for
+ the second checksum to be known.</p>
+ <p>The following code:</p>
+ <code>
+ Y = erlang:crc32(Data1),
+ Z = erlang:crc32(Y,Data2).</code>
+ <p>assigns the same value to <c>Z</c> as this:</p>
<code>
- X = erlang:crc32(Data1),
- Y = erlang:crc32(Data2),
- Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
- </code>
+ X = erlang:crc32(Data1),
+ Y = erlang:crc32(Data2),
+ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code>
</desc>
</func>
+
<func>
<name name="date" arity="0"/>
- <fsummary>Current date</fsummary>
+ <fsummary>Current date.</fsummary>
<desc>
<p>Returns the current date as <c>{Year, Month, Day}</c>.</p>
- <p>The time zone and daylight saving time correction depend on
+ <p>The time zone and Daylight Saving Time correction depend on
the underlying OS.</p>
+ <p>Example:</p>
<pre>
> <input>date().</input>
{1995,2,19}</pre>
</desc>
</func>
+
<func>
<name name="decode_packet" arity="3"/>
- <fsummary>Extracts a protocol packet from a binary</fsummary>
+ <fsummary>Extracts a protocol packet from a binary.</fsummary>
<desc>
-
<p>Decodes the binary <c><anno>Bin</anno></c> according to the packet
- protocol specified by <c><anno>Type</anno></c>. Very similar to the packet
- handling done by sockets with the option {packet,<anno>Type</anno>}.</p>
- <p>If an entire packet is contained in <c><anno>Bin</anno></c> it is
+ protocol specified by <c><anno>Type</anno></c>. Similar to the packet
+ handling done by sockets with option {packet,<anno>Type</anno>}.</p>
+ <p>If an entire packet is contained in <c><anno>Bin</anno></c>, it is
returned together with the remainder of the binary as
<c>{ok,<anno>Packet</anno>,<anno>Rest</anno>}</c>.</p>
<p>If <c><anno>Bin</anno></c> does not contain the entire packet,
- <c>{more,<anno>Length</anno>}</c> is returned. <c><anno>Length</anno></c> is either the
- expected <em>total size</em> of the packet or <c>undefined</c>
- if the expected packet size is not known. <c>decode_packet</c>
+ <c>{more,<anno>Length</anno>}</c> is returned.
+ <c><anno>Length</anno></c> is either the
+ expected <em>total size</em> of the packet, or <c>undefined</c>
+ if the expected packet size is unknown. <c>decode_packet</c>
can then be called again with more data added.</p>
- <p>If the packet does not conform to the protocol format
+ <p>If the packet does not conform to the protocol format,
<c>{error,<anno>Reason</anno>}</c> is returned.</p>
- <p>The following values of <c><anno>Type</anno></c> are valid:</p>
+ <p>The following <c>Type</c>s are valid:</p>
<taglist>
<tag><c>raw | 0</c></tag>
<item>
- <p>No packet handling is done. Entire binary is
+ <p>No packet handling is done. The entire binary is
returned unless it is empty.</p>
</item>
<tag><c>1 | 2 | 4</c></tag>
<item>
<p>Packets consist of a header specifying the number of
bytes in the packet, followed by that number of bytes.
- The length of header can be one, two, or four bytes;
+ The length of the header can be one, two, or four bytes;
the order of the bytes is big-endian. The header
- will be stripped off when the packet is returned.</p>
+ is stripped off when the packet is returned.</p>
</item>
<tag><c>line</c></tag>
<item>
- <p>A packet is a line terminated with newline. The
- newline character is included in the returned packet
- unless the line was truncated according to the option
- <c>line_length</c>.</p>
+ <p>A packet is a line terminated by a delimiter byte,
+ default is the latin1 newline character. The delimiter
+ byte is included in the returned packet unless the line
+ was truncated according to option <c>line_length</c>.</p>
</item>
<tag><c>asn1 | cdr | sunrm | fcgi | tpkt</c></tag>
<item>
@@ -697,41 +895,50 @@
<item>
<p>The Hypertext Transfer Protocol. The packets
are returned with the format according to
- <c><anno>HttpPacket</anno></c> described above. A packet is either a
- request, a response, a header or an end of header
- mark. Invalid lines are returned as <c><anno>HttpError</anno></c>.</p>
- <p>Recognized request methods and header fields are returned as atoms.
- Others are returned as strings. Strings of unrecognized header fields
- are formatted with only capital letters first and after hyphen characters
- (like <c>"Sec-Websocket-Key"</c>).</p>
- <p>The protocol type <c>http</c> should only be used for
- the first line when a <c><anno>HttpRequest</anno></c> or a
- <c><anno>HttpResponse</anno></c> is expected. The following calls
- should use <c>httph</c> to get <c><anno>HttpHeader</anno></c>'s until
- <c>http_eoh</c> is returned that marks the end of the
+ <c><anno>HttpPacket</anno></c> described earlier.
+ A packet is either a
+ request, a response, a header, or an end of header
+ mark. Invalid lines are returned as
+ <c><anno>HttpError</anno></c>.</p>
+ <p>Recognized request methods and header fields are returned
+ as atoms. Others are returned as strings. Strings of
+ unrecognized header fields are formatted with only
+ capital letters first and after hyphen characters, for
+ example, <c>"Sec-Websocket-Key"</c>.</p>
+ <p>The protocol type <c>http</c> is only to be used for
+ the first line when an <c><anno>HttpRequest</anno></c> or an
+ <c><anno>HttpResponse</anno></c> is expected.
+ The following calls are to use <c>httph</c> to get
+ <c><anno>HttpHeader</anno></c>s until
+ <c>http_eoh</c> is returned, which marks the end of the
headers and the beginning of any following message body.</p>
- <p>The variants <c>http_bin</c> and <c>httph_bin</c> will return
+ <p>The variants <c>http_bin</c> and <c>httph_bin</c> return
strings (<c>HttpString</c>) as binaries instead of lists.</p>
</item>
</taglist>
<p>The following options are available:</p>
<taglist>
<tag><c>{packet_size, integer() >= 0}</c></tag>
- <item><p>Sets the max allowed size of the packet body. If
- the packet header indicates that the length of the
- packet is longer than the max allowed length, the packet
- is considered invalid. Default is 0 which means no
- size limit.</p>
+ <item><p>Sets the maximum allowed size of the packet body.
+ If the packet header indicates that the length of the
+ packet is longer than the maximum allowed length, the
+ packet is considered invalid. Default is 0, which means
+ no size limit.</p>
</item>
<tag><c>{line_length, integer() >= 0}</c></tag>
- <item><p>For packet type <c>line</c>, truncate lines longer
- than the indicated length.</p>
- <p>Option <c>line_length</c> also applies to <c>http*</c>
- packet types as an alias for option <c>packet_size</c> in the
- case when <c>packet_size</c> itself is not set. This usage is
- only intended for backward compatibility.</p>
+ <item><p>For packet type <c>line</c>, lines longer than
+ the indicated length are truncated.</p>
+ <p>Option <c>line_length</c> also applies to <c>http*</c>
+ packet types as an alias for option <c>packet_size</c>
+ if <c>packet_size</c> itself is not set. This use is
+ only intended for backward compatibility.</p>
+ </item>
+ <tag><c>{line_delimiter, 0 =&lt; byte() =&lt; 255}</c></tag>
+ <item><p>For packet type <c>line</c>, sets the delimiting byte.
+ Default is the latin1 character <c>$\n</c>.</p>
</item>
</taglist>
+ <p>Examples:</p>
<pre>
> <input>erlang:decode_packet(1,&lt;&lt;3,"abcd"&gt;&gt;,[]).</input>
{ok,&lt;&lt;"abc"&gt;&gt;,&lt;&lt;"d"&gt;&gt;}
@@ -742,13 +949,11 @@
<func>
<name name="delete_element" arity="2"/>
- <fsummary>Delete element at index in a tuple</fsummary>
+ <fsummary>Deletes element at index in a tuple.</fsummary>
<type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>)</type_desc>
<desc>
- <p>
- Returns a new tuple with element at <c><anno>Index</anno></c> removed from
- tuple <c><anno>Tuple1</anno></c>.
- </p>
+ <p>Returns a new tuple with element at <c><anno>Index</anno></c>
+ removed from tuple <c><anno>Tuple1</anno></c>, for example:</p>
<pre>
> <input>erlang:delete_element(2, {one, two, three}).</input>
{one,three}</pre>
@@ -757,45 +962,49 @@
<func>
<name name="delete_module" arity="1"/>
- <fsummary>Make the current code for a module old</fsummary>
+ <fsummary>Makes the current code for a module old.</fsummary>
<desc>
- <p>Makes the current code for <c><anno>Module</anno></c> become old code, and
- deletes all references for this module from the export table.
+ <p>Makes the current code for <c><anno>Module</anno></c> become old code,
+ and deletes all references for this module from the export table.
Returns <c>undefined</c> if the module does not exist,
otherwise <c>true</c>.</p>
<warning>
<p>This BIF is intended for the code server (see
- <seealso marker="kernel:code">code(3)</seealso>) and should not be
- used elsewhere.</p>
+ <seealso marker="kernel:code">code(3)</seealso>) and is not
+ to be used elsewhere.</p>
</warning>
- <p>Failure: <c>badarg</c> if there is already an old version of
+ <p>Failure: <c>badarg</c> if there already is an old version of
<c>Module</c>.</p>
</desc>
</func>
+
<func>
<name name="demonitor" arity="1"/>
- <fsummary>Stop monitoring</fsummary>
+ <fsummary>Stops monitoring.</fsummary>
<desc>
- <p>If <c><anno>MonitorRef</anno></c> is a reference which the calling process
- obtained by calling
+ <p>If <c><anno>MonitorRef</anno></c> is a reference that the
+ calling process obtained by calling
<seealso marker="#monitor/2">monitor/2</seealso>,
this monitoring is turned off. If the monitoring is already
turned off, nothing happens.</p>
- <p>Once <c>demonitor(<anno>MonitorRef</anno>)</c> has returned it is
- guaranteed that no <c>{'DOWN', <anno>MonitorRef</anno>, _, _, _}</c> message
- due to the monitor will be placed in the caller's message queue
- in the future. A <c>{'DOWN', <anno>MonitorRef</anno>, _, _, _}</c> message
- might have been placed in the caller's message queue prior to
- the call, though. Therefore, in most cases, it is advisable
+ <p>Once <c>demonitor(<anno>MonitorRef</anno>)</c> has returned, it is
+ guaranteed that no <c>{'DOWN',
+ <anno>MonitorRef</anno>, _, _, _}</c> message,
+ because of the monitor, will be placed in the caller message queue
+ in the future. A <c>{'DOWN',
+ <anno>MonitorRef</anno>, _, _, _}</c> message
+ can have been placed in the caller message queue before
+ the call, though. It is therefore usually advisable
to remove such a <c>'DOWN'</c> message from the message queue
- after monitoring has been stopped.
- <seealso marker="#demonitor/2">demonitor(<anno>MonitorRef</anno>, [flush])</seealso> can be used instead of
+ after monitoring has been stopped.
+ <seealso marker="#demonitor/2"><c>demonitor(<anno>MonitorRef</anno>, [flush])</c></seealso>
+ can be used instead of
<c>demonitor(<anno>MonitorRef</anno>)</c> if this cleanup is wanted.</p>
<note>
- <p>Prior to OTP release R11B (erts version 5.5) <c>demonitor/1</c>
- behaved completely asynchronous, i.e., the monitor was active
+ <p>Prior to OTP release R11B (ERTS version 5.5) <c>demonitor/1</c>
+ behaved completely asynchronously, i.e., the monitor was active
until the "demonitor signal" reached the monitored entity. This
- had one undesirable effect, though. You could never know when
+ had one undesirable effect. You could never know when
you were guaranteed <em>not</em> to receive a <c>DOWN</c> message
due to the monitor.</p>
<p>Current behavior can be viewed as two combined operations:
@@ -804,31 +1013,31 @@
</note>
<p>Failure: It is an error if <c><anno>MonitorRef</anno></c> refers to a
monitoring started by another process. Not all such cases are
- cheap to check; if checking is cheap, the call fails with
- <c>badarg</c> (for example if <c><anno>MonitorRef</anno></c> is a remote
- reference).</p>
+ cheap to check. If checking is cheap, the call fails with
+ <c>badarg</c> for example, if <c><anno>MonitorRef</anno></c> is a
+ remote reference.</p>
</desc>
</func>
+
<func>
<name name="demonitor" arity="2"/>
- <fsummary>Stop monitoring</fsummary>
+ <fsummary>Stops monitoring.</fsummary>
<desc>
<p>The returned value is <c>true</c> unless <c>info</c> is part
- of <c><anno>OptionList</anno></c>.
- </p>
+ of <c><anno>OptionList</anno></c>.</p>
<p><c>demonitor(<anno>MonitorRef</anno>, [])</c> is equivalent to
- <seealso marker="#demonitor/1">demonitor(<anno>MonitorRef</anno>)</seealso>.</p>
- <p>Currently the following <c><anno>Option</anno></c>s are valid:</p>
+ <seealso marker="#demonitor/1"><c>demonitor(<anno>MonitorRef</anno>)</c></seealso>.</p>
+ <p>The available <c><anno>Option</anno></c>s are as follows:</p>
<taglist>
<tag><c>flush</c></tag>
<item>
- <p>Remove (one) <c>{_, <anno>MonitorRef</anno>, _, _, _}</c> message,
- if there is one, from the caller's message queue after
+ <p>Removes (one) <c>{_,
+ <anno>MonitorRef</anno>, _, _, _}</c> message,
+ if there is one, from the caller message queue after
monitoring has been stopped.</p>
<p>Calling <c>demonitor(<anno>MonitorRef</anno>, [flush])</c>
is equivalent to the following, but more efficient:</p>
<code type="none">
-
demonitor(MonitorRef),
receive
{_, MonitorRef, _, _, _} ->
@@ -839,78 +1048,90 @@
</item>
<tag><c>info</c></tag>
<item>
- <p>The returned value is one of the following:</p>
- <taglist>
- <tag><c>true</c></tag>
- <item><p>The monitor was found and removed. In this case
- no <c>'DOWN'</c> message due to this monitor have
- been nor will be placed in the message queue
- of the caller.
- </p>
- </item>
- <tag><c>false</c></tag>
- <item><p>The monitor was not found and could not be removed.
- This probably because someone already has placed a
- <c>'DOWN'</c> message corresponding to this monitor
- in the caller's message queue.
- </p>
- </item>
- </taglist>
- <p>If the <c>info</c> option is combined with the <c>flush</c>
- option, <c>false</c> will be returned if a flush was needed;
- otherwise, <c>true</c>.
- </p>
+ <p>The returned value is one of the following:</p>
+ <taglist>
+ <tag><c>true</c></tag>
+ <item>The monitor was found and removed. In this case,
+ no <c>'DOWN'</c> message corresponding to this
+ monitor has been delivered and will not be delivered.
+ </item>
+ <tag><c>false</c></tag>
+ <item>The monitor was not found and could not be removed.
+ This probably because someone already has placed a
+ <c>'DOWN'</c> message corresponding to this monitor
+ in the caller message queue.
+ </item>
+ </taglist>
+ <p>If option <c>info</c> is combined with option <c>flush</c>,
+ <c>false</c> is returned if a flush was needed,
+ otherwise <c>true</c>.</p>
</item>
</taglist>
<note>
- <p>More options may be added in the future.</p>
+ <p>More options can be added in a future release.</p>
</note>
- <p>Failure: <c>badarg</c> if <c><anno>OptionList</anno></c> is not a list, or
- if <c><anno>Option</anno></c> is not a valid option, or the same failure as for
- <seealso marker="#demonitor/1">demonitor/1</seealso></p>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>OptionList</anno></c> is not a list.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>Option</anno></c> is an invalid option.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>The same failure as for
+ <seealso marker="#demonitor/1">demonitor/1</seealso>.
+ </item>
+ </taglist>
</desc>
</func>
+
<func>
<name name="disconnect_node" arity="1"/>
- <fsummary>Force the disconnection of a node</fsummary>
+ <fsummary>Forces the disconnection of a node.</fsummary>
<desc>
- <p>Forces the disconnection of a node. This will appear to
- the node <c><anno>Node</anno></c> as if the local node has crashed. This
- BIF is mainly used in the Erlang network authentication
- protocols. Returns <c>true</c> if disconnection succeeds,
+ <p>Forces the disconnection of a node. This appears to
+ the node <c><anno>Node</anno></c> as if the local node has crashed.
+ This BIF is mainly used in the Erlang network authentication
+ protocols.</p>
+ <p>Returns <c>true</c> if disconnection succeeds,
otherwise <c>false</c>. If the local node is not alive,
- the function returns <c>ignored</c>.</p>
+ <c>ignored</c> is returned.</p>
</desc>
</func>
+
<func>
<name name="display" arity="1"/>
- <fsummary>Print a term on standard output</fsummary>
+ <fsummary>Prints a term on standard output.</fsummary>
<desc>
- <p>Prints a text representation of <c><anno>Term</anno></c> on the standard
- output. On OSE the term is printed to the ramlog.</p>
+ <p>Prints a text representation of <c><anno>Term</anno></c> on the
+ standard output. On OSE, the term is printed to the ramlog.</p>
<warning>
<p>This BIF is intended for debugging only.</p>
</warning>
</desc>
</func>
+
<func>
<name name="element" arity="2"/>
+ <fsummary>Returns the Nth element of a tuple.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
- <fsummary>Get Nth element of a tuple</fsummary>
<desc>
<p>Returns the <c><anno>N</anno></c>th element (numbering from 1) of
- <c><anno>Tuple</anno></c>.</p>
+ <c><anno>Tuple</anno></c>, for example:</p>
<pre>
> <input>element(2, {a, b, c}).</input>
b</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="erase" arity="0"/>
- <fsummary>Return and delete the process dictionary</fsummary>
+ <fsummary>Returns and deletes the process dictionary.</fsummary>
<desc>
- <p>Returns the process dictionary and deletes it.</p>
+ <p>Returns the process dictionary and deletes it, for
+ example:</p>
<pre>
> <input>put(key1, {1, 2, 3}),</input>
<input>put(key2, [a, b, c]),</input>
@@ -918,13 +1139,16 @@ b</pre>
[{key1,{1,2,3}},{key2,[a,b,c]}]</pre>
</desc>
</func>
+
<func>
<name name="erase" arity="1"/>
- <fsummary>Return and delete a value from the process dictionary</fsummary>
+ <fsummary>Returns and deletes a value from the process dictionary.</fsummary>
<desc>
- <p>Returns the value <c><anno>Val</anno></c> associated with <c><anno>Key</anno></c> and
- deletes it from the process dictionary. Returns
- <c>undefined</c> if no value is associated with <c><anno>Key</anno></c>.</p>
+ <p>Returns the value <c><anno>Val</anno></c> associated with
+ <c><anno>Key</anno></c> and deletes it from the process dictionary.
+ Returns <c>undefined</c> if no value is associated with
+ <c><anno>Key</anno></c>.</p>
+ <p>Example:</p>
<pre>
> <input>put(key1, {merry, lambs, are, playing}),</input>
<input>X = erase(key1),</input>
@@ -932,16 +1156,19 @@ b</pre>
{{merry,lambs,are,playing},undefined}</pre>
</desc>
</func>
+
<func>
<name name="error" arity="1"/>
- <fsummary>Stop execution with a given reason</fsummary>
+ <fsummary>Stops execution with a given reason.</fsummary>
<desc>
<p>Stops the execution of the calling process with the reason
- <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. The actual
- exit reason will be <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
+ <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
+ is any term. The exit reason is
+ <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
is a list of the functions most recently called (the current
function first). Since evaluating this function causes
the process to terminate, it has no return value.</p>
+ <p>Example:</p>
<pre>
> <input>catch error(foobar).</input>
{'EXIT',{foobar,[{erl_eval,do_apply,5},
@@ -951,29 +1178,34 @@ b</pre>
{shell,eval_loop,3}]}}</pre>
</desc>
</func>
+
<func>
<name name="error" arity="2"/>
- <fsummary>Stop execution with a given reason</fsummary>
+ <fsummary>Stops execution with a given reason.</fsummary>
<desc>
<p>Stops the execution of the calling process with the reason
- <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. The actual
- exit reason will be <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
+ <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
+ is any term. The exit reason is
+ <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
is a list of the functions most recently called (the current
- function first). <c><anno>Args</anno></c> is expected to be the list of
- arguments for the current function; in Beam it will be used
- to provide the actual arguments for the current function in
- the <c>Where</c> term. Since evaluating this function causes
+ function first). <c><anno>Args</anno></c> is expected to be the
+ list of arguments for the current function; in Beam it is used
+ to provide the arguments for the current function in
+ the term <c>Where</c>. Since evaluating this function causes
the process to terminate, it has no return value.</p>
</desc>
</func>
+
<func>
<name name="exit" arity="1"/>
- <fsummary>Stop execution with a given reason</fsummary>
+ <fsummary>Stops execution with a given reason.</fsummary>
<desc>
- <p>Stops the execution of the calling process with the exit
- reason <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. Since
+ <p>Stops the execution of the calling process with exit reason
+ <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
+ is any term. Since
evaluating this function causes the process to terminate, it
has no return value.</p>
+ <p>Example:</p>
<pre>
> <input>exit(foobar).</input>
** exception exit: foobar
@@ -981,110 +1213,117 @@ b</pre>
{'EXIT',foobar}</pre>
</desc>
</func>
+
<func>
<name name="exit" arity="2"/>
- <fsummary>Send an exit signal to a process or a port</fsummary>
+ <fsummary>Sends an exit signal to a process or a port.</fsummary>
<desc>
<p>Sends an exit signal with exit reason <c><anno>Reason</anno></c> to
the process or port identified by <c><anno>Pid</anno></c>.</p>
- <p>The following behavior apply if <c><anno>Reason</anno></c> is any term
- except <c>normal</c> or <c>kill</c>:</p>
- <p>If <c><anno>Pid</anno></c> is not trapping exits, <c><anno>Pid</anno></c> itself will
- exit with exit reason <c><anno>Reason</anno></c>. If <c><anno>Pid</anno></c> is trapping
- exits, the exit signal is transformed into a message
- <c>{'EXIT', From, <anno>Reason</anno>}</c> and delivered to the message
- queue of <c><anno>Pid</anno></c>. <c>From</c> is the pid of the process
- which sent the exit signal. See also
- <seealso marker="#process_flag/2">process_flag/2</seealso>.</p>
- <p>If <c><anno>Reason</anno></c> is the atom <c>normal</c>, <c><anno>Pid</anno></c> will
- not exit. If it is trapping exits, the exit signal is
- transformed into a message <c>{'EXIT', From, normal}</c>
- and delivered to its message queue.</p>
- <p>If <c><anno>Reason</anno></c> is the atom <c>kill</c>, that is if
- <c>exit(<anno>Pid</anno>, kill)</c> is called, an untrappable exit signal
- is sent to <c><anno>Pid</anno></c> which will unconditionally exit with
- exit reason <c>killed</c>.</p>
+ <p>The following behavior applies if <c><anno>Reason</anno></c>
+ is any term, except <c>normal</c> or <c>kill</c>:</p>
+ <list type="bulleted">
+ <item>If <c><anno>Pid</anno></c> is not trapping exits,
+ <c><anno>Pid</anno></c>
+ itself exits with exit reason <c><anno>Reason</anno></c>.
+ </item>
+ <item>If <c><anno>Pid</anno></c> is trapping exits, the exit
+ signal is transformed into a message
+ <c>{'EXIT', From, <anno>Reason</anno>}</c>
+ and delivered to the message queue of <c><anno>Pid</anno></c>.
+ </item>
+ <item><c>From</c> is the process identifier of the process
+ that sent the exit signal. See also
+ <seealso marker="#process_flag/2">process_flag/2</seealso>.
+ </item>
+ </list>
+ <p>If <c><anno>Reason</anno></c> is the atom <c>normal</c>,
+ <c><anno>Pid</anno></c>
+ does not exit. If it is trapping exits, the exit signal is
+ transformed into a message <c>{'EXIT', From, normal}</c>
+ and delivered to its message queue.</p>
+ <p>If <c><anno>Reason</anno></c> is the atom <c>kill</c>,
+ that is, if <c>exit(<anno>Pid</anno>, kill)</c> is called,
+ an untrappable exit signal is sent to <c><anno>Pid</anno></c>,
+ which unconditionally exits with exit reason <c>killed</c>.
+ </p>
</desc>
</func>
+
<func>
<name name="external_size" arity="1"/>
- <fsummary>Calculate the maximum size for a term encoded in the Erlang
- external term format</fsummary>
+ <fsummary>Calculates the maximum size for a term encoded in the Erlang external term format.</fsummary>
<desc>
<p>Calculates, without doing the encoding, the maximum byte size for
a term encoded in the Erlang external term format. The following
condition applies always:</p>
- <p>
<pre>
> <input>Size1 = byte_size(term_to_binary(<anno>Term</anno>)),</input>
> <input>Size2 = erlang:external_size(<anno>Term</anno>),</input>
> <input>true = Size1 =&lt; Size2.</input>
-true
- </pre>
- </p>
- <p>This is equivalent to a call to: <code>erlang:external_size(<anno>Term</anno>, [])
- </code></p>
+true</pre>
+ <p>This is equivalent to a call to:</p>
+<code>erlang:external_size(<anno>Term</anno>, [])</code>
</desc>
</func>
+
<func>
<name name="external_size" arity="2"/>
- <fsummary>Calculate the maximum size for a term encoded in the Erlang
- external term format</fsummary>
+ <fsummary>Calculates the maximum size for a term encoded in the Erlang external term format.</fsummary>
<desc>
<p>Calculates, without doing the encoding, the maximum byte size for
a term encoded in the Erlang external term format. The following
condition applies always:</p>
- <p>
<pre>
> <input>Size1 = byte_size(term_to_binary(<anno>Term</anno>, <anno>Options</anno>)),</input>
> <input>Size2 = erlang:external_size(<anno>Term</anno>, <anno>Options</anno>),</input>
> <input>true = Size1 =&lt; Size2.</input>
-true
- </pre>
- </p>
- <p>The option <c>{minor_version, <anno>Version</anno>}</c> specifies how floats
- are encoded. See
- <seealso marker="#term_to_binary/2">term_to_binary/2</seealso> for
- a more detailed description.
- </p>
+true</pre>
+ <p>Option <c>{minor_version, <anno>Version</anno>}</c> specifies how
+ floats are encoded. For a detailed description, see
+ <seealso marker="#term_to_binary/2">term_to_binary/2</seealso>.</p>
</desc>
</func>
+
<func>
<name name="float" arity="1"/>
- <fsummary>Convert a number to a float</fsummary>
+ <fsummary>Converts a number to a float.</fsummary>
<desc>
- <p>Returns a float by converting <c><anno>Number</anno></c> to a float.</p>
+ <p>Returns a float by converting <c><anno>Number</anno></c> to a float,
+ for example:</p>
<pre>
> <input>float(55).</input>
55.0</pre>
<p>Allowed in guard tests.</p>
<note>
- <p>Note that if used on the top-level in a guard, it will
- test whether the argument is a floating point number; for
- clarity, use
+ <p>If used on the top level in a guard, it tests whether the
+ argument is a floating point number; for clarity, use
<seealso marker="#is_float/1">is_float/1</seealso> instead.</p>
<p>When <c>float/1</c> is used in an expression in a guard,
such as '<c>float(A) == 4.0</c>', it converts a number as
- described above.</p>
+ described earlier.</p>
</note>
</desc>
</func>
+
<func>
<name name="float_to_binary" arity="1"/>
- <fsummary>Text representation of a float</fsummary>
+ <fsummary>Text representation of a float.</fsummary>
<desc>
- <p>The same as <c>float_to_binary(<anno>Float</anno>,[{scientific,20}])</c>.</p>
+ <p>The same as
+ <c>float_to_binary(<anno>Float</anno>,[{scientific,20}])</c>.</p>
</desc>
</func>
+
<func>
<name name="float_to_binary" arity="2"/>
- <fsummary>Text representation of a float formatted using given options</fsummary>
+ <fsummary>Text representation of a float formatted using given options.</fsummary>
<desc>
- <p>Returns a binary which corresponds to the text
+ <p>Returns a binary corresponding to the text
representation of <c><anno>Float</anno></c> using fixed decimal
- point formatting. The <c><anno>Options</anno></c> behave in the same
- way as <seealso marker="#float_to_list/2">float_to_list/2</seealso>.
- </p>
+ point formatting. <c><anno>Options</anno></c> behaves in the same
+ way as <seealso marker="#float_to_list/2">float_to_list/2</seealso>.</p>
+ <p>Examples:</p>
<pre>
> <input>float_to_binary(7.12, [{decimals, 4}]).</input>
&lt;&lt;"7.1200">>
@@ -1092,31 +1331,42 @@ true
&lt;&lt;"7.12">></pre>
</desc>
</func>
+
<func>
<name name="float_to_list" arity="1"/>
- <fsummary>Text representation of a float</fsummary>
+ <fsummary>Text representation of a float.</fsummary>
<desc>
- <p>The same as <c>float_to_list(<anno>Float</anno>,[{scientific,20}])</c>.</p>
+ <p>The same as
+ <c>float_to_list(<anno>Float</anno>,[{scientific,20}])</c>.</p>
</desc>
</func>
+
<func>
<name name="float_to_list" arity="2"/>
- <fsummary>Text representation of a float formatted using given options</fsummary>
- <desc>
- <p>Returns a string which corresponds to the text
- representation of <c>Float</c> using fixed decimal point formatting.
- When <c>decimals</c> option is specified
- the returned value will contain at most <c>Decimals</c> number of
- digits past the decimal point. If the number doesn't fit in the
- internal static buffer of 256 bytes, the function throws <c>badarg</c>.
- When <c>compact</c> option is provided
- the trailing zeros at the end of the list are truncated (this option is
- only meaningful together with the <c>decimals</c> option). When
- <c>scientific</c> option is provided, the float will be formatted using
- scientific notation with <c>Decimals</c> digits of precision. If
- <c>Options</c> is <c>[]</c> the function behaves like
- <c><seealso marker="#float_to_list/1">float_to_list/1</seealso></c>.
- </p>
+ <fsummary>Text representation of a float formatted using given options.</fsummary>
+ <desc>
+ <p>Returns a string corresponding to the text representation
+ of <c>Float</c> using fixed decimal point formatting. The
+ options are as follows:</p>
+ <list type="bulleted">
+ <item>If option <c>decimals</c> is specified, the returned value
+ contains at most <c>Decimals</c> number of digits past the
+ decimal point. If the number does not fit in the internal
+ static buffer of 256 bytes, the function throws <c>badarg</c>.
+ </item>
+ <item>If option <c>compact</c> is provided, the trailing zeros
+ at the end of the list are truncated. This option is only
+ meaningful together with option <c>decimals</c>.
+ </item>
+ <item>If option <c>scientific</c> is provided, the float is
+ formatted using scientific notation with <c>Decimals</c>
+ digits of precision.
+ </item>
+ <item>If <c>Options</c> is <c>[]</c>, the function behaves as
+ <seealso marker="#float_to_list/1">float_to_list/1</seealso>.
+ </item>
+ </list>
+ <p>Examples:</p>
<pre>
> <input>float_to_list(7.12, [{decimals, 4}]).</input>
"7.1200"
@@ -1124,36 +1374,40 @@ true
"7.12"</pre>
</desc>
</func>
+
<func>
<name name="fun_info" arity="1"/>
- <fsummary>Information about a fun</fsummary>
+ <fsummary>Information about a fun.</fsummary>
<desc>
- <p>Returns a list containing information about the fun
- <c><anno>Fun</anno></c>. Each element of the list is a tuple. The order of
- the tuples is not defined, and more tuples may be added in a
+ <p>Returns a list with information about the fun
+ <c><anno>Fun</anno></c>. Each list element is a tuple. The order
+ of the tuples is undefined, and more tuples can be added in a
future release.</p>
<warning>
<p>This BIF is mainly intended for debugging, but it can
- occasionally be useful in library functions that might need
- to verify, for instance, the arity of a fun.</p>
+ sometimes be useful in library functions that need
+ to verify, for example, the arity of a fun.</p>
</warning>
- <p>There are two types of funs with slightly different
- semantics:</p>
- <p>A fun created by <c>fun M:F/A</c> is called an
- <em>external</em> fun. Calling it will always call the
- function <c>F</c> with arity <c>A</c> in the latest code for
- module <c>M</c>. Note that module <c>M</c> does not even need
- to be loaded when the fun <c>fun M:F/A</c> is created.</p>
- <p>All other funs are called <em>local</em>. When a local fun
- is called, the same version of the code that created the fun
- will be called (even if newer version of the module has been
- loaded).</p>
- <p>The following elements will always be present in the list
+ <p>Two types of funs have slightly different semantics:</p>
+ <list type="bulleted">
+ <item>A fun created by <c>fun M:F/A</c> is called an
+ <em>external</em> fun. Calling it will always call the
+ function <c>F</c> with arity <c>A</c> in the latest code for
+ module <c>M</c>. Notice that module <c>M</c> does not even
+ need to be loaded when the fun <c>fun M:F/A</c> is created.
+ </item>
+ <item>All other funs are called <em>local</em>. When a local fun
+ is called, the same version of the code that created the fun
+ is called (even if a newer version of the module has been
+ loaded).
+ </item>
+ </list>
+ <p>The following elements are always present in the list
for both local and external funs:</p>
<taglist>
<tag><c>{type, Type}</c></tag>
<item>
- <p><c>Type</c> is either <c>local</c> or <c>external</c>.</p>
+ <p><c>Type</c> is <c>local</c> or <c>external</c>.</p>
</item>
<tag><c>{module, Module}</c></tag>
<item>
@@ -1168,147 +1422,154 @@ true
<p><c>Name</c> (an atom) is a function name.</p>
<p>If <c>Fun</c> is a local fun, <c>Name</c> is the name
of the local function that implements the fun.
- (This name was generated by the compiler, and is generally
+ (This name was generated by the compiler, and is
only of informational use. As it is a local function, it
- is not possible to call it directly.)
+ cannot be called directly.)
If no code is currently loaded for the fun, <c>[]</c>
- will be returned instead of an atom.</p>
+ is returned instead of an atom.</p>
<p>If <c>Fun</c> is an external fun, <c>Name</c> is the name
of the exported function that the fun refers to.</p>
</item>
<tag><c>{arity, Arity}</c></tag>
<item>
<p><c>Arity</c> is the number of arguments that the fun
- should be called with.</p>
+ is to be called with.</p>
</item>
<tag><c>{env, Env}</c></tag>
<item>
<p><c>Env</c> (a list) is the environment or free variables
- for the fun. (For external funs, the returned list is
- always empty.)</p>
+ for the fun. For external funs, the returned list is
+ always empty.</p>
</item>
</taglist>
- <p>The following elements will only be present in the list if
+ <p>The following elements are only present in the list if
<c>Fun</c> is local:</p>
<taglist>
<tag><c>{pid, Pid}</c></tag>
<item>
- <p><c>Pid</c> is the pid of the process that originally
- created the fun.</p>
+ <p><c>Pid</c> is the process identifier of the process
+ that originally created the fun.</p>
</item>
<tag><c>{index, Index}</c></tag>
<item>
- <p><c>Index</c> (an integer) is an index into the module's
+ <p><c>Index</c> (an integer) is an index into the module
fun table.</p>
</item>
<tag><c>{new_index, Index}</c></tag>
<item>
- <p><c>Index</c> (an integer) is an index into the module's
+ <p><c>Index</c> (an integer) is an index into the module
fun table.</p>
</item>
<tag><c>{new_uniq, Uniq}</c></tag>
<item>
- <p><c>Uniq</c> (a binary) is a unique value for this fun.
- It is calculated from the compiled code for the entire module.</p>
+ <p><c>Uniq</c> (a binary) is a unique value for this fun. It
+ is calculated from the compiled code for the entire module.</p>
</item>
<tag><c>{uniq, Uniq}</c></tag>
<item>
<p><c>Uniq</c> (an integer) is a unique value for this fun.
- Starting in the R15 release, this integer is calculated from
- the compiled code for the entire module. Before R15, this
- integer was based on only the body of the fun.
- </p>
+ As from OTP R15, this integer is calculated from the
+ compiled code for the entire module. Before OTP R15, this
+ integer was based on only the body of the fun.</p>
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="fun_info" arity="2"/>
+ <fsummary>Information about a fun.</fsummary>
<type name="fun_info_item"/>
- <fsummary>Information about a fun</fsummary>
<desc>
<p>Returns information about <c><anno>Fun</anno></c> as specified by
- <c><anno>Item</anno></c>, in the form <c>{<anno>Item</anno>,<anno>Info</anno>}</c>.</p>
+ <c><anno>Item</anno></c>, in the form
+ <c>{<anno>Item</anno>,<anno>Info</anno>}</c>.</p>
<p>For any fun, <c><anno>Item</anno></c> can be any of the atoms
- <c>module</c>, <c>name</c>, <c>arity</c>, <c>env</c>, or <c>type</c>.</p>
- <p>For a local fun, <c><anno>Item</anno></c> can also be any of the atoms
- <c>index</c>, <c>new_index</c>, <c>new_uniq</c>,
+ <c>module</c>, <c>name</c>, <c>arity</c>, <c>env</c>, or
+ <c>type</c>.</p>
+ <p>For a local fun, <c><anno>Item</anno></c> can also be any of the
+ atoms <c>index</c>, <c>new_index</c>, <c>new_uniq</c>,
<c>uniq</c>, and <c>pid</c>. For an external fun, the value
of any of these items is always the atom <c>undefined</c>.</p>
<p>See
<seealso marker="#fun_info/1">erlang:fun_info/1</seealso>.</p>
</desc>
</func>
+
<func>
<name name="fun_to_list" arity="1"/>
- <fsummary>Text representation of a fun</fsummary>
+ <fsummary>Text representation of a fun.</fsummary>
<desc>
- <p>Returns a string which corresponds to the text
+ <p>Returns a string corresponding to the text
representation of <c><anno>Fun</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="function_exported" arity="3"/>
- <fsummary>Check if a function is exported and loaded</fsummary>
+ <fsummary>Checks if a function is exported and loaded.</fsummary>
<desc>
<p>Returns <c>true</c> if the module <c><anno>Module</anno></c> is loaded
- and contains an exported function <c><anno>Function</anno>/<anno>Arity</anno></c>;
- otherwise <c>false</c>.</p>
- <p>Returns <c>false</c> for any BIF (functions implemented in C
- rather than in Erlang).</p>
+ and contains an exported function <c><anno>Function</anno>/<anno>Arity</anno></c>,
+ or if there is a BIF (a built-in function implemented in C)
+ with the given name, otherwise returns <c>false</c>.</p>
+ <note><p>This function used to return false for built-in
+ functions before the 18.0 release.</p></note>
</desc>
</func>
+
<func>
<name name="garbage_collect" arity="0"/>
- <fsummary>Force an immediate garbage collection of the calling process</fsummary>
+ <fsummary>Forces an immediate garbage collection of the calling process.</fsummary>
<desc>
- <p>Forces an immediate garbage collection of the currently
- executing process. The function should not be used, unless
- it has been noticed -- or there are good reasons to suspect --
+ <p>Forces an immediate garbage collection of the
+ executing process. The function is not to be used unless
+ it has been noticed (or there are good reasons to suspect)
that the spontaneous garbage collection will occur too late
- or not at all. Improper use may seriously degrade system
- performance.</p>
+ or not at all.</p>
+ <warning>
+ <p>Improper use can seriously degrade system performance.</p>
+ </warning>
</desc>
</func>
+
<func>
<name name="garbage_collect" arity="1"/>
- <fsummary>Garbage collect a process</fsummary>
+ <fsummary>Garbage collects a process.</fsummary>
<desc>
<p>The same as
<seealso marker="#garbage_collect/2"><c>garbage_collect(<anno>Pid</anno>, [])</c></seealso>.</p>
</desc>
</func>
+
<func>
<name name="garbage_collect" arity="2"/>
- <fsummary>Garbage collect a process</fsummary>
+ <fsummary>Garbage collects a process.</fsummary>
<desc>
- <p>Garbage collect the node local process identified by
- <c><anno>Pid</anno></c>.</p>
- <p>Currently available <c><anno>Option</anno></c>s:</p>
+ <p>Garbage collects the node local process identified by
+ <c><anno>Pid</anno></c>.</p>
+ <p>The available <c><anno>Option</anno></c>s are as follows:</p>
<taglist>
<tag><c>{async, RequestId}</c></tag>
- <item>
- The <c>garbage_collect/2</c> function will return
+ <item>The function <c>garbage_collect/2</c> returns
the value <c>async</c> immediately after the request
has been sent. When the request has been processed, the
- process that called this function will be passed a
- message on the form:<br/>
- <c>{garbage_collect, <anno>RequestId</anno>, <anno>GCResult</anno>}</c>.
- </item>
+ process that called this function is passed a message on
+ the form <c>{garbage_collect,
+ <anno>RequestId</anno>, <anno>GCResult</anno>}</c>.
+ </item>
</taglist>
<p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and
no <c>async</c> option has been passed, the garbage
- collection will be performed at once, i.e. the same as
- calling
+ collection is performed at once, that is, the same as calling
<seealso marker="#garbage_collect/0">garbage_collect/0</seealso>.
- In all other cases a request for garbage collection will
- be sent to the process identified by <c><anno>Pid</anno></c>,
+ Otherwise a request for garbage collection
+ is sent to the process identified by <c><anno>Pid</anno></c>,
and will be handled when appropriate. If no <c>async</c>
- option has been passed, the caller will block until
- <c><anno>GCResult</anno></c> is available and can be
- returned.</p>
+ option has been passed, the caller blocks until
+ <c><anno>GCResult</anno></c> is available and can be returned.</p>
<p><c><anno>GCResult</anno></c> informs about the result of
- the garbage collection request:</p>
+ the garbage collection request as follows:</p>
<taglist>
<tag><c>true</c></tag>
<item>
@@ -1317,14 +1578,13 @@ true
</item>
<tag><c>false</c></tag>
<item>
- No garbage collection was performed. This since the
+ No garbage collection was performed, as
the process identified by <c><anno>Pid</anno></c>
terminated before the request could be satisfied.
</item>
</taglist>
- <p>Note that the same caveats as for
- <seealso marker="#garbage_collect/0">garbage_collect/0</seealso>
- apply.</p>
+ <p>Notice that the same caveats apply as for
+ <seealso marker="#garbage_collect/0">garbage_collect/0</seealso>.</p>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
@@ -1333,17 +1593,18 @@ true
</item>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>OptionList</anno></c> is not a valid list of options.
+ If <c><anno>OptionList</anno></c> is an invalid list of options.
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="get" arity="0"/>
- <fsummary>Return the process dictionary</fsummary>
+ <fsummary>Returns the process dictionary.</fsummary>
<desc>
<p>Returns the process dictionary as a list of
- <c>{<anno>Key</anno>, <anno>Val</anno>}</c> tuples.</p>
+ <c>{<anno>Key</anno>, <anno>Val</anno>}</c> tuples, for example:</p>
<pre>
> <input>put(key1, merry),</input>
<input>put(key2, lambs),</input>
@@ -1352,13 +1613,15 @@ true
[{key1,merry},{key2,lambs},{key3,{are,playing}}]</pre>
</desc>
</func>
+
<func>
<name name="get" arity="1"/>
- <fsummary>Return a value from the process dictionary</fsummary>
+ <fsummary>Returns a value from the process dictionary.</fsummary>
<desc>
<p>Returns the value <c><anno>Val</anno></c> associated with <c><anno>Key</anno></c> in
the process dictionary, or <c>undefined</c> if <c><anno>Key</anno></c>
does not exist.</p>
+ <p>Example:</p>
<pre>
> <input>put(key1, merry),</input>
<input>put(key2, lambs),</input>
@@ -1367,20 +1630,35 @@ true
{are,playing}</pre>
</desc>
</func>
+
<func>
<name name="get_cookie" arity="0"/>
- <fsummary>Get the magic cookie of the local node</fsummary>
+ <fsummary>Gets the magic cookie of the local node.</fsummary>
+ <desc>
+ <p>Returns the magic cookie of the local node if the node is
+ alive, otherwise the atom <c>nocookie</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_keys" arity="0"/>
+ <fsummary>Return a list of all keys from the process dictionary</fsummary>
<desc>
- <p>Returns the magic cookie of the local node, if the node is
- alive; otherwise the atom <c>nocookie</c>.</p>
+ <p>Returns a list of keys all keys present in the process dictionary.</p>
+ <pre>
+> <input>put(dog, {animal,1}),</input>
+<input>put(cow, {animal,2}),</input>
+<input>put(lamb, {animal,3}),</input>
+<input>get_keys().</input>
+[dog,cow,lamb]</pre>
</desc>
</func>
<func>
<name name="get_keys" arity="1"/>
- <fsummary>Return a list of keys from the process dictionary</fsummary>
+ <fsummary>Returns a list of keys from the process dictionary.</fsummary>
<desc>
- <p>Returns a list of keys which are associated with the value
- <c><anno>Val</anno></c> in the process dictionary.</p>
+ <p>Returns a list of keys that are associated with the value
+ <c><anno>Val</anno></c> in the process dictionary, for example:</p>
<pre>
> <input>put(mary, {1, 2}),</input>
<input>put(had, {1, 2}),</input>
@@ -1392,40 +1670,40 @@ true
[mary,had,a,little,lamb]</pre>
</desc>
</func>
+
<func>
<name name="get_stacktrace" arity="0"/>
- <fsummary>Get the call stack back-trace of the last exception</fsummary>
+ <fsummary>Gets the call stack back-trace of the last exception.</fsummary>
<type name="stack_item"/>
<desc>
- <p>Get the call stack back-trace (<em>stacktrace</em>) of the last
- exception in the calling process as a list of
+ <p>Gets the call stack back-trace (<em>stacktrace</em>) of the
+ last exception in the calling process as a list of
<c>{<anno>Module</anno>,<anno>Function</anno>,<anno>Arity</anno>,<anno>Location</anno>}</c> tuples.
- The <c><anno>Arity</anno></c> field in the first tuple may be the argument
- list of that function call instead of an arity integer,
+ Field <c><anno>Arity</anno></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>If there has not been any exceptions in a process, the
stacktrace is <c>[]</c>. After a code change for the process,
- the stacktrace may also be reset to [].</p>
+ the stacktrace can also be reset to <c>[]</c>.</p>
<p>The stacktrace is the same data as the <c>catch</c> operator
returns, for example:</p>
<p><c>{'EXIT',{badarg,Stacktrace}} = catch abs(x)</c></p>
- <p><c><anno>Location</anno></c> is a (possibly empty) list of two-tuples that
- may indicate the location in the source code of the function.
- The first element is an atom that describes the type of
- information in the second element. Currently the following
- items may occur:</p>
+ <p><c><anno>Location</anno></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>
- <p>The second element of the tuple is a string (list of
- characters) representing the filename of the source file
- of the function.</p>
+ <item>The second element of the tuple is a string (list of
+ characters) representing the file name of the source file
+ of the function.
</item>
<tag><c>line</c></tag>
- <item>
- <p>The second element of the tuple is the line number
+ <item>The second element of the tuple is the line number
(an integer greater than zero) in the source file
- where the exception occurred or the function was called.</p>
+ where the exception occurred or the function was called.
</item>
</taglist>
<p>See also
@@ -1433,49 +1711,56 @@ true
<seealso marker="#error/2">erlang:error/2</seealso>.</p>
</desc>
</func>
+
<func>
<name name="group_leader" arity="0"/>
- <fsummary>Get the group leader for the calling process</fsummary>
+ <fsummary>Gets the group leader for the calling process.</fsummary>
<desc>
- <p>Returns the pid of the group leader for the process which
- evaluates the function.</p>
+ <p>Returns the process identifier of the group leader for the
+ process evaluating the function.</p>
<p>Every process is a member of some process group and all
- groups have a <em>group leader</em>. All IO from the group
+ groups have a <em>group leader</em>. All I/O from the group
is channeled to the group leader. When a new process is
spawned, it gets the same group leader as the spawning
process. Initially, at system start-up, <c>init</c> is both
its own group leader and the group leader of all processes.</p>
</desc>
</func>
+
<func>
<name name="group_leader" arity="2"/>
- <fsummary>Set the group leader for a process</fsummary>
+ <fsummary>Sets the group leader for a process.</fsummary>
<desc>
- <p>Sets the group leader of <c><anno>Pid</anno></c> to <c><anno>GroupLeader</anno></c>.
- Typically, this is used when a processes started from a
- certain shell should have another group leader than
+ <p>Sets the group leader of <c><anno>Pid</anno></c>
+ to <c><anno>GroupLeader</anno></c>.
+ Typically, this is used when a process started from a
+ certain shell is to have another group leader than
<c>init</c>.</p>
<p>See also
<seealso marker="#group_leader/0">group_leader/0</seealso>.</p>
</desc>
</func>
+
<func>
<name name="halt" arity="0"/>
- <fsummary>Halt the Erlang runtime system and indicate normal exit to the calling environment</fsummary>
+ <fsummary>Halts the Erlang runtime system and indicates normal exit to the calling environment.</fsummary>
<desc>
<p>The same as
<seealso marker="#halt/2"><c>halt(0, [])</c></seealso>.</p>
+ <p>Example:</p>
<pre>
> <input>halt().</input>
os_prompt% </pre>
</desc>
</func>
+
<func>
<name name="halt" arity="1"/>
- <fsummary>Halt the Erlang runtime system</fsummary>
+ <fsummary>Halts the Erlang runtime system.</fsummary>
<desc>
<p>The same as
<seealso marker="#halt/2"><c>halt(<anno>Status</anno>, [])</c></seealso>.</p>
+ <p>Example:</p>
<pre>
> <input>halt(17).</input>
os_prompt% <input>echo $?</input>
@@ -1483,178 +1768,189 @@ os_prompt% <input>echo $?</input>
os_prompt% </pre>
</desc>
</func>
+
<func>
<name name="halt" arity="2"/>
- <fsummary>Halt the Erlang runtime system</fsummary>
+ <fsummary>Halts the Erlang runtime system.</fsummary>
<desc>
<p><c><anno>Status</anno></c> must be a non-negative integer, a string,
or the atom <c>abort</c>.
Halts the Erlang runtime system. Has no return value.
- Depending on <c><anno>Status</anno></c>:
- </p>
+ Depending on <c><anno>Status</anno></c>, the following occurs:</p>
<taglist>
<tag>integer()</tag>
- <item>The runtime system exits with the integer value <c><anno>Status</anno></c>
- as status code to the calling environment (operating system).
+ <item>The runtime system exits with integer value
+ <c><anno>Status</anno></c>
+ as status code to the calling environment (OS).
</item>
<tag>string()</tag>
- <item>An erlang crash dump is produced with <c><anno>Status</anno></c> as slogan,
- and then the runtime system exits with status code <c>1</c>.
+ <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>.
</item>
<tag><c>abort</c></tag>
<item>
The runtime system aborts producing a core dump, if that is
- enabled in the operating system.
+ enabled in the OS.
</item>
</taglist>
- <p>Note that on many platforms, only the status codes 0-255 are
- supported by the operating system.
- </p>
- <p>For integer <c><anno>Status</anno></c> the Erlang runtime system closes all ports
- and allows async threads to finish their operations before exiting.
- To exit without such flushing use
- <c><anno>Option</anno></c> as <c>{flush,false}</c>.
- </p>
- <p>For statuses <c>string()</c> and <c>abort</c> the <c>flush</c>
- option is ignored and flushing is <em>not</em> done.
- </p>
+ <note><p>On many platforms, the OS supports only status
+ codes 0-255. A too large status code will be truncated by clearing
+ the high bits.</p></note>
+ <p>For integer <c><anno>Status</anno></c>, the Erlang runtime system
+ closes all ports and allows async threads to finish their
+ operations before exiting. To exit without such flushing, use
+ <c><anno>Option</anno></c> as <c>{flush,false}</c>.</p>
+ <p>For statuses <c>string()</c> and <c>abort</c>, option
+ <c>flush</c> is ignored and flushing is <em>not</em> done.</p>
</desc>
</func>
+
<func>
<name name="hash" arity="2"/>
- <fsummary>Hash function (deprecated)</fsummary>
+ <fsummary>Hash function (deprecated).</fsummary>
<desc>
<p>Returns a hash value for <c><anno>Term</anno></c> within the range
- <c>1..<anno>Range</anno></c>. The allowed range is 1..2^27-1.</p>
+ <c>1..<anno>Range</anno></c>. The maximum range is 1..2^27-1.</p>
<warning>
- <p>This BIF is deprecated as the hash value may differ on
- different architectures. Also the hash values for integer
- terms larger than 2^27 as well as large binaries are very
+ <p>This BIF is deprecated, as the hash value can differ on
+ different architectures. The hash values for integer
+ terms higher than 2^27 and large binaries are
poor. The BIF is retained for backward compatibility
- reasons (it may have been used to hash records into a file),
- but all new code should use one of the BIFs
+ reasons (it can have been used to hash records into a file),
+ but all new code is to use one of the BIFs
<c>erlang:phash/2</c> or <c>erlang:phash2/1,2</c> instead.</p>
</warning>
</desc>
</func>
+
<func>
<name name="hd" arity="1"/>
- <fsummary>Head of a list</fsummary>
+ <fsummary>Head of a list.</fsummary>
<desc>
- <p>Returns the head of <c><anno>List</anno></c>, that is, the first element.</p>
+ <p>Returns the head of <c><anno>List</anno></c>, that is,
+ the first element, for example:</p>
<pre>
> <input>hd([1,2,3,4,5]).</input>
1</pre>
<p>Allowed in guard tests.</p>
- <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty list [].</p>
+ <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty
+ list <c>[]</c>.</p>
</desc>
</func>
+
<func>
<name name="hibernate" arity="3"/>
- <fsummary>Hibernate a process until a message is sent to it</fsummary>
+ <fsummary>Hibernates a process until a message is sent to it.</fsummary>
<desc>
<p>Puts the calling process into a wait state where its memory
- allocation has been reduced as much as possible, which is
+ allocation has been reduced as much as possible. This is
useful if the process does not expect to receive any messages
- in the near future.</p>
- <p>The process will be awaken when a message is sent to it, and
- control will resume in <c><anno>Module</anno>:<anno>Function</anno></c> with
- the arguments given by <c><anno>Args</anno></c> with the call stack
- emptied, meaning that the process will terminate when that
- function returns. Thus <c>erlang:hibernate/3</c> will never
- return to its caller.</p>
+ soon.</p>
+ <p>The process is awaken when a message is sent to it, and control
+ resumes in <c><anno>Module</anno>:<anno>Function</anno></c> with
+ the arguments given by <c><anno>Args</anno></c> with the call
+ stack emptied, meaning that the process terminates when that
+ function returns. Thus <c>erlang:hibernate/3</c> never
+ returns to its caller.</p>
<p>If the process has any message in its message queue,
- the process will be awaken immediately in the same way as
- described above.</p>
+ the process is awakened immediately in the same way as
+ described earlier.</p>
<p>In more technical terms, what <c>erlang:hibernate/3</c> does
- is the following. It discards the call stack for the process.
- Then it garbage collects the process. After the garbage
- collection, all live data is in one continuous heap. The heap
+ is the following. It discards the call stack for the process,
+ and then garbage collects the process. After this,
+ all live data is in one continuous heap. The heap
is then shrunken to the exact same size as the live data
- which it holds (even if that size is less than the minimum
+ that it holds (even if that size is less than the minimum
heap size for the process).</p>
<p>If the size of the live data in the process is less than
the minimum heap size, the first garbage collection occurring
- after the process has been awaken will ensure that the heap
+ after the process is awakened ensures that the heap
size is changed to a size not smaller than the minimum heap
size.</p>
- <p>Note that emptying the call stack means that any surrounding
- <c>catch</c> is removed and has to be re-inserted after
+ <p>Notice that emptying the call stack means that any surrounding
+ <c>catch</c> is removed and must be reinserted after
hibernation. One effect of this is that processes started
using <c>proc_lib</c> (also indirectly, such as
- <c>gen_server</c> processes), should use
+ <c>gen_server</c> processes), are to use
<seealso marker="stdlib:proc_lib#hibernate/3">proc_lib:hibernate/3</seealso>
- instead to ensure that the exception handler continues to work
+ instead, to ensure that the exception handler continues to work
when the process wakes up.</p>
</desc>
</func>
<func>
<name name="insert_element" arity="3"/>
- <fsummary>Insert an element at index in a tuple</fsummary>
+ <fsummary>Inserts an element at index in a tuple.</fsummary>
<type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>) + 1</type_desc>
<desc>
- <p>
- Returns a new tuple with element <c><anno>Term</anno></c> insert at position
- <c><anno>Index</anno></c> in tuple <c><anno>Tuple1</anno></c>.
- All elements from position <c><anno>Index</anno></c> and upwards are subsequently
- pushed one step higher in the new tuple <c><anno>Tuple2</anno></c>.
- </p>
+ <p>Returns a new tuple with element <c><anno>Term</anno></c>
+ inserted at position
+ <c><anno>Index</anno></c> in tuple <c><anno>Tuple1</anno></c>.
+ All elements from position <c><anno>Index</anno></c> and upwards are
+ pushed one step higher in the new tuple <c><anno>Tuple2</anno></c>.</p>
+ <p>Example:</p>
<pre>
> <input>erlang:insert_element(2, {one, two, three}, new).</input>
{one,new,two,three}</pre>
</desc>
</func>
+
<func>
<name name="integer_to_binary" arity="1"/>
- <fsummary>Text representation of an integer</fsummary>
+ <fsummary>Text representation of an integer.</fsummary>
<desc>
- <p>Returns a binary which corresponds to the text
- representation of <c><anno>Integer</anno></c>.</p>
+ <p>Returns a binary corresponding to the text
+ representation of <c><anno>Integer</anno></c>, for example:</p>
<pre>
> <input>integer_to_binary(77).</input>
&lt;&lt;"77">></pre>
</desc>
</func>
+
<func>
<name name="integer_to_binary" arity="2"/>
- <fsummary>Text representation of an integer</fsummary>
+ <fsummary>Text representation of an integer.</fsummary>
<desc>
- <p>Returns a binary which corresponds to the text
- representation of <c><anno>Integer</anno></c> in base <c><anno>Base</anno></c>.</p>
+ <p>Returns a binary corresponding to the text
+ representation of <c><anno>Integer</anno></c> in base
+ <c><anno>Base</anno></c>, for example:</p>
<pre>
> <input>integer_to_binary(1023, 16).</input>
&lt;&lt;"3FF">></pre>
</desc>
</func>
+
<func>
<name name="integer_to_list" arity="1"/>
- <fsummary>Text representation of an integer</fsummary>
+ <fsummary>Text representation of an integer.</fsummary>
<desc>
- <p>Returns a string which corresponds to the text
- representation of <c><anno>Integer</anno></c>.</p>
+ <p>Returns a string corresponding to the text
+ representation of <c><anno>Integer</anno></c>, for example:</p>
<pre>
> <input>integer_to_list(77).</input>
"77"</pre>
</desc>
</func>
+
<func>
<name name="integer_to_list" arity="2"/>
- <fsummary>Text representation of an integer</fsummary>
+ <fsummary>Text representation of an integer.</fsummary>
<desc>
- <p>Returns a string which corresponds to the text
- representation of <c><anno>Integer</anno></c> in base <c><anno>Base</anno></c>.</p>
+ <p>Returns a string corresponding to the text
+ representation of <c><anno>Integer</anno></c> in base
+ <c><anno>Base</anno></c>, for example:</p>
<pre>
> <input>integer_to_list(1023, 16).</input>
"3FF"</pre>
</desc>
</func>
+
<func>
<name name="iolist_to_binary" arity="1"/>
- <fsummary>Convert an iolist to a binary</fsummary>
+ <fsummary>Converts an iolist to a binary.</fsummary>
<desc>
- <p>Returns a binary which is made from the integers and
- binaries in <c><anno>IoListOrBinary</anno></c>.</p>
+ <p>Returns a binary that is made from the integers and
+ binaries in <c><anno>IoListOrBinary</anno></c>, for example:</p>
<pre>
> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
&lt;&lt;1,2,3&gt;&gt;
@@ -1666,278 +1962,311 @@ os_prompt% </pre>
&lt;&lt;1,2,3,1,2,3,4,5,4,6&gt;&gt;</pre>
</desc>
</func>
+
<func>
<name name="iolist_size" arity="1"/>
- <fsummary>Size of an iolist</fsummary>
+ <fsummary>Size of an iolist.</fsummary>
<desc>
- <p>Returns an integer which is the size in bytes
- of the binary that would be the result of
- <c>iolist_to_binary(<anno>Item</anno>)</c>.</p>
+ <p>Returns an integer that is the size in bytes
+ of the binary that would be the result of
+ <c>iolist_to_binary(<anno>Item</anno>)</c>, for example:</p>
<pre>
> <input>iolist_size([1,2|&lt;&lt;3,4>>]).</input>
4</pre>
</desc>
</func>
+
<func>
<name name="is_alive" arity="0"/>
- <fsummary>Check whether the local node is alive</fsummary>
+ <fsummary>Checks whether the local node is alive.</fsummary>
<desc>
- <p>Returns <c>true</c> if the local node is alive; that is, if
- the node can be part of a distributed system. Otherwise, it
- returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if the local node is alive (that is, if
+ the node can be part of a distributed system), otherwise
+ <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="is_atom" arity="1"/>
- <fsummary>Check whether a term is an atom</fsummary>
+ <fsummary>Checks whether a term is an atom.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an atom;
- otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an atom,
+ otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_binary" arity="1"/>
- <fsummary>Check whether a term is a binary</fsummary>
+ <fsummary>Checks whether a term is a binary.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a binary;
- otherwise returns <c>false</c>.</p>
-
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a binary,
+ otherwise <c>false</c>.</p>
<p>A binary always contains a complete number of bytes.</p>
-
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_bitstring" arity="1"/>
- <fsummary>Check whether a term is a bitstring</fsummary>
+ <fsummary>Checks whether a term is a bitstring.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a bitstring (including a binary);
- otherwise returns <c>false</c>.</p>
-
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a
+ bitstring (including a binary), otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_boolean" arity="1"/>
- <fsummary>Check whether a term is a boolean</fsummary>
+ <fsummary>Checks whether a term is a boolean.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is
- either the atom <c>true</c> or the atom <c>false</c>
- (i.e. a boolean); otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is the
+ atom <c>true</c> or the atom <c>false</c> (that is, a boolean).
+ Otherwise returns <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_builtin" arity="3"/>
- <fsummary>Check if a function is a BIF implemented in C</fsummary>
+ <fsummary>Checks if a function is a BIF implemented in C.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Module</anno>:<anno>Function</anno>/<anno>Arity</anno></c> is
- a BIF implemented in C; otherwise returns <c>false</c>.
- This BIF is useful for builders of cross reference tools.</p>
+ <p>This BIF is useful for builders of cross-reference tools.</p>
+ <p>Returns <c>true</c> if
+ <c><anno>Module</anno>:<anno>Function</anno>/<anno>Arity</anno></c>
+ is a BIF implemented in C, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="is_float" arity="1"/>
- <fsummary>Check whether a term is a float</fsummary>
+ <fsummary>Checks whether a term is a float.</fsummary>
<desc>
<p>Returns <c>true</c> if <c><anno>Term</anno></c> is a floating point
- number; otherwise returns <c>false</c>.</p>
+ number, otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_function" arity="1"/>
- <fsummary>Check whether a term is a fun</fsummary>
+ <fsummary>Checks whether a term is a fun.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a fun; otherwise
- returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a fun, otherwise
+ <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_function" arity="2"/>
- <fsummary>Check whether a term is a fun with a given arity</fsummary>
+ <fsummary>Checks whether a term is a fun with a given arity.</fsummary>
<desc>
<p>Returns <c>true</c> if <c><anno>Term</anno></c> is a fun that can be
- applied with <c><anno>Arity</anno></c> number of arguments; otherwise
- returns <c>false</c>.</p>
+ applied with <c><anno>Arity</anno></c> number of arguments, otherwise
+ <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_integer" arity="1"/>
- <fsummary>Check whether a term is an integer</fsummary>
+ <fsummary>Checks whether a term is an integer.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer;
- otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer,
+ otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_list" arity="1"/>
- <fsummary>Check whether a term is a list</fsummary>
+ <fsummary>Checks whether a term is a list.</fsummary>
<desc>
<p>Returns <c>true</c> if <c><anno>Term</anno></c> is a list with
- zero or more elements; otherwise returns <c>false</c>.</p>
+ zero or more elements, otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_map" arity="1"/>
- <fsummary>Check whether a term is a map</fsummary>
+ <fsummary>Checks whether a term is a map.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a map;
- otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a map,
+ otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_number" arity="1"/>
- <fsummary>Check whether a term is a number</fsummary>
+ <fsummary>Checks whether a term is a number.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is either an integer or a
- floating point number; otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer or a
+ floating point number. Otherwise returns <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_pid" arity="1"/>
- <fsummary>Check whether a term is a pid</fsummary>
+ <fsummary>Checks whether a term is a process identifier.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a pid (process
- identifier); otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a process
+ identifier, otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_port" arity="1"/>
- <fsummary>Check whether a term is a port</fsummary>
+ <fsummary>Checks whether a term is a port.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a port identifier;
- otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a port identifier,
+ otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_process_alive" arity="1"/>
- <fsummary>Check whether a process is alive</fsummary>
+ <fsummary>Checks whether a process is alive.</fsummary>
<desc>
- <p>
- <c><anno>Pid</anno></c> must refer to a process at the local node.
- Returns <c>true</c> if the process exists and is alive, that
- is, is not exiting and has not exited. Otherwise, returns
+ <p><c><anno>Pid</anno></c> must refer to a process at the local node.</p>
+ <p>Returns <c>true</c> if the process exists and is alive, that
+ is, is not exiting and has not exited. Otherwise returns
<c>false</c>.
</p>
</desc>
</func>
+
<func>
<name name="is_record" arity="2"/>
- <fsummary>Check whether a term appears to be a record</fsummary>
+ <fsummary>Checks whether a term appears to be a record.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple and its first
- element is <c><anno>RecordTag</anno></c>. Otherwise, returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple and its
+ first element is <c><anno>RecordTag</anno></c>.
+ Otherwise returns <c>false</c>.</p>
<note>
<p>Normally the compiler treats calls to <c>is_record/2</c>
- specially. It emits code to verify that <c><anno>Term</anno></c> is a
- tuple, that its first element is <c><anno>RecordTag</anno></c>, and that
- the size is correct. However, if the <c><anno>RecordTag</anno></c> is
- not a literal atom, the <c>is_record/2</c> BIF will be
- called instead and the size of the tuple will not be
- verified.</p>
+ specially. It emits code to verify that <c><anno>Term</anno></c>
+ is a tuple, that its first element is
+ <c><anno>RecordTag</anno></c>, and that the
+ size is correct. However, if <c><anno>RecordTag</anno></c> is
+ not a literal atom, the BIF <c>is_record/2</c> is called
+ instead and the size of the tuple is not verified.</p>
</note>
- <p>Allowed in guard tests, if <c><anno>RecordTag</anno></c> is a literal
- atom.</p>
+ <p>Allowed in guard tests, if <c><anno>RecordTag</anno></c> is
+ a literal atom.</p>
</desc>
</func>
+
<func>
<name name="is_record" arity="3"/>
- <fsummary>Check whether a term appears to be a record</fsummary>
- <desc>
- <p><c><anno>RecordTag</anno></c> must be an atom. Returns <c>true</c> if
- <c><anno>Term</anno></c> is a tuple, its first element is <c><anno>RecordTag</anno></c>,
- and its size is <c><anno>Size</anno></c>. Otherwise, returns <c>false</c>.</p>
- <p>Allowed in guard tests, provided that <c><anno>RecordTag</anno></c> is
+ <fsummary>Checks whether a term appears to be a record.</fsummary>
+ <desc>
+ <p><c><anno>RecordTag</anno></c> must be an atom.</p>
+ <p>Returns <c>true</c> if
+ <c><anno>Term</anno></c> is a tuple,
+ its first element is <c><anno>RecordTag</anno></c>,
+ and its size is <c><anno>Size</anno></c>.
+ Otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests if <c><anno>RecordTag</anno></c> is
a literal atom and <c>Size</c> is a literal integer.</p>
<note>
- <p>This BIF is documented for completeness. In most cases
- <c>is_record/2</c> should be used.</p>
+ <p>This BIF is documented for completeness. Usually
+ <c>is_record/2</c> is to be used.</p>
</note>
</desc>
</func>
+
<func>
<name name="is_reference" arity="1"/>
- <fsummary>Check whether a term is a reference</fsummary>
+ <fsummary>Checks whether a term is a reference.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a reference;
- otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a reference,
+ otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="is_tuple" arity="1"/>
- <fsummary>Check whether a term is a tuple</fsummary>
+ <fsummary>Checks whether a term is a tuple.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple;
- otherwise returns <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple,
+ otherwise <c>false</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="length" arity="1"/>
- <fsummary>Length of a list</fsummary>
+ <fsummary>Length of a list.</fsummary>
<desc>
- <p>Returns the length of <c><anno>List</anno></c>.</p>
+ <p>Returns the length of <c><anno>List</anno></c>, for example:</p>
<pre>
> <input>length([1,2,3,4,5,6,7,8,9]).</input>
9</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="link" arity="1"/>
- <fsummary>Create a link to another process (or port)</fsummary>
+ <fsummary>Creates a link to another process (or port).</fsummary>
<desc>
<p>Creates a link between the calling process and another
- process (or port) <c><anno>PidOrPort</anno></c>, if there is not such a link
+ process (or port) <c><anno>PidOrPort</anno></c>, if there is
+ not such a link
already. If a process attempts to create a link to itself,
nothing is done. Returns <c>true</c>.</p>
- <p>If <c><anno>PidOrPort</anno></c> does not exist, the behavior of the BIF depends
- on if the calling process is trapping exits or not (see
+ <p>If <c><anno>PidOrPort</anno></c> does not exist, the behavior
+ of the BIF
+ depends on if the calling process is trapping exits or not (see
<seealso marker="#process_flag/2">process_flag/2</seealso>):</p>
<list type="bulleted">
<item>If the calling process is not trapping exits, and
- checking <c><anno>PidOrPort</anno></c> is cheap -- that is, if <c><anno>PidOrPort</anno></c> is
- local -- <c>link/1</c> fails with reason <c>noproc</c>.</item>
+ checking <c><anno>PidOrPort</anno></c> is cheap
+ (that is, if <c><anno>PidOrPort</anno></c>
+ is local), <c>link/1</c> fails with reason <c>noproc</c>.</item>
<item>Otherwise, if the calling process is trapping exits,
- and/or <c><anno>PidOrPort</anno></c> is remote, <c>link/1</c> returns
- <c>true</c>, but an exit signal with reason <c>noproc</c>
+ and/or <c><anno>PidOrPort</anno></c> is remote, <c>link/1</c>
+ returns <c>true</c>, but an exit signal with reason <c>noproc</c>
is sent to the calling process.</item>
</list>
</desc>
</func>
+
<func>
<name name="list_to_atom" arity="1"/>
- <fsummary>Convert from text representation to an atom</fsummary>
- <desc>
- <p>Returns the atom whose text representation is <c><anno>String</anno></c>.</p>
- <p><c><anno>String</anno></c> may only contain ISO-latin-1
- characters (i.e. numbers below 256) as the current
- implementation does not allow unicode characters >= 256 in
- atoms. For more information on Unicode support in atoms
- see <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8 encoded atoms</seealso>
- in the chapter about the external term format in the ERTS User's Guide.</p>
+ <fsummary>Converts from text representation to an atom.</fsummary>
+ <desc>
+ <p>Returns the atom whose text representation is
+ <c><anno>String</anno></c>.</p>
+ <p><c><anno>String</anno></c> can only contain ISO-latin-1
+ characters (that is,
+ numbers less than 256) as the implementation does not
+ allow unicode characters equal to or above 256 in atoms.
+ For more information on Unicode support in atoms, see
+ <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8
+ encoded atoms</seealso>
+ in Section "External Term Format" in the User's Guide.</p>
+ <p>Example:</p>
<pre>
> <input>list_to_atom("Erlang").</input>
'Erlang'</pre>
</desc>
</func>
+
<func>
<name name="list_to_binary" arity="1"/>
- <fsummary>Convert a list to a binary</fsummary>
+ <fsummary>Converts a list to a binary.</fsummary>
<desc>
- <p>Returns a binary which is made from the integers and
- binaries in <c><anno>IoList</anno></c>.</p>
+ <p>Returns a binary that is made from the integers and
+ binaries in <c><anno>IoList</anno></c>, for example:</p>
<pre>
> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
&lt;&lt;1,2,3&gt;&gt;
@@ -1949,40 +2278,46 @@ os_prompt% </pre>
&lt;&lt;1,2,3,1,2,3,4,5,4,6&gt;&gt;</pre>
</desc>
</func>
+
<func>
<name name="list_to_bitstring" arity="1"/>
+ <fsummary>Converts a list to a bitstring.</fsummary>
<type name="bitstring_list"/>
- <fsummary>Convert a list to a bitstring</fsummary>
<desc>
- <p>Returns a bitstring which is made from the integers and
- bitstrings in <c><anno>BitstringList</anno></c>. (The last tail in <c><anno>BitstringList</anno></c>
- is allowed to be a bitstring.)</p>
+ <p>Returns a bitstring that is made from the integers and
+ bitstrings in <c><anno>BitstringList</anno></c>. (The last tail in
+ <c><anno>BitstringList</anno></c> is allowed to be a bitstring.)</p>
+ <p>Example:</p>
<pre>
> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
&lt;&lt;1,2,3&gt;&gt;
> <input>Bin2 = &lt;&lt;4,5&gt;&gt;.</input>
&lt;&lt;4,5&gt;&gt;
-> <input>Bin3 = &lt;&lt;6,7:4,&gt;&gt;.</input>
-&lt;&lt;6&gt;&gt;
+> <input>Bin3 = &lt;&lt;6,7:4&gt;&gt;.</input>
+&lt;&lt;6,7:4&gt;&gt;
> <input>list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
-&lt;&lt;1,2,3,1,2,3,4,5,4,6,7:46&gt;&gt;</pre>
+&lt;&lt;1,2,3,1,2,3,4,5,4,6,7:4&gt;&gt;</pre>
</desc>
</func>
+
<func>
<name name="list_to_existing_atom" arity="1"/>
- <fsummary>Convert from text representation to an atom</fsummary>
+ <fsummary>Converts from text representation to an atom.</fsummary>
<desc>
- <p>Returns the atom whose text representation is <c><anno>String</anno></c>,
+ <p>Returns the atom whose text representation is
+ <c><anno>String</anno></c>,
but only if there already exists such atom.</p>
<p>Failure: <c>badarg</c> if there does not already exist an atom
whose text representation is <c><anno>String</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="list_to_float" arity="1"/>
- <fsummary>Convert from text representation to a float</fsummary>
+ <fsummary>Converts from text representation to a float.</fsummary>
<desc>
- <p>Returns the float whose text representation is <c><anno>String</anno></c>.</p>
+ <p>Returns the float whose text representation is
+ <c><anno>String</anno></c>, for example:</p>
<pre>
> <input>list_to_float("2.2017764e+0").</input>
2.2017764</pre>
@@ -1990,12 +2325,13 @@ os_prompt% </pre>
representation of a float.</p>
</desc>
</func>
+
<func>
<name name="list_to_integer" arity="1"/>
- <fsummary>Convert from text representation to an integer</fsummary>
+ <fsummary>Converts from text representation to an integer.</fsummary>
<desc>
<p>Returns an integer whose text representation is
- <c><anno>String</anno></c>.</p>
+ <c><anno>String</anno></c>, for example:</p>
<pre>
> <input>list_to_integer("123").</input>
123</pre>
@@ -2003,12 +2339,14 @@ os_prompt% </pre>
representation of an integer.</p>
</desc>
</func>
+
<func>
<name name="list_to_integer" arity="2"/>
- <fsummary>Convert from text representation to an integer</fsummary>
+ <fsummary>Converts from text representation to an integer.</fsummary>
<desc>
<p>Returns an integer whose text representation in base
- <c><anno>Base</anno></c> is <c><anno>String</anno></c>.</p>
+ <c><anno>Base</anno></c> is <c><anno>String</anno></c>,
+ for example:</p>
<pre>
> <input>list_to_integer("3FF", 16).</input>
1023</pre>
@@ -2016,47 +2354,52 @@ os_prompt% </pre>
representation of an integer.</p>
</desc>
</func>
+
<func>
<name name="list_to_pid" arity="1"/>
- <fsummary>Convert from text representation to a pid</fsummary>
+ <fsummary>Converts from text representation to a pid.</fsummary>
<desc>
- <p>Returns a pid whose text representation is <c><anno>String</anno></c>.</p>
- <warning>
- <p>This BIF is intended for debugging and for use in
- the Erlang operating system. It should not be used in
- application programs.</p>
- </warning>
+ <p>Returns a process identifier whose text representation is a
+ <c><anno>String</anno></c>, for example:</p>
<pre>
> <input>list_to_pid("&lt;0.4.1>").</input>
&lt;0.4.1></pre>
<p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad
- representation of a pid.</p>
+ representation of a process identifier.</p>
+ <warning>
+ <p>This BIF is intended for debugging and is not to be used
+ in application programs.</p>
+ </warning>
</desc>
</func>
+
<func>
<name name="list_to_tuple" arity="1"/>
- <fsummary>Convert a list to a tuple</fsummary>
+ <fsummary>Converts a list to a tuple.</fsummary>
<desc>
- <p>Returns a tuple which corresponds to <c><anno>List</anno></c>. <c><anno>List</anno></c>
- can contain any Erlang terms.</p>
+ <p>Returns a tuple corresponding to <c><anno>List</anno></c>,
+ for example</p>
<pre>
> <input>list_to_tuple([share, ['Ericsson_B', 163]]).</input>
{share, ['Ericsson_B', 163]}</pre>
+ <p><c><anno>List</anno></c> can contain any Erlang terms.</p>
</desc>
</func>
+
<func>
<name name="load_module" arity="2"/>
- <fsummary>Load object code for a module</fsummary>
+ <fsummary>Loads object code for a module.</fsummary>
<desc>
- <p>If <c><anno>Binary</anno></c> contains the object code for the module
- <c><anno>Module</anno></c>, this BIF loads that object code. Also, if
- the code for the module <c><anno>Module</anno></c> already exists, all
+ <p>If <c><anno>Binary</anno></c> contains the object code for module
+ <c><anno>Module</anno></c>, this BIF loads that object code. If
+ the code for module <c><anno>Module</anno></c> already exists, all
export references are replaced so they point to the newly
loaded code. The previously loaded code is kept in the system
- as old code, as there may still be processes which are
- executing that code. It returns either
- <c>{module, <anno>Module</anno>}</c>, or <c>{error, <anno>Reason</anno>}</c> if loading
- fails. <c><anno>Reason</anno></c> is one of the following:</p>
+ as old code, as there can still be processes executing
+ that code.</p>
+ <p>Returns either <c>{module, <anno>Module</anno>}</c>, or
+ <c>{error, <anno>Reason</anno>}</c> if loading fails.
+ <c><anno>Reason</anno></c> is any of the following:</p>
<taglist>
<tag><c>badfile</c></tag>
<item>
@@ -2066,118 +2409,122 @@ os_prompt% </pre>
</item>
<tag><c>not_purged</c></tag>
<item>
- <p><c><anno>Binary</anno></c> contains a module which cannot be loaded
- because old code for this module already exists.</p>
+ <p><c><anno>Binary</anno></c> contains a module that cannot be
+ loaded because old code for this module already exists.</p>
</item>
</taglist>
<warning>
<p>This BIF is intended for the code server (see
- <seealso marker="kernel:code">code(3)</seealso>) and should not be
- used elsewhere.</p>
+ <seealso marker="kernel:code">code(3)</seealso>)
+ and is not to be used elsewhere.</p>
</warning>
</desc>
</func>
+
<func>
<name name="load_nif" arity="2"/>
- <fsummary>Load NIF library</fsummary>
+ <fsummary>Loads NIF library.</fsummary>
<desc>
<note>
- <p>In releases older than OTP R14B, NIFs were an
- experimental feature. Versions of OTP older than R14B might
+ <p>Before OTP R14B, NIFs were an
+ experimental feature. Versions before OTP R14B can
have different and possibly incompatible NIF semantics and
- interfaces. For example, in R13B03 the return value on
- failure was
- <c>{error,Reason,Text}</c>.</p>
+ interfaces. For example, in OTP R13B03 the return value on
+ failure was <c>{error,Reason,Text}</c>.</p>
</note>
<p>Loads and links a dynamic library containing native
- implemented functions (NIFs) for a module. <c><anno>Path</anno></c> is a
- file path to the sharable object/dynamic library file minus
- the OS-dependent file extension (.so for Unix and .dll for
- Windows). See <seealso marker="erl_nif">erl_nif</seealso>
- on how to implement a NIF library.</p>
- <p><c><anno>LoadInfo</anno></c> can be any term. It will be passed on to
+ implemented functions (NIFs) for a module. <c><anno>Path</anno></c>
+ is a file path to the shareable object/dynamic library file minus
+ the OS-dependent file extension (<c>.so</c> for Unix and
+ <c>.dll</c> for Windows. For information on how to
+ implement a NIF library, see
+ <seealso marker="erl_nif">erl_nif</seealso>.</p>
+ <p><c><anno>LoadInfo</anno></c> can be any term. It is passed on to
the library as part of the initialization. A good practice is
to include a module version number to support future code
upgrade scenarios.</p>
<p>The call to <c>load_nif/2</c> must be made
<em>directly</em> from the Erlang code of the module that the
- NIF library belongs to.</p>
- <p>It returns either <c>ok</c>, or <c>{error,{<anno>Reason</anno>,Text}}</c>
- if loading fails. <c><anno>Reason</anno></c> is one of the atoms below,
- while <c><anno>Text</anno></c> is a human readable string that may give
- some more information about the failure.</p>
+ NIF library belongs to. It returns either <c>ok</c>, or
+ <c>{error,{<anno>Reason</anno>,Text}}</c> if loading fails.
+ <c><anno>Reason</anno></c> is one of the following atoms
+ while <c><anno>Text</anno></c> is a human readable string that
+ can give more information about the failure:</p>
<taglist>
<tag><c>load_failed</c></tag>
- <item>
- <p>The OS failed to load the NIF library.</p>
+ <item>The OS failed to load the NIF library.
</item>
<tag><c>bad_lib</c></tag>
- <item>
- <p>The library did not fulfil the requirements as a NIF
- library of the calling module.</p>
+ <item>The library did not fulfill the requirements as a NIF
+ library of the calling module.
</item>
<tag><c>load | reload | upgrade</c></tag>
- <item>
- <p>The corresponding library callback was not successful.</p>
+ <item>The corresponding library callback was unsuccessful.
</item>
<tag><c>old_code</c></tag>
- <item>
- <p>The call to <c>load_nif/2</c> was made from the old
- code of a module that has been upgraded. This is not
- allowed.</p>
+ <item>The call to <c>load_nif/2</c> was made from the old
+ code of a module that has been upgraded; this is not
+ allowed.
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="loaded" arity="0"/>
- <fsummary>List of all loaded modules</fsummary>
+ <fsummary>Lists all loaded modules.</fsummary>
<desc>
- <p>Returns a list of all loaded Erlang modules (current and/or
+ <p>Returns a list of all loaded Erlang modules (current and
old code), including preloaded modules.</p>
<p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
</desc>
</func>
+
<func>
<name name="localtime" arity="0"/>
- <fsummary>Current local date and time</fsummary>
+ <fsummary>Current local date and time.</fsummary>
<desc>
- <p>Returns the current local date and time
- <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c>.</p>
- <p>The time zone and daylight saving time correction depend
- on the underlying OS.</p>
+ <p>Returns the current local date and time,
+ <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c>,
+ for example:</p>
<pre>
> <input>erlang:localtime().</input>
{{1996,11,6},{14,45,17}}</pre>
+ <p>The time zone and Daylight Saving Time correction depend
+ on the underlying OS.</p>
</desc>
</func>
+
<func>
<name name="localtime_to_universaltime" arity="1"/>
- <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
+ <fsummary>Converts from local to Universal Time Coordinated (UTC) date and time.</fsummary>
<desc>
<p>Converts local date and time to Universal Time Coordinated
- (UTC), if this is supported by the underlying OS. Otherwise,
- no conversion is done and <c><anno>Localtime</anno></c> is returned.</p>
+ (UTC), if supported by the underlying OS. Otherwise
+ no conversion is done and <c><anno>Localtime</anno></c>
+ is returned.</p>
+ <p>Example:</p>
<pre>
> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).</input>
{{1996,11,6},{13,45,17}}</pre>
- <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> does not denote
- a valid date and time.</p>
+ <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> denotes an
+ invalid date and time.</p>
</desc>
</func>
+
<func>
<name name="localtime_to_universaltime" arity="2"/>
- <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
+ <fsummary>Converts from local to Universal Time Coordinated (UTC) date and time.</fsummary>
<desc>
<p>Converts local date and time to Universal Time Coordinated
- (UTC) just like <c>erlang:localtime_to_universaltime/1</c>,
- but the caller decides if daylight saving time is active or
- not.</p>
- <p>If <c><anno>IsDst</anno> == true</c> the <c><anno>Localtime</anno></c> is during
- daylight saving time, if <c><anno>IsDst</anno> == false</c> it is not,
- and if <c><anno>IsDst</anno> == undefined</c> the underlying OS may
+ (UTC) as <c>erlang:localtime_to_universaltime/1</c>,
+ but the caller decides if Daylight Saving Time is active.</p>
+ <p>If <c><anno>IsDst</anno> == true</c>, <c><anno>Localtime</anno></c> is
+ during Daylight Saving Time, if <c><anno>IsDst</anno> == false</c> it is
+ not. If <c><anno>IsDst</anno> == undefined</c>, the underlying OS can
guess, which is the same as calling
<c>erlang:localtime_to_universaltime(<anno>Localtime</anno>)</c>.</p>
+ <p>Examples:</p>
<pre>
> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).</input>
{{1996,11,6},{12,45,17}}
@@ -2185,216 +2532,227 @@ os_prompt% </pre>
{{1996,11,6},{13,45,17}}
> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).</input>
{{1996,11,6},{13,45,17}}</pre>
- <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> does not denote
- a valid date and time.</p>
+ <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> denotes an
+ invalid date and time.</p>
</desc>
</func>
+
<func>
<name name="make_ref" arity="0"/>
- <fsummary>Return an almost unique reference</fsummary>
+ <fsummary>Returns a unique reference.</fsummary>
<desc>
- <p>Returns an almost unique reference.</p>
- <p>The returned reference will re-occur after approximately 2^82
- calls; therefore it is unique enough for practical purposes.</p>
- <pre>
-> <input>make_ref().</input>
-#Ref&lt;0.0.0.135></pre>
+ <p>Returns a <seealso marker="doc/efficiency_guide:advanced#unique_references">unique
+ reference</seealso>. The reference is unique among
+ connected nodes.</p>
+ <warning><p>Known issue: When a node is restarted multiple
+ times with the same node name, references created
+ on a newer node can be mistaken for a reference
+ created on an older node with the same node name.</p></warning>
</desc>
</func>
+
<func>
<name name="make_tuple" arity="2"/>
- <fsummary>Create a new tuple of a given arity</fsummary>
+ <fsummary>Creates a new tuple of a given arity.</fsummary>
<desc>
- <p>Returns a new tuple of the given <c><anno>Arity</anno></c>, where all
- elements are <c><anno>InitialValue</anno></c>.</p>
+ <p>Creates a new tuple of the given <c><anno>Arity</anno></c>, where all
+ elements are <c><anno>InitialValue</anno></c>, for example:</p>
<pre>
> <input>erlang:make_tuple(4, []).</input>
{[],[],[],[]}</pre>
</desc>
</func>
+
<func>
<name name="make_tuple" arity="3"/>
- <fsummary>Create a new tuple with given arity and contents</fsummary>
- <desc>
- <p><c>erlang:make_tuple</c> first creates a tuple of size <c><anno>Arity</anno></c>
- where each element has the value <c><anno>DefaultValue</anno></c>. It then fills
- in values from <c><anno>InitList</anno></c>. Each list element in <c><anno>InitList</anno></c>
- must be a two-tuple where the first element is a position in the
- newly created tuple and the second element is any term. If a position
- occurs more than once in the list, the term corresponding to
- last occurrence will be used.</p>
+ <fsummary>Creates a new tuple with given arity and contents.</fsummary>
+ <desc>
+ <p>Creates a tuple of size <c><anno>Arity</anno></c>, where each element
+ has value <c><anno>DefaultValue</anno></c>, and then fills in
+ values from <c><anno>InitList</anno></c>.
+ Each list element in <c><anno>InitList</anno></c>
+ must be a two-tuple, where the first element is a position in the
+ newly created tuple and the second element is any term. If a
+ position occurs more than once in the list, the term corresponding
+ to the last occurrence is used.</p>
+ <p>Example:</p>
<pre>
> <input>erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).</input>
{{[],aa,[],[],zz}</pre>
</desc>
</func>
+
<func>
<name name="map_size" arity="1"/>
- <fsummary>Return the size of a map</fsummary>
+ <fsummary>Returns the size of a map.</fsummary>
<desc>
- <p>Returns an integer which is the number of key-value pairs in <c><anno>Map</anno></c>.</p>
+ <p>Returns an integer, which is the number of key-value pairs
+ in <c><anno>Map</anno></c>, for example:</p>
<pre>
> <input>map_size(#{a=>1, b=>2, c=>3}).</input>
3</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="max" arity="2"/>
- <fsummary>Return the largest of two term</fsummary>
+ <fsummary>Returns the largest of two terms.</fsummary>
<desc>
- <p>Return the largest of <c><anno>Term1</anno></c> and <c><anno>Term2</anno></c>;
- if the terms compare equal, <c><anno>Term1</anno></c> will be returned.</p>
+ <p>Returns the largest of <c><anno>Term1</anno></c> and
+ <c><anno>Term2</anno></c>.
+ If the terms are equal, <c><anno>Term1</anno></c> is returned.</p>
</desc>
</func>
+
<func>
<name name="md5" arity="1"/>
- <fsummary>Compute an MD5 message digest</fsummary>
+ <fsummary>Computes an MD5 message digest.</fsummary>
<desc>
- <p>Computes an <c>MD5</c> message digest from <c><anno>Data</anno></c>, where
- the length of the digest is 128 bits (16 bytes). <c><anno>Data</anno></c>
+ <p>Computes an MD5 message digest from <c><anno>Data</anno></c>, where
+ the length of the digest is 128 bits (16 bytes).
+ <c><anno>Data</anno></c>
is a binary or a list of small integers and binaries.</p>
- <p>See The MD5 Message Digest Algorithm (RFC 1321) for more
- information about MD5.</p>
- <warning><p>The MD5 Message Digest Algorithm is <em>not</em> considered
- safe for code-signing or software integrity purposes.</p></warning>
+ <p>For more information about MD5, see RFC 1321 - The
+ MD5 Message-Digest Algorithm.</p>
+ <warning><p>The MD5 Message-Digest Algorithm is <em>not</em> considered
+ safe for code-signing or software-integrity purposes.</p></warning>
</desc>
</func>
+
<func>
<name name="md5_final" arity="1"/>
- <fsummary>Finish the update of an MD5 context and return the computed MD5 message digest</fsummary>
+ <fsummary>Finishes the update of an MD5 context and returns the computed MD5 message digest.</fsummary>
<desc>
<p>Finishes the update of an MD5 <c><anno>Context</anno></c> and returns
the computed <c>MD5</c> message digest.</p>
</desc>
</func>
+
<func>
<name name="md5_init" arity="0"/>
- <fsummary>Create an MD5 context</fsummary>
+ <fsummary>Creates an MD5 context.</fsummary>
<desc>
<p>Creates an MD5 context, to be used in subsequent calls to
<c>md5_update/2</c>.</p>
</desc>
</func>
+
<func>
<name name="md5_update" arity="2"/>
- <fsummary>Update an MD5 context with data, and return a new context</fsummary>
+ <fsummary>Updates an MD5 context with data and returns a new context.</fsummary>
<desc>
- <p>Updates an MD5 <c><anno>Context</anno></c> with <c><anno>Data</anno></c>, and returns
- a <c><anno>NewContext</anno></c>.</p>
+ <p>Updates an MD5 <c><anno>Context</anno></c> with
+ <c><anno>Data</anno></c> and returns a
+ <c><anno>NewContext</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="memory" arity="0"/>
+ <fsummary>Information about dynamically allocated memory.</fsummary>
<type name="memory_type"/>
- <fsummary>Information about dynamically allocated memory</fsummary>
- <desc>
- <p>Returns a list containing information about memory
- dynamically allocated by the Erlang emulator. Each element of
- the list is a tuple <c>{Type, Size}</c>. The first element
- <c><anno>Type</anno></c>is an atom describing memory type. The second
- element <c><anno>Size</anno></c>is memory size in bytes. A description of
- each memory type follows:</p>
+ <desc>
+ <p>Returns a list with information about memory
+ dynamically allocated by the Erlang emulator. Each list
+ element is a tuple <c>{Type, Size}</c>. The first element
+ <c><anno>Type</anno></c> is an atom describing memory type. The second
+ element <c><anno>Size</anno></c> is the memory size in bytes.</p>
+ <p>The memory types are as follows:</p>
<taglist>
<tag><c>total</c></tag>
<item>
- <p>The total amount of memory currently allocated, which is
- the same as the sum of memory size for <c>processes</c>
+ <p>The total amount of memory currently allocated. This is
+ the same as the sum of the memory size for <c>processes</c>
and <c>system</c>.</p>
</item>
<tag><c>processes</c></tag>
<item>
- <p>The total amount of memory currently allocated by
+ <p>The total amount of memory currently allocated for
the Erlang processes.</p>
</item>
<tag><c>processes_used</c></tag>
<item>
<p>The total amount of memory currently used by the Erlang
- processes.</p>
- <p>This memory is part of the memory presented as
+ processes. This is part of the memory presented as
<c>processes</c> memory.</p>
</item>
<tag><c>system</c></tag>
<item>
- <p>The total amount of memory currently allocated by
+ <p>The total amount of memory currently allocated for
the emulator that is not directly related to any Erlang
- process.</p>
- <p>Memory presented as <c>processes</c> is not included in
- this memory.</p>
+ process. Memory presented as <c>processes</c> is not
+ included in this memory.</p>
</item>
<tag><c>atom</c></tag>
<item>
- <p>The total amount of memory currently allocated for atoms.</p>
- <p>This memory is part of the memory presented as
+ <p>The total amount of memory currently allocated for atoms.
+ This memory is part of the memory presented as
<c>system</c> memory.</p>
</item>
<tag><c>atom_used</c></tag>
<item>
- <p>The total amount of memory currently used for atoms.</p>
- <p>This memory is part of the memory presented as
+ <p>The total amount of memory currently used for atoms.
+ This memory is part of the memory presented as
<c>atom</c> memory.</p>
</item>
<tag><c>binary</c></tag>
<item>
<p>The total amount of memory currently allocated for
- binaries.</p>
- <p>This memory is part of the memory presented as
- <c>system</c> memory.</p>
+ binaries. This memory is part of the memory presented
+ as <c>system</c> memory.</p>
</item>
<tag><c>code</c></tag>
<item>
<p>The total amount of memory currently allocated for
- Erlang code.</p>
- <p>This memory is part of the memory presented as
- <c>system</c> memory.</p>
+ Erlang code. This memory is part of the memory presented
+ as <c>system</c> memory.</p>
</item>
<tag><c>ets</c></tag>
<item>
<p>The total amount of memory currently allocated for ets
- tables.</p>
- <p>This memory is part of the memory presented as
+ tables. This memory is part of the memory presented as
<c>system</c> memory.</p>
</item>
<tag><c>low</c></tag>
<item>
- <p>Only on 64-bit halfword emulator.</p>
- <p>The total amount of memory allocated in low memory areas
- that are restricted to less than 4 Gb even though
- the system may have more physical memory.</p>
- <p>May be removed in future releases of halfword emulator.</p>
+ <p>Only on 64-bit halfword emulator.
+ The total amount of memory allocated in low memory areas
+ that are restricted to less than 4 GB, although
+ the system can have more memory.</p>
+ <p>Can be removed in a future release of the halfword
+ emulator.</p>
</item>
<tag><c>maximum</c></tag>
<item>
<p>The maximum total amount of memory allocated since
- the emulator was started.</p>
- <p>This tuple is only present when the emulator is run with
- instrumentation.</p>
+ the emulator was started. This tuple is only present
+ when the emulator is run with instrumentation.</p>
<p>For information on how to run the emulator with
- instrumentation see
+ instrumentation, see
<seealso marker="tools:instrument">instrument(3)</seealso>
and/or <seealso marker="erts:erl">erl(1)</seealso>.</p>
</item>
</taglist>
<note>
<p>The <c>system</c> value is not complete. Some allocated
- memory that should be part of the <c>system</c> value are
- not.</p>
+ memory that is to be part of this value is not.</p>
<p>When the emulator is run with instrumentation,
the <c>system</c> value is more accurate, but memory
- directly allocated by <c>malloc</c> (and friends) are still
+ directly allocated for <c>malloc</c> (and friends) is still
not part of the <c>system</c> value. Direct calls to
- <c>malloc</c> are only done from OS specific runtime
- libraries and perhaps from user implemented Erlang drivers
+ <c>malloc</c> are only done from OS-specific runtime
+ libraries and perhaps from user-implemented Erlang drivers
that do not use the memory allocation functions in
the driver interface.</p>
- <p>Since the <c>total</c> value is the sum of <c>processes</c>
- and <c>system</c> the error in <c>system</c> will propagate
+ <p>As the <c>total</c> value is the sum of <c>processes</c>
+ and <c>system</c>, the error in <c>system</c> propagates
to the <c>total</c> value.</p>
<p>The different amounts of memory that are summed are
- <em>not</em> gathered atomically which also introduce
+ <em>not</em> gathered atomically, which introduces
an error in the result.</p>
</note>
- <p>The different values has the following relation to each
+ <p>The different values have the following relation to each
other. Values beginning with an uppercase letter is not part
of the result.</p>
<code type="none">
@@ -2402,69 +2760,62 @@ os_prompt% </pre>
processes = processes_used + ProcessesNotUsed
system = atom + binary + code + ets + OtherSystem
atom = atom_used + AtomNotUsed
-
RealTotal = processes + RealSystem
RealSystem = system + MissedSystem</code>
- <p>More tuples in the returned list may be added in the future.</p>
+ <p>More tuples in the returned list can be added in a
+ future release.</p>
<note>
<p>The <c>total</c> value is supposed to be the total amount
of memory dynamically allocated by the emulator. Shared
libraries, the code of the emulator itself, and
- the emulator stack(s) are not supposed to be included. That
+ the emulator stacks are not supposed to be included. That
is, the <c>total</c> value is <em>not</em> supposed to be
- equal to the total size of all pages mapped to the emulator.
- Furthermore, due to fragmentation and pre-reservation of
- memory areas, the size of the memory segments which contain
- the dynamically allocated memory blocks can be substantially
+ equal to the total size of all pages mapped to the emulator.</p>
+ <p>Furthermore, because of fragmentation and prereservation of
+ memory areas, the size of the memory segments containing
+ the dynamically allocated memory blocks can be much
larger than the total size of the dynamically allocated
memory blocks.</p>
</note>
<note>
- <p>
- Since erts version 5.6.4 <c>erlang:memory/0</c> requires that
+ <p>As from <c>ERTS</c> 5.6.4, <c>erlang:memory/0</c> requires that
all <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
- allocators are enabled (default behaviour).
- </p>
+ allocators are enabled (default behavior).</p>
</note>
- <p>Failure:</p>
- <taglist>
- <tag><c>notsup</c></tag>
- <item>
- If an <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
- allocator has been disabled.
- </item>
- </taglist>
+ <p>Failure: <c>notsup</c> if an
+ <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
+ allocator has been disabled.</p>
</desc>
</func>
+
<func>
<name name="memory" arity="1" clause_i="1"/>
<name name="memory" arity="1" clause_i="2"/>
+ <fsummary>Information about dynamically allocated memory.</fsummary>
<type name="memory_type"/>
- <fsummary>Information about dynamically allocated memory</fsummary>
<desc>
<p>Returns the memory size in bytes allocated for memory of
type <c><anno>Type</anno></c>. The argument can also be given as a list
of <c>memory_type()</c> atoms, in which case a corresponding list of
<c>{memory_type(), Size :: integer >= 0}</c> tuples is returned.</p>
<note>
- <p>
- Since erts version 5.6.4 <c>erlang:memory/1</c> requires that
+ <p>As from <c>ERTS</c> version 5.6.4,
+ <c>erlang:memory/1</c> requires that
all <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
- allocators are enabled (default behaviour).
- </p>
+ allocators are enabled (default behavior).</p>
</note>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>Type</anno></c> is not one of the memory types listed in the
- documentation of
+ If <c><anno>Type</anno></c> is not one of the memory types
+ listed in the description of
<seealso marker="#memory/0">erlang:memory/0</seealso>.
</item>
<tag><c>badarg</c></tag>
<item>
- If <c>maximum</c> is passed as <c><anno>Type</anno></c> and the emulator
- is not run in instrumented mode.
+ If <c>maximum</c> is passed as <c><anno>Type</anno></c> and
+ the emulator is not run in instrumented mode.
</item>
<tag><c>notsup</c></tag>
<item>
@@ -2476,226 +2827,367 @@ os_prompt% </pre>
<seealso marker="#memory/0">erlang:memory/0</seealso>.</p>
</desc>
</func>
+
<func>
<name name="min" arity="2"/>
- <fsummary>Return the smallest of two term</fsummary>
+ <fsummary>Returns the smallest of two terms.</fsummary>
<desc>
- <p>Return the smallest of <c><anno>Term1</anno></c> and <c><anno>Term2</anno></c>;
- if the terms compare equal, <c><anno>Term1</anno></c> will be returned.</p>
+ <p>Returns the smallest of <c><anno>Term1</anno></c> and
+ <c><anno>Term2</anno></c>.
+ If the terms are equal, <c><anno>Term1</anno></c> is returned.</p>
</desc>
</func>
+
<func>
<name name="module_loaded" arity="1"/>
- <fsummary>Check if a module is loaded</fsummary>
+ <fsummary>Checks if a module is loaded.</fsummary>
<desc>
- <p>Returns <c>true</c> if the module <c><anno>Module</anno></c> is loaded,
- otherwise returns <c>false</c>. It does not attempt to load
+ <p>Returns <c>true</c> if the module <c><anno>Module</anno></c>
+ is loaded, otherwise <c>false</c>. It does not attempt to load
the module.</p>
<warning>
<p>This BIF is intended for the code server (see
- <seealso marker="kernel:code">code(3)</seealso>) and should not be
+ <seealso marker="kernel:code">code(3)</seealso>) and is not to be
used elsewhere.</p>
</warning>
</desc>
</func>
+
<func>
- <name name="monitor" arity="2"/>
- <fsummary>Start monitoring</fsummary>
- <desc>
- <p>The calling process starts monitoring <c><anno>Item</anno></c> which is
- an object of type <c><anno>Type</anno></c>.</p>
- <p>Currently only processes can be monitored, i.e. the only
- allowed <c><anno>Type</anno></c> is <c>process</c>, but other types may be
- allowed in the future.</p>
- <p><c><anno>Item</anno></c> can be:</p>
- <taglist>
- <tag><c>pid()</c></tag>
- <item>
- <p>The pid of the process to monitor.</p>
- </item>
- <tag><c>{RegName, 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>RegName</c> will be monitored.</p>
- </item>
- <tag><c>RegName</c></tag>
- <item>
- <p>The process locally registered as <c>RegName</c> will be
- monitored.</p>
- </item>
- </taglist>
- <note>
- <p>When a process is monitored by registered name, the process
- that has the registered name at the time when
- <c>monitor/2</c> is called will be monitored.
- The monitor will not be effected, if the registered name is
- unregistered.</p>
- </note>
- <p>A <c>'DOWN'</c> message will be sent to the monitoring
- process if <c><anno>Item</anno></c> dies, if <c><anno>Item</anno></c> does not exist,
- or if the connection is lost to the node which <c><anno>Item</anno></c>
- resides on. A <c>'DOWN'</c> message has the following pattern:</p>
- <code type="none">
-{'DOWN', MonitorRef, Type, Object, Info}</code>
- <p>where <c>MonitorRef</c> and <c>Type</c> are the same as
- described above, and:</p>
- <taglist>
- <tag><c>Object</c></tag>
- <item>
- <p>A reference to the monitored object:</p>
- <list type="bulleted">
- <item>the pid of the monitored process, if <c><anno>Item</anno></c> was
- specified as a pid.</item>
- <item><c>{RegName, Node}</c>, if <c><anno>Item</anno></c> was specified as
- <c>{RegName, Node}</c>.</item>
- <item><c>{RegName, Node}</c>, if <c><anno>Item</anno></c> was specified as
- <c>RegName</c>. <c>Node</c> will in this case be the
- name of the local node (<c>node()</c>).</item>
- </list>
- </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 <c><anno>Node</anno></c>).</p>
- </item>
- </taglist>
- <note>
- <p>If/when <c>monitor/2</c> is extended (e.g. to
- handle other item types than <c>process</c>), other
- possible values for <c>Object</c>, and <c>Info</c> in the
- <c>'DOWN'</c> message will be introduced.</p>
- </note>
- <p>The monitoring is turned off either 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 one
- where remote process monitoring by registered name is not
- implemented), the call fails with <c>badarg</c>.</p>
- <p>Making several calls to <c>monitor/2</c> for the same
- <c><anno>Item</anno></c> is not an error; it results in as many, completely
- independent, monitorings.</p>
+ <name name="monitor" arity="2" clause_i="1"/>
+ <name name="monitor" arity="2" clause_i="2"/>
+ <fsummary>Starts monitoring.</fsummary>
+ <type name="registered_name"/>
+ <type name="registered_process_identifier"/>
+ <type name="monitor_process_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>
+ <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>
+ <item>
+ <p>Monitor changes in
+ <seealso marker="#time_offset/0">time offset</seealso>
+ between
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ monotonic time</seealso> and
+ <seealso marker="time_correction#Erlang_System_Time">Erlang
+ system time</seealso>. There is only one valid
+ <c><anno>Item</anno></c> in combination with the
+ <c>time_offset <anno>Type</anno></c>, namely the atom
+ <c>clock_service</c>. Note that the atom <c>clock_service</c> is
+ <em>not</em> the registered name of a process. In this specific
+ case it serves as an identifier of the runtime system internal
+ clock service at current runtime system instance.</p>
+
+ <p>The monitor is triggered when the time offset is changed.
+ This either if the time offset value is changed, or if the
+ offset is changed from preliminary to final during
+ <seealso marker="#system_flag_time_offset">finalization
+ of the time offset</seealso> when the
+ <seealso marker="time_correction#Single_Time_Warp_Mode">single
+ time warp mode</seealso> is used. When a change from preliminary
+ to final time offset is made, the monitor will be triggered once
+ regardless of whether the time offset value was actually changed
+ or not.</p>
+
+ <p>If the runtime system is in
+ <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+ time warp mode</seealso>, the time offset will be changed when
+ the runtime system detects that the
+ <seealso marker="time_correction#OS_System_Time">OS system
+ time</seealso> has changed. The runtime system will, however,
+ not detect this immediately when it happens. A task checking
+ the time offset is scheduled to execute at least once a minute,
+ so under normal operation this should be detected within a
+ minute, but during heavy load it might take longer time.</p>
+
+ <p>The monitor will <em>not</em> be automatically removed
+ after it has been triggered. That is, repeated changes of
+ the time offset will trigger the monitor repeatedly.</p>
+
+ <p>When the monitor is triggered a <c>'CHANGE'</c> message will
+ be sent to the monitoring process. A <c>'CHANGE'</c> message has
+ the following pattern:</p>
+ <code type="none">{'CHANGE', MonitorRef, Type, Item, NewTimeOffset}</code>
+ <p>where <c>MonitorRef</c>, <c><anno>Type</anno></c>, and
+ <c><anno>Item</anno></c> are the same as described above, and
+ <c>NewTimeOffset</c> is the new time offset.</p>
+
+ <p>When the <c>'CHANGE'</c> message has been received you are
+ guaranteed not to retrieve the old time offset when calling
+ <seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso>.
+ 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>
+ <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>
<note>
- <p>The format of the <c>'DOWN'</c> message changed in the 5.2
- version of the emulator (OTP release R9B) for monitor <em>by registered name</em>. The <c>Object</c> element of
- the <c>'DOWN'</c> message could in earlier versions
- sometimes be the pid of the monitored process and sometimes
- be the registered name. Now the <c>Object</c> element is
- always a tuple consisting of the registered name and
- the node name. Processes on new nodes (emulator version 5.2
- or greater) will always get <c>'DOWN'</c> messages on
- the new format even if they are monitoring processes on old
- nodes. Processes on old nodes will always get <c>'DOWN'</c>
- messages on the old format.</p>
+ <p>If or when <c>monitor/2</c> is extended, other
+ possible values for <c>Tag</c>, <c>Object</c> and
+ <c>Info</c> in the monitor message will be introduced.</p>
</note>
</desc>
</func>
+
<func>
<name name="monitor_node" arity="2"/>
- <fsummary>Monitor the status of a node</fsummary>
+ <fsummary>Monitors the status of a node.</fsummary>
<desc>
- <p>Monitors the status of the node <c><anno>Node</anno></c>. If <c><anno>Flag</anno></c>
- is <c>true</c>, monitoring is turned on; if <c><anno>Flag</anno></c> is
- <c>false</c>, monitoring is turned off.</p>
+ <p>Monitors the status of the node <c><anno>Node</anno></c>.
+ If <c><anno>Flag</anno></c>
+ is <c>true</c>, monitoring is turned on. If <c><anno>Flag</anno></c>
+ is <c>false</c>, monitoring is turned off.</p>
<p>Making several calls to <c>monitor_node(Node, true)</c> for
- the same <c><anno>Node</anno></c> is not an error; it results in as many,
- completely independent, monitorings.</p>
+ the same <c><anno>Node</anno></c> is not an error; it results
+ in as many independent monitoring instances.</p>
<p>If <c><anno>Node</anno></c> fails or does not exist, the message
<c>{nodedown, Node}</c> is delivered to the process. If a
process has made two calls to <c>monitor_node(Node, true)</c>
- and <c><anno>Node</anno></c> terminates, two <c>nodedown</c> messages are
- delivered to the process. If there is no connection to
- <c><anno>Node</anno></c>, there will be an attempt to create one. If this
- fails, a <c>nodedown</c> message is delivered.</p>
+ and <c><anno>Node</anno></c> terminates, two <c>nodedown</c> messages
+ are delivered to the process. If there is no connection to
+ <c><anno>Node</anno></c>, an attempt is made to create one.
+ If this fails, a <c>nodedown</c> message is delivered.</p>
<p>Nodes connected through hidden connections can be monitored
- as any other node.</p>
+ as any other nodes.</p>
<p>Failure: <c>badarg</c> if the local node is not alive.</p>
</desc>
</func>
+
<func>
<name name="monitor_node" arity="3"/>
- <fsummary>Monitor the status of a node</fsummary>
+ <fsummary>Monitors the status of a node.</fsummary>
<desc>
- <p>Behaves as <c>monitor_node/2</c> except that it allows an
+ <p>Behaves as
+ <seealso marker="#monitor_node/2">monitor_node/2</seealso>
+ except that it allows an
extra option to be given, namely <c>allow_passive_connect</c>.
- The option allows the BIF to wait the normal net connection
- timeout for the <em>monitored node</em> to connect itself,
+ This option allows the BIF to wait the normal network connection
+ time-out for the <em>monitored node</em> to connect itself,
even if it cannot be actively connected from this node
- (i.e. it is blocked). The state where this might be useful can
- only be achieved by using the kernel option
- <c>dist_auto_connect once</c>. If that kernel option is not
- used, the <c>allow_passive_connect</c> option has no
- effect.</p>
+ (that is, it is blocked). The state where this can be useful
+ can only be achieved by using the <c>Kernel</c> option
+ <c>dist_auto_connect once</c>. If that option is not
+ used, option <c>allow_passive_connect</c> has no effect.</p>
<note>
- <p>The <c>allow_passive_connect</c> option is used
+ <p>Option <c>allow_passive_connect</c> is used
internally and is seldom needed in applications where the
- network topology and the kernel options in effect is known in
- advance.</p>
+ network topology and the <c>Kernel</c> options in effect
+ are known in advance.</p>
</note>
<p>Failure: <c>badarg</c> if the local node is not alive or the
option list is malformed.</p>
</desc>
</func>
+
+ <func>
+ <name name="monotonic_time" arity="0"/>
+ <fsummary>Current Erlang monotonic time.</fsummary>
+ <desc>
+ <p>Returns the current
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ monotonic time</seealso> in <c>native</c>
+ <seealso marker="#type_time_unit">time unit</seealso>. This
+ is a monotonically increasing time since some unspecified point in
+ time.</p>
+
+ <note><p>This is a
+ <seealso marker="time_correction#Monotonically_Increasing">monotonically increasing</seealso> time, but <em>not</em> a
+ <seealso marker="time_correction#Strictly_Monotonically_Increasing">strictly monotonically increasing</seealso>
+ time. That is, consecutive calls to
+ <c>erlang:monotonic_time/0</c> can produce the same result.</p>
+
+ <p>Different runtime system instances will use different
+ unspecified points in time as base for their Erlang monotonic clocks.
+ That is, it is <em>pointless</em> comparing monotonic times from
+ different runtime system instances. Different runtime system instances
+ may also place this unspecified point in time different relative
+ runtime system start. It may be placed in the future (time at start
+ is a negative value), the past (time at start is a
+ positive value), or the runtime system start (time at start is
+ zero). The monotonic time at runtime system start can be
+ retrieved by calling
+ <seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso>.</p></note>
+ </desc>
+ </func>
+ <func>
+ <name name="monotonic_time" arity="1"/>
+ <fsummary>Current Erlang monotonic time</fsummary>
+ <desc>
+ <p>Returns the current
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ monotonic time</seealso> converted
+ into the <c><anno>Unit</anno></c> passed as argument.</p>
+
+ <p>Same as calling
+ <seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso><c>,
+ native, <anno>Unit</anno>)</c>
+ however optimized for commonly used <c><anno>Unit</anno></c>s.</p>
+ </desc>
+ </func>
<func>
<name name="nif_error" arity="1"/>
- <fsummary>Stop execution with a given reason</fsummary>
+ <fsummary>Stops execution with a given reason.</fsummary>
<desc>
<p>Works exactly like
- <seealso marker="#error/1">erlang:error/1</seealso>,
- but Dialyzer thinks that this BIF will return an arbitrary term.
- When used in a stub function for a NIF to generate an
- exception when the NIF library is not loaded, Dialyzer
- will not generate false warnings.</p>
+ <seealso marker="#error/1">erlang:error/1</seealso>, but
+ <c>Dialyzer</c> thinks that this BIF will return an arbitrary
+ term. When used in a stub function for a NIF to generate an
+ exception when the NIF library is not loaded, <c>Dialyzer</c>
+ does not generate false warnings.</p>
</desc>
</func>
+
<func>
<name name="nif_error" arity="2"/>
- <fsummary>Stop execution with a given reason</fsummary>
+ <fsummary>Stops execution with a given reason.</fsummary>
<desc>
<p>Works exactly like
- <seealso marker="#error/2">erlang:error/2</seealso>,
- but Dialyzer thinks that this BIF will return an arbitrary term.
- When used in a stub function for a NIF to generate an
- exception when the NIF library is not loaded, Dialyzer
- will not generate false warnings.</p>
+ <seealso marker="#error/2">erlang:error/2</seealso>, but
+ <c>Dialyzer</c> thinks that this BIF will return an arbitrary
+ term. When used in a stub function for a NIF to generate an
+ exception when the NIF library is not loaded, <c>Dialyzer</c>
+ does not generate false warnings.</p>
</desc>
</func>
+
<func>
<name name="node" arity="0"/>
- <fsummary>Name of the local node</fsummary>
+ <fsummary>Name of the local node.</fsummary>
<desc>
<p>Returns the name of the local node. If the node is not alive,
<c>nonode@nohost</c> is returned instead.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="node" arity="1"/>
- <fsummary>At which node is a pid, port or reference located</fsummary>
+ <fsummary>At which node a pid, port, or reference originates.</fsummary>
<desc>
- <p>Returns the node where <c><anno>Arg</anno></c> is located. <c><anno>Arg</anno></c> can
- be a pid, a reference, or a port. If the local node is not
+ <p>Returns the node where <c><anno>Arg</anno></c> originates.
+ <c><anno>Arg</anno></c> can
+ be a process identifier, a reference, or a port.
+ If the local node is not
alive, <c>nonode@nohost</c> is returned.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="nodes" arity="0"/>
- <fsummary>All visible nodes in the system</fsummary>
+ <fsummary>All visible nodes in the system.</fsummary>
<desc>
- <p>Returns a list of all visible nodes in the system, excluding
+ <p>Returns a list of all visible nodes in the system, except
the local node. Same as <c>nodes(visible)</c>.</p>
</desc>
</func>
+
<func>
<name name="nodes" arity="1"/>
- <fsummary>All nodes of a certain type in the system</fsummary>
+ <fsummary>All nodes of a certain type in the system.</fsummary>
<desc>
- <p>Returns a list of nodes according to argument given.
- The result returned when the argument is a list, is the list
+ <p>Returns a list of nodes according to the argument given.
+ The returned result when the argument is a list, is the list
of nodes satisfying the disjunction(s) of the list elements.</p>
<p><c><anno>NodeType</anno></c> can be any of the following:</p>
<taglist>
@@ -2717,129 +3209,130 @@ os_prompt% </pre>
</item>
<tag><c>known</c></tag>
<item>
- <p>Nodes which are known to this node, i.e., connected,
- previously connected, etc.</p>
+ <p>Nodes that are known to this node. That is, connected
+ nodes and nodes referred to by process identifiers, port
+ identifiers and references located on this node.
+ The set of known nodes is garbage collected. Notice that
+ this garbage collection can be delayed. For more
+ information, see
+ <seealso marker="erlang#system_info_delayed_node_table_gc">delayed_node_table_gc</seealso>.
+ </p>
</item>
</taglist>
<p>Some equalities: <c>[node()] = nodes(this)</c>,
<c>nodes(connected) = nodes([visible, hidden])</c>, and
<c>nodes() = nodes(visible)</c>.</p>
- <p>If the local node is not alive,
- <c>nodes(this) == nodes(known) == [nonode@nohost]</c>, for
- any other <c><anno>Arg</anno></c> the empty list [] is returned.</p>
</desc>
</func>
+
<func>
<name name="now" arity="0"/>
+ <fsummary>Elapsed time since 00:00 GMT.</fsummary>
<type name="timestamp"/>
- <fsummary>Elapsed time since 00:00 GMT</fsummary>
<desc>
+ <warning><p><em>This function is deprecated! Do not use it!</em>
+ See the users guide chapter
+ <seealso marker="time_correction">Time and Time Correction</seealso>
+ for more information. Specifically the
+ <seealso marker="time_correction#Dos_and_Donts">Dos and Dont's</seealso>
+ section for information on what to use instead of <c>erlang:now/0</c>.
+ </p></warning>
<p>Returns the tuple <c>{MegaSecs, Secs, MicroSecs}</c> which is
- the elapsed time since 00:00 GMT, January 1, 1970 (zero hour)
+ the elapsed time since 00:00 GMT, January 1, 1970 (zero hour),
on the assumption that the underlying OS supports this.
- Otherwise, some other point in time is chosen. It is also
- guaranteed that subsequent calls to this BIF returns
+ Otherwise some other point in time is chosen. It is also
+ guaranteed that subsequent calls to this BIF return
continuously increasing values. Hence, the return value from
- <c>now()</c> can be used to generate unique time-stamps,
- and if it is called in a tight loop on a fast machine
+ <c>now()</c> can be used to generate unique time-stamps.
+ If it is called in a tight loop on a fast machine,
the time of the node can become skewed.</p>
- <p>It can only be used to check the local time of day if
- the time-zone info of the underlying operating system is
+ <p>Can only be used to check the local time of day if
+ the time-zone information of the underlying OS is
properly configured.</p>
- <p>If you do not need the return value to be unique and
- monotonically increasing, use
- <seealso marker="kernel:os#timestamp/0">os:timestamp/0</seealso>
- instead to avoid some overhead.</p>
</desc>
</func>
+
<func>
<name name="open_port" arity="2"/>
- <fsummary>Open a port</fsummary>
+ <fsummary>Opens a port.</fsummary>
<desc>
<p>Returns a port identifier as the result of opening a
new Erlang port. A port can be seen as an external Erlang
- process.
- </p>
+ process.</p>
<p>The name of the executable as well as the arguments
- given in <c>cd</c>, <c>env</c>, <c>args</c> and <c>arg0</c> is subject to
- Unicode file name translation if the system is running
+ given in <c>cd</c>, <c>env</c>, <c>args</c>, and <c>arg0</c> are
+ subject to Unicode file name translation if the system is running
in Unicode file name mode. To avoid
- translation or force i.e. UTF-8, supply the executable
+ translation or to force, for example UTF-8, supply the executable
and/or arguments as a binary in the correct
- encoding. See the <seealso
- marker="kernel:file">file</seealso> module, the
- <seealso marker="kernel:file#native_name_encoding/0">
- file:native_name_encoding/0</seealso> function and the
- <seealso marker="stdlib:unicode_usage">stdlib users guide
- </seealso> for details.</p>
-
- <note><p>The characters in the name (if given as a list)
- can only be &gt; 255 if the Erlang VM is started in
- Unicode file name translation mode, otherwise the name
+ encoding. For details, see the module
+ <seealso marker="kernel:file">file</seealso>, the function
+ <seealso marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>, and the
+ <seealso marker="stdlib:unicode_usage">STDLIB </seealso>
+ User's Guide.</p>
+ <note><p>The characters in the name (if given as a list) can
+ only be higher than 255 if the Erlang Virtual Machine is started
+ in Unicode file name translation mode. Otherwise the name
of the executable is limited to the ISO-latin-1
character set.</p></note>
-
- <p><c><anno>PortName</anno></c> is one of the following:</p>
+ <p><c><anno>PortName</anno></c> can be any of the following:</p>
<taglist>
<tag><c>{spawn, <anno>Command</anno>}</c></tag>
<item>
- <p>Starts an external program. <c><anno>Command</anno></c> is the name
- of the external program which will be run. <c><anno>Command</anno></c>
+ <p>Starts an external program. <c><anno>Command</anno></c>
+ is the name of the external program to be run.
+ <c><anno>Command</anno></c>
runs outside the Erlang work space unless an Erlang
- driver with the name <c><anno>Command</anno></c> is found. If found,
- that driver will be started. A driver runs in the Erlang
- workspace, which means that it is linked with the Erlang
+ driver with the name <c><anno>Command</anno></c> is found.
+ If found, that driver is started. A driver runs in the Erlang
+ work space, which means that it is linked with the Erlang
runtime system.</p>
<p>When starting external programs on Solaris, the system
call <c>vfork</c> is used in preference to <c>fork</c>
for performance reasons, although it has a history of
- being less robust. If there are problems with using
- <c>vfork</c>, setting the environment variable
- <c>ERL_NO_VFORK</c> to any value will cause <c>fork</c>
+ being less robust. If there are problems using
+ <c>vfork</c>, setting environment variable
+ <c>ERL_NO_VFORK</c> to any value causes <c>fork</c>
to be used instead.</p>
-
- <p>For external programs, the <c>PATH</c> is searched
+ <p>For external programs, <c>PATH</c> is searched
(or an equivalent method is used to find programs,
- depending on operating system). This is done by invoking
- the shell on certain platforms. The first space
- separated token of the command will be considered as the
+ depending on OS). This is done by invoking
+ the shell on certain platforms. The first space-separated
+ token of the command is considered as the
name of the executable (or driver). This (among other
things) makes this option unsuitable for running
- programs having spaces in file or directory names. Use
- {spawn_executable, <anno>Command</anno>} instead if spaces in executable
- file names is desired.</p>
+ programs having spaces in file names or directory names.
+ If spaces in executable file names are desired, use
+ <c>{spawn_executable, <anno>Command</anno>}</c> instead.</p>
</item>
<tag><c>{spawn_driver, <anno>Command</anno>}</c></tag>
<item>
<p>Works like <c>{spawn, <anno>Command</anno>}</c>, but demands the
- first (space separated) token of the command to be the name of a
+ first (space-separated) token of the command to be the name of a
loaded driver. If no driver with that name is loaded, a
<c>badarg</c> error is raised.</p>
</item>
<tag><c>{spawn_executable, <anno>FileName</anno>}</c></tag>
<item>
-
<p>Works like <c>{spawn, <anno>FileName</anno>}</c>, but only runs
- external executables. The <c><anno>FileName</anno></c> in its whole
- is used as the name of the executable, including any
- spaces. If arguments are to be passed, the
- <c>args</c> and <c>arg0</c> <c><anno>PortSettings</anno></c> can be used.</p>
-
- <p>The shell is not usually invoked to start the
- program, it's executed directly. Neither is the
- <c>PATH</c> (or equivalent) searched. To find a program
- in the PATH to execute, use <seealso
- marker="kernel:os#find_executable/1">os:find_executable/1</seealso>.</p>
+ external executables. <c><anno>FileName</anno></c> in its whole
+ is used as the name of the executable, including any spaces.
+ If arguments are to be passed, the <c><anno>PortSettings</anno></c>
+ <c>args</c> and <c>arg0</c> can be used.</p>
+ <p>The shell is usually not invoked to start the
+ program, it is executed directly. <c>PATH</c> (or
+ equivalent) is not searched. To find a program
+ in <c>PATH</c> to execute, use
+ <seealso marker="kernel:os#find_executable/1">os:find_executable/1</seealso>.</p>
<p>Only if a shell script or <c>.bat</c> file is
- executed, the appropriate command interpreter will
- implicitly be invoked, but there will still be no
- command argument expansion or implicit PATH search.</p>
-
- <p>If the <c><anno>FileName</anno></c> cannot be run, an error
- exception, with the posix error code as the reason, is
- raised. The error reason may differ between operating
- systems. Typically the error <c>enoent</c> is raised
- when one tries to run a program that is not found and
+ executed, the appropriate command interpreter is
+ invoked implicitly, but there is still no
+ command argument expansion or implicit <c>PATH</c> search.</p>
+ <p>If <c><anno>FileName</anno></c> cannot be run, an error
+ exception is raised, with the POSIX error code as the reason.
+ The error reason can differ between OSs.
+ Typically the error <c>enoent</c> is raised when an
+ attempt is made to run a program that is not found and
<c>eacces</c> is raised when the given file is not
executable.</p>
</item>
@@ -2849,19 +3342,18 @@ os_prompt% </pre>
file descriptors used by Erlang. The file descriptor
<c><anno>In</anno></c> can be used for standard input, and the file
descriptor <c><anno>Out</anno></c> for standard output. It is only
- used for various servers in the Erlang operating system
- (<c>shell</c> and <c>user</c>). Hence, its use is very
- limited.</p>
+ used for various servers in the Erlang OS (<c>shell</c>
+ and <c>user</c>). Hence, its use is limited.</p>
</item>
</taglist>
<p><c><anno>PortSettings</anno></c> is a list of settings for the port.
- Valid settings are:</p>
+ The valid settings are as follows:</p>
<taglist>
<tag><c>{packet, <anno>N</anno>}</c></tag>
<item>
<p>Messages are preceded by their length, sent in <c><anno>N</anno></c>
- bytes, with the most significant byte first. Valid values
- for <c>N</c> are 1, 2, or 4.</p>
+ bytes, with the most significant byte first. The valid values
+ for <c>N</c> are 1, 2, and 4.</p>
</item>
<tag><c>stream</c></tag>
<item>
@@ -2872,116 +3364,108 @@ os_prompt% </pre>
<tag><c>{line, <anno>L</anno>}</c></tag>
<item>
<p>Messages are delivered on a per line basis. Each line
- (delimited by the OS-dependent newline sequence) is
- delivered in one single message. The message data format
- is <c>{Flag, Line}</c>, where <c>Flag</c> is either
- <c>eol</c> or <c>noeol</c> and <c>Line</c> is the actual
- data delivered (without the newline sequence).</p>
+ (delimited by the OS-dependent new line sequence) is
+ delivered in a single message. The message data format
+ is <c>{Flag, Line}</c>, where <c>Flag</c> is
+ <c>eol</c> or <c>noeol</c>, and <c>Line</c> is the
+ data delivered (without the new line sequence).</p>
<p><c><anno>L</anno></c> specifies the maximum line length in bytes.
- Lines longer than this will be delivered in more than one
- message, with the <c>Flag</c> set to <c>noeol</c> for all
+ Lines longer than this are delivered in more than one
+ message, with <c>Flag</c> set to <c>noeol</c> for all
but the last message. If end of file is encountered
- anywhere else than immediately following a newline
- sequence, the last line will also be delivered with
- the <c>Flag</c> set to <c>noeol</c>. In all other cases,
+ anywhere else than immediately following a new line
+ sequence, the last line is also delivered with
+ <c>Flag</c> set to <c>noeol</c>. Otherwise
lines are delivered with <c>Flag</c> set to <c>eol</c>.</p>
- <p>The <c>{packet, <anno>N</anno>}</c> and <c>{line, <anno>L</anno>}</c> settings are
- mutually exclusive.</p>
+ <p>The <c>{packet, <anno>N</anno>}</c> and <c>{line,
+ <anno>L</anno>}</c> settings are mutually exclusive.</p>
</item>
<tag><c>{cd, <anno>Dir</anno>}</c></tag>
<item>
- <p>This is only valid for <c>{spawn, <anno>Command</anno>}</c> and
- <c>{spawn_executable, <anno>FileName</anno>}</c>.
+ <p>Only valid for <c>{spawn, <anno>Command</anno>}</c> and
+ <c>{spawn_executable, <anno>FileName</anno>}</c>.
The external program starts using <c><anno>Dir</anno></c> as its
- working directory. <c><anno>Dir</anno></c> must be a string.
- </p>
+ working directory. <c><anno>Dir</anno></c> must be a string.</p>
</item>
<tag><c>{env, <anno>Env</anno>}</c></tag>
<item>
- <p>This is only valid for <c>{spawn, <anno>Command</anno>}</c> and
+ <p>Only valid for <c>{spawn, <anno>Command</anno>}</c> and
<c>{spawn_executable, <anno>FileName</anno>}</c>.
The environment of the started process is extended using
the environment specifications in <c><anno>Env</anno></c>.</p>
- <p><c><anno>Env</anno></c> should be a list of tuples <c>{<anno>Name</anno>, <anno>Val</anno>}</c>,
- where <c><anno>Name</anno></c> is the name of an environment variable,
- and <c><anno>Val</anno></c> is the value it is to have in the spawned
- port process. Both <c><anno>Name</anno></c> and <c><anno>Val</anno></c> must be
- strings. The one exception is <c><anno>Val</anno></c> being the atom
+ <p><c><anno>Env</anno></c> is to be a list of tuples
+ <c>{<anno>Name</anno>, <anno>Val</anno>}</c>,
+ where <c><anno>Name</anno></c> is the name of an
+ environment variable, and <c><anno>Val</anno></c> is the
+ value it is to have in the spawned
+ port process. Both <c><anno>Name</anno></c> and
+ <c><anno>Val</anno></c> must be strings. The one
+ exception is <c><anno>Val</anno></c> being the atom
<c>false</c> (in analogy with <c>os:getenv/1</c>), which
- removes the environment variable.
- </p>
+ removes the environment variable.</p>
</item>
<tag><c>{args, [ string() | binary() ]}</c></tag>
<item>
-
- <p>This option is only valid for <c>{spawn_executable, <anno>FileName</anno>}</c>
+ <p>Only valid for <c>{spawn_executable, <anno>FileName</anno>}</c>
and specifies arguments to the executable. Each argument
is given as a separate string and (on Unix) eventually
ends up as one element each in the argument vector. On
- other platforms, similar behavior is mimicked.</p>
-
- <p>The arguments are not expanded by the shell prior to
- being supplied to the executable, most notably this
- means that file wildcard expansion will not happen. Use
- <seealso
- marker="stdlib:filelib#wildcard/1">filelib:wildcard/1</seealso>
- to expand wildcards for the arguments. Note that even if
+ other platforms, a similar behavior is mimicked.</p>
+ <p>The arguments are not expanded by the shell before
+ being supplied to the executable. Most notably this
+ means that file wild card expansion does not happen.
+ To expand wild cards for the arguments, use
+ <seealso marker="stdlib:filelib#wildcard/1">filelib:wildcard/1</seealso>.
+ Notice that even if
the program is a Unix shell script, meaning that the
- shell will ultimately be invoked, wildcard expansion
- will not happen and the script will be provided with the
- untouched arguments. On Windows&reg;, wildcard expansion
- is always up to the program itself, why this isn't an
- issue.</p>
-
- <p>Note also that the actual executable name (a.k.a. <c>argv[0]</c>)
- should not be given in this list. The proper executable name will
- automatically be used as argv[0] where applicable.</p>
-
- <p>If one, for any reason, wants to explicitly set the
- program name in the argument vector, the <c>arg0</c>
- option can be used.</p>
-
+ shell ultimately is invoked, wild card expansion
+ does not happen, and the script is provided with the
+ untouched arguments. On Windows, wild card expansion
+ is always up to the program itself, therefore this is
+ not an issue issue.</p>
+ <p>The executable name (also known as <c>argv[0]</c>)
+ is not to be given in this list. The proper executable name
+ is automatically used as argv[0], where applicable.</p>
+ <p>If you explicitly want to set the
+ program name in the argument vector, option <c>arg0</c>
+ can be used.</p>
</item>
<tag><c>{arg0, string() | binary()}</c></tag>
<item>
-
- <p>This option is only valid for <c>{spawn_executable, <anno>FileName</anno>}</c>
+ <p>Only valid for <c>{spawn_executable, <anno>FileName</anno>}</c>
and explicitly specifies the program name argument when
- running an executable. This might in some circumstances,
- on some operating systems, be desirable. How the program
- responds to this is highly system dependent and no specific
+ running an executable. This can in some circumstances,
+ on some OSs, be desirable. How the program
+ responds to this is highly system-dependent and no specific
effect is guaranteed.</p>
-
</item>
-
<tag><c>exit_status</c></tag>
<item>
- <p>This is only valid for <c>{spawn, <anno>Command</anno>}</c> where
- <c><anno>Command</anno></c> refers to an external program, and for
- <c>{spawn_executable, <anno>FileName</anno>}</c>.</p>
+ <p>Only valid for <c>{spawn, <anno>Command</anno>}</c>, where
+ <c><anno>Command</anno></c> refers to an external program, and
+ for <c>{spawn_executable, <anno>FileName</anno>}</c>.</p>
<p>When the external process connected to the port exits, a
message of the form <c>{Port,{exit_status,Status}}</c> is
sent to the connected process, where <c>Status</c> is the
exit status of the external process. If the program
- aborts, on Unix the same convention is used as the shells
- do (i.e., 128+signal).</p>
- <p>If the <c>eof</c> option has been given as well,
- the <c>eof</c> message and the <c>exit_status</c> message
- appear in an unspecified order.</p>
- <p>If the port program closes its stdout without exiting,
- the <c>exit_status</c> option will not work.</p>
+ aborts on Unix, the same convention is used as the shells
+ do (that is, 128+signal).</p>
+ <p>If option <c>eof</c> is also given, the messages <c>eof</c>
+ and <c>exit_status</c> appear in an unspecified order.</p>
+ <p>If the port program closes its <c>stdout</c> without exiting,
+ option <c>exit_status</c> does not work.</p>
</item>
<tag><c>use_stdio</c></tag>
<item>
- <p>This is only valid for <c>{spawn, <anno>Command</anno>}</c> and
+ <p>Only valid for <c>{spawn, <anno>Command</anno>}</c> and
<c>{spawn_executable, <anno>FileName</anno>}</c>. It
allows the standard input and output (file descriptors 0
- and 1) of the spawned (UNIX) process for communication
+ and 1) of the spawned (Unix) process for communication
with Erlang.</p>
</item>
<tag><c>nouse_stdio</c></tag>
<item>
- <p>The opposite of <c>use_stdio</c>. Uses file descriptors
+ <p>The opposite of <c>use_stdio</c>. It uses file descriptors
3 and 4 for communication with Erlang.</p>
</item>
<tag><c>stderr_to_stdout</c></tag>
@@ -2993,14 +3477,15 @@ os_prompt% </pre>
</item>
<tag><c>overlapped_io</c></tag>
<item>
- <p>Affects ports to external programs on Windows&reg; only.
- The standard input and standard output handles of the port program
- will, if this option is supplied, be opened with the flag
- FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do
+ <p>Affects ports to external programs on Windows only. The
+ standard input and standard output handles of the port program
+ are, if this option is supplied, opened with flag
+ <c>FILE_FLAG_OVERLAPPED</c>, so that the port program can
+ (and must) do
overlapped I/O on its standard handles. This is not normally
the case for simple port programs, but an option of value for the
- experienced Windows programmer. <em>On all other platforms, this
- option is silently discarded</em>.</p>
+ experienced Windows programmer. <em>On all other platforms, this
+ option is silently discarded.</em></p>
</item>
<tag><c>in</c></tag>
<item>
@@ -3012,345 +3497,354 @@ os_prompt% </pre>
</item>
<tag><c>binary</c></tag>
<item>
- <p>All IO from the port are binary data objects as opposed
+ <p>All I/O from the port is binary data objects as opposed
to lists of bytes.</p>
</item>
<tag><c>eof</c></tag>
<item>
- <p>The port will not be closed at the end of the file and
- produce an exit signal. Instead, it will remain open and
- a <c>{Port, eof}</c> message will be sent to the process
+ <p>The port is not closed at the end of the file and does not
+ produce an exit signal. Instead, it remains open and
+ a <c>{Port, eof}</c> message is sent to the process
holding the port.</p>
</item>
<tag><c>hide</c></tag>
<item>
- <p>When running on Windows, suppress creation of a new
+ <p>When running on Windows, suppresses creation of a new
console window when spawning the port program.
(This option has no effect on other platforms.)</p>
</item>
- <tag><marker id="open_port_parallelism"><c>{parallelism, Boolean}</c></marker></tag>
+ <tag><c>{parallelism, Boolean}</c></tag>
<item>
- <p>Set scheduler hint for port parallelism. If set to <c>true</c>,
- the VM will schedule port tasks when doing so will improve
- parallelism in the system. If set to <c>false</c>, the VM will
- try to perform port tasks immediately, improving latency at the
- expense of parallelism. The default can be set on system startup
- by passing the
- <seealso marker="erl#+spp">+spp</seealso> command line argument
- to <seealso marker="erl">erl(1)</seealso>.
- </p>
+ <marker id="open_port_parallelism"></marker>
+ <p>Sets scheduler hint for port parallelism. If set to
+ <c>true</c>, the Virtual Machine schedules port tasks;
+ when doing so, it improves parallelism in the system. If set
+ to <c>false</c>, the Virtual Machine tries to
+ perform port tasks immediately, improving latency at the
+ expense of parallelism. The default can be set at system startup
+ by passing command-line argument
+ <seealso marker="erl#+spp">+spp</seealso> to <c>erl(1)</c>.</p>
</item>
</taglist>
- <p>The default is <c>stream</c> for all types of port and
+ <p>Default is <c>stream</c> for all port types and
<c>use_stdio</c> for spawned ports.</p>
<p>Failure: If the port cannot be opened, the exit reason is
- <c>badarg</c>, <c>system_limit</c>, or the Posix error code which
- most closely describes the error, or <c>einval</c> if no Posix code
- is appropriate:</p>
+ <c>badarg</c>, <c>system_limit</c>, or the POSIX error code that
+ most closely describes the error, or <c>einval</c> if no POSIX
+ code is appropriate:</p>
<taglist>
<tag><c>badarg</c></tag>
- <item>
- <p>Bad input arguments to <c>open_port</c>.</p>
+ <item>Bad input arguments to <c>open_port</c>.
</item>
<tag><c>system_limit</c></tag>
- <item>
- <p>All available ports in the Erlang emulator are in use.</p>
+ <item>All available ports in the Erlang emulator are in use.
</item>
<tag><c>enomem</c></tag>
- <item>
- <p>There was not enough memory to create the port.</p>
+ <item>Not enough memory to create the port.
</item>
<tag><c>eagain</c></tag>
- <item>
- <p>There are no more available operating system processes.</p>
+ <item>No more available OS processes.
</item>
<tag><c>enametoolong</c></tag>
- <item>
- <p>The external command given was too long.</p>
+ <item>Too long external command.
</item>
<tag><c>emfile</c></tag>
- <item>
- <p>There are no more available file descriptors (for the operating system process
- that the Erlang emulator runs in).</p>
+ <item>No more available file descriptors (for the
+ OS process that the Erlang emulator runs in).
</item>
<tag><c>enfile</c></tag>
- <item>
- <p>The file table is full (for the entire operating system).</p>
+ <item>Full file table (for the entire OS).
</item>
<tag><c>eacces</c></tag>
- <item>
- <p>The <c>Command</c> given in <c>{spawn_executable, Command}</c> does not point out an executable file.</p>
+ <item><c>Command</c> given in <c>{spawn_executable, Command}</c>
+ does not point out an executable file.
</item>
<tag><c>enoent</c></tag>
- <item>
- <p>The <c><anno>FileName</anno></c> given in <c>{spawn_executable, <anno>FileName</anno>}</c> does not point out an existing file.</p>
+ <item><c><anno>FileName</anno></c> given in
+ <c>{spawn_executable, <anno>FileName</anno>}</c>
+ does not point out an existing file.
</item>
</taglist>
<p>During use of a port opened using <c>{spawn, Name}</c>,
- <c>{spawn_driver, Name}</c> or <c>{spawn_executable, Name}</c>,
+ <c>{spawn_driver, Name}</c>, or <c>{spawn_executable, Name}</c>,
errors arising when sending messages to it are reported to
the owning process using signals of the form
- <c>{'EXIT', Port, PosixCode}</c>. See <c>file(3)</c> for
- possible values of <c>PosixCode</c>.</p>
+ <c>{'EXIT', Port, PosixCode}</c>. For the possible values of
+ <c>PosixCode</c>, see the
+ <seealso marker="kernel:file">file(3)</seealso>
+ manual page in <c>Kernel</c>.</p>
<p>The maximum number of ports that can be open at the same
- time can be configured by passing the
- <seealso marker="erl#max_ports"><c>+Q</c></seealso>
- command line flag to
- <seealso marker="erl"><c>erl(1)</c></seealso>.</p>
+ time can be configured by passing command-line flag
+ <seealso marker="erl#max_ports"><c>+Q</c></seealso> to
+ <c>erl(1)</c>.</p>
</desc>
</func>
+
<func>
<name name="phash" arity="2"/>
+ <fsummary>Portable hash function.</fsummary>
<type_desc variable="Range">Range = 1..2^32, Hash = 1..Range</type_desc>
- <fsummary>Portable hash function</fsummary>
<desc>
- <p>Portable hash function that will give the same hash for
+ <p>Portable hash function that gives the same hash for
the same Erlang term regardless of machine architecture and
- ERTS version (the BIF was introduced in ERTS 4.9.1.1). Range
- can be between 1 and 2^32, the function returns a hash value
- for <c><anno>Term</anno></c> within the range <c>1..<anno>Range</anno></c>.</p>
- <p>This BIF could be used instead of the old deprecated
- <c>erlang:hash/2</c> BIF, as it calculates better hashes for
- all data-types, but consider using <c>phash2/1,2</c> instead.</p>
+ <c>ERTS</c> version (the BIF was introduced in <c>ERTS</c> 4.9.1.1).
+ The function returns a hash value for
+ <c><anno>Term</anno></c> within the range
+ <c>1..<anno>Range</anno></c>. The maximum value for
+ <c><anno>Range</anno></c> is 2^32.</p>
+ <p>This BIF can be used instead of the old deprecated BIF
+ <c>erlang:hash/2</c>, as it calculates better hashes for
+ all data types, but consider using <c>phash2/1,2</c> instead.</p>
</desc>
</func>
+
<func>
<name name="phash2" arity="1"/>
<name name="phash2" arity="2"/>
+ <fsummary>Portable hash function.</fsummary>
<type_desc variable="Range">1..2^32</type_desc>
<type_desc variable="Hash">0..Range-1</type_desc>
- <fsummary>Portable hash function</fsummary>
<desc>
- <p>Portable hash function that will give the same hash for
+ <p>Portable hash function that gives the same hash for
the same Erlang term regardless of machine architecture and
- ERTS version (the BIF was introduced in ERTS 5.2). Range can
- be between 1 and 2^32, the function returns a hash value for
- <c><anno>Term</anno></c> within the range <c>0..<anno>Range</anno>-1</c>. When called
- without the <c><anno>Range</anno></c> argument, a value in the range
- <c>0..2^27-1</c> is returned.</p>
- <p>This BIF should always be used for hashing terms. It
+ <c>ERTS</c> version (the BIF was introduced in <c>ERTS</c> 5.2).
+ The function returns a hash value for
+ <c><anno>Term</anno></c> within the range
+ <c>0..<anno>Range</anno>-1</c>. The maximum value for
+ <c><anno>Range</anno></c> is 2^32. When without argument
+ <c><anno>Range</anno></c>, a value in the range
+ 0..2^27-1 is returned.</p>
+ <p>This BIF is always to be used for hashing terms. It
distributes small integers better than <c>phash/2</c>, and
it is faster for bignums and binaries.</p>
- <p>Note that the range <c>0..<anno>Range</anno>-1</c> is different from
- the range of <c>phash/2</c> (<c>1..<anno>Range</anno></c>).</p>
+ <p>Notice that the range <c>0..<anno>Range</anno>-1</c> is
+ different from the range of <c>phash/2</c>, which is
+ <c>1..<anno>Range</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="pid_to_list" arity="1"/>
- <fsummary>Text representation of a pid</fsummary>
+ <fsummary>Text representation of a pid.</fsummary>
<desc>
- <p>Returns a string which corresponds to the text
+ <p>Returns a string corresponding to the text
representation of <c><anno>Pid</anno></c>.</p>
<warning>
- <p>This BIF is intended for debugging and for use in
- the Erlang operating system. It should not be used in
- application programs.</p>
+ <p>This BIF is intended for debugging and is not to be used
+ in application programs.</p>
</warning>
</desc>
</func>
+
<func>
<name name="port_close" arity="1"/>
- <fsummary>Close an open port</fsummary>
+ <fsummary>Closes an open port.</fsummary>
<desc>
<p>Closes an open port. Roughly the same as
- <c><anno>Port</anno> ! {self(), close}</c> except for the error behaviour
- (see below), being synchronous, and that the port does
- <em>not</em> reply with <c>{Port, closed}</c>. Any process may
+ <c><anno>Port</anno> ! {self(), close}</c> except for the error behavior
+ (see the following), being synchronous, and that the port does
+ <em>not</em> reply with <c>{Port, closed}</c>. Any process can
close a port with <c>port_close/1</c>, not only the port owner
(the connected process). If the calling process is linked to
- port identified by <c><anno>Port</anno></c>, an exit signal due
- to that link will be received by the process prior to the return
- from <c>port_close/1</c>.</p>
- <p>For comparison: <c><anno>Port</anno> ! {self(), close}</c> fails with
- <c>badarg</c> if <c><anno>Port</anno></c> cannot be sent to (i.e.,
- <c><anno>Port</anno></c> refers neither to a port nor to a process). If
- <c><anno>Port</anno></c> is a closed port nothing happens. If <c><anno>Port</anno></c>
+ the port identified by <c><anno>Port</anno></c>, the exit
+ signal from the port is guaranteed to be delivered before
+ <c>port_close/1</c> returns.</p>
+ <p>For comparison: <c><anno>Port</anno> ! {self(), close}</c>
+ only fails with <c>badarg</c> if <c><anno>Port</anno></c> does
+ not refer to a port or a process. If <c><anno>Port</anno></c>
+ is a closed port, nothing happens. If <c><anno>Port</anno></c>
is an open port and the calling process is the port owner,
- the port replies with <c>{Port, closed}</c> when all buffers
- have been flushed and the port really closes, but if
- the calling process is not the port owner the <em>port owner</em> fails with <c>badsig</c>.</p>
-
- <p>Note that any process can close a port using
- <c><anno>Port</anno> ! {PortOwner, close}</c> just as if it itself was
+ the port replies with <c>{Port, closed}</c> when all buffers
+ have been flushed and the port really closes. If the calling
+ process is not the port owner, the <em>port owner</em> fails
+ with <c>badsig</c>.</p>
+ <p>Notice that any process can close a port using
+ <c><anno>Port</anno> ! {PortOwner, close}</c> as if it itself was
the port owner, but the reply always goes to the port owner.</p>
- <p>As of OTP-R16 <c><anno>Port</anno> ! {PortOwner, close}</c> is truly
- asynchronous. Note that this operation has always been
+ <p>As from OTP R16, <c><anno>Port</anno> ! {PortOwner, close}</c> is truly
+ asynchronous. Notice that this operation has always been
documented as an asynchronous operation, while the underlying
implementation has been synchronous. <c>port_close/1</c> is
- however still fully synchronous. This due to its error
+ however still fully synchronous. This because of its error
behavior.</p>
- <p>Failure:</p>
- <taglist>
- <tag><c>badarg</c></tag>
- <item>
- If <c><anno>Port</anno></c> is not an identifier of an open
- port, or the registered name of an open port. If the calling
- process was linked to the previously open port identified by
- <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to this exception.
- </item>
- </taglist>
+ <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an identifier
+ of an open port, or the registered name of an open port.
+ If the calling process was previously linked to the closed
+ port, identified by <c><anno>Port</anno></c>, the exit
+ signal from the port is guaranteed to be delivered before
+ this <c>badarg</c> exception occurs.</p>
</desc>
</func>
+
<func>
<name name="port_command" arity="2"/>
- <fsummary>Send data to a port</fsummary>
+ <fsummary>Sends data to a port.</fsummary>
<desc>
<p>Sends data to a port. Same as
- <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c> except for the error
- behaviour and being synchronous (see below). Any process may
- send data to a port with <c>port_command/2</c>, not only the
+ <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c> except
+ for the error
+ behavior and being synchronous (see the following). Any process
+ can send data to a port with <c>port_command/2</c>, not only the
port owner (the connected process).</p>
<p>For comparison: <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c>
- fails with <c>badarg</c> if <c><anno>Port</anno></c> cannot be sent to
- (i.e., <c><anno>Port</anno></c> refers neither to a port nor to a process).
- If <c><anno>Port</anno></c> is a closed port the data message disappears
+ only fails with <c>badarg</c> if <c><anno>Port</anno></c>
+ does not refer to a port or a process. If
+ <c><anno>Port</anno></c> is a closed port, the data message
+ disappears
without a sound. If <c><anno>Port</anno></c> is open and the calling
process is not the port owner, the <em>port owner</em> fails
with <c>badsig</c>. The port owner fails with <c>badsig</c>
- also if <c><anno>Data</anno></c> is not a valid IO list.</p>
- <p>Note that any process can send to a port using
- <c><anno>Port</anno> ! {PortOwner, {command, <anno>Data</anno>}}</c> just as if it
- itself was the port owner.</p>
- <p>If the port is busy, the calling process will be suspended
- until the port is not busy anymore.</p>
- <p>As of OTP-R16 <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c> is
- truly asynchronous. Note that this operation has always been
+ also if <c><anno>Data</anno></c> is an invalid I/O list.</p>
+ <p>Notice that any process can send to a port using
+ <c><anno>Port</anno> ! {PortOwner, {command, <anno>Data</anno>}}</c>
+ as if it itself was the port owner.</p>
+ <p>If the port is busy, the calling process is suspended
+ until the port is not busy any more.</p>
+ <p>As from OTP-R16, <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c>
+ is truly asynchronous. Notice that this operation has always been
documented as an asynchronous operation, while the underlying
implementation has been synchronous. <c>port_command/2</c> is
- however still fully synchronous. This due to its error
+ however still fully synchronous. This because of its error
behavior.</p>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
<item>
If <c><anno>Port</anno></c> is not an identifier of an open
- port, or the registered name of an open port. If the calling
- process was linked to the previously open port identified by
- <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to this exception.
+ port, or the registered name of an open port. If the
+ calling process was previously linked to the closed port,
+ identified by <c><anno>Port</anno></c>, the exit signal
+ from the port is guaranteed to be delivered before this
+ <c>badarg</c> exception occurs.
</item>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>Data</anno></c> is not a valid io list.
+ If <c><anno>Data</anno></c> is an invalid I/O list.
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="port_command" arity="3"/>
- <fsummary>Send data to a port</fsummary>
+ <fsummary>Sends data to a port.</fsummary>
<desc>
<p>Sends data to a port. <c>port_command(Port, Data, [])</c>
equals <c>port_command(Port, Data)</c>.</p>
- <p>If the port command is aborted <c>false</c> is returned;
- otherwise, <c>true</c> is returned.</p>
- <p>If the port is busy, the calling process will be suspended
- until the port is not busy anymore.</p>
- <p>Currently the following <c><anno>Option</anno></c>s are valid:</p>
+ <p>If the port command is aborted, <c>false</c> is returned,
+ otherwise <c>true</c>.</p>
+ <p>If the port is busy, the calling process is suspended
+ until the port is not busy any more.</p>
+ <p>The following <c><anno>Option</anno></c>s are valid:</p>
<taglist>
<tag><c>force</c></tag>
- <item>The calling process will not be suspended if the port is
- busy; instead, the port command is forced through. The
- call will fail with a <c>notsup</c> exception if the
+ <item>The calling process is not suspended if the port is
+ busy, instead the port command is forced through. The
+ call fails with a <c>notsup</c> exception if the
driver of the port does not support this. For more
- information see the
- <seealso marker="driver_entry#driver_flags"><![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]></seealso>
- driver flag.
+ information, see driver flag
+ <seealso marker="driver_entry#driver_flags"><![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]></seealso>.
</item>
<tag><c>nosuspend</c></tag>
- <item>The calling process will not be suspended if the port is
- busy; instead, the port command is aborted and
+ <item>The calling process is not suspended if the port is
+ busy, instead the port command is aborted and
<c>false</c> is returned.
</item>
</taglist>
<note>
- <p>More options may be added in the future.</p>
+ <p>More options can be added in a future release.</p>
</note>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
<item>
If <c><anno>Port</anno></c> is not an identifier of an open
- port, or the registered name of an open port. If the calling
- process was linked to the previously open port identified by
- <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to this exception.
+ port, or the registered name of an open port. If the
+ calling process was previously linked to the closed port,
+ identified by <c><anno>Port</anno></c>, the exit signal
+ from the port is guaranteed to be delivered before this
+ <c>badarg</c> exception occurs.
</item>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>Data</anno></c> is not a valid io list.
+ If <c><anno>Data</anno></c> is an invalid I/O list.
</item>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>OptionList</anno></c> is not a valid option list.
+ If <c><anno>OptionList</anno></c> is an invalid option list.
</item>
<tag><c>notsup</c></tag>
<item>
- If the <c>force</c> option has been passed, but the
+ If option <c>force</c> has been passed, but the
driver of the port does not allow forcing through
a busy port.
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="port_connect" arity="2"/>
- <fsummary>Set the owner of a port</fsummary>
+ <fsummary>Sets the owner of a port.</fsummary>
<desc>
<p>Sets the port owner (the connected port) to <c><anno>Pid</anno></c>.
- Roughly the same as <c><anno>Port</anno> ! {Owner, {connect, <anno>Pid</anno>}}</c>
+ Roughly the same as
+ <c><anno>Port</anno> ! {Owner, {connect, <anno>Pid</anno>}}</c>
except for the following:</p>
<list type="bulleted">
<item>
- <p>The error behavior differs, see below.</p>
+ <p>The error behavior differs, see the following.</p>
</item>
<item>
<p>The port does <em>not</em> reply with
<c>{Port,connected}</c>.</p>
</item>
<item>
- <p><c>port_connect/1</c> is synchronous, see below.</p>
+ <p><c>port_connect/1</c> is synchronous, see the following.</p>
</item>
<item>
<p>The new port owner gets linked to the port.</p>
</item>
</list>
- <p>The old port owner stays linked to the port and have to call
- <c>unlink(Port)</c> if this is not desired. Any process may
+ <p>The old port owner stays linked to the port and must call
+ <c>unlink(Port)</c> if this is not desired. Any process can
set the port owner to be any process with
<c>port_connect/2</c>.</p>
- <p>For comparison: <c><anno>Port</anno> ! {self(), {connect, <anno>Pid</anno>}}</c> fails
- with <c>badarg</c> if <c><anno>Port</anno></c> cannot be sent to (i.e.,
- <c><anno>Port</anno></c> refers neither to a port nor to a process). If
- <c><anno>Port</anno></c> is a closed port nothing happens. If <c><anno>Port</anno></c>
+ <p>For comparison:
+ <c><anno>Port</anno> ! {self(), {connect, <anno>Pid</anno>}}</c>
+ only fails with <c>badarg</c> if <c><anno>Port</anno></c>
+ does not refer to a port or a process. If
+ <c><anno>Port</anno></c> is a closed port, nothing happens.
+ If <c><anno>Port</anno></c>
is an open port and the calling process is the port owner,
the port replies with <c>{Port, connected}</c> to the old
- port owner. Note that the old port owner is still linked to
- the port, and that the new is not. If <c><anno>Port</anno></c> is an open
+ port owner. Notice that the old port owner is still linked to
+ the port, while the new is not. If <c><anno>Port</anno></c> is an open
port and the calling process is not the port owner,
the <em>port owner</em> fails with <c>badsig</c>. The port
owner fails with <c>badsig</c> also if <c><anno>Pid</anno></c> is not an
- existing local pid.</p>
- <p>Note that any process can set the port owner using
- <c><anno>Port</anno> ! {PortOwner, {connect, <anno>Pid</anno>}}</c> just as if it
- itself was the port owner, but the reply always goes to
+ existing local process identifier.</p>
+ <p>Notice that any process can set the port owner using
+ <c><anno>Port</anno> ! {PortOwner, {connect, <anno>Pid</anno>}}</c>
+ as if it itself was the port owner, but the reply always goes to
the port owner.</p>
- <p>As of OTP-R16 <c><anno>Port</anno> ! {PortOwner, {connect, <anno>Pid</anno>}}</c> is
- truly asynchronous. Note that this operation has always been
+ <p>As from OTP-R16,
+ <c><anno>Port</anno> ! {PortOwner, {connect, <anno>Pid</anno>}}</c> is
+ truly asynchronous. Notice that this operation has always been
documented as an asynchronous operation, while the underlying
implementation has been synchronous. <c>port_connect/2</c> is
- however still fully synchronous. This due to its error
+ however still fully synchronous. This because of its error
behavior.</p>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>Port</anno></c> is not an identifier of an open
- port, or the registered name of an open port. If the calling
- process was linked to the previously open port identified by
- <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to this exception.
+ If <c><anno>Port</anno></c> is not an identifier of an open port, or
+ the registered name of an open port. If the calling
+ process was previously linked to the closed port,
+ identified by <c><anno>Port</anno></c>, the exit signal
+ from the port is guaranteed to be delivered before this
+ <c>badarg</c> exception occurs.
</item>
<tag><c>badarg</c></tag>
<item>If process identified by <c>Pid</c> is not an existing
@@ -3358,53 +3852,75 @@ os_prompt% </pre>
</taglist>
</desc>
</func>
+
<func>
<name name="port_control" arity="3"/>
- <fsummary>Perform a synchronous control operation on a port</fsummary>
+ <fsummary>Performs a synchronous control operation on a port.</fsummary>
<desc>
<p>Performs a synchronous control operation on a port.
- The meaning of <c><anno>Operation</anno></c> and <c><anno>Data</anno></c> depends on
- the port, i.e., on the port driver. Not all port drivers
+ The meaning of <c><anno>Operation</anno></c> and
+ <c><anno>Data</anno></c> depends on
+ the port, that is, on the port driver. Not all port drivers
support this control feature.</p>
- <p>Returns: a list of integers in the range 0 through 255, or a
+ <p>Returns a list of integers in the range 0..255, or a
binary, depending on the port driver. The meaning of
the returned data also depends on the port driver.</p>
- <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an open port or
- the registered name of an open port, if <c><anno>Operation</anno></c>
- cannot fit in a 32-bit integer, if the port driver does not
- support synchronous control operations, or if the port driver
- so decides for any reason (probably something wrong with
- <c><anno>Operation</anno></c> or <c><anno>Data</anno></c>).</p>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c><anno>Port</anno></c> is not an open port or the registered
+ name of an open port.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c><anno>Operation</anno></c> cannot fit in a 32-bit integer.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If the port driver does not support synchronous control
+ operations.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If the port driver so decides for any reason (probably
+ something wrong with <c><anno>Operation</anno></c> or
+ <c><anno>Data</anno></c>).
+ </item>
+ </taglist>
</desc>
</func>
+
<func>
<name name="port_call" arity="3"/>
- <fsummary>Synchronous call to a port with term data</fsummary>
+ <fsummary>Performs a synchronous call to a port with term data.</fsummary>
<desc>
<p>Performs a synchronous call to a port. The meaning of
- <c><anno>Operation</anno></c> and <c><anno>Data</anno></c> depends on the port, i.e.,
+ <c><anno>Operation</anno></c> and <c><anno>Data</anno></c>
+ depends on the port, that is,
on the port driver. Not all port drivers support this feature.</p>
- <p><c><anno>Port</anno></c> is a port identifier, referring to a driver.</p>
+ <p><c><anno>Port</anno></c> is a port identifier,
+ referring to a driver.</p>
<p><c><anno>Operation</anno></c> is an integer, which is passed on to
the driver.</p>
- <p><c><anno>Data</anno></c> is any Erlang term. This data is converted to
- binary term format and sent to the port.</p>
- <p>Returns: a term from the driver. The meaning of the returned
+ <p><c><anno>Data</anno></c> is any Erlang term. This data is converted
+ to binary term format and sent to the port.</p>
+ <p>Returns a term from the driver. The meaning of the returned
data also depends on the port driver.</p>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>Port</anno></c> is not an identifier of an open
- port, or the registered name of an open port. If the calling
- process was linked to the previously open port identified by
- <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to this exception.
+ If <c><anno>Port</anno></c> is not an identifier of an open port,
+ or the registered name of an open port. If the calling
+ process was previously linked to the closed port,
+ identified by <c><anno>Port</anno></c>, the exit signal
+ from the port is guaranteed to be delivered before this
+ <c>badarg</c> exception occurs.
</item>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>Operation</anno></c> does not fit in a
- 32-bit integer.
+ If <c><anno>Operation</anno></c> does not fit in a 32-bit integer.
</item>
<tag><c>badarg</c></tag>
<item>
@@ -3414,171 +3930,183 @@ os_prompt% </pre>
<tag><c>badarg</c></tag>
<item>
If the port driver so decides for any reason (probably
- something wrong with <c><anno>Operation</anno></c>, or
- <c><anno>Data</anno></c>).
+ something wrong with <c><anno>Operation</anno></c>
+ or <c><anno>Data</anno></c>).
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="port_info" arity="1"/>
- <fsummary>Information about a port</fsummary>
+ <fsummary>Information about a port.</fsummary>
<desc>
<p>Returns a list containing tuples with information about
- the <c><anno>Port</anno></c>, or <c>undefined</c> if the port is not open.
- The order of the tuples is not defined, nor are all the
- tuples mandatory.
- If <c>undefined</c> is returned and the calling process
- was linked to a previously open port identified by
- <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/1</c>.</p>
- <p>Currently the result will containt information about the
- following <c>Item</c>s: <c>registered_name</c> (if the port has
- a registered name), <c>id</c>, <c>connected</c>, <c>links</c>,
- <c>name</c>, <c>input</c>, and <c>output</c>. For more information
- about the different <c>Item</c>s, see
+ <c><anno>Port</anno></c>, or <c>undefined</c> if the port is not open.
+ The order of the tuples is undefined, and all the
+ tuples are not mandatory.
+ 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/1</c>
+ returns <c>undefined</c>.</p>
+ <p>The result contains information about the following
+ <c>Item</c>s:</p>
+ <list type="bulleted">
+ <item><c>registered_name</c> (if the port has a registered
+ name)</item>
+ <item><c>id</c></item>
+ <item><c>connected</c></item>
+ <item><c>links</c></item>
+ <item><c>name</c></item>
+ <item><c>input</c></item>
+ <item><c>output</c></item>
+ </list>
+ <p>For more information about the different <c>Item</c>s, see
<seealso marker="#port_info/2">port_info/2</seealso>.</p>
<p>Failure: <c>badarg</c> if <c>Port</c> is not a local port
identifier, or an atom.</p>
</desc>
</func>
+
<func>
<name name="port_info" arity="2" clause_i="1"/>
- <fsummary>Information about the connected process of a port</fsummary>
+ <fsummary>Information about the connected process of a port.</fsummary>
<desc>
<p><c><anno>Pid</anno></c> is the process identifier of the process
connected to the port.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="2"/>
- <fsummary>Information about the internal index of a port</fsummary>
+ <fsummary>Information about the internal index of a port.</fsummary>
<desc>
<p><c><anno>Index</anno></c> is the internal index of the port. This
- index may be used to separate ports.</p>
+ index can be used to separate ports.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="3"/>
- <fsummary>Information about the input of a port</fsummary>
+ <fsummary>Information about the input of a port.</fsummary>
<desc>
<p><c><anno>Bytes</anno></c> is the total number of bytes
read from the port.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="4"/>
- <fsummary>Information about the links of a port</fsummary>
+ <fsummary>Information about the links of a port.</fsummary>
<desc>
<p><c><anno>Pids</anno></c> is a list of the process identifiers
of the processes that the port is linked to.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="5"/>
- <fsummary>Information about the locking of a port</fsummary>
+ <fsummary>Information about the locking of a port.</fsummary>
<desc>
- <p><c><anno>Locking</anno></c> is currently either <c>false</c>
- (emulator without SMP support), <c>port_level</c> (port specific
- locking), or <c>driver_level</c> (driver specific locking). Note
- that these results are highly implementation specific and might
- change in the future.</p>
+ <p><c><anno>Locking</anno></c> is one of the following:</p>
+ <list type="bulleted">
+ <item><c>false</c> (emulator without SMP support)</item>
+ <item><c>port_level</c> (port-specific locking)</item>
+ <item><c>driver_level</c> (driver-specific locking)</item>
+ </list>
+ <p>Notice that these results are highly implementation-specific
+ and can change in a future release.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="6"/>
- <fsummary>Information about the memory size of a port</fsummary>
+ <fsummary>Information about the memory size of a port.</fsummary>
<desc>
- <p><c><anno>Bytes</anno></c> is the total amount of memory,
- in bytes, allocated for this port by the runtime system. Note
- that the port itself might have allocated memory which is not
+ <p><c><anno>Bytes</anno></c> is the total number of
+ bytes allocated for this port by the runtime system. The
+ port itself can have allocated memory that is not
included in <c><anno>Bytes</anno></c>.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="7"/>
- <fsummary>Information about the monitors of a port</fsummary>
+ <fsummary>Information about the monitors of a port.</fsummary>
<desc>
<p><c><anno>Monitors</anno></c> represent processes that this port
- is monitoring.</p>
+ monitors.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="8"/>
- <fsummary>Information about the name of a port</fsummary>
+ <fsummary>Information about the name of a port.</fsummary>
<desc>
<p><c><anno>Name</anno></c> is the command name set by
<seealso marker="#open_port/2">open_port/2</seealso>.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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 OS pid of a port</fsummary>
+ <fsummary>Information about the OS pid of a port.</fsummary>
<desc>
<p><c><anno>OsPid</anno></c> is the process identifier (or equivalent)
of an OS process created with
@@ -3586,432 +4114,464 @@ os_prompt% </pre>
Command}, Options)</seealso>. If the port is not the result of spawning
an OS process, the value is <c>undefined</c>.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="10"/>
- <fsummary>Information about the output of a port</fsummary>
+ <fsummary>Information about the output of a port.</fsummary>
<desc>
<p><c><anno>Bytes</anno></c> is the total number of bytes written
- to the port from Erlang processes using either
+ to the port from Erlang processes using
<seealso marker="#port_command/2">port_command/2</seealso>,
<seealso marker="#port_command/3">port_command/3</seealso>,
- or <c><anno>Port</anno> ! {Owner, {command, Data}</c>.
- </p>
+ or <c><anno>Port</anno> ! {Owner, {command, Data}</c>.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="11"/>
- <fsummary>Information about the parallelism hint of a port</fsummary>
+ <fsummary>Information about the parallelism hint of a port.</fsummary>
<desc>
<p><c><anno>Boolean</anno></c> corresponds to the port parallelism
- hint being used by this port. For more information see
- the <seealso marker="#open_port_parallelism">parallelism</seealso>
- option of <seealso marker="#open_port/2">open_port/2</seealso>.</p>
+ hint being used by this port. For more information, see option
+ <seealso marker="#open_port_parallelism">parallelism</seealso>
+ of <seealso marker="#open_port/2">open_port/2</seealso>.</p>
</desc>
</func>
+
<func>
<name name="port_info" arity="2" clause_i="12"/>
- <fsummary>Information about the queue size of a port</fsummary>
+ <fsummary>Information about the queue size of a port.</fsummary>
<desc>
- <p><c><anno>Bytes</anno></c> is the total amount of data,
- in bytes, queued by the port using the ERTS driver queue
+ <p><c><anno>Bytes</anno></c> is the total number
+ of bytes queued by the port using the <c>ERTS</c> driver queue
implementation.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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="13"/>
- <fsummary>Information about the registered name of a port</fsummary>
+ <fsummary>Information about the registered name of a port.</fsummary>
<desc>
<p><c><anno>RegisteredName</anno></c> is the registered name of
the port. If the port has no registered name, <c>[]</c> is returned.</p>
<p>If the port identified by <c><anno>Port</anno></c> is not open,
- <c>undefined</c> is returned. If <c>undefined</c> is returned and
- the calling process was linked to a previously open port identified
- by <c><anno>Port</anno></c>, an exit signal due to this link
- was received by the process prior to the return from
- <c>port_info/2</c>.</p>
+ <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_to_list" arity="1"/>
- <fsummary>Text representation of a port identifier</fsummary>
+ <fsummary>Text representation of a port identifier.</fsummary>
<desc>
- <p>Returns a string which corresponds to the text
+ <p>Returns a string corresponding to the text
representation of the port identifier <c><anno>Port</anno></c>.</p>
<warning>
- <p>This BIF is intended for debugging and for use in
- the Erlang operating system. It should not be used in
- application programs.</p>
+ <p>This BIF is intended for debugging. It is not to be used
+ in application programs.</p>
</warning>
</desc>
</func>
+
<func>
<name name="ports" arity="0"/>
- <fsummary>All open ports</fsummary>
+ <fsummary>Lists all existing ports.</fsummary>
<desc>
<p>Returns a list of port identifiers corresponding to all the
- ports currently existing on the local node.</p>
-
- <p>Note that a port that is exiting, exists but is not open.</p>
+ ports existing on the local node.</p>
+ <p>Notice that an exiting port exists, but is not open.</p>
</desc>
</func>
+
<func>
<name name="pre_loaded" arity="0"/>
- <fsummary>List of all pre-loaded modules</fsummary>
+ <fsummary>Lists all pre-loaded modules.</fsummary>
<desc>
- <p>Returns a list of Erlang modules which are pre-loaded in
+ <p>Returns a list of Erlang modules that are preloaded in
the system. As all loading of code is done through the file
system, the file system must have been loaded previously.
- Hence, at least the module <c>init</c> must be pre-loaded.</p>
+ Hence, at least the module <c>init</c> must be preloaded.</p>
</desc>
</func>
+
<func>
<name name="process_display" arity="2"/>
- <fsummary>Write information about a local process on standard error</fsummary>
+ <fsummary>Writes information about a local process on standard error.</fsummary>
<desc>
<p>Writes information about the local process <c><anno>Pid</anno></c> on
- standard error. The currently allowed value for the atom
+ standard error. The only allowed value for the atom
<c><anno>Type</anno></c> is <c>backtrace</c>, which shows the contents of
the call stack, including information about the call chain, with
the current function printed first. The format of the output
is not further defined.</p>
</desc>
</func>
+
<func>
<name name="process_flag" arity="2" clause_i="1"/>
- <fsummary>Set process flag trap_exit for the calling process</fsummary>
+ <fsummary>Sets process flag <c>trap_exit</c> for the calling process.</fsummary>
<desc>
<p>When <c>trap_exit</c> is set to <c>true</c>, exit signals
- arriving to a process are converted to <c>{'EXIT', From, Reason}</c> messages, which can be received as ordinary
+ arriving to a process are converted to <c>{'EXIT', From, Reason}</c>
+ messages, which can be received as ordinary
messages. If <c>trap_exit</c> is set to <c>false</c>, the
process exits if it receives an exit signal other than
<c>normal</c> and the exit signal is propagated to its
- linked processes. Application processes should normally
- not trap exits.</p>
+ linked processes. Application processes are normally
+ not to trap exits.</p>
<p>Returns the old value of the flag.</p>
<p>See also <seealso marker="#exit/2">exit/2</seealso>.</p>
</desc>
</func>
+
<func>
<name name="process_flag" arity="2" clause_i="2"/>
- <fsummary>Set process flag error_handler for the calling process</fsummary>
+ <fsummary>Sets process flag <c>error_handler</c> for the calling process.</fsummary>
<desc>
- <p>This is used by a process to redefine the error handler
+ <p>Used by a process to redefine the error handler
for undefined function calls and undefined registered
- processes. Inexperienced users should not use this flag
- since code auto-loading is dependent on the correct
+ processes. Inexperienced users are not to use this flag,
+ as code auto-loading depends on the correct
operation of the error handling module.</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
<func>
<name name="process_flag" arity="2" clause_i="3"/>
- <fsummary>Set process flag min_heap_size for the calling process</fsummary>
+ <fsummary>Sets process flag <c>min_heap_size</c> for the calling process.</fsummary>
<desc>
- <p>This changes the minimum heap size for the calling
- process.</p>
+ <p>Changes the minimum heap size for the calling process.</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
<func>
<name name="process_flag" arity="2" clause_i="4"/>
- <fsummary>Set process flag min_bin_vheap_size for the calling process</fsummary>
+ <fsummary>Sets process flag <c>min_bin_vheap_size</c> for the calling process.</fsummary>
<desc>
- <p>This changes the minimum binary virtual heap size for the calling
+ <p>Changes the minimum binary virtual heap size for the calling
process.</p>
- <p>Returns the old value of the flag.</p> </desc>
+ <p>Returns the old value of the flag.</p>
+ </desc>
</func>
+
<func>
<name name="process_flag" arity="2" clause_i="5"/>
+ <fsummary>Sets process flag <c>priority</c> for the calling process.</fsummary>
<type name="priority_level"/>
- <fsummary>Set process flag priority for the calling process</fsummary>
<desc>
<p><marker id="process_flag_priority"></marker>
- This sets the process priority. <c><anno>Level</anno></c> is an atom.
- There are currently four priority levels: <c>low</c>,
- <c>normal</c>, <c>high</c>, and <c>max</c>. The default
- priority level is <c>normal</c>. <em>NOTE</em>: The
- <c>max</c> priority level is reserved for internal use in
- the Erlang runtime system, and should <em>not</em> be used
- by others.
- </p>
- <p>Internally in each priority level processes are scheduled
- in a round robin fashion.
- </p>
+ Sets the process priority. <c><anno>Level</anno></c> is an atom.
+ There are four priority levels: <c>low</c>,
+ <c>normal</c>, <c>high</c>, and <c>max</c>. Default
+ is <c>normal</c>.</p>
+ <note>
+ <p>Priority level <c>max</c> is reserved for internal use in
+ the Erlang runtime system, and is <em>not</em> to be used
+ by others.</p>
+ </note>
+ <p>Internally in each priority level, processes are scheduled
+ in a round robin fashion.</p>
<p>Execution of processes on priority <c>normal</c> and
- priority <c>low</c> will be interleaved. Processes on
- priority <c>low</c> will be selected for execution less
- frequently than processes on priority <c>normal</c>.
- </p>
- <p>When there are runnable processes on priority <c>high</c>
- no processes on priority <c>low</c>, or <c>normal</c> will
- be selected for execution. Note, however, that this does
- <em>not</em> mean that no processes on priority <c>low</c>,
- or <c>normal</c> will be able to run when there are
- processes on priority <c>high</c> running. On the runtime
- system with SMP support there might be more processes running
- in parallel than processes on priority <c>high</c>, i.e.,
- a <c>low</c>, and a <c>high</c> priority process might
- execute at the same time.
- </p>
- <p>When there are runnable processes on priority <c>max</c>
+ <c>low</c> are interleaved. Processes on priority
+ <c>low</c> are selected for execution less
+ frequently than processes on priority <c>normal</c>.</p>
+ <p>When there are runnable processes on priority <c>high</c>,
+ no processes on priority <c>low</c> or <c>normal</c> are
+ selected for execution. Notice however, that this does
+ <em>not</em> mean that no processes on priority <c>low</c>
+ or <c>normal</c> can run when there are processes
+ running on priority <c>high</c>. On the runtime
+ system with SMP support, more processes can be running
+ in parallel than processes on priority <c>high</c>, that is,
+ a <c>low</c> and a <c>high</c> priority process can
+ execute at the same time.</p>
+ <p>When there are runnable processes on priority <c>max</c>,
no processes on priority <c>low</c>, <c>normal</c>, or
- <c>high</c> will be selected for execution. As with the
- <c>high</c> priority, processes on lower priorities might
- execute in parallel with processes on priority <c>max</c>.
- </p>
+ <c>high</c> are selected for execution. As with priority
+ <c>high</c>, processes on lower priorities can
+ execute in parallel with processes on priority <c>max</c>.</p>
<p>Scheduling is preemptive. Regardless of priority, a process
- is preempted when it has consumed more than a certain amount
+ is preempted when it has consumed more than a certain number
of reductions since the last time it was selected for
- execution.
- </p>
- <p><em>NOTE</em>: You should not depend on the scheduling
+ execution.</p>
+ <note>
+ <p>Do not depend on the scheduling
to remain exactly as it is today. Scheduling, at least on
- the runtime system with SMP support, is very likely to be
- modified in the future in order to better utilize available
- processor cores.
- </p>
- <p>There is currently <em>no</em> automatic mechanism for
- avoiding priority inversion, such as priority inheritance,
- or priority ceilings. When using priorities you have
- to take this into account and handle such scenarios by
- yourself.
- </p>
+ the runtime system with SMP support, is likely to be
+ changed in a future release to use available
+ processor cores better.</p>
+ </note>
+ <p>There is <em>no</em> automatic mechanism for
+ avoiding priority inversion, such as priority inheritance
+ or priority ceilings. When using priorities,
+ take this into account and handle such scenarios by
+ yourself.</p>
<p>Making calls from a <c>high</c> priority process into code
- that you don't have control over may cause the <c>high</c>
- priority process to wait for a processes with lower
- priority, i.e., effectively decreasing the priority of the
+ that you have no control over can cause the <c>high</c>
+ priority process to wait for a process with lower
+ priority. That is, effectively decreasing the priority of the
<c>high</c> priority process during the call. Even if this
- isn't the case with one version of the code that you don't
- have under your control, it might be the case in a future
- version of it. This might, for example, happen if a
- <c>high</c> priority process triggers code loading, since
- the code server runs on priority <c>normal</c>.
- </p>
+ is not the case with one version of the code that you have no
+ control over, it can be the case in a future
+ version of it. This can, for example, occur if a
+ <c>high</c> priority process triggers code loading, as
+ the code server runs on priority <c>normal</c>.</p>
<p>Other priorities than <c>normal</c> are normally not needed.
- When other priorities are used, they need to be used
- with care, especially the <c>high</c> priority <em>must</em>
- be used with care. A process on <c>high</c> priority should
- only perform work for short periods of time. Busy looping for
- long periods of time in a <c>high</c> priority process will
- most likely cause problems, since there are important servers
- in OTP running on priority <c>normal</c>.
- </p>
+ When other priorities are used, use them with care,
+ <em>especially</em> priority <c>high</c>. A
+ process on priority <c>high</c> is only
+ to perform work for short periods. Busy looping for
+ long periods in a <c>high</c> priority process does
+ most likely cause problems, as important OTP servers
+ run on priority <c>normal</c>.</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
<func>
<name name="process_flag" arity="2" clause_i="6"/>
- <fsummary>Set process flag save_calls for the calling process</fsummary>
+ <fsummary>Sets process flag <c>save_calls</c> for the calling process.</fsummary>
<desc>
<p><c><anno>N</anno></c> must be an integer in the interval 0..10000.
- If <c><anno>N</anno></c> &gt; 0, call saving is made active for the
- process, which means that information about the <c><anno>N</anno></c>
- most recent global function calls, BIF calls, sends and
+ If <c><anno>N</anno></c> is greater than 0, call saving is made
+ active for the
+ process. This means that information about the <c><anno>N</anno></c>
+ most recent global function calls, BIF calls, sends, and
receives made by the process are saved in a list, which
can be retrieved with
<c>process_info(Pid, last_calls)</c>. A global function
call is one in which the module of the function is
explicitly mentioned. Only a fixed amount of information
- is saved: a tuple <c>{Module, Function, Arity}</c> for
- function calls, and the mere atoms <c>send</c>,
- <c>'receive'</c> and <c>timeout</c> for sends and receives
- (<c>'receive'</c> when a message is received and
- <c>timeout</c> when a receive times out). If <c>N</c> = 0,
+ is saved, as follows:</p>
+ <list type="bulleted">
+ <item>A tuple <c>{Module, Function, Arity}</c> for
+ function calls</item>
+ <item> The atoms <c>send</c>, <c>'receive'</c>, and
+ <c>timeout</c> for sends and receives (<c>'receive'</c>
+ when a message is received and <c>timeout</c> when a
+ receive times out)</item>
+ </list>
+ <p>If <c>N</c> = 0,
call saving is disabled for the process, which is the
default. Whenever the size of the call saving list is set,
its contents are reset.</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
<func>
<name name="process_flag" arity="2" clause_i="7"/>
- <fsummary>Set process flag sensitive for the calling process</fsummary>
+ <fsummary>Sets process flag <c>sensitive</c> for the calling process.</fsummary>
<desc>
- <p>Set or clear the <c>sensitive</c> flag for the current process.
+ <p>Sets or clears flag <c>sensitive</c> for the current process.
When a process has been marked as sensitive by calling
- <c>process_flag(sensitive, true)</c>, features in the run-time
- system that can be used for examining the data and/or inner working
+ <c>process_flag(sensitive, true)</c>, features in the runtime
+ system that can be used for examining the data or inner working
of the process are silently disabled.</p>
<p>Features that are disabled include (but are not limited to)
the following:</p>
- <p>Tracing: Trace flags can still be set for the process, but no
- trace messages of any kind will be generated.
- (If the <c>sensitive</c> flag is turned off, trace messages will
- again be generated if there are any trace flags set.)</p>
- <p>Sequential tracing: The sequential trace token will be propagated
- as usual, but no sequential trace messages will be generated.</p>
- <p><c>process_info/1,2</c> cannot be used to read out the message
- queue or the process dictionary (both will be returned as empty lists).</p>
+ <list type="bulleted">
+ <item>Tracing: Trace flags can still be set for the process,
+ but no trace messages of any kind are generated. (If flag
+ <c>sensitive</c> is turned off, trace messages are again
+ generated if any trace flags are set.)</item>
+ <item>Sequential tracing: The sequential trace token is
+ propagated as usual, but no sequential trace messages are
+ generated.</item>
+ </list>
+ <p><c>process_info/1,2</c> cannot be used to read out the
+ message queue or the process dictionary (both are returned
+ as empty lists).</p>
<p>Stack back-traces cannot be displayed for the process.</p>
<p>In crash dumps, the stack, messages, and the process dictionary
- will be omitted.</p>
+ are omitted.</p>
<p>If <c>{save_calls,N}</c> has been set for the process, no
- function calls will be saved to the call saving list.
- (The call saving list will not be cleared; furthermore, send, receive,
- and timeout events will still be added to the list.)</p>
+ function calls are saved to the call saving list.
+ (The call saving list is not cleared. Furthermore, send, receive,
+ and timeout events are still added to the list.)</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
<func>
<name name="process_flag" arity="3"/>
- <fsummary>Set process flags for a process</fsummary>
+ <fsummary>Sets process flags for a process.</fsummary>
<desc>
- <p>Sets certain flags for the process <c><anno>Pid</anno></c>, in the same
- manner as
+ <p>Sets certain flags for the process <c><anno>Pid</anno></c>,
+ in the same manner as
<seealso marker="#process_flag/2">process_flag/2</seealso>.
- Returns the old value of the flag. The allowed values for
+ Returns the old value of the flag. The valid values for
<c><anno>Flag</anno></c> are only a subset of those allowed in
- <c>process_flag/2</c>, namely: <c>save_calls</c>.</p>
- <p>Failure: <c>badarg</c> if <c><anno>Pid</anno></c> is not a local process.</p>
+ <c>process_flag/2</c>, namely <c>save_calls</c>.</p>
+ <p>Failure: <c>badarg</c> if <c><anno>Pid</anno></c>
+ is not a local process.</p>
</desc>
</func>
+
<func>
<name name="process_info" arity="1"/>
+ <fsummary>Information about a process.</fsummary>
<type name="process_info_result_item"/>
<type name="priority_level"/>
<type name="stack_item"/>
- <fsummary>Information about a process</fsummary>
<desc>
<p>Returns a list containing <c><anno>InfoTuple</anno></c>s with
miscellaneous information about the process identified by
- <c>Pid</c>, or <c>undefined</c> if the process is not alive.
- </p>
- <p>
- The order of the <c><anno>InfoTuple</anno></c>s is not defined, nor
- are all the <c><anno>InfoTuple</anno></c>s mandatory. The <c><anno>InfoTuple</anno></c>s
- part of the result may be changed without prior notice.
- Currently <c><anno>InfoTuple</anno></c>s with the following items
- are part of the result:
- <c>current_function</c>, <c>initial_call</c>, <c>status</c>,
- <c>message_queue_len</c>, <c>messages</c>, <c>links</c>,
- <c>dictionary</c>, <c>trap_exit</c>, <c>error_handler</c>,
- <c>priority</c>, <c>group_leader</c>, <c>total_heap_size</c>,
- <c>heap_size</c>, <c>stack_size</c>, <c>reductions</c>, and
- <c>garbage_collection</c>.
- If the process identified by <c><anno>Pid</anno></c> has a registered name
- also an <c><anno>InfoTuple</anno></c> with the item <c>registered_name</c>
- will appear.
- </p>
- <p>See <seealso marker="#process_info/2">process_info/2</seealso>
- for information about specific <c><anno>InfoTuple</anno></c>s.</p>
+ <c>Pid</c>, or <c>undefined</c> if the process is not alive.</p>
+ <p>The order of the <c><anno>InfoTuple</anno></c>s is undefined and
+ all <c><anno>InfoTuple</anno></c>s are not mandatory.
+ The <c><anno>InfoTuple</anno></c>s
+ part of the result can be changed without prior notice.</p>
+ <p>The <c><anno>InfoTuple</anno></c>s with the following items
+ are part of the result:</p>
+ <list type="bulleted">
+ <item><c>current_function</c></item>
+ <item><c>initial_call</c></item>
+ <item><c>status</c></item>
+ <item><c>message_queue_len</c></item>
+ <item><c>messages</c></item>
+ <item><c>links</c></item>
+ <item><c>dictionary</c></item>
+ <item><c>trap_exit</c></item>
+ <item><c>error_handler</c></item>
+ <item><c>priority</c></item>
+ <item><c>group_leader</c></item>
+ <item><c>total_heap_size</c></item>
+ <item><c>heap_size</c></item>
+ <item><c>stack_size</c></item>
+ <item><c>reductions</c></item>
+ <item><c>garbage_collection</c></item>
+ </list>
+ <p>If the process identified by <c><anno>Pid</anno></c> has a
+ registered name,
+ also an <c><anno>InfoTuple</anno></c> with item <c>registered_name</c>
+ appears.</p>
+ <p>For information about specific <c><anno>InfoTuple</anno></c>s, see
+ <seealso marker="#process_info/2">process_info/2</seealso>.</p>
<warning>
- <p>This BIF is intended for <em>debugging only</em>, use
- <seealso marker="#process_info/2">process_info/2</seealso>
- for all other purposes.
- </p>
+ <p>This BIF is intended for <em>debugging only</em>. For
+ all other purposes, use
+ <seealso marker="#process_info/2">process_info/2</seealso>.</p>
</warning>
- <p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process.</p>
+ <p>Failure: <c>badarg</c> if <c><anno>Pid</anno></c> is not a
+ local process.</p>
</desc>
</func>
+
<func>
<name name="process_info" arity="2" clause_i="1"/>
<name name="process_info" arity="2" clause_i="2"/>
+ <fsummary>Information about a process.</fsummary>
<type name="process_info_item"/>
<type name="process_info_result_item"/>
<type name="stack_item"/>
<type name="priority_level"/>
- <fsummary>Information about a process</fsummary>
<desc>
- <p>Returns information about the process identified by <c><anno>Pid</anno></c>
- as specified by the <c><anno>Item</anno></c> or the <c><anno>ItemList</anno></c>, or <c>undefined</c> if the
- process is not alive.
- </p>
- <p>If the process is alive and a single <c><anno>Item</anno></c> is given,
- the returned value is the corresponding
- <c><anno>InfoTuple</anno></c> unless <c>Item =:= registered_name</c>
- and the process has no registered name. In this case
- <c>[]</c> is returned. This strange behavior is due to
- historical reasons, and is kept for backward compatibility.
- </p>
- <p>If an <c>ItemList</c> is given, the result is an
- <c><anno>InfoTupleList</anno></c>. The <c><anno>InfoTuple</anno></c>s in the
- <c><anno>InfoTupleList</anno></c> will appear with the corresponding
- <c><anno>Item</anno></c>s in the same order as the <c><anno>Item</anno></c>s appeared
- in the <c><anno>ItemList</anno></c>. Valid <c><anno>Item</anno></c>s may appear multiple
- times in the <c><anno>ItemList</anno></c>.
- </p>
- <note><p>If <c>registered_name</c> is part of an <c><anno>ItemList</anno></c>
+ <p>Returns information about the process identified by
+ <c><anno>Pid</anno></c>, as specified by
+ <c><anno>Item</anno></c> or <c><anno>ItemList</anno></c>.
+ Returns <c>undefined</c> if the process is not alive.</p>
+ <p>If the process is alive and a single <c><anno>Item</anno></c>
+ is given, the returned value is the corresponding
+ <c><anno>InfoTuple</anno></c>, unless <c>Item =:= registered_name</c>
+ and the process has no registered name. In this case,
+ <c>[]</c> is returned. This strange behavior is because of
+ historical reasons, and is kept for backward compatibility.</p>
+ <p>If <c><anno>ItemList</anno></c> is given, the result is
+ <c><anno>InfoTupleList</anno></c>.
+ The <c><anno>InfoTuple</anno></c>s in
+ <c><anno>InfoTupleList</anno></c> appear with the corresponding
+ <c><anno>Item</anno></c>s in the same order as the
+ <c><anno>Item</anno></c>s appeared
+ in <c><anno>ItemList</anno></c>. Valid <c><anno>Item</anno></c>s can
+ appear multiple times in <c><anno>ItemList</anno></c>.</p>
+ <note><p>If <c>registered_name</c> is part of <c><anno>ItemList</anno></c>
and the process has no name registered a
- <c>{registered_name, []}</c> <c><anno>InfoTuple</anno></c> <em>will</em>
- appear in the resulting <c><anno>InfoTupleList</anno></c>. This
- behavior is different than when a single
- <c>Item =:= registered_name</c> is given, and than when
- <c>process_info/1</c> is used.
- </p></note>
- <p>Currently the following <c><anno>InfoTuple</anno></c>s with corresponding
+ <c>{registered_name, []}</c>, <c><anno>InfoTuple</anno></c>
+ <em>will</em> appear in the resulting
+ <c><anno>InfoTupleList</anno></c>. This
+ behavior is different when a single
+ <c>Item =:= registered_name</c> is given, and when
+ <c>process_info/1</c> is used.</p>
+ </note>
+ <p>The following <c><anno>InfoTuple</anno></c>s with corresponding
<c><anno>Item</anno></c>s are valid:</p>
<taglist>
<tag><c>{backtrace, <anno>Bin</anno>}</c></tag>
<item>
- <p>The binary <c><anno>Bin</anno></c> contains the same information as
- the output from
+ <p>Binary <c><anno>Bin</anno></c> contains the same information
+ as the output from
<c>erlang:process_display(<anno>Pid</anno>, backtrace)</c>. Use
<c>binary_to_list/1</c> to obtain the string of characters
from the binary.</p>
</item>
<tag><c>{binary, <anno>BinInfo</anno>}</c></tag>
<item>
- <p><c><anno>BinInfo</anno></c> is a list containing miscellaneous information
- about binaries currently being referred to by this process.
- This <c><anno>InfoTuple</anno></c> may be changed or removed without prior
- notice.</p>
+ <p><c><anno>BinInfo</anno></c> is a list containing miscellaneous
+ information about binaries currently being referred to by this
+ process. This <c><anno>InfoTuple</anno></c> can be changed or
+ removed without prior notice.</p>
</item>
<tag><c>{catchlevel, <anno>CatchLevel</anno>}</c></tag>
<item>
<p><c><anno>CatchLevel</anno></c> is the number of currently active
- catches in this process. This <c><anno>InfoTuple</anno></c> may be
+ catches in this process. This <c><anno>InfoTuple</anno></c> can be
changed or removed without prior notice.</p>
</item>
- <tag><c>{current_function, {<anno>Module</anno>, <anno>Function</anno>, <anno>Arity</anno>}}</c></tag>
+ <tag><c>{current_function, {<anno>Module</anno>,
+ <anno>Function</anno>, Arity}}</c></tag>
<item>
- <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>, <c><anno>Arity</anno></c> is
+ <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>,
+ <c><anno>Arity</anno></c> is
the current function call of the process.</p>
</item>
- <tag><c>{current_location, {<anno>Module</anno>, <anno>Function</anno>, <anno>Arity</anno>, <anno>Location</anno>}}</c></tag>
+ <tag><c>{current_location, {<anno>Module</anno>,
+ <anno>Function</anno>, <anno>Arity</anno>,
+ <anno>Location</anno>}}</c></tag>
<item>
- <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>, <c><anno>Arity</anno></c> is
+ <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>,
+ <c><anno>Arity</anno></c> is
the current function call of the process.
- <c><anno>Location</anno></c> is a list of two-tuples that describes the
- location in the source code.
- </p>
+ <c><anno>Location</anno></c> is a list of two-tuples describing the
+ location in the source code.</p>
</item>
<tag><c>{current_stacktrace, <anno>Stack</anno>}</c></tag>
<item>
- <p>Return the current call stack back-trace (<em>stacktrace</em>)
+ <p>Returns the current call stack back-trace (<em>stacktrace</em>)
of the process. The stack has the same format as returned by
- <seealso marker="#get_stacktrace/0">erlang:get_stacktrace/0</seealso>.
- </p>
+ <seealso marker="#get_stacktrace/0">erlang:get_stacktrace/0</seealso>.</p>
</item>
<tag><c>{dictionary, <anno>Dictionary</anno>}</c></tag>
<item>
- <p><c><anno>Dictionary</anno></c> is the dictionary of the process.</p>
+ <p><c><anno>Dictionary</anno></c> is the process dictionary.</p>
</item>
<tag><c>{error_handler, <anno>Module</anno>}</c></tag>
<item>
@@ -4020,34 +4580,36 @@ os_prompt% </pre>
</item>
<tag><c>{garbage_collection, <anno>GCInfo</anno>}</c></tag>
<item>
- <p><c><anno>GCInfo</anno></c> is a list which contains miscellaneous
+ <p><c><anno>GCInfo</anno></c> is a list containing miscellaneous
information about garbage collection for this process.
- The content of <c><anno>GCInfo</anno></c> may be changed without
+ The content of <c><anno>GCInfo</anno></c> can be changed without
prior notice.</p>
</item>
<tag><c>{group_leader, <anno>GroupLeader</anno>}</c></tag>
<item>
- <p><c><anno>GroupLeader</anno></c> is group leader for the IO of
+ <p><c><anno>GroupLeader</anno></c> is group leader for the I/O of
the process.</p>
</item>
<tag><c>{heap_size, <anno>Size</anno>}</c></tag>
<item>
- <p><c><anno>Size</anno></c> is the size in words of youngest heap generation
- of the process. This generation currently include the stack
- of the process. This information is highly implementation
- dependent, and may change if the implementation change.
- </p>
+ <p><c><anno>Size</anno></c> is the size in words of the youngest heap
+ generation of the process. This generation includes
+ the process stack. This information is highly
+ implementation-dependent, and can change if the
+ implementation changes.</p>
</item>
- <tag><c>{initial_call, {Module, Function, Arity}}</c></tag>
+ <tag><c>{initial_call, {<anno>Module</anno>, <anno>Function</anno>,
+ <anno>Arity</anno>}}</c></tag>
<item>
- <p><c>Module</c>, <c>Function</c>, <c>Arity</c> is
+ <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>,
+ <c><anno>Arity</anno></c> is
the initial function call with which the process was
spawned.</p>
</item>
<tag><c>{links, <anno>PidsAndPorts</anno>}</c></tag>
<item>
- <p><c><anno>PidsAndPorts</anno></c> is a list of pids and
- port identifiers, with processes or ports to which the process
+ <p><c><anno>PidsAndPorts</anno></c> is a list of process identifiers
+ and port identifiers, with processes or ports to which the process
has a link.</p>
</item>
<tag><c>{last_calls, false|Calls}</c></tag>
@@ -4061,14 +4623,14 @@ os_prompt% </pre>
<tag><c>{memory, <anno>Size</anno>}</c></tag>
<item>
<p><c><anno>Size</anno></c> is the size in bytes of the process. This
- includes call stack, heap and internal structures.</p>
+ includes call stack, heap, and internal structures.</p>
</item>
<tag><c>{message_queue_len, <anno>MessageQueueLen</anno>}</c></tag>
<item>
<p><c><anno>MessageQueueLen</anno></c> is the number of messages
currently in the message queue of the process. This is
the length of the list <c><anno>MessageQueue</anno></c> returned as
- the info item <c>messages</c> (see below).</p>
+ the information item <c>messages</c> (see the following).</p>
</item>
<tag><c>{messages, <anno>MessageQueue</anno>}</c></tag>
<item>
@@ -4077,31 +4639,35 @@ os_prompt% </pre>
</item>
<tag><c>{min_heap_size, <anno>MinHeapSize</anno>}</c></tag>
<item>
- <p><c><anno>MinHeapSize</anno></c> is the minimum heap size for the process.</p>
+ <p><c><anno>MinHeapSize</anno></c> is the minimum heap size
+ for the process.</p>
</item>
<tag><c>{min_bin_vheap_size, <anno>MinBinVHeapSize</anno>}</c></tag>
<item>
- <p><c><anno>MinBinVHeapSize</anno></c> is the minimum binary virtual heap size for the process.</p>
+ <p><c><anno>MinBinVHeapSize</anno></c> is the minimum binary virtual
+ heap size for the process.</p>
</item>
<tag><c>{monitored_by, <anno>Pids</anno>}</c></tag>
<item>
- <p>A list of pids that are monitoring the process (with
+ <p>A list of process identifiers monitoring the process (with
<c>monitor/2</c>).</p>
</item>
<tag><c>{monitors, <anno>Monitors</anno>}</c></tag>
<item>
<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 pid, the list item
- is <c>{process, <anno>Pid</anno>}</c>, and for a remote 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>
</item>
- <tag><c>{priority, Level}</c></tag>
+ <tag><c>{priority, <anno>Level</anno>}</c></tag>
<item>
<p><c><anno>Level</anno></c> is the current priority level for
- the process. For more information on priorities see
- <seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p>
+ the process. For more information on priorities, see
+ <seealso marker="#process_flag_priority">process_flag(priority,
+ Level)</seealso>.</p>
</item>
<tag><c>{reductions, <anno>Number</anno>}</c></tag>
<item>
@@ -4116,240 +4682,346 @@ os_prompt% </pre>
</item>
<tag><c>{sequential_trace_token, [] | <anno>SequentialTraceToken</anno>}</c></tag>
<item>
- <p><c><anno>SequentialTraceToken</anno></c> the sequential trace token for
- the process. This <c><anno>InfoTuple</anno></c> may be changed or removed
- without prior notice.</p>
+ <p><c><anno>SequentialTraceToken</anno></c> is the sequential trace
+ token for the process. This <c><anno>InfoTuple</anno></c> can be
+ changed or removed without prior notice.</p>
</item>
<tag><c>{stack_size, <anno>Size</anno>}</c></tag>
<item>
- <p><c><anno>Size</anno></c> is the stack size of the process in words.</p>
+ <p><c><anno>Size</anno></c> is the stack size, in words,
+ of the process.</p>
</item>
<tag><c>{status, <anno>Status</anno>}</c></tag>
<item>
- <p><c><anno>Status</anno></c> is the status of the process. <c><anno>Status</anno></c>
- is <c>exiting</c>, <c>garbage_collecting</c>,
- <c>waiting</c> (for a message), <c>running</c>,
- <c>runnable</c> (ready to run, but another process is
- running), or <c>suspended</c> (suspended on a "busy" port
- or by the <c>erlang:suspend_process/[1,2]</c> BIF).</p>
+ <p><c><anno>Status</anno></c> is the status of the process and is one
+ of the following:</p>
+ <list type="bulleted">
+ <item><c>exiting</c></item>
+ <item><c>garbage_collecting</c></item>
+ <item><c>waiting</c> (for a message)</item>
+ <item><c>running</c></item>
+ <item><c>runnable</c> (ready to run, but another process is
+ running)</item>
+ <item><c>suspended</c> (suspended on a "busy" port
+ or by the BIF <c>erlang:suspend_process/[1,2]</c>)</item>
+ </list>
</item>
<tag><c>{suspending, <anno>SuspendeeList</anno>}</c></tag>
<item>
- <p><c><anno>SuspendeeList</anno></c> is a list of <c>{<anno>Suspendee</anno>,
- <anno>ActiveSuspendCount</anno>, <anno>OutstandingSuspendCount</anno>}</c> tuples.
- <c><anno>Suspendee</anno></c> is the pid of a process that have been or is to
- be suspended by the process identified by <c><anno>Pid</anno></c> via the
- <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>
- BIF, or the
- <seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso>
- BIF. <c><anno>ActiveSuspendCount</anno></c> is the number of times the
- <c><anno>Suspendee</anno></c> has been suspended by <c><anno>Pid</anno></c>.
+ <p><c><anno>SuspendeeList</anno></c> is a list of
+ <c>{<anno>Suspendee</anno>, <anno>ActiveSuspendCount</anno>,
+ <anno>OutstandingSuspendCount</anno>}</c> tuples.
+ <c><anno>Suspendee</anno></c> is the process identifier of a
+ process that has been, or is to be,
+ suspended by the process identified by <c><anno>Pid</anno></c>
+ through one of the following BIFs:</p>
+ <list type="bulleted">
+ <item>
+ <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>
+ </item>
+ <item>
+ <seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso>
+ </item>
+ </list>
+ <p><c><anno>ActiveSuspendCount</anno></c> is the number of
+ times <c><anno>Suspendee</anno></c> has been suspended by
+ <c><anno>Pid</anno></c>.
<c><anno>OutstandingSuspendCount</anno></c> is the number of not yet
- completed suspend requests sent by <c><anno>Pid</anno></c>. That is,
- if <c><anno>ActiveSuspendCount</anno> =/= 0</c>, <c><anno>Suspendee</anno></c> is
- currently in the suspended state, and if
- <c><anno>OutstandingSuspendCount</anno> =/= 0</c> the <c>asynchronous</c>
- option of <c>erlang:suspend_process/2</c> has been used and
- the suspendee has not yet been suspended by <c><anno>Pid</anno></c>.
- Note that the <c><anno>ActiveSuspendCount</anno></c> and
- <c><anno>OutstandingSuspendCount</anno></c> are not the total suspend count
- on <c><anno>Suspendee</anno></c>, only the parts contributed by <c>Pid</c>.
- </p>
+ completed suspend requests sent by <c><anno>Pid</anno></c>, that is:</p>
+ <list type="bulleted">
+ <item>If <c><anno>ActiveSuspendCount</anno> =/= 0</c>,
+ <c><anno>Suspendee</anno></c> is
+ currently in the suspended state.
+ </item>
+ <item>If <c><anno>OutstandingSuspendCount</anno> =/= 0</c>, option
+ <c>asynchronous</c> of <c>erlang:suspend_process/2</c>
+ has been used and the suspendee has not yet been
+ suspended by <c><anno>Pid</anno></c>.
+ </item>
+ </list>
+ <p>Notice that <c><anno>ActiveSuspendCount</anno></c> and
+ <c><anno>OutstandingSuspendCount</anno></c> are not the
+ total suspend count on <c><anno>Suspendee</anno></c>,
+ only the parts contributed by <c><anno>Pid</anno></c>.</p>
</item>
<tag><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 currently include the stack
- of the process.
- </p>
+ <p><c><anno>Size</anno></c> is the total size, in words, of all heap
+ fragments of the process. This includes the process stack.</p>
</item>
<tag><c>{trace, <anno>InternalTraceFlags</anno>}</c></tag>
<item>
- <p><c><anno>InternalTraceFlags</anno></c> is an integer representing
- internal trace flag for this process. This <c><anno>InfoTuple</anno></c>
- may be changed or removed without prior notice.</p>
+ <p><c><anno>InternalTraceFlags</anno></c> is an integer
+ representing the internal trace flag for this process.
+ This <c><anno>InfoTuple</anno></c>
+ can be changed or removed without prior notice.</p>
</item>
<tag><c>{trap_exit, <anno>Boolean</anno>}</c></tag>
<item>
- <p><c><anno>Boolean</anno></c> is <c>true</c> if the process is trapping
- exits, otherwise it is <c>false</c>.</p>
+ <p><c><anno>Boolean</anno></c> is <c>true</c> if the process
+ is trapping exits, otherwise <c>false</c>.</p>
</item>
</taglist>
- <p>Note however, that not all implementations support every one
- of the above <c><anno>Item</anno></c>s.</p>
- <p>Failure: <c>badarg</c> if <c><anno>Pid</anno></c> is not a local process,
- or if <c><anno>Item</anno></c> is not a valid <c><anno>Item</anno></c>.</p>
+ <p>Notice that not all implementations support all
+ these <c><anno>Item</anno></c>s.</p>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>Pid</anno></c> is not a local process.</item>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>Item</anno></c> is an invalid item.</item>
+ </taglist>
</desc>
</func>
+
<func>
<name name="processes" arity="0"/>
- <fsummary>All processes</fsummary>
+ <fsummary>All processes.</fsummary>
<desc>
<p>Returns a list of process identifiers corresponding to
- all the processes currently existing on the local node.
- </p>
- <p>Note that a process that is exiting, exists but is not alive, i.e.,
- <c>is_process_alive/1</c> will return <c>false</c> for a process
- that is exiting, but its process identifier will be part
- of the result returned from <c>processes/0</c>.
- </p>
+ all the processes currently existing on the local node.</p>
+ <p>Notice that an exiting process exists, but is not alive.
+ That is, <c>is_process_alive/1</c> returns <c>false</c>
+ for an exiting process, but its process identifier is part
+ of the result returned from <c>processes/0</c>.</p>
+ <p>Example:</p>
<pre>
> <input>processes().</input>
[&lt;0.0.0&gt;,&lt;0.2.0&gt;,&lt;0.4.0&gt;,&lt;0.5.0&gt;,&lt;0.7.0&gt;,&lt;0.8.0&gt;]</pre>
</desc>
</func>
+
<func>
<name name="purge_module" arity="1"/>
- <fsummary>Remove old code for a module</fsummary>
+ <fsummary>Removes old code for a module.</fsummary>
<desc>
- <p>Removes old code for <c><anno>Module</anno></c>. Before this BIF is used,
- <c>erlang:check_process_code/2</c> should be called to check
- that no processes are executing old code in the module.</p>
+ <p>Removes old code for <c><anno>Module</anno></c>.
+ Before this BIF is used,
+ <c>erlang:check_process_code/2</c> is to be called to check
+ that no processes execute old code in the module.</p>
<warning>
<p>This BIF is intended for the code server (see
- <seealso marker="kernel:code">code(3)</seealso>) and should not be
- used elsewhere.</p>
+ <seealso marker="kernel:code">code(3)</seealso>)
+ and is not to be used elsewhere.</p>
</warning>
<p>Failure: <c>badarg</c> if there is no old code for
<c><anno>Module</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="put" arity="2"/>
- <fsummary>Add a new value to the process dictionary</fsummary>
- <desc>
- <p>Adds a new <c><anno>Key</anno></c> to the process dictionary, associated
- with the value <c><anno>Val</anno></c>, and returns <c>undefined</c>. If
- <c><anno>Key</anno></c> already exists, the old value is deleted and
- replaced by <c><anno>Val</anno></c> and the function returns the old value.</p>
- <note>
- <p>The values stored when <c>put</c> is evaluated within
- the scope of a <c>catch</c> will not be retracted if a
- <c>throw</c> is evaluated, or if an error occurs.</p>
- </note>
+ <fsummary>Adds a new value to the process dictionary.</fsummary>
+ <desc>
+ <p>Adds a new <c><anno>Key</anno></c> to the process dictionary,
+ associated with the value <c><anno>Val</anno></c>, and returns
+ <c>undefined</c>. If <c><anno>Key</anno></c> exists, the old
+ value is deleted and replaced by <c><anno>Val</anno></c>, and
+ the function returns the old value.</p>
+ <p>Example:</p>
<pre>
> <input>X = put(name, walrus), Y = put(name, carpenter),</input>
<input>Z = get(name),</input>
<input>{X, Y, Z}.</input>
{undefined,walrus,carpenter}</pre>
+ <note>
+ <p>The values stored when <c>put</c> is evaluated within
+ the scope of a <c>catch</c> are not retracted if a
+ <c>throw</c> is evaluated, or if an error occurs.</p>
+ </note>
</desc>
</func>
+
<func>
<name name="raise" arity="3"/>
+ <fsummary>Stops execution with an exception of given class, reason, and call stack backtrace.</fsummary>
<type name="raise_stacktrace"/>
- <fsummary>Stop execution with an exception of given class, reason and call stack backtrace</fsummary>
<desc>
<p>Stops the execution of the calling process with an
- exception of given class, reason and call stack backtrace
+ exception of given class, reason, and call stack backtrace
(<em>stacktrace</em>).</p>
<warning>
- <p>This BIF is intended for debugging and for use in
- the Erlang operating system. In general, it should
- be avoided in applications, unless you know
- very well what you are doing.</p>
+ <p>This BIF is intended for debugging. Avoid to use it in applications,
+ unless you really know what you are doing.</p>
</warning>
- <p><c><anno>Class</anno></c> is one of <c>error</c>, <c>exit</c> or
- <c>throw</c>, so if it were not for the stacktrace
- <c>erlang:raise(<anno>Class</anno>, <anno>Reason</anno>, <anno>Stacktrace</anno>)</c> is
- equivalent to <c>erlang:<anno>Class</anno>(<anno>Reason</anno>)</c>.
- <c><anno>Reason</anno></c> is any term and <c><anno>Stacktrace</anno></c> is a list as
- returned from <c>get_stacktrace()</c>, that is a list of
- 4-tuples <c>{Module, Function, Arity | Args,
- Location}</c> where <c>Module</c> and <c>Function</c>
- are atoms and the third element is an integer arity or an
- argument list. The stacktrace may also contain <c>{Fun,
- Args, Location}</c> tuples where
- <c>Fun</c> is a local fun and <c>Args</c> is an argument list.</p>
- <p>The <c>Location</c> element at the end is optional.
+ <p><c><anno>Class</anno></c> is <c>error</c>, <c>exit</c>, or
+ <c>throw</c>. So, if it were not for the stacktrace,
+ <c>erlang:raise(<anno>Class</anno>, <anno>Reason</anno>,
+ <anno>Stacktrace</anno>)</c> is
+ equivalent to <c>erlang:<anno>Class</anno>(<anno>Reason</anno>)</c>.</p>
+ <p><c><anno>Reason</anno></c> is any term.
+ <c><anno>Stacktrace</anno></c> is a list as
+ returned from <c>get_stacktrace()</c>, that is, a list of
+ four-tuples <c>{Module, Function, Arity | Args,
+ Location}</c>, where <c>Module</c> and <c>Function</c>
+ are atoms, and the third element is an integer arity or an
+ argument list. The stacktrace can also contain <c>{Fun,
+ Args, Location}</c> tuples, where <c>Fun</c> is a local
+ fun and <c>Args</c> is an argument list.</p>
+ <p>Element <c>Location</c> at the end is optional.
Omitting it is equivalent to specifying an empty list.</p>
<p>The stacktrace is used as the exception stacktrace for the
- calling process; it will be truncated to the current
+ calling process; it is truncated to the current
maximum stacktrace depth.</p>
- <p>Because evaluating this function causes the process to
- terminate, it has no return value - unless the arguments are
- invalid, in which case the function <em>returns the error reason</em>, that is <c>badarg</c>. If you want to be
- really sure not to return you can call
- <c>error(erlang:raise(<anno>Class</anno>, <anno>Reason</anno>, <anno>Stacktrace</anno>))</c>
+ <p>Since evaluating this function causes the process to
+ terminate, it has no return value unless the arguments are
+ invalid, in which case the function <em>returns the error
+ reason</em> <c>badarg</c>. If you want to be
+ sure not to return, you can call
+ <c>error(erlang:raise(<anno>Class</anno>, <anno>Reason</anno>,
+ <anno>Stacktrace</anno>))</c>
and hope to distinguish exceptions later.</p>
</desc>
</func>
+
<func>
- <name name="read_timer" arity="1"/>
- <fsummary>Number of milliseconds remaining for a timer</fsummary>
- <desc>
- <p><c><anno>TimerRef</anno></c> is a timer reference returned by
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>
- or
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>.
- If the timer is active, the function returns the time in
- milliseconds left until the timer will expire, otherwise
- <c>false</c> (which means that <c><anno>TimerRef</anno></c> was never a
- timer, that it has been cancelled, or that it has already
- delivered its message).</p>
+ <name name="read_timer" arity="2"/>
+ <fsummary>Reads the state of a timer.</fsummary>
+ <desc>
+ <p>
+ Read the state of a timer that has been created by either
+ <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>,
+ or <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>.
+ <c><anno>TimerRef</anno></c> identifies the timer, and
+ was returned by the BIF that created the timer.
+ </p>
+ <p>Available <c><anno>Option</anno>s</c>:</p>
+ <taglist>
+ <tag><c>{async, Async}</c></tag>
+ <item>
+ <p>
+ Asynchronous request for state information. <c>Async</c>
+ defaults to <c>false</c> which will cause the operation
+ to be performed synchronously. In this case, the <c>Result</c>
+ is returned by <c>erlang:read_timer()</c>. When
+ <c>Async</c> is <c>true</c>, <c>erlang:read_timer()</c>
+ sends an asynchronous request for the state information
+ to the timer service that manages the timer, and then returns
+ <c>ok</c>. A message on the format <c>{read_timer,
+ <anno>TimerRef</anno>, <anno>Result</anno>}</c> is
+ sent to the caller of <c>erlang:read_timer()</c> when the
+ operation has been processed.
+ </p>
+ </item>
+ </taglist>
+ <p>
+ More <c><anno>Option</anno></c>s may be added in the future.
+ </p>
+ <p>
+ If <c><anno>Result</anno></c> is an integer, it represents the
+ time in milli-seconds left until the timer expires.</p>
+ <p>
+ If <c><anno>Result</anno></c> is <c>false</c>, a
+ timer corresponding to <c><anno>TimerRef</anno></c> could not
+ be found. This can be because the timer had expired,
+ it had been canceled, or because <c><anno>TimerRef</anno></c>
+ never has corresponded to a timer. Even if the timer has expired,
+ it does not tell you whether or not the timeout message has
+ arrived at its destination yet.
+ </p>
+ <note>
+ <p>
+ The timer service that manages the timer may be co-located
+ with another scheduler than the scheduler that the calling
+ process is executing on. If this is the case, communication
+ with the timer service takes much longer time than if it
+ is located locally. If the calling process is in critical
+ path, and can do other things while waiting for the result
+ of this operation, you want to use option <c>{async, true}</c>.
+ If using option <c>{async, false}</c>, the calling
+ process will be blocked until the operation has been
+ performed.
+ </p>
+ </note>
<p>See also
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>,
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
+ <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>,
+ <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>,
and
- <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>.</p>
+ <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>.</p>
</desc>
</func>
<func>
+ <name name="read_timer" arity="1"/>
+ <fsummary>Reads the state of a timer.</fsummary>
+ <desc>
+ <p>Read the state of a timer. The same as calling
+ <seealso marker="#read_timer/2"><c>erlang:read_timer(TimerRef,
+ [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
<name name="ref_to_list" arity="1"/>
- <fsummary>Text representation of a reference</fsummary>
+ <fsummary>Text representation of a reference.</fsummary>
<desc>
- <p>Returns a string which corresponds to the text
+ <p>Returns a string corresponding to the text
representation of <c><anno>Ref</anno></c>.</p>
<warning>
- <p>This BIF is intended for debugging and for use in
- the Erlang operating system. It should not be used in
- application programs.</p>
+ <p>This BIF is intended for debugging and is not to be used
+ in application programs.</p>
</warning>
</desc>
</func>
+
<func>
<name name="register" arity="2"/>
- <fsummary>Register a name for a pid (or port)</fsummary>
+ <fsummary>Registers a name for a pid (or port).</fsummary>
<desc>
- <p>Associates the name <c><anno>RegName</anno></c> with a pid or a port
- identifier. <c><anno>RegName</anno></c>, which must be an atom, can be used
- instead of the pid / port identifier in the send operator
+ <p>Associates the name <c><anno>RegName</anno></c> with a process
+ identifier (pid) or a port identifier.
+ <c><anno>RegName</anno></c>, which must be an atom, can be used
+ instead of the pid or port identifier in send operator
(<c><anno>RegName</anno> ! Message</c>).</p>
+ <p>Example:</p>
<pre>
> <input>register(db, Pid).</input>
true</pre>
- <p>Failure: <c>badarg</c> if <c><anno>PidOrPort</anno></c> is not an existing,
- local process or port, if <c><anno>RegName</anno></c> is already in use,
- if the process or port is already registered (already has a
- name), or if <c><anno>RegName</anno></c> is the atom <c>undefined</c>.</p>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>PidOrPort</anno></c> is not an existing local
+ process or port.</item>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>RegName</anno></c> is already in use.</item>
+ <tag><c>badarg</c></tag>
+ <item>If the process or port is already registered
+ (already has a name).</item>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>RegName</anno></c> is the atom
+ <c>undefined</c>.</item>
+ </taglist>
</desc>
</func>
+
<func>
<name name="registered" arity="0"/>
- <fsummary>All registered names</fsummary>
+ <fsummary>All registered names.</fsummary>
<desc>
- <p>Returns a list of names which have been registered using
- <seealso marker="#register/2">register/2</seealso>.</p>
+ <p>Returns a list of names that have been registered using
+ <seealso marker="#register/2">register/2</seealso>, for
+ example:</p>
<pre>
> <input>registered().</input>
[code_server, file_server, init, user, my_db]</pre>
</desc>
</func>
+
<func>
<name name="resume_process" arity="1"/>
- <fsummary>Resume a suspended process</fsummary>
+ <fsummary>Resumes a suspended process.</fsummary>
<desc>
<p>Decreases the suspend count on the process identified by
- <c><anno>Suspendee</anno></c>. <c><anno>Suspendee</anno></c> should previously have been
- suspended via
- <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>,
+ <c><anno>Suspendee</anno></c>. <c><anno>Suspendee</anno></c>
+ is previously to have been suspended through
+ <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>
or
<seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso>
- by the process calling <c>erlang:resume_process(<anno>Suspendee</anno>)</c>. When
- the suspend count on <c><anno>Suspendee</anno></c> reach zero, <c><anno>Suspendee</anno></c>
- will be resumed, i.e., the state of the <c>Suspendee</c> is changed
- from suspended into the state <c><anno>Suspendee</anno></c> was in before it was
- suspended.
- </p>
+ by the process calling
+ <c>erlang:resume_process(<anno>Suspendee</anno>)</c>. When the
+ suspend count on <c><anno>Suspendee</anno></c> reaches zero,
+ <c><anno>Suspendee</anno></c> is resumed, that is, its state
+ is changed from suspended into the state it had before it was
+ suspended.</p>
<warning>
<p>This BIF is intended for debugging only.</p>
</warning>
@@ -4357,7 +5029,7 @@ true</pre>
<taglist>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>Suspendee</anno></c> isn't a process identifier.
+ If <c><anno>Suspendee</anno></c> is not a process identifier.
</item>
<tag><c>badarg</c></tag>
<item>
@@ -4367,58 +5039,65 @@ true</pre>
</item>
<tag><c>badarg</c></tag>
<item>
- If the process identified by <c><anno>Suspendee</anno></c> is not alive.
+ If the process identified by <c><anno>Suspendee</anno></c>
+ is not alive.
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="round" arity="1"/>
- <fsummary>Return an integer by rounding a number</fsummary>
+ <fsummary>Returns an integer by rounding a number.</fsummary>
<desc>
- <p>Returns an integer by rounding <c><anno>Number</anno></c>.</p>
+ <p>Returns an integer by rounding <c><anno>Number</anno></c>,
+ for example:</p>
<pre>
-> <input>round(5.5).</input>
+<input>round(5.5).</input>
6</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="self" arity="0"/>
- <fsummary>Pid of the calling process</fsummary>
+ <fsummary>Returns pid of the calling process.</fsummary>
<desc>
- <p>Returns the pid (process identifier) of the calling process.</p>
+ <p>Returns the process identifier of the calling process, for
+ example:</p>
<pre>
> <input>self().</input>
&lt;0.26.0></pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="send" arity="2"/>
- <fsummary>Send a message</fsummary>
+ <fsummary>Sends a message.</fsummary>
<type name="dst"/>
<desc>
- <p>Sends a message and returns <c><anno>Msg</anno></c>. This is the same as
- <c><anno>Dest</anno> ! <anno>Msg</anno></c>.</p>
- <p><c><anno>Dest</anno></c> may be a remote or local pid, a (local) port, a
- locally registered name, or a tuple <c>{<anno>RegName</anno>, <anno>Node</anno>}</c>
+ <p>Sends a message and returns <c><anno>Msg</anno></c>. This
+ is the same as <c><anno>Dest</anno> ! <anno>Msg</anno></c>.</p>
+ <p><c><anno>Dest</anno></c> can be a remote or local process identifier,
+ a (local) port, a locally registered name, or a tuple
+ <c>{<anno>RegName</anno>, <anno>Node</anno>}</c>
for a registered name at another node.</p>
</desc>
</func>
+
<func>
<name name="send" arity="3"/>
+ <fsummary>Sends a message conditionally.</fsummary>
<type name="dst"/>
- <fsummary>Send a message conditionally</fsummary>
- <desc>
- <p>Sends a message and returns <c>ok</c>, or does not send
- the message but returns something else (see below). Otherwise
- the same as
- <seealso marker="#send/2">erlang:send/2</seealso>. See
- also
- <seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2,3</seealso>.
- for more detailed explanation and warnings.</p>
- <p>The possible options are:</p>
+ <desc>
+ <p>Either sends a message and returns <c>ok</c>, or does not send
+ the message but returns something else (see the following).
+ Otherwise the same as
+ <seealso marker="#send/2">erlang:send/2</seealso>.
+ For more detailed explanation and warnings, see
+ <seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2,3</seealso>.</p>
+ <p>The options are as follows:</p>
<taglist>
<tag><c>nosuspend</c></tag>
<item>
@@ -4428,319 +5107,366 @@ true</pre>
<tag><c>noconnect</c></tag>
<item>
<p>If the destination node would have to be auto-connected
- before doing the send, <c>noconnect</c> is returned
+ to do the send, <c>noconnect</c> is returned
instead.</p>
</item>
</taglist>
<warning>
- <p>As with <c>erlang:send_nosuspend/2,3</c>: Use with extreme
- care!</p>
+ <p>As with <c>erlang:send_nosuspend/2,3</c>: use with extreme
+ care.</p>
</warning>
</desc>
</func>
+
<func>
- <name name="send_after" arity="3"/>
- <type_desc variable="Time">0 &lt;= Time &lt;= 4294967295</type_desc>
+ <name name="send_after" arity="4"/>
<fsummary>Start a timer</fsummary>
<desc>
- <p>Starts a timer which will send the message <c>Msg</c>
- to <c><anno>Dest</anno></c> after <c><anno>Time</anno></c> milliseconds.</p>
- <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to be a <c>pid()</c> of a local process, dead or alive.</p>
- <p>The <c><anno>Time</anno></c> value can, in the current implementation, not be greater than 4294967295.</p>
- <p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, it is supposed to be the name of
- a registered process. The process referred to by the name is
- looked up at the time of delivery. No error is given if
- the name does not refer to a process.</p>
-
- <p>If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will be automatically
- canceled if the process referred to by the <c>pid()</c> is not alive,
- or when the process exits. This feature was introduced in
- erts version 5.4.11. Note that timers will not be
- automatically canceled when <c><anno>Dest</anno></c> is an <c>atom</c>.</p>
- <p>See also
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
- <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>,
- and
- <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
- <p>Failure: <c>badarg</c> if the arguments does not satisfy
- the requirements specified above.</p>
+ <p>
+ Starts a timer. When the timer expires, the message
+ <c><anno>Msg</anno></c> is sent to the process
+ identified by <c><anno>Dest</anno></c>. Apart from
+ the format of the timeout message,
+ <c>erlang:send_after/4</c> works exactly as
+ <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>.</p>
</desc>
</func>
<func>
+ <name name="send_after" arity="3"/>
+ <fsummary>Starts a timer.</fsummary>
+ <desc>
+ <p>Starts a timer. The same as calling
+ <seealso marker="#send_after/4"><c>erlang:send_after(<anno>Time</anno>,
+ <anno>Dest</anno>, <anno>Msg</anno>, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
<name name="send_nosuspend" arity="2"/>
- <fsummary>Try to send a message without ever blocking</fsummary>
+ <fsummary>Tries to send a message without ever blocking.</fsummary>
<type name="dst"/>
<desc>
<p>The same as
- <seealso marker="#send/3">erlang:send(<anno>Dest</anno>, <anno>Msg</anno>, [nosuspend])</seealso>, but returns <c>true</c> if
+ <seealso marker="#send/3">erlang:send(<anno>Dest</anno>,
+ <anno>Msg</anno>, [nosuspend])</seealso>,
+ but returns <c>true</c> if
the message was sent and <c>false</c> if the message was not
sent because the sender would have had to be suspended.</p>
- <p>This function is intended for send operations towards an
+ <p>This function is intended for send operations to an
unreliable remote node without ever blocking the sending
(Erlang) process. If the connection to the remote node
(usually not a real Erlang node, but a node written in C or
- Java) is overloaded, this function <em>will not send the message</em> but return <c>false</c> instead.</p>
- <p>The same happens, if <c><anno>Dest</anno></c> refers to a local port that
- is busy. For all other destinations (allowed for the ordinary
- send operator <c>'!'</c>) this function sends the message and
+ Java) is overloaded, this function <em>does not send the message</em>
+ and returns <c>false</c>.</p>
+ <p>The same occurs if <c><anno>Dest</anno></c> refers to a local port
+ that is busy. For all other destinations (allowed for the ordinary
+ send operator <c>'!'</c>), this function sends the message and
returns <c>true</c>.</p>
- <p>This function is only to be used in very rare circumstances
+ <p>This function is only to be used in rare circumstances
where a process communicates with Erlang nodes that can
- disappear without any trace causing the TCP buffers and
- the drivers queue to be over-full before the node will actually
- be shut down (due to tick timeouts) by <c>net_kernel</c>. The
- normal reaction to take when this happens is some kind of
+ disappear without any trace, causing the TCP buffers and
+ the drivers queue to be over-full before the node is
+ shut down (because of tick time-outs) by <c>net_kernel</c>.
+ The normal reaction to take when this occurs is some kind of
premature shutdown of the other node.</p>
- <p>Note that ignoring the return value from this function would
- result in <em>unreliable</em> message passing, which is
+ <p>Notice that ignoring the return value from this function would
+ result in an <em>unreliable</em> message passing, which is
contradictory to the Erlang programming model. The message is
<em>not</em> sent if this function returns <c>false</c>.</p>
- <p>Note also that in many systems, transient states of
+ <p>In many systems, transient states of
overloaded queues are normal. The fact that this function
- returns <c>false</c> does not in any way mean that the other
+ returns <c>false</c> does not mean that the other
node is guaranteed to be non-responsive, it could be a
- temporary overload. Also a return value of <c>true</c> does
- only mean that the message could be sent on the (TCP) channel
- without blocking, the message is not guaranteed to have
- arrived at the remote node. Also in the case of a disconnected
+ temporary overload. Also, a return value of <c>true</c> does
+ only mean that the message can be sent on the (TCP) channel
+ without blocking, the message is not guaranteed to
+ arrive at the remote node. For a disconnected
non-responsive node, the return value is <c>true</c> (mimics
- the behaviour of the <c>!</c> operator). The expected
- behaviour as well as the actions to take when the function
- returns <c>false</c> are application and hardware specific.</p>
+ the behavior of operator <c>!</c>). The expected
+ behavior and the actions to take when the function
+ returns <c>false</c> are application- and hardware-specific.</p>
<warning>
- <p>Use with extreme care!</p>
+ <p>Use with extreme care.</p>
</warning>
</desc>
</func>
+
<func>
<name name="send_nosuspend" arity="3"/>
- <fsummary>Try to send a message without ever blocking</fsummary>
+ <fsummary>Tries to send a message without ever blocking.</fsummary>
<type name="dst"/>
<desc>
<p>The same as
- <seealso marker="#send/3">erlang:send(<anno>Dest</anno>, <anno>Msg</anno>, [nosuspend | <anno>Options</anno>])</seealso>,
- but with boolean return value.</p>
+ <seealso marker="#send/3">erlang:send(<anno>Dest</anno>,
+ <anno>Msg</anno>, [nosuspend | <anno>Options</anno>])</seealso>,
+ but with a Boolean return value.</p>
<p>This function behaves like
- <seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2)</seealso>,
- but takes a third parameter, a list of options. The only
- currently implemented option is <c>noconnect</c>. The option
- <c>noconnect</c> makes the function return <c>false</c> if
+ <seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2</seealso>,
+ but takes a third parameter, a list of options.
+ The only option is <c>noconnect</c>, which
+ makes the function return <c>false</c> if
the remote node is not currently reachable by the local
- node. The normal behaviour is to try to connect to the node,
- which may stall the process for a shorter period. The use of
- the <c>noconnect</c> option makes it possible to be
- absolutely sure not to get even the slightest delay when
+ node. The normal behavior is to try to connect to the node,
+ which can stall the process during a short period. The use of
+ option <c>noconnect</c> makes it possible to be
+ sure not to get the slightest delay when
sending to a remote process. This is especially useful when
- communicating with nodes who expect to always be
- the connecting part (i.e. nodes written in C or Java).</p>
+ communicating with nodes that expect to always be
+ the connecting part (that is, nodes written in C or Java).</p>
<p>Whenever the function returns <c>false</c> (either when a
suspend would occur or when <c>noconnect</c> was specified and
the node was not already connected), the message is guaranteed
<em>not</em> to have been sent.</p>
<warning>
- <p>Use with extreme care!</p>
+ <p>Use with extreme care.</p>
</warning>
</desc>
</func>
+
<func>
<name name="set_cookie" arity="2"/>
- <fsummary>Set the magic cookie of a node</fsummary>
+ <fsummary>Sets the magic cookie of a node.</fsummary>
<desc>
<p>Sets the magic cookie of <c><anno>Node</anno></c> to the atom
- <c><anno>Cookie</anno></c>. If <c><anno>Node</anno></c> is the local node, the function
+ <c><anno>Cookie</anno></c>. If <c><anno>Node</anno></c> is the
+ local node, the function
also sets the cookie of all other unknown nodes to
- <c><anno>Cookie</anno></c> (see
- <seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso> in the Erlang Reference Manual).</p>
+ <c><anno>Cookie</anno></c> (see Section
+ <seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso>
+ in the Erlang Reference Manual in System Documentation).</p>
<p>Failure: <c>function_clause</c> if the local node is not
alive.</p>
</desc>
</func>
+
<func>
<name name="setelement" arity="3"/>
- <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>)</type_desc>
- <fsummary>Set Nth element of a tuple</fsummary>
+ <fsummary>Sets the Nth element of a tuple.</fsummary>
+ <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno></type_desc>
<desc>
- <p>Returns a tuple which is a copy of the argument <c><anno>Tuple1</anno></c>
- with the element given by the integer argument <c><anno>Index</anno></c>
+ <p>Returns a tuple that is a copy of argument
+ <c><anno>Tuple1</anno></c>
+ with the element given by integer argument
+ <c><anno>Index</anno></c>
(the first element is the element with index 1) replaced by
- the argument <c><anno>Value</anno></c>.</p>
+ argument <c><anno>Value</anno></c>, for example:</p>
<pre>
> <input>setelement(2, {10, green, bottles}, red).</input>
{10,red,bottles}</pre>
</desc>
</func>
+
<func>
<name name="size" arity="1"/>
- <fsummary>Size of a tuple or binary</fsummary>
+ <fsummary>Size of a tuple or binary.</fsummary>
<desc>
- <p>Returns an integer which is the size of the argument
- <c><anno>Item</anno></c>, which must be either a tuple or a binary.</p>
+ <p>Returns the number of elements in a tuple or the number of
+ bytes in a binary or bitstring, for example:</p>
<pre>
> <input>size({morni, mulle, bwange}).</input>
-3</pre>
+3
+> <input>size(&lt;&lt;11, 22, 33&gt;&gt;).</input>
+3
+</pre>
+ <p>For bitstrings the number of whole bytes is returned. That is, if the number of bits
+ in the bitstring is not divisible by 8, the resulting
+ number of bytes is rounded <em>down</em>.</p>
<p>Allowed in guard tests.</p>
+ <p>See also
+ <seealso marker="#tuple_size/1"><c>tuple_size/1</c></seealso>,
+ <seealso marker="#byte_size/1"><c>byte_size/1</c></seealso>
+ and
+ <seealso marker="#bit_size/1"><c>bit_size/1</c></seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn" arity="1"/>
- <fsummary>Create a new process with a fun as entry point</fsummary>
+ <fsummary>Creates a new process with a fun as entry point.</fsummary>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Fun</anno></c> to the empty list <c>[]</c>. Otherwise works
- like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ <p>Returns the process identifier of a new process started by the
+ application of <c><anno>Fun</anno></c> to the empty list
+ <c>[]</c>. Otherwise
+ works like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn" arity="2"/>
- <fsummary>Create a new process with a fun as entry point on a given node</fsummary>
+ <fsummary>Creates a new process with a fun as entry point on a given node.</fsummary>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Fun</anno></c> to the empty list <c>[]</c> on <c><anno>Node</anno></c>. If
- <c><anno>Node</anno></c> does not exist, a useless pid is returned.
- Otherwise works like
+ <p>Returns the process identifier of a new process started
+ by the application of <c><anno>Fun</anno></c> to the
+ empty list <c>[]</c> on <c><anno>Node</anno></c>. If
+ <c><anno>Node</anno></c> does not exist, a useless pid is
+ returned. Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn" arity="3"/>
- <fsummary>Create a new process with a function as entry point</fsummary>
- <desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c>. The new process
- created will be placed in the system scheduler queue and be
- run some time later.</p>
- <p><c>error_handler:undefined_function(<anno>Module</anno>, <anno>Function</anno>, <anno>Args</anno>)</c> is evaluated by the new process if
- <c><anno>Module</anno>:<anno>Function</anno>/Arity</c> does not exist (where
- <c>Arity</c> is the length of <c><anno>Args</anno></c>). The error handler
+ <fsummary>Creates a new process with a function as entry point.</fsummary>
+ <desc>
+ <p>Returns the process identifier of a new process started by
+ the application of <c><anno>Module</anno>:<anno>Function</anno></c>
+ to <c><anno>Args</anno></c>.</p>
+ <p><c>error_handler:undefined_function(<anno>Module</anno>,
+ <anno>Function</anno>, <anno>Args</anno>)</c>
+ is evaluated by the new process if
+ <c><anno>Module</anno>:<anno>Function</anno>/Arity</c>
+ does not exist (where <c>Arity</c> is the length of
+ <c><anno>Args</anno></c>). The error handler
can be redefined (see
<seealso marker="#process_flag/2">process_flag/2</seealso>).
If <c>error_handler</c> is undefined, or the user has
- redefined the default <c>error_handler</c> its replacement is
- undefined, a failure with the reason <c>undef</c> will occur.</p>
+ redefined the default <c>error_handler</c> and its replacement is
+ undefined, a failure with reason <c>undef</c> occurs.</p>
+ <p>Example:</p>
<pre>
> <input>spawn(speed, regulator, [high_speed, thin_cut]).</input>
&lt;0.13.1></pre>
</desc>
</func>
+
<func>
<name name="spawn" arity="4"/>
- <fsummary>Create a new process with a function as entry point on a given node</fsummary>
+ <fsummary>Creates a new process with a function as entry point on a given node.</fsummary>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. If
- <c><anno>Node</anno></c> does not exists, a useless pid is returned.
+ <p>Returns the process identifier (pid) of a new process started
+ by the application
+ of <c><anno>Module</anno>:<anno>Function</anno></c>
+ to <c><anno>Args</anno></c> on <c><anno>Node</anno></c>. If
+ <c><anno>Node</anno></c> does not exist, a useless pid is returned.
Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn_link" arity="1"/>
- <fsummary>Create and link to a new process with a fun as entry point</fsummary>
+ <fsummary>Creates and links to a new process with a fun as entry point.</fsummary>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Fun</anno></c> to the empty list []. A link is created between
+ <p>Returns the process identifier of a new process started by
+ the application of <c><anno>Fun</anno></c> to the empty list
+ <c>[]</c>. A link is created between
the calling process and the new process, atomically.
Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn_link" arity="2"/>
- <fsummary>Create and link to a new process with a fun as entry point on a specified node</fsummary>
+ <fsummary>Creates and links to a new process with a fun as entry point on a specified node.</fsummary>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Fun</anno></c> to the empty list [] on <c><anno>Node</anno></c>. A link is
+ <p>Returns the process identifier (pid) of a new process started
+ by the application of <c><anno>Fun</anno></c> to the empty
+ list <c>[]</c> on <c><anno>Node</anno></c>. A link is
created between the calling process and the new process,
- atomically. If <c><anno>Node</anno></c> does not exist, a useless pid is
- returned (and due to the link, an exit signal with exit
- reason <c>noconnection</c> will be received). Otherwise works
- like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ atomically. If <c><anno>Node</anno></c> does not exist,
+ a useless pid is returned and an exit signal with
+ reason <c>noconnection</c> is sent to the calling
+ process. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn_link" arity="3"/>
- <fsummary>Create and link to a new process with a function as entry point</fsummary>
+ <fsummary>Creates and links to a new process with a function as entry point.</fsummary>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c>. A link is created
+ <p>Returns the process identifier of a new process started by
+ the application of <c><anno>Module</anno>:<anno>Function</anno></c>
+ to <c><anno>Args</anno></c>. A link is created
between the calling process and the new process, atomically.
Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn_link" arity="4"/>
- <fsummary>Create and link to a new process with a function as entry point on a given node</fsummary>
+ <fsummary>Creates and links to a new process with a function as entry point on a given node.</fsummary>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. A
+ <p>Returns the process identifier (pid) of a new process
+ started by the application
+ of <c><anno>Module</anno>:<anno>Function</anno></c>
+ to <c><anno>Args</anno></c> on <c><anno>Node</anno></c>. A
link is created between the calling process and the new
- process, atomically. If <c><anno>Node</anno></c> does not exist, a useless
- pid is returned (and due to the link, an exit signal with exit
- reason <c>noconnection</c> will be received). Otherwise works
- like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ process, atomically. If <c><anno>Node</anno></c> does
+ not exist, a useless pid is returned and an exit signal with
+ reason <c>noconnection</c> is sent to the calling
+ process. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn_monitor" arity="1"/>
- <fsummary>Create and monitor a new process with a fun as entry point</fsummary>
+ <fsummary>Creates and monitors a new process with a fun as entry point.</fsummary>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Fun</anno></c> to the empty list [] and reference for a monitor
- created to the new process.
+ <p>Returns the process identifier of a new process, started by
+ the application of <c><anno>Fun</anno></c> to the empty list
+ <c>[]</c>,
+ and a reference for a monitor created to the new process.
Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn_monitor" arity="3"/>
- <fsummary>Create and monitor a new process with a function as entry point</fsummary>
+ <fsummary>Creates and monitors a new process with a function as entry point.</fsummary>
<desc>
<p>A new process is started by the application
- of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c>, and the process is
- monitored at the same time. Returns the pid and a reference
- for the monitor.
- Otherwise works like
+ of <c><anno>Module</anno>:<anno>Function</anno></c>
+ to <c><anno>Args</anno></c>. The process is
+ monitored at the same time. Returns the process identifier
+ and a reference for the monitor. Otherwise works like
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn_opt" arity="2"/>
- <type name="priority_level" />
- <fsummary>Create a new process with a fun as entry point</fsummary>
+ <fsummary>Creates a new process with a fun as entry point.</fsummary>
+ <type name="priority_level"/>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Fun</anno></c> to the empty list <c>[]</c>. Otherwise
- works like
+ <p>Returns the process identifier (pid) of a new process
+ started by the application of <c><anno>Fun</anno></c>
+ to the empty list <c>[]</c>. Otherwise works like
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
- <p>If the option <c>monitor</c> is given, the newly created
- process will be monitored and both the pid and reference for
- the monitor will be returned.</p>
+ <p>If option <c>monitor</c> is given, the newly created
+ process is monitored, and both the pid and reference for
+ the monitor is returned.</p>
</desc>
</func>
+
<func>
<name name="spawn_opt" arity="3"/>
- <type name="priority_level" />
- <fsummary>Create a new process with a fun as entry point on a given node</fsummary>
+ <fsummary>Creates a new process with a fun as entry point on a given node.</fsummary>
+ <type name="priority_level"/>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Fun</anno></c> to the empty list <c>[]</c> on <c><anno>Node</anno></c>. If
- <c><anno>Node</anno></c> does not exist, a useless pid is returned.
- Otherwise works like
+ <p>Returns the process identifier (pid) of a new process started
+ by the application of <c><anno>Fun</anno></c> to the
+ empty list <c>[]</c> on <c><anno>Node</anno></c>. If
+ <c><anno>Node</anno></c> does not exist, a useless pid is
+ returned. Otherwise works like
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
</desc>
</func>
+
<func>
<name name="spawn_opt" arity="4"/>
- <type name="priority_level" />
- <fsummary>Create a new process with a function as entry point</fsummary>
+ <fsummary>Creates a new process with a function as entry point.</fsummary>
+ <type name="priority_level"/>
<desc>
- <p>Works exactly like
+ <p>Works as
<seealso marker="#spawn/3">spawn/3</seealso>, except that an
extra option list is given when creating the process.</p>
- <p>If the option <c>monitor</c> is given, the newly created
- process will be monitored and both the pid and reference for
- the monitor will be returned.</p>
+ <p>If option <c>monitor</c> is given, the newly created
+ process is monitored, and both the pid and reference for
+ the monitor is returned.</p>
+ <p>The options are as follows:</p>
<taglist>
<tag><c>link</c></tag>
<item>
@@ -4749,112 +5475,123 @@ true</pre>
</item>
<tag><c>monitor</c></tag>
<item>
- <p>Monitor the new process (just like
+ <p>Monitors the new process (like
<seealso marker="#monitor/2">monitor/2</seealso> does).</p>
</item>
- <tag><c>{priority, <anno>Level</anno>}</c></tag>
+ <tag><c>{priority, <anno>Level</anno></c></tag>
<item>
<p>Sets the priority of the new process. Equivalent to
executing
- <seealso marker="#process_flag_priority">process_flag(priority, <anno>Level</anno>)</seealso> in the start function of the new process,
- except that the priority will be set before the process is
- selected for execution for the first time. For more information
- on priorities see
- <seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p>
+ <seealso marker="#process_flag_priority">process_flag(priority,
+ <anno>Level</anno>)</seealso>
+ in the start function of the new process,
+ except that the priority is set before the process is
+ selected for execution for the first time. For more
+ information on priorities, see
+ <seealso marker="#process_flag_priority">process_flag(priority,
+ <anno>Level</anno>)</seealso>.</p>
</item>
<tag><c>{fullsweep_after, <anno>Number</anno>}</c></tag>
<item>
- <p>This option is only useful for performance tuning.
- In general, you should not use this option unless you
- know that there is problem with execution times and/or
- memory consumption, and you should measure to make sure
- that the option improved matters.
- </p>
+ <p>Useful only for performance tuning. Do not use this
+ option unless you
+ know that there is problem with execution times or
+ memory consumption, and ensure
+ that the option improves matters.</p>
<p>The Erlang runtime system uses a generational garbage
collection scheme, using an "old heap" for data that has
survived at least one garbage collection. When there is
no more room on the old heap, a fullsweep garbage
- collection will be done.</p>
- <p>The <c>fullsweep_after</c> option makes it possible to
+ collection is done.</p>
+ <p>Option <c>fullsweep_after</c> makes it possible to
specify the maximum number of generational collections
- before forcing a fullsweep even if there is still room on
- the old heap. Setting the number to zero effectively
- disables the general collection algorithm, meaning that
+ before forcing a fullsweep, even if there is room on
+ the old heap. Setting the number to zero
+ disables the general collection algorithm, that is,
all live data is copied at every garbage collection.</p>
- <p>Here are a few cases when it could be useful to change
- <c>fullsweep_after</c>. Firstly, if binaries that are no
- longer used should be thrown away as soon as possible.
- (Set <c><anno>Number</anno></c> to zero.) Secondly, a process that
- mostly have short-lived data will be fullsweeped seldom
- or never, meaning that the old heap will contain mostly
- garbage. To ensure a fullsweep once in a while, set
- <c><anno>Number</anno></c> to a suitable value such as 10 or 20.
- Thirdly, in embedded systems with limited amount of RAM
- and no virtual memory, one might want to preserve memory
- by setting <c><anno>Number</anno></c> to zero. (The value may be set
- globally, see
- <seealso marker="#system_flag/2">erlang:system_flag/2</seealso>.)</p>
+ <p>A few cases when it can be useful to change
+ <c>fullsweep_after</c>:</p>
+ <list type="bulleted">
+ <item>If binaries that are no longer used are to be
+ thrown away as soon as possible. (Set
+ <c><anno>Number</anno></c> to zero.)
+ </item>
+ <item>A process that mostly have short-lived data is
+ fullsweeped seldom or never, that is, the old heap
+ contains mostly garbage. To ensure a fullsweep
+ occasionally, set <c><anno>Number</anno></c> to a
+ suitable value, such as 10 or 20.
+ </item>
+ <item>In embedded systems with a limited amount of RAM
+ and no virtual memory, you might want to preserve memory
+ by setting <c><anno>Number</anno></c> to zero.
+ (The value can be set globally, see
+ <seealso marker="#system_flag/2">erlang:system_flag/2</seealso>.)
+ </item>
+ </list>
</item>
<tag><c>{min_heap_size, <anno>Size</anno>}</c></tag>
<item>
- <p>This option is only useful for performance tuning.
- In general, you should not use this option unless you
- know that there is problem with execution times and/or
- memory consumption, and you should measure to make sure
- that the option improved matters.
- </p>
- <p>Gives a minimum heap size in words. Setting this value
- higher than the system default might speed up some
+ <p>Useful only for performance tuning. Do not use this
+ option unless you know that there is problem with
+ execution times or memory consumption, and
+ ensure that the option improves matters.</p>
+ <p>Gives a minimum heap size, in words. Setting this value
+ higher than the system default can speed up some
processes because less garbage collection is done.
- Setting too high value, however, might waste memory and
- slow down the system due to worse data locality.
- Therefore, it is recommended to use this option only for
+ However, setting a too high value can waste memory and
+ slow down the system because of worse data locality.
+ Therefore, use this option only for
fine-tuning an application and to measure the execution
time with various <c><anno>Size</anno></c> values.</p>
</item>
<tag><c>{min_bin_vheap_size, <anno>VSize</anno>}</c></tag>
<item>
- <p>This option is only useful for performance tuning.
- In general, you should not use this option unless you
- know that there is problem with execution times and/or
- memory consumption, and you should measure to make sure
- that the option improved matters.
- </p>
- <p>Gives a minimum binary virtual heap size in words. Setting this value
- higher than the system default might speed up some
+ <p>Useful only for performance tuning. Do not use this
+ option unless you know that there is problem with
+ execution times or memory consumption, and
+ ensure that the option improves matters.</p>
+ <p>Gives a minimum binary virtual heap size, in words.
+ Setting this value
+ higher than the system default can speed up some
processes because less garbage collection is done.
- Setting too high value, however, might waste memory.
- Therefore, it is recommended to use this option only for
+ However, setting a too high value can waste memory.
+ Therefore, use this option only for
fine-tuning an application and to measure the execution
time with various <c><anno>VSize</anno></c> values.</p>
</item>
-
</taglist>
</desc>
</func>
+
<func>
<name name="spawn_opt" arity="5"/>
- <type name="priority_level" />
- <fsummary>Create a new process with a function as entry point on a given node</fsummary>
+ <fsummary>Creates a new process with a function as entry point on a given node.</fsummary>
+ <type name="priority_level"/>
<desc>
- <p>Returns the pid of a new process started by the application
- of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. If
+ <p>Returns the process identifier (pid) of a new process started
+ by the application
+ of <c><anno>Module</anno>:<anno>Function</anno></c> to
+ <c><anno>Args</anno></c> on <c><anno>Node</anno></c>. If
<c><anno>Node</anno></c> does not exist, a useless pid is returned.
Otherwise works like
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
- <note><p>The <c>monitor</c> option is currently not supported by
+ <note><p>Option <c>monitor</c> is not supported by
<c>spawn_opt/5</c>.</p></note>
</desc>
</func>
+
<func>
<name name="split_binary" arity="2"/>
+ <fsummary>Splits a binary into two.</fsummary>
<type_desc variable="Pos">0..byte_size(Bin)</type_desc>
- <fsummary>Split a binary into two</fsummary>
<desc>
- <p>Returns a tuple containing the binaries which are the result
- of splitting <c><anno>Bin</anno></c> into two parts at position <c><anno>Pos</anno></c>.
+ <p>Returns a tuple containing the binaries that are the result
+ of splitting <c><anno>Bin</anno></c> into two parts at
+ position <c><anno>Pos</anno></c>.
This is not a destructive operation. After the operation,
- there will be three binaries altogether.</p>
+ there are three binaries altogether.</p>
+ <p>Example:</p>
<pre>
> <input>B = list_to_binary("0123456789").</input>
&lt;&lt;"0123456789">>
@@ -4868,156 +5605,269 @@ true</pre>
7</pre>
</desc>
</func>
+
<func>
- <name name="start_timer" arity="3"/>
- <type_desc variable="Time">0 &lt;= Time &lt;= 4294967295</type_desc>
- <fsummary>Start a timer</fsummary>
+ <name name="start_timer" arity="4"/>
+ <fsummary>Starts a timer.</fsummary>
<desc>
- <p>Starts a timer which will send the message
- <c>{timeout, <anno>TimerRef</anno>, <anno>Msg</anno>}</c> to <c><anno>Dest</anno></c>
- after <c><anno>Time</anno></c> milliseconds.</p>
- <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to be a <c>pid()</c> of a local process, dead or alive.</p>
- <p>The <c><anno>Time</anno></c> value can, in the current implementation, not be greater than 4294967295.</p>
- <p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, it is supposed to be the name of
- a registered process. The process referred to by the name is
- looked up at the time of delivery. No error is given if
- the name does not refer to a process.</p>
- <p>If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will be automatically
- canceled if the process referred to by the <c>pid()</c> is not alive,
- or when the process exits. This feature was introduced in
- erts version 5.4.11. Note that timers will not be
- automatically canceled when <c><anno>Dest</anno></c> is an <c>atom()</c>.</p>
+ <p>
+ Starts a timer. When the timer expires, the message
+ <c>{timeout, <anno>TimerRef</anno>, <anno>Msg</anno>}</c>
+ is sent to the process identified by
+ <c><anno>Dest</anno></c>.
+ </p>
+ <p>Available <c><anno>Option</anno></c>s:</p>
+ <taglist>
+ <tag><c>{abs, false}</c></tag>
+ <item>
+ <p>
+ This is the default. It means the
+ <c><anno>Time</anno></c> value is interpreted
+ as a time in milli-seconds <em>relative</em> current
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ monotonic time</seealso>.
+ </p>
+ </item>
+ <tag><c>{abs, true}</c></tag>
+ <item>
+ <p>
+ Absolute <c><anno>Time</anno></c> value. The
+ <c><anno>Time</anno></c> value is interpreted as an
+ absolute Erlang monotonic time in milli-seconds.
+ </p>
+ </item>
+ </taglist>
+ <p>
+ More <c><anno>Option</anno></c>s may be added in the future.
+ </p>
+ <p>
+ The absolute point in time, the timer is set to expire on,
+ has to be in the interval
+ <c>[</c><seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso><c>,
+ </c><seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso><c>]</c>.
+ Further, if a relative time is specified, the <c><anno>Time</anno></c> value
+ is not allowed to be negative.
+ </p>
+ <p>
+ If <c><anno>Dest</anno></c> is a <c>pid()</c>, it must
+ be a <c>pid()</c> of a process created on the current
+ runtime system instance. This process may or may not
+ have terminated. If <c><anno>Dest</anno></c> is an
+ <c>atom()</c>, it is interpreted as the name of a
+ locally registered process. The process referred to by the
+ name is looked up at the time of timer expiration. No error
+ is given if the name does not refer to a process.
+ </p>
+ <p>
+ If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer is
+ automatically canceled if the process referred to by the
+ <c>pid()</c> is not alive, or if the process exits. This
+ feature was introduced in ERTS version 5.4.11. Notice that
+ timers are not automatically canceled when
+ <c><anno>Dest</anno></c> is an <c>atom()</c>.
+ </p>
<p>See also
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>,
- <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>,
+ <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>,
+ <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>,
and
- <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
- <p>Failure: <c>badarg</c> if the arguments does not satisfy
- the requirements specified above.</p>
+ <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p>
+ <p>Failure: <c>badarg</c> if the arguments do not satisfy
+ the requirements specified here.</p>
</desc>
</func>
+
<func>
- <name name="statistics" arity="1" clause_i="1"/>
- <fsummary>Information about context switches</fsummary>
+ <name name="start_timer" arity="3"/>
+ <fsummary>Starts a timer.</fsummary>
<desc>
- <p><c><anno>ContextSwitches</anno></c> is the total number of context
- switches since the system started.</p>
+ <p>Starts a timer. The same as calling
+ <seealso marker="#start_timer/4"><c>erlang:start_timer(<anno>Time</anno>,
+ <anno>Dest</anno>, <anno>Msg</anno>, [])</c></seealso>.</p>
</desc>
</func>
+
+ <func>
+ <name name="statistics" arity="1" clause_i="1"/>
+ <fsummary>Information about active processes and ports.</fsummary>
+ <desc><marker id="statistics_active_tasks"></marker>
+ <p>
+ Returns a list where each element represents the amount
+ of active processes and ports on each run queue and its
+ associated scheduler. That is, the number of processes and
+ ports that are ready to run, or are currently running. The
+ element location in the list corresponds to the scheduler
+ and its run queue. The first element corresponds to scheduler
+ number 1 and so on. The information is <em>not</em> gathered
+ atomically. That is, the result is not necessarily a
+ consistent snapshot of the state, but instead quite
+ efficiently gathered. See also,
+ <seealso marker="#statistics_total_active_tasks"><c>statistics(total_active_tasks)</c></seealso>,
+ <seealso marker="#statistics_run_queue_lengths"><c>statistics(run_queue_lengths)</c></seealso>, and
+ <seealso marker="#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>.
+ </p>
+ </desc>
+ </func>
+
<func>
<name name="statistics" arity="1" clause_i="2"/>
- <fsummary>Information about exact reductions</fsummary>
+ <fsummary>Information about context switches.</fsummary>
<desc>
- <marker id="statistics_exact_reductions"></marker>
- <note><p><c>statistics(exact_reductions)</c> is
- a more expensive operation than
- <seealso marker="#statistics_reductions">statistics(reductions)</seealso>
- especially on an Erlang machine with SMP support.</p>
- </note>
+ <p>Returns the total number of context switches since the
+ system started.</p>
</desc>
</func>
+
<func>
<name name="statistics" arity="1" clause_i="3"/>
- <fsummary>Information about garbage collection</fsummary>
+ <fsummary>Information about exact reductions.</fsummary>
<desc>
- <p>This information may not be valid for all implementations.</p>
- <pre>
-> <input>statistics(garbage_collection).</input>
-{85,23961,0}
-</pre>
+ <marker id="statistics_exact_reductions"></marker>
+ <p>Returns the number of exact reductions.</p>
+ <note><p><c>statistics(exact_reductions)</c> is
+ a more expensive operation than
+ <seealso marker="#statistics_reductions">statistics(reductions)</seealso>,
+ especially on an Erlang machine with SMP support.</p>
+ </note>
</desc>
</func>
+
<func>
<name name="statistics" arity="1" clause_i="4"/>
- <fsummary>Information about io</fsummary>
+ <fsummary>Information about garbage collection.</fsummary>
<desc>
- <p><c><anno>Input</anno></c> is the total number of bytes received
- through ports, and <c><anno>Output</anno></c> is the total number of
- bytes output to ports.</p>
+ <p>Returns information about garbage collection, for example:</p>
+ <pre>
+> <input>statistics(garbage_collection).</input>
+{85,23961,0}</pre>
+ <p>This information can be invalid for some implementations.</p>
</desc>
</func>
+
<func>
<name name="statistics" arity="1" clause_i="5"/>
- <fsummary>Information about reductions</fsummary>
+ <fsummary>Information about I/O.</fsummary>
<desc>
- <marker id="statistics_reductions"></marker>
- <note>
- <p>Since erts-5.5 (OTP release R11B)
- this value does not include reductions performed in current
- time slices of currently scheduled processes. If an
- exact value is wanted, use
- <seealso marker="#statistics_exact_reductions">statistics(exact_reductions)</seealso>.</p>
- </note>
- <pre>
-> <input>statistics(reductions).</input>
-{2046,11}
-</pre>
+ <p>Returns <c><anno>Input</anno></c>,
+ which is the total number of bytes
+ received through ports, and <c><anno>Output</anno></c>,
+ which is the total number of bytes output to ports.</p>
</desc>
</func>
+
<func>
<name name="statistics" arity="1" clause_i="6"/>
- <fsummary>Information about the run-queue</fsummary>
+ <fsummary>Information about reductions.</fsummary>
<desc>
- <p>Returns the total length of the run queues, that is, the number
- of processes that are ready to run on all available run queues.</p>
+ <marker id="statistics_reductions"></marker>
+ <p>Returns information about reductions, for example:</p>
+ <pre>
+> <input>statistics(reductions).</input>
+{2046,11}</pre>
+ <note><p>As from <c>ERTS</c> 5.5 (OTP R11B),
+ this value does not include reductions performed in current
+ time slices of currently scheduled processes. If an
+ exact value is wanted, use
+ <seealso marker="#statistics_exact_reductions">statistics(exact_reductions)</seealso>.</p>
+ </note>
</desc>
</func>
+
<func>
<name name="statistics" arity="1" clause_i="7"/>
- <fsummary>Information about run-time</fsummary>
- <desc>
- <p>Note that the run-time is the sum of the run-time for all
- threads in the Erlang run-time system and may therefore be greater
- than the wall-clock time. The time is returned in milliseconds.</p>
- <pre>
-> <input>statistics(runtime).</input>
-{1690,1620}
-</pre>
+ <fsummary>Information about the run-queues.</fsummary>
+ <desc><marker id="statistics_run_queue"></marker>
+ <p>
+ Returns the total length of the run-queues. That is, the number
+ of processes and ports that are ready to run on all available
+ run-queues. The information is gathered atomically. That
+ is, the result is a consistent snapshot of the state, but
+ this operation is much more expensive compared to
+ <seealso marker="#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>.
+ This especially when a large amount of schedulers is used.
+ </p>
</desc>
</func>
+
<func>
<name name="statistics" arity="1" clause_i="8"/>
- <fsummary>Information about each schedulers work time</fsummary>
- <desc>
- <marker id="statistics_scheduler_wall_time"></marker>
- <p>
- Returns a list of tuples with <c>{<anno>SchedulerId</anno>,
- <anno>ActiveTime</anno>, <anno>TotalTime</anno>}</c>, where
- <c>SchedulerId</c> is an integer id of the scheduler, <c>ActiveTime</c> is
- the duration the scheduler has been busy, <c>TotalTime</c> is the total time duration since
- <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso>
- activation. The time unit is not defined and may be subject to change
- between releases, operating systems and system restarts.
- <c>scheduler_wall_time</c> should only be used to calculate relative
- values for scheduler-utilization. <c>ActiveTime</c> can never exceed <c>TotalTime</c>.
- </p>
-
- <p>The definition of a busy scheduler is when it is not idle or not
- scheduling (selecting) a process or port, meaning; executing process
- code, executing linked-in-driver or NIF code, executing
- built-in-functions or any other runtime handling, garbage collecting
- or handling any other memory management. Note, a scheduler may also be
- busy even if the operating system has scheduled out the scheduler
- thread.
- </p>
+ <fsummary>Information about the run-queue lengths.</fsummary>
+ <desc><marker id="statistics_run_queue_lengths"></marker>
+ <p>
+ Returns a list where each element represents the amount
+ of processes and ports ready to run for each run queue. The
+ element location in the list corresponds to the run queue
+ of a scheduler. The first element corresponds to the run
+ queue of scheduler number 1 and so on. The information is
+ <em>not</em> gathered atomically. That is, the result is
+ not necessarily a consistent snapshot of the state, but
+ instead quite efficiently gathered. See also,
+ <seealso marker="#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>,
+ <seealso marker="#statistics_active_tasks"><c>statistics(active_tasks)</c></seealso>, and
+ <seealso marker="#statistics_total_active_tasks"><c>statistics(total_active_tasks)</c></seealso>.
+ </p>
+ </desc>
+ </func>
- <p>
- Returns <c>undefined</c> if the system flag
- <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso>
- is turned off.
- </p>
+ <func>
+ <name name="statistics" arity="1" clause_i="9"/>
+ <fsummary>Information about runtime.</fsummary>
+ <desc>
+ <p>Returns information about runtime, in milliseconds.</p>
+ <p>This is the sum of the runtime for all threads
+ in the Erlang runtime system and can therefore be greater
+ than the wall clock time.</p>
+ <p>Example:</p>
+ <pre>
+> <input>statistics(runtime).</input>
+{1690,1620}</pre>
+ </desc>
+ </func>
- <p>The list of scheduler information is unsorted and may appear in different order
- between calls.
- </p>
- <p>Using <c>scheduler_wall_time</c> to calculate scheduler utilization.</p>
+ <func>
+ <name name="statistics" arity="1" clause_i="10"/>
+ <fsummary>Information about each schedulers work time.</fsummary>
+ <desc>
+ <marker id="statistics_scheduler_wall_time"></marker>
+ <p>Returns a list of tuples with
+ <c>{<anno>SchedulerId</anno>, <anno>ActiveTime</anno>,
+ <anno>TotalTime</anno>}</c>, where
+ <c><anno>SchedulerId</anno></c> is an integer ID of the scheduler,
+ <c><anno>ActiveTime</anno></c> is
+ the duration the scheduler has been busy, and
+ <c><anno>TotalTime</anno></c> is the total time duration since
+ <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso>
+ activation. The time unit is undefined and can be subject
+ to change between releases, OSs, and system restarts.
+ <c>scheduler_wall_time</c> is only to be used to
+ calculate relative values for scheduler-utilization.
+ <c><anno>ActiveTime</anno></c> can never exceed
+ <c><anno>TotalTime</anno></c>.</p>
+ <p>The definition of a busy scheduler is when it is not idle
+ and is not scheduling (selecting) a process or port,
+ that is:</p>
+ <list type="bulleted">
+ <item>Executing process code</item>
+ <item>Executing linked-in-driver or NIF code</item>
+ <item>Executing built-in-functions, or any other runtime
+ handling</item>
+ <item>Garbage collecting</item>
+ <item>Handling any other memory management</item>
+ </list>
+ <p>Notice that a scheduler can also be busy even if the
+ OS has scheduled out the scheduler thread.</p>
+ <p>Returns <c>undefined</c> if system flag
+ <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso>
+ is turned off.</p>
+ <p>The list of scheduler information is unsorted and can
+ appear in different order between calls.</p>
+ <p>Using <c>scheduler_wall_time</c> to calculate scheduler-utilization:</p>
<pre>
> <input>erlang:system_flag(scheduler_wall_time, true).</input>
false
> <input>Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.</input>
-ok
-</pre>
- <p>Some time later we will take another snapshot and calculate scheduler-utilization per scheduler.</p>
+ok</pre>
+ <p>Some time later the user takes another snapshot and calculates
+ scheduler-utilization per scheduler, for example:</p>
<pre>
> <input>Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.</input>
ok
@@ -5030,86 +5880,127 @@ ok
{5,0.9717956667018103},
{6,0.9739235846420741},
{7,0.973237033077876},
- {8,0.9741297293248656}]
-</pre>
- <p>Using the same snapshots to calculate a total scheduler-utilization.</p>
+ {8,0.9741297293248656}]</pre>
+ <p>Using the same snapshots to calculate a total scheduler-utilization:</p>
<pre>
> <input>{A, T} = lists:foldl(fun({{_, A0, T0}, {_, A1, T1}}, {Ai,Ti}) ->
{Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), A/T.</input>
-0.9769136803764825
-</pre>
+0.9769136803764825</pre>
<note>
- <p><c>scheduler_wall_time</c> is by default disabled. Use <c>erlang:system_flag(scheduler_wall_time, true)</c> to enable it. </p>
+ <p><c>scheduler_wall_time</c> is by default disabled. To
+ enable it, use
+ <c>erlang:system_flag(scheduler_wall_time, true)</c>.</p>
</note>
</desc>
</func>
+
+ <func>
+ <name name="statistics" arity="1" clause_i="11"/>
+ <fsummary>Information about active processes and ports.</fsummary>
+ <desc><marker id="statistics_total_active_tasks"></marker>
+ <p>
+ Returns the total amount of active processes and ports in
+ the system. That is, the number of processes and ports that
+ are ready to run, or are currently running. The information
+ is <em>not</em> gathered atomically. That is, the result
+ is not necessarily a consistent snapshot of the state, but
+ instead quite efficiently gathered. See also,
+ <seealso marker="#statistics_active_tasks"><c>statistics(active_tasks)</c></seealso>,
+ <seealso marker="#statistics_run_queue_lengths"><c>statistics(run_queue_lengths)</c></seealso>, and
+ <seealso marker="#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>.
+ </p>
+ </desc>
+ </func>
+
<func>
- <name name="statistics" arity="1" clause_i="9"/>
- <fsummary>Information about wall-clock</fsummary>
+ <name name="statistics" arity="1" clause_i="12"/>
+ <fsummary>Information about the run-queue lengths.</fsummary>
+ <desc><marker id="statistics_total_run_queue_lengths"></marker>
+ <p>
+ Returns the total length of the run-queues. That is, the number
+ of processes and ports that are ready to run on all available
+ run-queues. The information is <em>not</em> gathered atomically.
+ That is, the result is not necessarily a consistent snapshot of
+ the state, but much more efficiently gathered compared to
+ <seealso marker="#statistics_run_queue"><c>statistics(run_queue)</c></seealso>.
+ See also,
+ <seealso marker="#statistics_run_queue_lengths"><c>statistics(run_queue_lengths)</c></seealso>,
+ <seealso marker="#statistics_total_active_tasks"><c>statistics(total_active_tasks)</c></seealso>, and
+ <seealso marker="#statistics_active_tasks"><c>statistics(active_tasks)</c></seealso>.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="statistics" arity="1" clause_i="13"/>
+ <fsummary>Information about wall clock.</fsummary>
<desc>
- <p><c>wall_clock</c> can be used in the same manner as
+ <p>Returns information about wall clock. <c>wall_clock</c> can
+ be used in the same manner as
<c>runtime</c>, except that real time is measured as
opposed to runtime or CPU time.</p>
</desc>
</func>
+
<func>
<name name="suspend_process" arity="2"/>
- <fsummary>Suspend a process</fsummary>
+ <fsummary>Suspends a process.</fsummary>
<desc>
<p>Increases the suspend count on the process identified by
- <c><anno>Suspendee</anno></c> and puts it in the suspended state if it isn't
- already in the suspended state. A suspended process will not be
- scheduled for execution until the process has been resumed.
- </p>
-
+ <c><anno>Suspendee</anno></c> and puts it in the suspended
+ state if it is not
+ already in that state. A suspended process will not be
+ scheduled for execution until the process has been resumed.</p>
<p>A process can be suspended by multiple processes and can
be suspended multiple times by a single process. A suspended
- process will not leave the suspended state until its suspend
- count reach zero. The suspend count of <c><anno>Suspendee</anno></c>
- is decreased when
+ process does not leave the suspended state until its suspend
+ count reaches zero. The suspend count of
+ <c><anno>Suspendee</anno></c> is decreased when
<seealso marker="#resume_process/1">erlang:resume_process(<anno>Suspendee</anno>)</seealso>
is called by the same process that called
- <c>erlang:suspend_process(<anno>Suspendee</anno>)</c>. All increased suspend
- counts on other processes acquired by a process will automatically be
+ <c>erlang:suspend_process(<anno>Suspendee</anno>)</c>.
+ All increased suspend
+ counts on other processes acquired by a process are automatically
decreased when the process terminates.</p>
-
- <p>Currently the following options (<c><anno>Opt</anno></c>s) are available:</p>
+ <p>The options (<c><anno>Opt</anno></c>s) are as follows:</p>
<taglist>
<tag><c>asynchronous</c></tag>
<item>
A suspend request is sent to the process identified by
- <c><anno>Suspendee</anno></c>. <c><anno>Suspendee</anno></c> will eventually suspend
- unless it is resumed before it was able to suspend. The caller
- of <c>erlang:suspend_process/2</c> will return immediately,
- regardless of whether the <c><anno>Suspendee</anno></c> has suspended yet
- or not. Note that the point in time when the <c><anno>Suspendee</anno></c>
- will actually suspend cannot be deduced from other events
- in the system. The only guarantee given is that the
- <c><anno>Suspendee</anno></c> will <em>eventually</em> suspend (unless it
- is resumed). If the <c>asynchronous</c> option has <em>not</em>
- been passed, the caller of <c>erlang:suspend_process/2</c> will
- be blocked until the <c><anno>Suspendee</anno></c> has actually suspended.
+ <c><anno>Suspendee</anno></c>. <c><anno>Suspendee</anno></c>
+ eventually suspends
+ unless it is resumed before it could suspend. The caller
+ of <c>erlang:suspend_process/2</c> returns immediately,
+ regardless of whether <c><anno>Suspendee</anno></c> has
+ suspended yet or not. The point in time when
+ <c><anno>Suspendee</anno></c> suspends cannot be deduced
+ from other events in the system. It is only guaranteed that
+ <c><anno>Suspendee</anno></c> <em>eventually</em> suspends
+ (unless it
+ is resumed). If option <c>asynchronous</c> has <em>not</em>
+ been passed, the caller of <c>erlang:suspend_process/2</c> is
+ blocked until <c><anno>Suspendee</anno></c> has suspended.
</item>
<tag><c>unless_suspending</c></tag>
<item>
- The process identified by <c><anno>Suspendee</anno></c> will be suspended
- unless the calling process already is suspending the
- <c><anno>Suspendee</anno></c>. If <c>unless_suspending</c> is combined
- with the <c>asynchronous</c> option, a suspend request will be
- sent unless the calling process already is suspending the
- <c><anno>Suspendee</anno></c> or if a suspend request already has been sent
- and is in transit. If the calling process already is suspending
- the <c><anno>Suspendee</anno></c>, or if combined with the <c>asynchronous</c>
- option and a send request already is in transit,
- <c>false</c> is returned and the suspend count on <c><anno>Suspendee</anno></c>
- will remain unchanged.
+ The process identified by <c><anno>Suspendee</anno></c> is
+ suspended unless the calling process already is suspending
+ <c><anno>Suspendee</anno></c>.
+ If <c>unless_suspending</c> is combined
+ with option <c>asynchronous</c>, a suspend request is
+ sent unless the calling process already is suspending
+ <c><anno>Suspendee</anno></c> or if a suspend request
+ already has been sent and is in transit. If the calling
+ process already is suspending <c><anno>Suspendee</anno></c>,
+ or if combined with option <c>asynchronous</c>
+ and a send request already is in transit,
+ <c>false</c> is returned and the suspend count on
+ <c><anno>Suspendee</anno></c> remains unchanged.
</item>
</taglist>
-
<p>If the suspend count on the process identified by
- <c><anno>Suspendee</anno></c> was increased, <c>true</c> is returned; otherwise,
- <c>false</c> is returned.</p>
-
+ <c><anno>Suspendee</anno></c> is increased, <c>true</c>
+ is returned, otherwise <c>false</c>.</p>
<warning>
<p>This BIF is intended for debugging only.</p>
</warning>
@@ -5117,310 +6008,322 @@ ok
<taglist>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>Suspendee</anno></c> isn't a process identifier.
+ If <c><anno>Suspendee</anno></c> is not a process identifier.
</item>
<tag><c>badarg</c></tag>
<item>
- If the process identified by <c><anno>Suspendee</anno></c> is same the process as
- the process calling <c>erlang:suspend_process/2</c>.
+ If the process identified by <c><anno>Suspendee</anno></c>
+ is the same process
+ as the process calling <c>erlang:suspend_process/2</c>.
</item>
<tag><c>badarg</c></tag>
<item>
- If the process identified by <c><anno>Suspendee</anno></c> is not alive.
+ If the process identified by <c><anno>Suspendee</anno></c>
+ is not alive.
</item>
<tag><c>badarg</c></tag>
<item>
- If the process identified by <c><anno>Suspendee</anno></c> resides on another node.
+ If the process identified by <c><anno>Suspendee</anno></c>
+ resides on another node.
</item>
<tag><c>badarg</c></tag>
<item>
- If <c><anno>OptList</anno></c> isn't a proper list of valid <c><anno>Opt</anno></c>s.
+ If <c><anno>OptList</anno></c> is not a proper list of valid
+ <c><anno>Opt</anno></c>s.
</item>
<tag><c>system_limit</c></tag>
<item>
- If the process identified by <c><anno>Suspendee</anno></c> has been suspended more
- times by the calling process than can be represented by the
- currently used internal data structures. The current system limit
- is larger than 2 000 000 000 suspends, and it will never be less
- than that.
+ If the process identified by <c><anno>Suspendee</anno></c>
+ has been suspended
+ more times by the calling process than can be represented by the
+ currently used internal data structures. The system limit is
+ higher than 2,000,000,000 suspends and will never be lower.
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="suspend_process" arity="1"/>
- <fsummary>Suspend a process</fsummary>
+ <fsummary>Suspends a process.</fsummary>
<desc>
- <p>Suspends the process identified by <c><anno>Suspendee</anno></c>. The
- same as calling
- <seealso marker="#suspend_process/2">erlang:suspend_process(<anno>Suspendee</anno>, [])</seealso>. For more information see the documentation of <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>.
- </p>
+ <p>Suspends the process identified by
+ <c><anno>Suspendee</anno></c>. The same as calling
+ <seealso marker="#suspend_process/2">erlang:suspend_process(<anno>Suspendee</anno>,
+ [])</seealso>.</p>
<warning>
<p>This BIF is intended for debugging only.</p>
</warning>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="1"/>
- <fsummary>Set system flag backtrace_depth</fsummary>
+ <fsummary>Sets system flag <c>backtrace_depth</c>.</fsummary>
<desc>
<p>Sets the maximum depth of call stack back-traces in the
exit reason element of <c>'EXIT'</c> tuples.</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="2"/>
+ <fsummary>Sets system flag <c>cpu_topology</c>.</fsummary>
<type name="cpu_topology"/>
<type name="level_entry"/>
<type name="level_tag"/>
<type name="sub_level"/>
<type name="info_list"/>
- <fsummary>Set system flag cpu_topology</fsummary>
<desc>
<warning>
<p><marker id="system_flag_cpu_topology"></marker>
- This argument is <em>deprecated</em> and
- scheduled for removal in erts-5.10/OTP-R16. Instead of using
- this argument you are advised to use the <c>erl</c> command
- line argument <seealso marker="erts:erl#+sct">+sct</seealso>.
- When this argument has been removed a final CPU topology to use
- will be determined at emulator boot time.</p>
+ This argument is <em>deprecated</em> and scheduled for
+ removal in <c>ERTS</c> 5.10/OTP R16. Instead of using this
+ argument, use command-line argument
+ <seealso marker="erts:erl#+sct">+sct</seealso> in
+ <c>erl(1)</c>.</p>
+ <p>When this argument is removed, a final CPU topology
+ to use is determined at emulator boot time.</p>
</warning>
- <p>Sets the user defined <c><anno>CpuTopology</anno></c>. The user defined
- CPU topology will override any automatically detected
- CPU topology. By passing <c>undefined</c> as <c><anno>CpuTopology</anno></c>
- the system will revert back to the CPU topology automatically
+ <p>Sets the user-defined <c><anno>CpuTopology</anno></c>.
+ The user-defined
+ CPU topology overrides any automatically detected
+ CPU topology. By passing <c>undefined</c> as
+ <c><anno>CpuTopology</anno></c>,
+ the system reverts to the CPU topology automatically
detected. The returned value equals the value returned
from <c>erlang:system_info(cpu_topology)</c> before the
- change was made.
- </p>
+ change was made.</p>
<p>Returns the old value of the flag.</p>
<p>The CPU topology is used when binding schedulers to logical
processors. If schedulers are already bound when the CPU
- topology is changed, the schedulers will be sent a request
- to rebind according to the new CPU topology.
- </p>
- <p>The user defined CPU topology can also be set by passing
- the <seealso marker="erts:erl#+sct">+sct</seealso> command
- line argument to <c>erl</c>.
- </p>
- <p>For information on the <c><anno>CpuTopology</anno></c> type
- and more, see the documentation of
- <seealso marker="#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>,
- and the <c>erl</c> <seealso marker="erts:erl#+sct">+sct</seealso>
- and <seealso marker="erts:erl#+sbt">+sbt</seealso>
- command line flags.
- </p>
+ topology is changed, the schedulers are sent a request
+ to rebind according to the new CPU topology.</p>
+ <p>The user-defined CPU topology can also be set by passing
+ command-line argument
+ <seealso marker="erts:erl#+sct">+sct</seealso> to
+ <c>erl(1)</c>.</p>
+ <p>For information on type <c><anno>CpuTopology</anno></c>
+ and more, see
+ <seealso marker="#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>
+ as well as the command-line flags
+ <seealso marker="erts:erl#+sct">+sct</seealso> and
+ <seealso marker="erts:erl#+sbt">+sbt</seealso> in
+ <c>erl(1)</c>.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="3"/>
- <fsummary>Set system flag dirty CPU schedulers online</fsummary>
+ <fsummary>Sets <c>system_flag_dirty_cpu_schedulers_online</c>.</fsummary>
<desc>
<p><marker id="system_flag_dirty_cpu_schedulers_online"></marker>
- Sets the amount of dirty CPU schedulers online. Valid range is
- <![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]> where <c>N</c> is the
- lesser of the return values of <c>erlang:system_info(dirty_cpu_schedulers)</c> and
- <c>erlang:system_info(schedulers_online)</c>.
- </p>
+ Sets the number of dirty CPU schedulers online. Range is
+ <![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]>, where <c>N</c>
+ is the smallest of the return values of
+ <c>erlang:system_info(dirty_cpu_schedulers)</c> and
+ <c>erlang:system_info(schedulers_online)</c>.</p>
<p>Returns the old value of the flag.</p>
- <p>Note that the number of dirty CPU schedulers online may change if the number of
- schedulers online changes. For example, if there are 12 schedulers and all are
- online, and 6 dirty CPU schedulers, all online as well, and <c>system_flag/2</c>
- is used to set the number of schedulers online to 6, then the number of dirty
- CPU schedulers online is automatically decreased by half as well, down to 3.
- Similarly, the number of dirty CPU schedulers online increases proportionally
- to increases in the number of schedulers online.</p>
- <p><em>Note that the dirty schedulers functionality is experimental</em>, and
- that you have to enable support for dirty schedulers when building OTP in order
- to try out the functionality.</p>
- <p>For more information see
+ <p>The number of dirty CPU schedulers online can change if the
+ number of schedulers online changes. For example, if 12
+ schedulers and 6 dirty CPU schedulers are online, and
+ <c>system_flag/2</c> is used to set the number of
+ schedulers online to 6, then the number of dirty CPU
+ schedulers online is automatically decreased by half as well,
+ down to 3. Similarly, the number of dirty CPU schedulers
+ online increases proportionally to increases in the number of
+ schedulers online.</p>
+ <note><p>The dirty schedulers functionality is experimental.
+ Enable support for dirty schedulers when building OTP to
+ try out the functionality.</p>
+ </note>
+ <p>For more information, see
<seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso>
and
- <seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>.
- </p>
+ <seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="4"/>
- <fsummary>Set system flag fullsweep_after</fsummary>
+ <fsummary>Sets system flag <c>fullsweep_after</c>.</fsummary>
<desc>
- <p><c><anno>Number</anno></c> is a non-negative integer which indicates
+ <p>Sets system flag <c>fullsweep_after</c>.
+ <c><anno>Number</anno></c> is a non-negative integer indicating
how many times generational garbage collections can be
done without forcing a fullsweep collection. The value
- applies to new processes; processes already running are
+ applies to new processes, while processes already running are
not affected.</p>
<p>Returns the old value of the flag.</p>
<p>In low-memory systems (especially without virtual
- memory), setting the value to 0 can help to conserve
+ memory), setting the value to <c>0</c> can help to conserve
memory.</p>
- <p>An alternative way to set this value is through the
- (operating system) environment variable
- <c>ERL_FULLSWEEP_AFTER</c>.</p>
+ <p>This value can also be set through (OS)
+ environment variable <c>ERL_FULLSWEEP_AFTER</c>.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="5"/>
- <fsummary>Set system flag min_heap_size</fsummary>
- <desc>
- <p>Sets the default minimum heap size for processes. The
- size is given in words. The new <c>min_heap_size</c> only
- effects processes spawned after the change of
- <c>min_heap_size</c> has been made.
- The <c>min_heap_size</c> can be set for individual
- processes by use of
+ <fsummary>Sets system flag <c>min_heap_size</c>.</fsummary>
+ <desc>
+ <p>Sets the default minimum heap size for processes. The size
+ is given in words. The new <c>min_heap_size</c> effects
+ only processes spawned after the change of
+ <c>min_heap_size</c> has been made. <c>min_heap_size</c>
+ can be set for individual processes by using
<seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or
- <seealso marker="#process_flag/2">process_flag/2</seealso>. </p>
+ <seealso marker="#process_flag/2">process_flag/2</seealso>.</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="6"/>
- <fsummary>Set system flag min_bin_vheap_size</fsummary>
+ <fsummary>Sets system flag <c>min_bin_vheap_size</c>.</fsummary>
<desc>
- <p>Sets the default minimum binary virtual heap size for processes. The
- size is given in words. The new <c>min_bin_vhheap_size</c> only
- effects processes spawned after the change of
+ <p>Sets the default minimum binary virtual heap size for
+ processes. The size is given in words.
+ The new <c>min_bin_vhheap_size</c> effects only
+ processes spawned after the change of
<c>min_bin_vhheap_size</c> has been made.
- The <c>min_bin_vheap_size</c> can be set for individual
- processes by use of
+ <c>min_bin_vheap_size</c> can be set for individual
+ processes by using
<seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or
- <seealso marker="#process_flag/2">process_flag/2</seealso>. </p>
+ <seealso marker="#process_flag/2">process_flag/2</seealso>.</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="7"/>
- <fsummary>Set system flag multi_scheduling</fsummary>
+ <fsummary>Sets system flag <c>multi_scheduling</c>.</fsummary>
<desc>
<p><marker id="system_flag_multi_scheduling"></marker>
If multi-scheduling is enabled, more than one scheduler
thread is used by the emulator. Multi-scheduling can be
- blocked. When multi-scheduling has been blocked, only
- one scheduler thread will schedule Erlang processes.</p>
- <p>If <c><anno>BlockState</anno> =:= block</c>, multi-scheduling will
- be blocked. If <c><anno>BlockState</anno> =:= unblock</c> and no-one
- else is blocking multi-scheduling and this process has
- only blocked one time, multi-scheduling will be unblocked.
- One process can block multi-scheduling multiple times.
- If a process has blocked multiple times, it has to
+ blocked. When multi-scheduling is blocked, only
+ one scheduler thread schedules Erlang processes.</p>
+ <p>If <c><anno>BlockState</anno> =:= block</c>, multi-scheduling is
+ blocked. If <c><anno>BlockState</anno> =:= unblock</c> and no one
+ else blocks multi-scheduling, and this process has
+ blocked only once, multi-scheduling is unblocked.</p>
+ <p>One process can block multi-scheduling multiple times.
+ If a process has blocked multiple times, it must
unblock exactly as many times as it has blocked before it
has released its multi-scheduling block. If a process that
- has blocked multi-scheduling exits, it will release its
+ has blocked multi-scheduling exits, it releases its
blocking of multi-scheduling.</p>
<p>The return values are <c>disabled</c>, <c>blocked</c>,
or <c>enabled</c>. The returned value describes the
state just after the call to
<c>erlang:system_flag(multi_scheduling, <anno>BlockState</anno>)</c>
- has been made. The return values are described in the
- documentation of <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>.</p>
- <p><em>NOTE</em>: Blocking of multi-scheduling should normally
- not be needed. If you feel that you need to
- block multi-scheduling, think through the
- problem at least a couple of times again.
- Blocking multi-scheduling should only be used
- as a last resort since it will most likely be
- a <em>very inefficient</em> way to solve the
- problem.</p>
- <p>See also <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>,
+ has been made. For information about the return values, see
+ <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>.</p>
+ <note><p>Blocking of multi-scheduling is normally not needed.
+ If you feel that you need to block multi-scheduling,
+ consider it a few more times again. Blocking multi-scheduling
+ is only to be used as a last resort, as it is most likely
+ a <em>very inefficient</em> way to solve the problem.</p>
+ </note>
+ <p>See also
+ <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>,
<seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="8"/>
+ <fsummary>Sets system flag <c>scheduler_bind_type</c>.</fsummary>
<type name="scheduler_bind_type"/>
- <fsummary>Set system flag scheduler_bind_type</fsummary>
<desc>
<warning>
<p><marker id="system_flag_scheduler_bind_type"></marker>
- This argument is <em>deprecated</em> and
- scheduled for removal in erts-5.10/OTP-R16. Instead of using
- this argument you are advised to use the <c>erl</c> command
- line argument <seealso marker="erts:erl#+sbt">+sbt</seealso>.
- When this argument has been removed a final scheduler bind type
- to use will be determined at emulator boot time.</p>
+ This argument is <em>deprecated</em> and scheduled for
+ removal in <c>ERTS</c> 5.10/OTP R16. Instead of using this
+ argument, use command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt</seealso> in <c>erl(1)</c>.
+ When this argument is removed, a final scheduler bind
+ type to use is determined at emulator boot time.</p>
</warning>
<p>Controls if and how schedulers are bound to logical
processors.</p>
- <p>When <c>erlang:system_flag(scheduler_bind_type, <anno>How</anno>)</c> is
- called, an asynchronous signal is sent to all schedulers
- online which causes them to try to bind or unbind as requested.
- <em>NOTE:</em> If a scheduler fails to bind, this
- will often be silently ignored. This since it isn't always
- possible to verify valid logical processor identifiers. If
- an error is reported, it will be reported to the
- <c>error_logger</c>. If you want to verify that the
- schedulers actually have bound as requested, call
- <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
- </p>
- <p>Schedulers can currently only be bound on newer Linux,
+ <p>When <c>erlang:system_flag(scheduler_bind_type, <anno>How</anno>)</c>
+ is called, an asynchronous signal is sent to all schedulers
+ online, causing them to try to bind or unbind as requested.</p>
+ <note><p>If a scheduler fails to bind, this is often silently
+ ignored, as it is not always possible to verify valid
+ logical processor identifiers. If an error is reported,
+ it is reported to <c>error_logger</c>. To verify that the
+ schedulers have bound as requested, call
+ <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.</p>
+ </note>
+ <p>Schedulers can be bound on newer Linux,
Solaris, FreeBSD, and Windows systems, but more systems will be
- supported in the future.
- </p>
+ supported in future releases.</p>
<p>In order for the runtime system to be able to bind schedulers,
- the CPU topology needs to be known. If the runtime system fails
- to automatically detect the CPU topology, it can be defined.
+ the CPU topology must be known. If the runtime system fails
+ to detect the CPU topology automatically, it can be defined.
For more information on how to define the CPU topology, see
- the <c>erl</c> <seealso marker="erts:erl#+sct">+sct</seealso> command
- line flag.
- </p>
- <p>The runtime system will by default <em>not</em> bind schedulers
- to logical processors.
- </p>
- <p><em>NOTE:</em> If the Erlang runtime system is the only
- operating system process that binds threads to logical processors,
- this improves the performance of the runtime system. However,
- if other operating system processes (as for example another Erlang
- runtime system) also bind threads to logical processors, there
- might be a performance penalty instead. In some cases this
- performance penalty might be severe. If this is the case, you
- are advised to not bind the schedulers.</p>
- <p>Schedulers can be bound in different ways. The <c><anno>How</anno></c>
- argument determines how schedulers are bound. <c><anno>How</anno></c> can
- currently be one of:</p>
+ command-line flag <seealso marker="erts:erl#+sct">+sct</seealso>
+ in <c>erl(1)</c>.</p>
+ <p>The runtime system does by default <em>not</em> bind schedulers
+ to logical processors.</p>
+ <note><p>If the Erlang runtime system is the only OS
+ process binding threads to logical processors, this
+ improves the performance of the runtime system. However,
+ if other OS processes (for example, another Erlang
+ runtime system) also bind threads to logical processors,
+ there can be a performance penalty instead. Sometimes this
+ performance penalty can be severe. If so, it is recommended
+ to not bind the schedulers.</p>
+ </note>
+ <p>Schedulers can be bound in different ways. Argument
+ <c><anno>How</anno></c> determines how schedulers are
+ bound and can be any of the following:</p>
<taglist>
<tag><c>unbound</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt u</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt u</seealso> in <c>erl(1)</c>.
</p></item>
<tag><c>no_spread</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt ns</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt ns</seealso> in <c>erl(1)</c>.
</p></item>
<tag><c>thread_spread</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt ts</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt ts</seealso> in <c>erl(1)</c>.
</p></item>
<tag><c>processor_spread</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt ps</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt ps</seealso> in <c>erl(1)</c>.
</p></item>
<tag><c>spread</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt s</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt s</seealso> in <c>erl(1)</c>.
</p></item>
<tag><c>no_node_thread_spread</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt nnts</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt nnts</seealso> in <c>erl(1)</c>.
</p></item>
<tag><c>no_node_processor_spread</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt nnps</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt nnps</seealso> in <c>erl(1)</c>.
</p></item>
<tag><c>thread_no_node_processor_spread</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt tnnps</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt tnnps</seealso> in <c>erl(1)</c>.
</p></item>
<tag><c>default_bind</c></tag>
- <item><p>Same as the <c>erl</c> command line argument
- <seealso marker="erts:erl#+sbt">+sbt db</seealso>.
+ <item><p>Same as command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt db</seealso> in <c>erl(1)</c>.
</p></item>
</taglist>
- <p>The value returned equals <c><anno>How</anno></c> before the
- <c>scheduler_bind_type</c> flag was changed.</p>
- <p>Failure:</p>
+ <p>The returned value equals <c><anno>How</anno></c> before flag
+ <c>scheduler_bind_type</c> was changed.</p>
+ <p>Failures:</p>
<taglist>
<tag><c>notsup</c></tag>
<item>
@@ -5428,139 +6331,171 @@ ok
</item>
<tag><c>badarg</c></tag>
<item>
- <p>If <c>How</c> isn't one of the documented alternatives.</p>
+ <p>If <c><anno>How</anno></c> is not one of the documented
+ alternatives.</p>
</item>
<tag><c>badarg</c></tag>
<item>
- <p>If no CPU topology information is available.</p>
+ <p>If CPU topology information is unavailable.</p>
</item>
</taglist>
<p>The scheduler bind type can also be set by passing
- the <seealso marker="erts:erl#+sbt">+sbt</seealso> command
- line argument to <c>erl</c>.
- </p>
+ command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt</seealso> to <c>erl(1)</c>.</p>
<p>For more information, see
<seealso marker="#system_info_scheduler_bind_type">erlang:system_info(scheduler_bind_type)</seealso>,
<seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>,
- the <c>erl</c> <seealso marker="erts:erl#+sbt">+sbt</seealso>
- and <seealso marker="erts:erl#+sct">+sct</seealso> command line
- flags.
- </p>
+ as well as command-line flags
+ <seealso marker="erts:erl#+sbt">+sbt</seealso>
+ and <seealso marker="erts:erl#+sct">+sct</seealso>
+ in <c>erl(1)</c>.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="9"/>
- <fsummary>Set system flag scheduler_wall_time</fsummary>
+ <fsummary>Sets system flag <c>scheduler_wall_time</c>.</fsummary>
<desc><p><marker id="system_flag_scheduler_wall_time"></marker>
- Turns on/off scheduler wall time measurements. </p>
- <p>For more information see,
- <seealso marker="#statistics_scheduler_wall_time">erlang:statistics(scheduler_wall_time)</seealso>.
- </p>
+ Turns on or off scheduler wall time measurements.</p>
+ <p>For more information, see
+ <seealso marker="#statistics_scheduler_wall_time">erlang:statistics(scheduler_wall_time)</seealso>.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="10"/>
- <fsummary>Set system flag schedulers_online</fsummary>
+ <fsummary>Sets system flag <c>schedulers_online</c>.</fsummary>
<desc>
<p><marker id="system_flag_schedulers_online"></marker>
- Sets the amount of schedulers online. Valid range is
- <![CDATA[1 <= SchedulersOnline <= erlang:system_info(schedulers)]]>.
- </p>
+ Sets the number of schedulers online. Range is
+ <![CDATA[1 <= SchedulersOnline <= erlang:system_info(schedulers)]]>.</p>
<p>Returns the old value of the flag.</p>
- <p>Note that if the emulator was built with support for <seealso
- marker="#system_flag_dirty_cpu_schedulers_online">dirty schedulers</seealso>,
- changing the number of schedulers online can also change the number of dirty
- CPU schedulers online. For example, if there are 12 schedulers and all are
- online, and 6 dirty CPU schedulers, all online as well, and <c>system_flag/2</c>
- is used to set the number of schedulers online to 6, then the number of dirty
- CPU schedulers online is automatically decreased by half as well, down to 3.
- Similarly, the number of dirty CPU schedulers online increases proportionally
- to increases in the number of schedulers online.</p>
- <p>For more information see,
- <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>,
+ <p>If the emulator was built with support for
+ <seealso marker="#system_flag_dirty_cpu_schedulers_online">dirty schedulers</seealso>,
+ changing the number of schedulers online can also change the
+ number of dirty CPU schedulers online. For example, if 12
+ schedulers and 6 dirty CPU schedulers are online, and
+ <c>system_flag/2</c> is used to set the number of schedulers
+ online to 6, then the number of dirty CPU schedulers online
+ is automatically decreased by half as well, down to 3.
+ Similarly, the number of dirty CPU schedulers online increases
+ proportionally to increases in the number of schedulers online.</p>
+ <p>For more information, see
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>
and
- <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>.
- </p>
+ <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>.</p>
</desc>
</func>
+
<func>
<name name="system_flag" arity="2" clause_i="11"/>
- <fsummary>Set system flag trace_control_word</fsummary>
+ <fsummary>Sets system flag <c>trace_control_word</c>.</fsummary>
<desc>
- <p>Sets the value of the node's trace control word to
- <c><anno>TCW</anno></c>. <c><anno>TCW</anno></c> should be an unsigned integer. For
- more information see documentation of the
+ <p>Sets the value of the node trace control word to
+ <c><anno>TCW</anno></c>, which is to be an unsigned integer.
+ For more information, see the function
<seealso marker="erts:match_spec#set_tcw">set_tcw</seealso>
- function in the match specification documentation in the
- ERTS User's Guide.</p>
+ in Section "Match Specifications in Erlang" in the
+ User's Guide.</p>
<p>Returns the old value of the flag.</p>
</desc>
</func>
+
+ <func>
+ <name name="system_flag" arity="2" clause_i="12"/>
+ <fsummary>Finalize the Time Offset</fsummary>
+ <desc>
+ <p><marker id="system_flag_time_offset"></marker>
+ Finalizes the <seealso marker="#time_offset/0">time offset</seealso>
+ when <seealso marker="time_correction#Single_Time_Warp_Mode">single
+ time warp mode</seealso> is used. If another time warp mode
+ is used, the time offset state is left unchanged.</p>
+ <p>Returns the old state identifier. That is:</p>
+ <list>
+ <item><p>If <c>preliminary</c> is returned, finalization was
+ performed and the time offset is now final.</p></item>
+
+ <item><p>If <c>final</c> is returned, the time offset was
+ already in the final state. This either because another
+ <c>erlang:system_flag(time_offset, finalize)</c> call, or
+ because <seealso marker="time_correction#No_Time_Warp_Mode">no
+ time warp mode</seealso> is used.</p></item>
+
+ <item><p>If <c>volatile</c> is returned, the time offset
+ cannot be finalized because
+ <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+ time warp mode</seealso> is used.</p></item>
+ </list>
+ </desc>
+ </func>
+
<func>
<name name="system_info" arity="1" clause_i="1"/>
<name name="system_info" arity="1" clause_i="2"/>
<name name="system_info" arity="1" clause_i="3"/>
<name name="system_info" arity="1" clause_i="4"/>
<name name="system_info" arity="1" clause_i="5"/>
+ <fsummary>Information about the system allocators.</fsummary>
<type variable="Allocator" name_i="2"/>
<type variable="Version" name_i="2"/>
<type variable="Features" name_i="2"/>
<type variable="Settings" name_i="2"/>
<type variable="Alloc" name_i="3"/>
- <fsummary>Information about the allocators of the system</fsummary>
<desc>
- <p>
- Returns various information about the
- <marker id="system_info_allocator_tags">allocators</marker> of the
+ <marker id="system_info_allocator_tags"></marker>
+ <p>Returns various information about the allocators of the
current system (emulator) as specified by
<c><anno>Item</anno></c>:</p>
+ <marker id="system_info_allocated_areas"></marker>
<taglist>
- <tag><marker id="system_info_allocated_areas"><c>allocated_areas</c></marker></tag>
+ <tag><c>allocated_areas</c></tag>
<item>
<p>Returns a list of tuples with information about
miscellaneous allocated memory areas.</p>
- <p>Each tuple contains an atom describing type of memory as
- first element and amount of allocated memory in bytes as
- second element. In those cases when there is information
- present about allocated and used memory, a third element
- is present. This third element contains the amount of
+ <p>Each tuple contains an atom describing the type of
+ memory as first element and the amount of allocated
+ memory in bytes as second element. When information
+ about allocated and used memory is present, also a
+ third element is present, containing the amount of
used memory in bytes.</p>
<p><c>erlang:system_info(allocated_areas)</c> is intended
- for debugging, and the content is highly implementation
- dependent. The content of the results will therefore
- change when needed without prior notice.</p>
- <p><em>Note:</em> The sum of these values is <em>not</em>
+ for debugging, and the content is highly
+ implementation-dependent. The content of the results
+ therefore changes when needed without prior notice.</p>
+ <p>Notice that the sum of these values is <em>not</em>
the total amount of memory allocated by the emulator.
Some values are part of other values, and some memory
- areas are not part of the result. If you are interested
- in the total amount of memory allocated by the emulator
- see <seealso marker="#memory/0">erlang:memory/0,1</seealso>.</p>
+ areas are not part of the result. For information about
+ the total amount of memory allocated by the emulator, see
+ <seealso marker="#memory/0">erlang:memory/0,1</seealso>.</p>
</item>
- <tag><marker id="system_info_allocator"><c>allocator</c></marker></tag>
+ <tag><c>allocator</c></tag>
<item>
- <p>Returns <c>{<anno>Allocator</anno>, <anno>Version</anno>, <anno>Features</anno>, <anno>Settings</anno>}.</c></p>
- <p>Explanation:</p>
+ <marker id="system_info_allocator"></marker>
+ <p>Returns <c>{<anno>Allocator</anno>, <anno>Version</anno>,
+ <anno>Features</anno>, <anno>Settings</anno></c>, where:</p>
<list type="bulleted">
<item>
- <p><c><anno>Allocator</anno></c> corresponds to the <c>malloc()</c>
- implementation used. If <c><anno>Allocator</anno></c> equals
+ <p><c><anno>Allocator</anno></c> corresponds to the
+ <c>malloc()</c> implementation used. If
+ <c><anno>Allocator</anno></c> equals
<c>undefined</c>, the <c>malloc()</c> implementation
- used could not be identified. Currently
- <c>glibc</c> can be identified.</p>
+ used cannot be identified. <c>glibc</c> can be
+ identified.</p>
</item>
<item>
- <p><c><anno>Version</anno></c> is a list of integers (but not a
- string) representing the version of
+ <p><c><anno>Version</anno></c> is a list of integers
+ (but not a string) representing the version of
the <c>malloc()</c> implementation used.</p>
</item>
<item>
- <p><c><anno>Features</anno></c> is a list of atoms representing
- allocation features used.</p>
+ <p><c><anno>Features</anno></c> is a list of atoms
+ representing the allocation features used.</p>
</item>
<item>
- <p><c><anno>Settings</anno></c> is a list of subsystems, their
- configurable parameters, and used values. Settings
- may differ between different combinations of
+ <p><c><anno>Settings</anno></c> is a list of subsystems,
+ their configurable parameters, and used values. Settings
+ can differ between different combinations of
platforms, allocators, and allocation features.
Memory sizes are given in bytes.</p>
</item>
@@ -5568,165 +6503,169 @@ ok
<p>See also "System Flags Effecting erts_alloc" in
<seealso marker="erts:erts_alloc#flags">erts_alloc(3)</seealso>.</p>
</item>
- <tag><marker id="system_info_alloc_util_allocators"><c>alloc_util_allocators</c></marker></tag>
+ <tag><c>alloc_util_allocators</c></tag>
<item>
- <p>Returns a list of the names of all allocators
- using the ERTS internal <c>alloc_util</c> framework
- as atoms. For more information see the
- <seealso marker="erts:erts_alloc#alloc_util">"the
- alloc_util framework" section in the
- erts_alloc(3)</seealso> documentation.
- </p>
+ <marker id="system_info_alloc_util_allocators"></marker>
+ <p>Returns a list of the names of all allocators using
+ the <c>ERTS</c> internal <c>alloc_util</c> framework
+ as atoms. For more information, see Section
+ <seealso marker="erts:erts_alloc#alloc_util">"The
+ alloc_util framework" in erts_alloc(3)</seealso>.</p>
</item>
- <tag><marker id="system_info_allocator_tuple"><c>{allocator, <anno>Alloc</anno>}</c></marker></tag>
+ <tag><c>{allocator, <anno>Alloc</anno>}</c></tag>
<item>
+ <marker id="system_info_allocator_tuple"></marker>
<p>Returns information about the specified allocator.
- As of erts version 5.6.1 the return value is a list
- of <c>{instance, InstanceNo, InstanceInfo}</c> tuples
+ As from <c>ERTS</c> 5.6.1, the return value is a list
+ of <c>{instance, InstanceNo, InstanceInfo}</c> tuples,
where <c>InstanceInfo</c> contains information about
- a specific instance of the allocator. As of erts version
- 5.10.4 the returned list when calling
+ a specific instance of the allocator. As from
+ <c>ERTS</c> 5.10.4, the returned list when calling
<c>erlang:system_info({allocator, mseg_alloc})</c> also
- include an <c>{erts_mmap, _}</c> tuple as one element
- in the list.
- If <c><anno>Alloc</anno></c> is not a recognized allocator,
- <c>undefined</c> is returned. If <c><anno>Alloc</anno></c> is disabled,
+ includes an <c>{erts_mmap, _}</c> tuple as one element
+ in the list. If <c><anno>Alloc</anno></c> is not a
+ recognized allocator, <c>undefined</c> is returned.
+ If <c><anno>Alloc</anno></c> is disabled,
<c>false</c> is returned.</p>
- <p><em>Note:</em> The information returned is highly
- implementation dependent and may be changed, or removed
+ <p>Notice that the information returned is highly
+ implementation-dependent and can be changed or removed
at any time without prior notice. It was initially
intended as a tool when developing new allocators, but
- since it might be of interest for others it has been
+ as it can be of interest for others it has been
briefly documented.</p>
<p>The recognized allocators are listed in
<seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>.
After reading the <c>erts_alloc(3)</c> documentation,
the returned information
- should more or less speak for itself. But it can be worth
+ more or less speaks for itself, but it can be worth
explaining some things. Call counts are presented by two
- values. The first value is giga calls, and the second
- value is calls. <c>mbcs</c>, and <c>sbcs</c> are
- abbreviations for, respectively, multi-block carriers, and
- single-block carriers. Sizes are presented in bytes. When
- it is not a size that is presented, it is the amount of
- something. Sizes and amounts are often presented by three
- values, the first is current value, the second is maximum
- value since the last call to
- <c>erlang:system_info({allocator, Alloc})</c>, and
- the third is maximum value since the emulator was started.
- If only one value is present, it is the current value.
+ values, the first value is giga calls, and the second
+ value is calls. <c>mbcs</c> and <c>sbcs</c> denote
+ multi-block carriers, and single-block carriers,
+ respectively. Sizes are presented in bytes. When a
+ size is not presented, it is the amount of something.
+ Sizes and amounts are often presented by three values:</p>
+ <list type="bulleted">
+ <item>The first is the current value.</item>
+ <item>The second is the maximum value since the last call
+ to <c>erlang:system_info({allocator, Alloc})</c>.</item>
+ <item>The third is the maximum value since the emulator
+ was started.</item>
+ </list>
+ <p>If only one value is present, it is the current value.
<c>fix_alloc</c> memory block types are presented by two
- values. The first value is memory pool size and
- the second value used memory size.</p>
+ values. The first value is the memory pool size and
+ the second value is the used memory size.</p>
</item>
- <tag><marker id="system_info_allocator_sizes"><c>{allocator_sizes, <anno>Alloc</anno>}</c></marker></tag>
+ <tag><c>{allocator_sizes, <anno>Alloc</anno>}</c></tag>
<item>
+ <marker id="system_info_allocator_sizes"></marker>
<p>Returns various size information for the specified
allocator. The information returned is a subset of the
information returned by
- <seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, <anno>Alloc</anno>})</seealso>.
+ <seealso marker="#system_info_allocator_tuple"><c>erlang:system_info({allocator, <anno>Alloc</anno>})</c></seealso>.
</p>
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="system_info" arity="1" clause_i="10"/>
<name name="system_info" arity="1" clause_i="11"/>
+ <fsummary>Information about the CPU topology of the system.</fsummary>
<type name="cpu_topology"/>
<type name="level_entry"/>
<type_desc name="cpu_topology">
- <marker id="system_info_cpu_topology"></marker>
All <c><anno>LevelEntry</anno></c>s of a list
must contain the same <c><anno>LevelTag</anno></c>, except
on the top level where both <c>node</c> and
- <c>processor</c> <c><anno>LevelTag</anno></c>s may co-exist.
+ <c>processor</c> <c><anno>LevelTag</anno></c>s can coexist.
</type_desc>
<type_desc name="level_entry">
- <c>{<anno>LevelTag</anno>, <anno>SubLevel</anno>} == {<anno>LevelTag</anno>, [], <anno>SubLevel</anno>}</c>
+ <c>{<anno>LevelTag</anno>,
+ <anno>SubLevel</anno>} == {<anno>LevelTag</anno>, [],
+ <anno>SubLevel</anno>}</c>
</type_desc>
<type name="level_tag"/>
<type_desc name="level_tag">
- More <c><anno>LevelTag</anno></c>s may be introduced in the future.
+ More <c><anno>LevelTag</anno></c>s can be introduced in a
+ future release.
</type_desc>
<type name="sub_level"/>
<type name="info_list"/>
<type_desc name="info_list">
- The <c>info_list()</c> may be extended in the future.
+ The <c>info_list()</c> can be extended in a future release.
</type_desc>
- <fsummary>Information about the CPU topology of the system</fsummary>
<desc>
- <p>Returns various information about the
- <marker id="system_info_cpu_topology_tags">CPU topology</marker>
- of the current system
- (emulator) as specified by <c><anno>Item</anno></c>:</p>
+ <marker id="system_info_cpu_topology_tags"></marker>
+ <marker id="system_info_cpu_topology"></marker>
+ <p>Returns various information about the CPU topology of
+ the current system (emulator) as specified by
+ <c><anno>Item</anno></c>:</p>
<taglist>
<tag><c>cpu_topology</c></tag>
<item>
- <p>Returns the <c><anno>CpuTopology</anno></c> which currently is used by the
- emulator. The CPU topology is used when binding schedulers
+ <p>Returns the <c><anno>CpuTopology</anno></c> currently used by
+ the emulator. The CPU topology is used when binding schedulers
to logical processors. The CPU topology used is the
- <seealso marker="erlang#system_info_cpu_topology_defined">user
- defined CPU topology</seealso> if such exists; otherwise, the
- <seealso marker="erlang#system_info_cpu_topology_detected">automatically
- detected CPU topology</seealso> if such exists. If no CPU topology
+ <seealso marker="erlang#system_info_cpu_topology_defined">user-defined CPU topology</seealso>,
+ if such exists, otherwise the
+ <seealso marker="erlang#system_info_cpu_topology_detected">automatically detected CPU topology</seealso>,
+ if such exists. If no CPU topology
exists, <c>undefined</c> is returned.</p>
- <p><c>node</c> refers to NUMA (non-uniform memory access)
- nodes, and <c>thread</c> refers to hardware threads
- (e.g. Intels hyper-threads).</p>
- <p>A level in the <c><anno>CpuTopology</anno></c> term can be omitted if
- only one entry exists and the <c><anno>InfoList</anno></c> is empty.
- </p>
+ <p><c>node</c> refers to Non-Uniform Memory Access (NUMA)
+ nodes. <c>thread</c> refers to hardware threads
+ (for example, Intel hyper-threads).</p>
+ <p>A level in term <c><anno>CpuTopology</anno></c> can be
+ omitted if only one entry exists and
+ <c><anno>InfoList</anno></c> is empty.</p>
<p><c>thread</c> can only be a sub level to <c>core</c>.
- <c>core</c> can be a sub level to either <c>processor</c>
- or <c>node</c>. <c>processor</c> can either be on the
+ <c>core</c> can be a sub level to <c>processor</c>
+ or <c>node</c>. <c>processor</c> can be on the
top level or a sub level to <c>node</c>. <c>node</c>
- can either be on the top level or a sub level to
+ can be on the top level or a sub level to
<c>processor</c>. That is, NUMA nodes can be processor
internal or processor external. A CPU topology can
consist of a mix of processor internal and external
- NUMA nodes, as long as each logical CPU belongs to one
- and only one NUMA node. Cache hierarchy is not part of
- the <c><anno>CpuTopology</anno></c> type yet, but will be in the
- future. Other things may also make it into the CPU
- topology in the future. In other words, expect the
- <c><anno>CpuTopology</anno></c> type to change.
- </p>
- </item>
- <tag><marker id="system_info_cpu_topology_defined"><c>{cpu_topology, defined}</c></marker></tag>
- <item>
- <p>Returns the user defined <c><anno>CpuTopology</anno></c>. For more
- information see the documentation of
- the <c>erl</c> <seealso marker="erts:erl#+sct">+sct</seealso> command
- line flag, and the documentation of the
- <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>
- argument.
- </p>
- </item>
- <tag><marker id="system_info_cpu_topology_detected"><c>{cpu_topology, detected}</c></marker></tag>
- <item>
- <p>Returns the automatically detected <c><anno>CpuTopology</anno></c>. The
- emulator currently only detects the CPU topology on some newer
- Linux, Solaris, FreeBSD, and Windows systems. On Windows system with
- more than 32 logical processors the CPU topology is not detected.
- </p>
- <p>For more information see the documentation of the
- <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>
- argument.
- </p>
+ NUMA nodes, as long as each logical CPU belongs to
+ <em>one</em> NUMA node. Cache hierarchy is not part of
+ the <c><anno>CpuTopology</anno></c> type, but will be in a
+ future release. Other things can also make it into the CPU
+ topology in a future release. In other words, expect the
+ <c><anno>CpuTopology</anno></c> type to change.</p>
+ </item>
+ <tag><c>{cpu_topology, defined}</c></tag>
+ <item>
+ <marker id="system_info_cpu_topology_defined"></marker>
+ <p>Returns the user-defined <c><anno>CpuTopology</anno></c>.
+ For more information, see command-line flag
+ <seealso marker="erts:erl#+sct">+sct</seealso> in
+ <c>erl(1)</c> and argument
+ <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>.</p>
+ </item>
+ <tag><c>{cpu_topology, detected}</c></tag>
+ <item>
+ <marker id="system_info_cpu_topology_detected"></marker>
+ <p>Returns the automatically detected
+ <c><anno>CpuTopology</anno>y</c>. The
+ emulator detects the CPU topology on some newer
+ Linux, Solaris, FreeBSD, and Windows systems.
+ On Windows system with more than 32 logical processors,
+ the CPU topology is not detected.</p>
+ <p>For more information, see argument
+ <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>.</p>
</item>
<tag><c>{cpu_topology, used}</c></tag>
<item>
- <p>Returns the <c><anno>CpuTopology</anno></c> which is used by the
- emulator. For more information see the
- documentation of the
- <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>
- argument.
- </p>
+ <p>Returns <c><anno>CpuTopology</anno></c> used by the emulator.
+ For more information, see argument
+ <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>.</p>
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="system_info" arity="1" clause_i="6"/>
<name name="system_info" arity="1" clause_i="7"/>
@@ -5776,7 +6715,19 @@ ok
<name name="system_info" arity="1" clause_i="53"/>
<name name="system_info" arity="1" clause_i="54"/>
<name name="system_info" arity="1" clause_i="55"/>
- <fsummary>Information about the system</fsummary>
+ <name name="system_info" arity="1" clause_i="56"/>
+ <name name="system_info" arity="1" clause_i="57"/>
+ <name name="system_info" arity="1" clause_i="58"/>
+ <name name="system_info" arity="1" clause_i="59"/>
+ <name name="system_info" arity="1" clause_i="60"/>
+ <name name="system_info" arity="1" clause_i="61"/>
+ <name name="system_info" arity="1" clause_i="62"/>
+ <name name="system_info" arity="1" clause_i="63"/>
+ <name name="system_info" arity="1" clause_i="64"/>
+ <name name="system_info" arity="1" clause_i="65"/>
+ <name name="system_info" arity="1" clause_i="66"/>
+ <name name="system_info" arity="1" clause_i="67"/>
+ <fsummary>Information about the system.</fsummary>
<desc>
<p>Returns various information about the current system
(emulator) as specified by <c><anno>Item</anno></c>:</p>
@@ -5793,8 +6744,7 @@ ok
Other possible return values are <c>debug</c>, <c>purify</c>,
<c>quantify</c>, <c>purecov</c>, <c>gcov</c>, <c>valgrind</c>,
<c>gprof</c>, and <c>lcnt</c>. Possible return values
- may be added and/or removed at any time without prior notice.
- </p>
+ can be added or removed at any time without prior notice.</p>
</item>
<tag><c>c_compiler_used</c></tag>
<item>
@@ -5802,26 +6752,25 @@ ok
compiling the runtime system. The first element is an
atom describing the name of the compiler, or <c>undefined</c>
if unknown. The second element is a term describing the
- version of the compiler, or <c>undefined</c> if unknown.
- </p>
+ version of the compiler, or <c>undefined</c> if unknown.</p>
</item>
<tag><c>check_io</c></tag>
<item>
<p>Returns a list containing miscellaneous information
- regarding the emulators internal I/O checking. Note,
- the content of the returned list may vary between
- platforms and over time. The only thing guaranteed is
+ about the emulators internal I/O checking. Notice that
+ the content of the returned list can vary between
+ platforms and over time. It is only guaranteed
that a list is returned.</p>
</item>
<tag><c>compat_rel</c></tag>
<item>
<p>Returns the compatibility mode of the local node as
an integer. The integer returned represents the
- Erlang/OTP release which the current emulator has been
+ Erlang/OTP release that the current emulator has been
set to be backward compatible with. The compatibility
- mode can be configured at startup by using the command
- line flag <c>+R</c>, see
- <seealso marker="erts:erl#compat_rel">erl(1)</seealso>.</p>
+ mode can be configured at startup by using command-line flag
+ <seealso marker="erts:erl#compat_rel">+R</seealso> in
+ <c>erl(1)</c>.</p>
</item>
<tag><c>cpu_topology</c></tag>
<item>
@@ -5834,176 +6783,200 @@ ok
creation of a node is stored in process identifiers, port
identifiers, and references. This makes it (to some
extent) possible to distinguish between identifiers from
- different incarnations of a node. Currently valid
- creations are integers in the range 1..3, but this may
- (probably will) change in the future. If the node is not
- alive, 0 is returned.</p>
+ different incarnations of a node. The valid
+ creations are integers in the range 1..3, but this will
+ probably change in a future release. If the node is not
+ alive, <c>0</c> is returned.</p>
</item>
<tag><c>debug_compiled</c></tag>
<item>
<p>Returns <c>true</c> if the emulator has been debug
- compiled; otherwise, <c>false</c>.
- </p>
+ compiled, otherwise <c>false</c>.</p>
+ </item>
+ <tag><c>delayed_node_table_gc</c></tag>
+ <item>
+ <marker id="system_info_delayed_node_table_gc"></marker>
+ <p>Returns the amount of time in seconds garbage collection
+ of an entry in a node table is delayed. This limit can be set
+ on startup by passing the command line flag
+ <seealso marker="erts:erl#+zdntgc">+zdntgc</seealso>
+ to <c>erl</c>. For more information see the documentation of the
+ command line flag.</p>
</item>
- <tag><marker id="system_info_dirty_cpu_schedulers"><c>dirty_cpu_schedulers</c></marker></tag>
+ <tag><c>dirty_cpu_schedulers</c></tag>
<item>
+ <marker id="system_info_dirty_cpu_schedulers"></marker>
<p>Returns the number of dirty CPU scheduler threads used by
the emulator. Dirty CPU schedulers execute CPU-bound
- native functions such as NIFs, linked-in driver code, and BIFs
- that cannot be managed cleanly by the emulator's normal schedulers.
- </p>
- <p>The number of dirty CPU scheduler threads is determined at emulator
- boot time and cannot be changed after that. The number of dirty CPU
- scheduler threads online can however be changed at any time. The number of
- dirty CPU schedulers can be set on startup by passing
- the <seealso marker="erts:erl#+SDcpu">+SDcpu</seealso> or
- <seealso marker="erts:erl#+SDPcpu">+SDPcpu</seealso> command line flags,
- see <seealso marker="erts:erl#+SDcpu">erl(1)</seealso>.
- </p>
- <p><em>Note that the dirty schedulers functionality is experimental</em>, and
- that you have to enable support for dirty schedulers when building OTP in
- order to try out the functionality.</p>
- <p>See also <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>,
+ native functions, such as NIFs, linked-in driver code,
+ and BIFs that cannot be managed cleanly by the normal
+ emulator schedulers.</p>
+ <p>The number of dirty CPU scheduler threads is determined
+ at emulator boot time and cannot be changed after that.
+ However, the number of dirty CPU scheduler threads online
+ can be changed at any time. The number of dirty CPU
+ schedulers can be set at startup by passing
+ command-line flag
+ <seealso marker="erts:erl#+SDcpu">+SDcpu</seealso> or
+ <seealso marker="erts:erl#+SDPcpu">+SDPcpu</seealso> in
+ <c>erl(1)</c>.</p>
+ <p>Notice that the dirty schedulers functionality is
+ experimental. Enable support for dirty schedulers when
+ building OTP to try out the functionality.</p>
+ <p>See also
+ <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>,
<seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>,
<seealso marker="#system_info_dirty_io_schedulers">erlang:system_info(dirty_io_schedulers)</seealso>,
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>,
<seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>, and
<seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>.</p>
</item>
- <tag><marker id="system_info_dirty_cpu_schedulers_online"><c>dirty_cpu_schedulers_online</c></marker></tag>
- <item>
- <p>Returns the number of dirty CPU schedulers online. The return value
- satisfies the following relationship:
- <c><![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]></c>, where <c>N</c> is
- the lesser of the return values of <c>erlang:system_info(dirty_cpu_schedulers)</c> and
- <c>erlang:system_info(schedulers_online)</c>.
- </p>
- <p>The number of dirty CPU schedulers online can be set on startup by passing
- the <seealso marker="erts:erl#+SDcpu">+SDcpu</seealso> command line flag, see
- <seealso marker="erts:erl#+SDcpu">erl(1)</seealso>.
- </p>
- <p><em>Note that the dirty schedulers functionality is experimental</em>, and
- that you have to enable support for dirty schedulers when building OTP in
- order to try out the functionality.</p>
+ <tag><c>dirty_cpu_schedulers_online</c></tag>
+ <item>
+ <marker id="system_info_dirty_cpu_schedulers_online"></marker>
+ <p>Returns the number of dirty CPU schedulers online.
+ The return value satisfies
+ <c><![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]></c>,
+ where <c>N</c> is the smallest of the return values of
+ <c>erlang:system_info(dirty_cpu_schedulers)</c> and
+ <c>erlang:system_info(schedulers_online)</c>.</p>
+ <p>The number of dirty CPU schedulers online can be set at
+ startup by passing command-line flag
+ <seealso marker="erts:erl#+SDcpu">+SDcpu</seealso> in
+ <c>erl(1)</c>.</p>
+ <p>Notice that the dirty schedulers functionality is
+ experimental. Enable support for dirty schedulers when
+ building OTP to try out the functionality.</p>
<p>For more information, see
<seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso>,
<seealso marker="#system_info_dirty_io_schedulers">erlang:system_info(dirty_io_schedulers)</seealso>,
<seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>, and
- <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>.
- </p>
- </item>
- <tag><marker id="system_info_dirty_io_schedulers"><c>dirty_io_schedulers</c></marker></tag>
- <item>
- <p>Returns the number of dirty I/O schedulers as an integer. Dirty I/O schedulers
- execute I/O-bound native functions such as NIFs and linked-in driver code that
- cannot be managed cleanly by the emulator's normal schedulers.
- </p>
- <p>This value can be set on startup by passing
- the <seealso marker="erts:erl#+SDio">+SDio</seealso> command line flag, see
- <seealso marker="erts:erl#+SDio">erl(1)</seealso>.
- </p>
- <p><em>Note that the dirty schedulers functionality is experimental</em>, and
- that you have to enable support for dirty schedulers when building OTP in
- order to try out the functionality.</p>
+ <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>.</p>
+ </item>
+ <tag><c>dirty_io_schedulers</c></tag>
+ <item>
+ <marker id="system_info_dirty_io_schedulers"></marker>
+ <p>Returns the number of dirty I/O schedulers as an integer.
+ Dirty I/O schedulers execute I/O-bound native functions,
+ such as NIFs and linked-in driver code, which cannot be
+ managed cleanly by the normal emulator schedulers.</p>
+ <p>This value can be set at startup by passing command-line
+ argument <seealso marker="erts:erl#+SDio">+SDio</seealso>
+ in <c>erl(1)</c>.</p>
+ <p>Notice that the dirty schedulers functionality is
+ experimental. Enable support for dirty schedulers when
+ building OTP to try out the functionality.</p>
<p>For more information, see
<seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso>,
<seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>, and
- <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>.
- </p>
+ <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>.</p>
</item>
<tag><c>dist</c></tag>
<item>
<p>Returns a binary containing a string of distribution
information formatted as in Erlang crash dumps. For more
- information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso>
- chapter in the ERTS User's Guide.</p>
+ information, see Section
+ <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso>
+ in the User's Guide.</p>
</item>
- <tag><marker id="system_info_dist_buf_busy_limit"><c>dist_buf_busy_limit</c></marker></tag>
+ <tag><c>dist_buf_busy_limit</c></tag>
<item>
+ <marker id="system_info_dist_buf_busy_limit"></marker>
<p>Returns the value of the distribution buffer busy limit
- in bytes. This limit can be set on startup by passing the
- <seealso marker="erts:erl#+zdbbl">+zdbbl</seealso> command line
- flag to <c>erl</c>.</p>
+ in bytes. This limit can be set at startup by passing
+ command-line flag
+ <seealso marker="erts:erl#+zdbbl">+zdbbl</seealso>
+ to <c>erl</c>.</p>
</item>
<tag><c>dist_ctrl</c></tag>
<item>
<p>Returns a list of tuples
- <c>{Node, ControllingEntity}</c>, one entry for each
- connected remote node. The <c><anno>Node</anno></c> is the name of the
- node and the <c><anno>ControllingEntity</anno></c> is the port or pid
- responsible for the communication to that node. More
- specifically, the <c><anno>ControllingEntity</anno></c> for nodes
- connected via TCP/IP (the normal case) is the socket
- actually used in communication with the specific node.</p>
+ <c>{<anno>Node</anno>, <anno>ControllingEntity</anno>}</c>,
+ one entry for each connected remote node.
+ <c><anno>Node</anno></c> is the node name
+ and <c><anno>ControllingEntity</anno></c> is the port or process
+ identifier responsible for the communication to that node.
+ More specifically, <c><anno>ControllingEntity</anno></c> for
+ nodes connected through TCP/IP (the normal case) is the socket
+ used in communication with the specific node.</p>
</item>
<tag><c>driver_version</c></tag>
<item>
- <p>Returns a string containing the erlang driver version
- used by the runtime system. It will be on the form
+ <p>Returns a string containing the Erlang driver version
+ used by the runtime system. It has the form
<seealso marker="erts:erl_driver#version_management">"&lt;major ver&gt;.&lt;minor ver&gt;"</seealso>.</p>
</item>
<tag><c>dynamic_trace</c></tag>
<item>
<p>Returns an atom describing the dynamic trace framework
- compiled into the virtual machine. It can currently be either
- <c>dtrace</c>, <c>systemtap</c> or <c>none</c>. For a
- commercial or standard build, this is always <c>none</c>,
- the other return values indicate a custom configuration
- (e.g. <c>./configure --with-dynamic-trace=dtrace</c>). See
- the <seealso marker="runtime_tools:dyntrace">dyntrace
- </seealso> manual page and the
+ compiled into the virtual machine. It can be
+ <c>dtrace</c>, <c>systemtap</c>, or <c>none</c>. For a
+ commercial or standard build, it is always <c>none</c>.
+ The other return values indicate a custom configuration
+ (for example, <c>./configure --with-dynamic-trace=dtrace</c>).
+ For more information about dynamic tracing, see the
+ <seealso marker="runtime_tools:dyntrace">dyntrace</seealso>
+ manual page and the
<c>README.dtrace</c>/<c>README.systemtap</c> files in the
- Erlang source code top directory for more information
- about dynamic tracing.</p>
+ Erlang source code top directory.</p>
</item>
<tag><c>dynamic_trace_probes</c></tag>
<item>
- <p>Returns a <c>boolean()</c> indicating if dynamic trace probes
- (either dtrace or systemtap) are built into the
- emulator. This can only be <c>true</c> if the virtual
- machine was built for dynamic tracing
- (i.e. <c>system_info(dynamic_trace)</c> returns
+ <p>Returns a <c>boolean()</c> indicating if dynamic trace
+ probes (<c>dtrace</c> or <c>systemtap</c>) are built into
+ the emulator. This can only be <c>true</c> if the Virtual
+ Machine was built for dynamic tracing (that is,
+ <c>system_info(dynamic_trace)</c> returns
<c>dtrace</c> or <c>systemtap</c>).</p>
</item>
+ <tag><marker id="system_info_end_time"/><c>end_time</c></tag>
+ <item><p>The last <seealso marker="#monotonic_time/0">Erlang monotonic
+ time</seealso> in <c>native</c>
+ <seealso marker="#type_time_unit">time unit</seealso> that
+ can be represented internally in the current Erlang runtime system
+ instance. The time between the
+ <seealso marker="#system_info_start_time">start time</seealso> and
+ the end time is at least a quarter of a millennium.</p></item>
<tag><c>elib_malloc</c></tag>
<item>
<p>This option will be removed in a future release.
- The return value will always be <c>false</c> since
- the elib_malloc allocator has been removed.</p>
+ The return value will always be <c>false</c>, as the
+ <c>elib_malloc</c> allocator has been removed.</p>
</item>
- <tag><marker id="system_info_eager_check_io"><c>eager_check_io</c></marker></tag>
+ <tag><marker id="system_info_eager_check_io"/><c>eager_check_io</c></tag>
<item>
<p>
- Returns the value of the <c>erl</c>
- <seealso marker="erl#+secio">+secio</seealso> command line
- flag which is either <c>true</c> or <c>false</c>. See the
+ Returns the value of the <c>erl</c> command line flag
+ <seealso marker="erl#+secio">+secio</seealso>
+ which is either <c>true</c> or <c>false</c>. See the
documentation of the command line flag for information about
the different values.
</p>
</item>
<tag><c>ets_limit</c></tag>
<item>
- <p>Returns the maximum number of ETS tables allowed. This limit
- can be increased on startup by passing the <seealso
- marker="erts:erl#+e">+e</seealso> command line flag to
- <c>erl</c> or by setting the environment variable
- <c>ERL_MAX_ETS_TABLES</c> before starting the Erlang runtime
- system.</p>
+ <p>Returns the maximum number of ETS tables allowed. This
+ limit can be increased at startup by passing
+ command-line flag
+ <seealso marker="erts:erl#+e">+e</seealso> to
+ <c>erl(1)</c> or by setting environment variable
+ <c>ERL_MAX_ETS_TABLES</c> before starting the Erlang
+ runtime system.</p>
</item>
<tag><c>fullsweep_after</c></tag>
<item>
- <p>Returns <c>{fullsweep_after, integer() >= 0}</c> which is the
- <c>fullsweep_after</c> garbage collection setting used
- by default. For more information see
- <c>garbage_collection</c> described below.</p>
+ <p>Returns <c>{fullsweep_after, integer() >= 0}</c>, which is
+ the <c>fullsweep_after</c> garbage collection setting used
+ by default. For more information, see
+ <c>garbage_collection</c> described in the following.</p>
</item>
<tag><c>garbage_collection</c></tag>
<item>
<p>Returns a list describing the default garbage collection
settings. A process spawned on the local node by a
- <c>spawn</c> or <c>spawn_link</c> will use these
+ <c>spawn</c> or <c>spawn_link</c> uses these
garbage collection settings. The default settings can be
- changed by use of
+ changed by using
<seealso marker="#system_flag/2">system_flag/2</seealso>.
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>
can spawn a process that does not use the default
@@ -6017,8 +6990,8 @@ ok
</item>
<tag><c>heap_type</c></tag>
<item>
- <p>Returns the heap type used by the current emulator.
- Currently only the following heap type exists:</p>
+ <p>Returns the heap type used by the current emulator. One
+ heap type exists:</p>
<taglist>
<tag><c>private</c></tag>
<item>
@@ -6033,51 +7006,51 @@ ok
<item>
<p>Returns a binary containing a string of miscellaneous
system information formatted as in Erlang crash dumps.
- For more information see the
- <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter in the ERTS
- User's Guide.</p>
+ For more information, see Section
+ <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso>
+ in the User's Guide.</p>
</item>
<tag><c>kernel_poll</c></tag>
<item>
<p>Returns <c>true</c> if the emulator uses some kind of
- kernel-poll implementation; otherwise, <c>false</c>.</p>
+ kernel-poll implementation, otherwise <c>false</c>.</p>
</item>
<tag><c>loaded</c></tag>
<item>
<p>Returns a binary containing a string of loaded module
information formatted as in Erlang crash dumps. For more
- information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
- in the ERTS User's Guide.</p>
+ information, see Section
+ <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso>
+ in the User's Guide.</p>
</item>
- <tag><marker id="logical_processors"><c>logical_processors</c></marker></tag>
+ <tag><c>logical_processors</c></tag>
<item>
+ <marker id="logical_processors"></marker>
<p>Returns the detected number of logical processors configured
- on the system. The return value is either an integer, or
- the atom <c>unknown</c> if the emulator wasn't able to
- detect logical processors configured.
- </p>
+ in the system. The return value is either an integer, or
+ the atom <c>unknown</c> if the emulator cannot
+ detect the configured logical processors.</p>
</item>
- <tag><marker id="logical_processors_available"><c>logical_processors_available</c></marker></tag>
+ <tag><c>logical_processors_available</c></tag>
<item>
- <p>Returns the detected number of logical processors available to
- the Erlang runtime system. The return value is either an
- integer, or the atom <c>unknown</c> if the emulator wasn't
- able to detect logical processors available. The number
- of logical processors available is less than or equal to
- the number of <seealso marker="#logical_processors_online">logical
- processors online</seealso>.
- </p>
+ <marker id="logical_processors_available"></marker>
+ <p>Returns the detected number of logical processors available
+ to the Erlang runtime system. The return value is either an
+ integer, or the atom <c>unknown</c> if the emulator
+ cannot detect the available logical processors. The number
+ of available logical processors is less than or equal to
+ the number of
+ <seealso marker="#logical_processors_online">logical processors online</seealso>.</p>
</item>
- <tag><marker id="logical_processors_online"><c>logical_processors_online</c></marker></tag>
+ <tag><c>logical_processors_online</c></tag>
<item>
+ <marker id="logical_processors_online"></marker>
<p>Returns the detected number of logical processors online on
the system. The return value is either an integer,
- or the atom <c>unknown</c> if the emulator wasn't able to
+ or the atom <c>unknown</c> if the emulator cannot
detect logical processors online. The number of logical
processors online is less than or equal to the number of
- <seealso marker="#logical_processors">logical processors
- configured</seealso>.
- </p>
+ <seealso marker="#logical_processors">logical processors configured</seealso>.</p>
</item>
<tag><c>machine</c></tag>
<item>
@@ -6085,27 +7058,30 @@ ok
</item>
<tag><c>min_heap_size</c></tag>
<item>
- <p>Returns <c>{min_heap_size, <anno>MinHeapSize</anno>}</c> where <c><anno>MinHeapSize</anno></c> is the current system wide
- minimum heap size for spawned processes.</p>
+ <p>Returns <c>{min_heap_size, <anno>MinHeapSize</anno>}</c>,
+ where <c><anno>MinHeapSize</anno></c> is the current
+ system-wide minimum heap size for spawned processes.</p>
</item>
<tag><c>min_bin_vheap_size</c></tag>
<item>
- <p>Returns <c>{min_bin_vheap_size, <anno>MinBinVHeapSize</anno>}</c> where <c><anno>MinBinVHeapSize</anno></c> is the current system wide
+ <p>Returns <c>{min_bin_vheap_size,
+ <anno>MinBinVHeapSize</anno>}</c>, where
+ <c><anno>MinBinVHeapSize</anno></c> is the current system-wide
minimum binary virtual heap size for spawned processes.</p>
</item>
<tag><c>modified_timing_level</c></tag>
<item>
- <p>Returns the modified timing level (an integer) if
- modified timing has been enabled; otherwise,
- <c>undefined</c>. See the <c>+T</c> command line flag
- in the documentation of the
- <seealso marker="erts:erl#+T">erl(1)</seealso>
- command for more information on modified timing.</p>
+ <p>Returns the modified timing-level (an integer) if
+ modified timing is enabled, otherwise, <c>undefined</c>.
+ For more information about modified timing, see
+ command-line flag
+ <seealso marker="erts:erl#+T">+T</seealso>
+ in <c>erl(1)</c></p>
</item>
- <tag><marker id="system_info_multi_scheduling"><c>multi_scheduling</c></marker></tag>
+ <tag><c>multi_scheduling</c></tag>
<item>
- <p>Returns <c>disabled</c>, <c>blocked</c>, or <c>enabled</c>.
- A description of the return values:</p>
+ <marker id="system_info_multi_scheduling"></marker>
+ <p>Returns <c>disabled</c>, <c>blocked</c>, or <c>enabled</c>:</p>
<taglist>
<tag><c>disabled</c></tag>
<item>
@@ -6116,182 +7092,317 @@ ok
<tag><c>blocked</c></tag>
<item>
<p>The emulator has more than one scheduler thread,
- but all scheduler threads but one have been blocked,
- i.e., only one scheduler thread will schedule
- Erlang processes and execute Erlang code.</p>
+ but all scheduler threads except one are blocked,
+ that is, only one scheduler thread schedules
+ Erlang processes and executes Erlang code.</p>
</item>
<tag><c>enabled</c></tag>
<item>
<p>The emulator has more than one scheduler thread,
- and no scheduler threads have been blocked, i.e.,
- all available scheduler threads will schedule
+ and no scheduler threads are blocked, that is,
+ all available scheduler threads schedule
Erlang processes and execute Erlang code.</p>
</item>
</taglist>
- <p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
- <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and
+ <p>See also
+ <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
+ <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>,
+ and
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
</item>
- <tag><marker id="system_info_multi_scheduling_blockers"><c>multi_scheduling_blockers</c></marker></tag>
+ <tag><c>multi_scheduling_blockers</c></tag>
<item>
- <p>Returns a list of <c><anno>PID</anno></c>s when multi-scheduling
- is blocked; otherwise, the empty list. The <c><anno>PID</anno></c>s
- in the list is <c><anno>PID</anno></c>s of the processes currently
- blocking multi-scheduling. A <c><anno>PID</anno></c> will only be
- present once in the list, even if the corresponding
+ <marker id="system_info_multi_scheduling_blockers"></marker>
+ <p>Returns a list of <c><anno>Pid</anno></c>s when
+ multi-scheduling is blocked, otherwise the empty list is
+ returned. The <c><anno>Pid</anno></c>s in the list
+ represent all the processes currently
+ blocking multi-scheduling. A <c><anno>Pid</anno></c> occurs
+ only once in the list, even if the corresponding
process has blocked multiple times.</p>
- <p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
- <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and
+ <p>See also
+ <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
+ <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>,
+ and
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
</item>
<tag><c>nif_version</c></tag>
<item>
- <p>Returns a string containing the erlang NIF version
- used by the runtime system. It will be on the form "&lt;major ver&gt;.&lt;minor ver&gt;".</p>
+ <p>Returns a string containing the version of the Erlang NIF interface
+ used by the runtime system. It is on the form
+ "&lt;major ver&gt;.&lt;minor ver&gt;".</p>
</item>
- <tag><marker id="system_info_otp_release"><c>otp_release</c></marker></tag>
+ <tag><c>otp_release</c></tag>
<item>
+ <marker id="system_info_otp_release"></marker>
<p>Returns a string containing the OTP release number of the
- OTP release that the currently executing ERTS application is
+ OTP release that the currently executing <c>ERTS</c> application is
part of.</p>
- <p>As of OTP release 17, the OTP release number corresponds to
- the major OTP version number. There is no
- <c>erlang:system_info()</c> argument giving the exact OTP
- version. This since the exact OTP version in the general case
- is hard to determine. For more information see
- <seealso marker="doc/system_principles:versions">the
- documentation of versions in the system principles
- guide</seealso>.</p>
- </item>
- <tag><marker id="system_info_port_parallelism"><c>port_parallelism</c></marker></tag>
- <item><p>Returns the default port parallelism scheduling hint used.
- For more information see the
- <seealso marker="erl#+spp">+spp</seealso> command line argument
- of <seealso marker="erl">erl(1)</seealso>.</p></item>
+ <p>As from OTP 17, the OTP release number corresponds to
+ the major OTP version number. No
+ <c>erlang:system_info()</c> argument gives the exact OTP
+ version. This is because the exact OTP version in the general case
+ is difficult to determine. For more information, see the description
+ of versions in <seealso marker="doc/system_principles:versions">
+ System principles</seealso> in System Documentation.</p>
+ </item>
+ <tag><marker id="system_info_os_monotonic_time_source"/><c>os_monotonic_time_source</c></tag>
+ <item>
+ <p>Returns a list containing information about the source of
+ <seealso marker="erts:time_correction#OS_Monotonic_Time">OS
+ monotonic time</seealso> that is used by the runtime system.</p>
+ <p>If <c>[]</c> is returned, no OS monotonic time is
+ available. The list contains two-tuples with <c>Key</c>s
+ as first element, and <c>Value</c>s as second element. The
+ order of these tuples is undefined. The following
+ tuples can be part of the list, but more tuples can be
+ introduced in the future:</p>
+ <taglist>
+ <tag><c>{function, Function}</c></tag>
+ <item><p><c>Function</c> is the name of the function
+ used. This tuple always exist if OS monotonic time is
+ available to the runtime system.</p></item>
+
+ <tag><c>{clock_id, ClockId}</c></tag>
+ <item><p>This tuple only exist if <c>Function</c>
+ can be used with different clocks. <c>ClockId</c>
+ corresponds to the clock identifier used when calling
+ <c>Function</c>.</p></item>
+
+ <tag><c>{resolution, OsMonotonicTimeResolution}</c></tag>
+ <item><p>Highest possible
+ <seealso marker="time_correction#Time_Resolution">resolution</seealso>
+ of current OS monotonic time source as parts per
+ second. If no resolution information can be retrieved
+ from the OS, <c>OsMonotonicTimeResolution</c> is
+ set to the resolution of the time unit of
+ <c>Function</c>s return value. That is, the actual
+ resolution can be lower than
+ <c>OsMonotonicTimeResolution</c>. Also note that
+ the resolution does not say anything about the
+ <seealso marker="time_correction#Time_Accuracy">accuracy</seealso>,
+ and whether the
+ <seealso marker="time_correction#Time_Precision">precision</seealso>
+ do align with the resolution. You do,
+ however, know that the precision is not better than
+ <c>OsMonotonicTimeResolution</c>.</p></item>
+
+ <tag><c>{extended, Extended}</c></tag>
+ <item><p><c>Extended</c> equals <c>yes</c> if
+ the range of time values has been extended;
+ otherwise, <c>Extended</c> equals <c>no</c>. The
+ range needs to be extended if <c>Function</c>
+ returns values that wrap fast. This typically
+ is the case when the return value is a 32-bit
+ value.</p></item>
+
+ <tag><c>{parallel, Parallel}</c></tag>
+ <item><p><c>Parallel</c> equals <c>yes</c> if
+ <c>Function</c> is called in parallel from multiple
+ threads. If it is not called in parallel, because
+ calls needs to be serialized, <c>Parallel</c> equals
+ <c>no</c>.</p></item>
+
+ <tag><c>{time, OsMonotonicTime}</c></tag>
+ <item><p><c>OsMonotonicTime</c> equals current OS
+ monotonic time in <c>native</c>
+ <seealso marker="#type_time_unit">time unit</seealso>.</p></item>
+ </taglist>
+ </item>
+ <tag><marker id="system_info_os_system_time_source"/><c>os_system_time_source</c></tag>
+ <item>
+ <p>Returns a list containing information about the source of
+ <seealso marker="erts:time_correction#OS_System_Time">OS
+ system time</seealso> that is used by the runtime system.</p>
+ <p>The list contains two-tuples with <c>Key</c>s
+ as first element, and <c>Value</c>s as second element. The
+ order if these tuples is undefined. The following
+ tuples can be part of the list, but more tuples can be
+ introduced in the future:</p>
+ <taglist>
+ <tag><c>{function, Function}</c></tag>
+ <item><p><c>Function</c> is the name of the funcion
+ used.</p></item>
+
+ <tag><c>{clock_id, ClockId}</c></tag>
+ <item><p>This tuple only exist if <c>Function</c>
+ can be used with different clocks. <c>ClockId</c>
+ corresponds to the clock identifier used when calling
+ <c>Function</c>.</p></item>
+
+ <tag><c>{resolution, OsSystemTimeResolution}</c></tag>
+ <item><p>Highest possible
+ <seealso marker="time_correction#Time_Resolution">resolution</seealso>
+ of current OS system time source as parts per
+ second. If no resolution information can be retrieved
+ from the OS, <c>OsSystemTimeResolution</c> is
+ set to the resolution of the time unit of
+ <c>Function</c>s return value. That is, the actual
+ resolution may be lower than
+ <c>OsSystemTimeResolution</c>. Also note that
+ the resolution does not say anything about the
+ <seealso marker="time_correction#Time_Accuracy">accuracy</seealso>,
+ and whether the
+ <seealso marker="time_correction#Time_Precision">precision</seealso>
+ do align with the resolution. You do,
+ however, know that the precision is not better than
+ <c>OsSystemTimeResolution</c>.</p></item>
+
+ <tag><c>{parallel, Parallel}</c></tag>
+ <item><p><c>Parallel</c> equals <c>yes</c> if
+ <c>Function</c> is called in parallel from multiple
+ threads. If it is not called in parallel, because
+ calls needs to be serialized, <c>Parallel</c> equals
+ <c>no</c>.</p></item>
+
+ <tag><c>{time, OsSystemTime}</c></tag>
+ <item><p><c>OsSystemTime</c> equals current OS
+ system time in <c>native</c>
+ <seealso marker="#type_time_unit">time unit</seealso>.</p></item>
+ </taglist>
+ </item>
+ <tag><c>port_parallelism</c></tag>
+ <item>
+ <marker id="system_info_port_parallelism"></marker>
+ <p>Returns the default port parallelism scheduling hint used.
+ For more information, see command-line argument
+ <seealso marker="erl#+spp">+spp</seealso> in <c>erl(1)</c>.</p></item>
<tag><marker id="system_info_port_count"/><c>port_count</c></tag>
<item>
- <p>Returns the number of ports currently existing at
- the local node as an integer. The same value as
- <c>length(erlang:ports())</c> returns, but more efficient.</p>
+ <p>Returns the number of ports currently existing at the
+ local node. The value is given as an integer. This is
+ the same value as returned by
+ <c>length(erlang:ports())</c>, but more efficient.</p>
</item>
- <tag><marker id="system_info_port_limit"><c>port_limit</c></marker></tag>
+ <tag><c>port_limit</c></tag>
<item>
+ <marker id="system_info_port_limit"></marker>
<p>Returns the maximum number of simultaneously existing
- ports at the local node as an integer. This limit
- can be configured at startup by using the
- <seealso marker="erl#+Q">+Q</seealso>
- command line flag of
- <seealso marker="erl">erl(1)</seealso>.</p>
+ ports at the local node as an integer. This limit can be
+ configured at startup by using command-line flag
+ <seealso marker="erl#+Q">+Q</seealso> in <c>erl(1)</c>.</p>
</item>
<tag><marker id="system_info_process_count"/><c>process_count</c></tag>
<item>
- <p>Returns the number of processes currently existing at
- the local node as an integer. The same value as
- <c>length(processes())</c> returns, but more efficient.</p>
+ <p>Returns the number of processes currently existing at the
+ local node. The value is given as an integer. This is
+ the same value as returned by
+ <c>length(processes())</c>, but more efficient.</p>
</item>
- <tag><marker id="system_info_process_limit"><c>process_limit</c></marker></tag>
+ <tag><c>process_limit</c></tag>
<item>
+ <marker id="system_info_process_limit"></marker>
<p>Returns the maximum number of simultaneously existing
- processes at the local node as an integer. This limit
- can be configured at startup by using the
- <seealso marker="erl#+P">+P</seealso>
- command line flag of
- <seealso marker="erl">erl(1)</seealso>.</p>
+ processes at the local node. The value is given as an
+ integer. This limit can be configured at startup by using
+ command-line flag <seealso marker="erl#+P">+P</seealso>
+ in <c>erl(1)</c>.</p>
</item>
<tag><c>procs</c></tag>
<item>
<p>Returns a binary containing a string of process and port
information formatted as in Erlang crash dumps. For more
- information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
- in the ERTS User's Guide.</p>
+ information, see Section
+ <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso>
+ in the User's Guide.</p>
</item>
- <tag><marker id="system_info_scheduler_bind_type"><c>scheduler_bind_type</c></marker></tag>
+ <tag><c>scheduler_bind_type</c></tag>
<item>
- <p>Returns information on how user has requested
+ <marker id="system_info_scheduler_bind_type"></marker>
+ <p>Returns information about how the user has requested
schedulers to be bound or not bound.</p>
- <p><em>NOTE:</em> Even though user has requested
- schedulers to be bound, they might have silently failed
- to bind. In order to inspect actual scheduler bindings call
- <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
- </p>
- <p>For more information, see
- the <c>erl</c> <seealso marker="erts:erl#+sbt">+sbt</seealso>
- command line argument, and
- <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
- </p>
- </item>
- <tag><marker id="system_info_scheduler_bindings"><c>scheduler_bindings</c></marker></tag>
- <item>
- <p>Returns information on currently used scheduler
+ <p>Notice that even though a user has requested
+ schedulers to be bound, they can silently have failed
+ to bind. To inspect the scheduler bindings, call
+ <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.</p>
+ <p>For more information, see command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt</seealso>
+ in <c>erl(1)</c> and
+ <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.</p>
+ </item>
+ <tag><c>scheduler_bindings</c></tag>
+ <item>
+ <marker id="system_info_scheduler_bindings"></marker>
+ <p>Returns information about the currently used scheduler
bindings.</p>
<p>A tuple of a size equal to
- <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso> is returned. The elements of the tuple are integers
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>
+ is returned. The tuple elements are integers
or the atom <c>unbound</c>. Logical processor identifiers
are represented as integers. The <c>N</c>th
element of the tuple equals the current binding for
the scheduler with the scheduler identifier equal to
- <c>N</c>. E.g., if the schedulers have been bound,
+ <c>N</c>. For example, if the schedulers are bound,
<c>element(erlang:system_info(scheduler_id),
- erlang:system_info(scheduler_bindings))</c> will return
+ erlang:system_info(scheduler_bindings))</c> returns
the identifier of the logical processor that the calling
- process is executing on.
- </p>
- <p>Note that only schedulers online can be bound to logical
+ process is executing on.</p>
+ <p>Notice that only schedulers online can be bound to logical
processors.</p>
- <p>For more information, see
- the <c>erl</c> <seealso marker="erts:erl#+sbt">+sbt</seealso>
- command line argument,
+ <p>For more information, see command-line argument
+ <seealso marker="erts:erl#+sbt">+sbt</seealso>
+ in <c>erl(1)</c> and
<seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>.
</p>
</item>
- <tag><marker id="system_info_scheduler_id"><c>scheduler_id</c></marker></tag>
+ <tag><c>scheduler_id</c></tag>
<item>
- <p>Returns the scheduler id (<c>SchedulerId</c>) of the
+ <marker id="system_info_scheduler_id"></marker>
+ <p>Returns the scheduler ID (<c>SchedulerId</c>) of the
scheduler thread that the calling process is executing
- on. <c><anno>SchedulerId</anno></c> is a positive integer; where
- <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]></c>. See also
+ on. <c><anno>SchedulerId</anno></c> is a positive integer,
+ where
+ <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]></c>.
+ See also
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
</item>
- <tag><marker id="system_info_schedulers"><c>schedulers</c></marker></tag>
+ <tag><c>schedulers</c></tag>
<item>
+ <marker id="system_info_schedulers"></marker>
<p>Returns the number of scheduler threads used by
the emulator. Scheduler threads online schedules Erlang
processes and Erlang ports, and execute Erlang code
- and Erlang linked in driver code.</p>
+ and Erlang linked-in driver code.</p>
<p>The number of scheduler threads is determined at
- emulator boot time and cannot be changed after
- that. The amount of schedulers online can
- however be changed at any time.</p>
- <p>See also <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>,
+ emulator boot time and cannot be changed later.
+ However, the number of schedulers online can
+ be changed at any time.</p>
+ <p>See also
+ <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>,
<seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>,
<seealso marker="#system_info_scheduler_id">erlang:system_info(scheduler_id)</seealso>,
<seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
- <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and
- and <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>.</p>
+ <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>,
+ and
+ <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>.</p>
</item>
- <tag><marker id="system_info_schedulers_online"><c>schedulers_online</c></marker></tag>
+ <tag><c>schedulers_online</c></tag>
<item>
- <p>Returns the amount of schedulers online. The scheduler
- identifiers of schedulers online satisfy the following
- relationship:
- <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers_online)]]></c>.
- </p>
+ <marker id="system_info_schedulers_online"></marker>
+ <p>Returns the number of schedulers online. The scheduler
+ identifiers of schedulers online satisfy the relationship
+ <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers_online)]]></c>.</p>
<p>For more information, see
- <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>,
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>
and
- <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>.
- </p> <name name="system_info" arity="1" clause_i="49"/>
-
+ <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>.</p>
</item>
<tag><c>smp_support</c></tag>
<item>
<p>Returns <c>true</c> if the emulator has been compiled
- with smp support; otherwise, <c>false</c>.</p>
- </item>
+ with SMP support, otherwise <c>false</c> is returned.</p>
+ </item>
+ <tag><marker id="system_info_start_time"/><c>start_time</c></tag>
+ <item><p>The <seealso marker="#monotonic_time/0">Erlang monotonic
+ time</seealso> in <c>native</c>
+ <seealso marker="#type_time_unit">time unit</seealso> at the
+ time when current Erlang runtime system instance started. See also
+ <seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso>.
+ </p></item>
<tag><c>system_version</c></tag>
<item>
<p>Returns a string containing version number and
- some important properties such as the number of schedulers.</p>
+ some important properties, such as the number of schedulers.</p>
</item>
<tag><c>system_architecture</c></tag>
<item>
@@ -6301,109 +7412,168 @@ ok
<tag><c>threads</c></tag>
<item>
<p>Returns <c>true</c> if the emulator has been compiled
- with thread support; otherwise, <c>false</c> is
- returned.</p>
+ with thread support, otherwise <c>false</c> is returned.</p>
</item>
- <tag><marker id="system_info_thread_pool_size"><c>thread_pool_size</c></marker></tag>
+ <tag><c>thread_pool_size</c></tag>
<item>
+ <marker id="system_info_thread_pool_size"></marker>
<p>Returns the number of async threads in the async thread
pool used for asynchronous driver calls
- (<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>)
- as an integer.</p>
+ (<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>).
+ The value is given as an integer.</p>
</item>
- <tag><marker id="system_info_tolerant_timeofday"><c>tolerant_timeofday</c></marker></tag>
+
+ <tag><c>time_correction</c></tag>
+ <item>
+ <marker id="system_info_time_correction"></marker>
+ <p>Returns a boolean value indicating whether
+ <seealso marker="time_correction#Time_Correction">time correction</seealso>
+ is enabled or not.
+ </p></item>
+ <tag><c>time_offset</c></tag>
+ <item>
+ <marker id="system_info_time_offset"></marker>
+ <p>Returns the state of the time offset:</p>
+ <taglist>
+ <tag><c>preliminary</c></tag>
+ <item><p>The time offset is preliminary, and will be changed
+ at a later time when being finalized. The preliminary time offset
+ is used during the preliminary phase of the
+ <seealso marker="time_correction#Single_Time_Warp_Mode">single
+ time warp mode</seealso>.</p></item>
+
+ <tag><c>final</c></tag>
+ <item><p>The time offset is final. This either because
+ <seealso marker="time_correction#No_Time_Warp_Mode">no
+ time warp mode</seealso> is used, or because the time
+ offset have been finalized when
+ <seealso marker="time_correction#Single_Time_Warp_Mode">single
+ time warp mode</seealso> is used.</p></item>
+
+ <tag><c>volatile</c></tag>
+ <item><p>The time offset is volatile. That is, it can
+ change at any time. This is because
+ <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+ time warp mode</seealso> is used.</p></item>
+ </taglist>
+ </item>
+ <tag><marker id="system_info_time_warp_mode"/><c>time_warp_mode</c></tag>
+ <item><p>Returns a value identifying the
+ <seealso marker="time_correction#Time_Warp_Modes">time warp
+ mode</seealso> being used:</p>
+ <taglist>
+ <tag><c>no_time_warp</c></tag>
+ <item><p>The <seealso marker="time_correction#No_Time_Warp_Mode">no
+ time warp mode</seealso> is used.</p></item>
+
+ <tag><c>single_time_warp</c></tag>
+ <item><p>The <seealso marker="time_correction#Single_Time_Warp_Mode">single
+ time warp mode</seealso> is used.</p></item>
+
+ <tag><c>multi_time_warp</c></tag>
+ <item><p>The <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+ time warp mode</seealso> is used.</p></item>
+ </taglist>
+ </item>
+ <tag><c>tolerant_timeofday</c></tag>
<item>
- <p>Returns whether compensation for sudden changes of system
- time is <c>enabled</c> or <c>disabled</c>.</p>
- <p>See also <seealso marker="erts:erl#+c">+c</seealso>
- command line flag.</p>
+ <marker id="system_info_tolerant_timeofday"></marker>
+ <p>Returns whether a pre erts-7.0 backwards compatible compensation
+ for sudden changes of system time is <c>enabled</c> or <c>disabled</c>.
+ Such compensation is <c>enabled</c> when the
+ <seealso marker="#system_info_time_offset">time offset</seealso> is
+ <c>final</c>, and
+ <seealso marker="#system_info_time_correction">time correction</seealso>
+ is enabled.</p>
</item>
<tag><c>trace_control_word</c></tag>
<item>
- <p>Returns the value of the node's trace control word.
- For more information see documentation of the function
- <c>get_tcw</c> in "Match Specifications in Erlang",
- <seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p>
+ <p>Returns the value of the node trace control word. For
+ more information, see function <c>get_tcw</c> in Section
+ <seealso marker="erts:match_spec#get_tcw">Match Specifications in Erlang</seealso> in the User's Guide.</p>
</item>
- <tag><marker id="update_cpu_info"><c>update_cpu_info</c></marker></tag>
+ <tag><c>update_cpu_info</c></tag>
<item>
- <p>The runtime system rereads the CPU information available and
- updates its internally stored information about the
- <seealso marker="#system_info_cpu_topology_detected">detected CPU
- topology</seealso> and the amount of logical processors
+ <marker id="update_cpu_info"></marker>
+ <p>The runtime system rereads the CPU information available
+ and updates its internally stored information about the
+ <seealso marker="#system_info_cpu_topology_detected">detected
+ CPU topology</seealso> and the number of logical processors
<seealso marker="#logical_processors">configured</seealso>,
<seealso marker="#logical_processors_online">online</seealso>, and
- <seealso marker="#logical_processors_available">available</seealso>.
- If the CPU information has changed since the last time it was read,
- the atom <c>changed</c> is returned; otherwise, the atom
- <c>unchanged</c> is returned. If the CPU information has changed
+ <seealso marker="#logical_processors_available">available</seealso>.</p>
+ <p>If the CPU information has changed since the last time
+ it was read, the atom <c>changed</c> is returned, otherwise
+ the atom <c>unchanged</c>. If the CPU information has changed,
you probably want to
- <seealso marker="#system_flag_schedulers_online">adjust the amount
- of schedulers online</seealso>. You typically want to have as
- many schedulers online as
- <seealso marker="#logical_processors_available">logical processors
- available</seealso>.
- </p>
+ <seealso marker="#system_flag_schedulers_online">adjust the
+ number of schedulers online</seealso>. You typically want
+ to have as many schedulers online as
+ <seealso marker="#logical_processors_available">logical
+ processors available</seealso>.</p>
</item>
- <tag><marker id="system_info_version"><c>version</c></marker></tag>
+ <tag><c>version</c></tag>
<item>
+ <marker id="system_info_version"></marker>
<p>Returns a string containing the version number of the
emulator.</p>
</item>
<tag><c>wordsize</c></tag>
<item>
- <p>Same as <c>{wordsize, internal}.</c></p>
+ <p>Same as <c>{wordsize, internal}</c>.</p>
</item>
<tag><c>{wordsize, internal}</c></tag>
<item>
<p>Returns the size of Erlang term words in bytes as an
- integer, i.e. on a 32-bit architecture 4 is returned,
- and on a pure 64-bit architecture 8 is returned. On a
+ integer, that is, 4 is returned on a 32-bit architecture,
+ and 8 is returned on a pure 64-bit architecture. On a
halfword 64-bit emulator, 4 is returned, as the Erlang
- terms are stored using a virtual wordsize of half the
- system's wordsize.</p>
+ terms are stored using a virtual word size of half the
+ system word size.</p>
</item>
<tag><c>{wordsize, external}</c></tag>
<item>
- <p>Returns the true wordsize of the emulator, i.e. the size
- of a pointer, in bytes as an integer. On a pure 32-bit
- architecture 4 is returned, on both a halfword and pure
+ <p>Returns the true word size of the emulator, that is,
+ the size of a pointer. The value is given in bytes
+ as an integer. On a pure 32-bit architecture, 4 is
+ returned. On both a half word and on a pure
64-bit architecture, 8 is returned.</p>
</item>
</taglist>
<note>
- <p>The <c>scheduler</c> argument has changed name to
- <c>scheduler_id</c>. This in order to avoid mixup with
- the <c>schedulers</c> argument. The <c>scheduler</c>
- argument was introduced in ERTS version 5.5 and renamed
- in ERTS version 5.5.1.</p>
+ <p>Argument <c>scheduler</c> has changed name to
+ <c>scheduler_id</c> to avoid mix up with argument
+ <c>schedulers</c>. Argument <c>scheduler</c> was
+ introduced in <c>ERTS</c> 5.5 and renamed in
+ <c>ERTS</c> 5.5.1.</p>
</note>
</desc>
</func>
<func>
<name name="system_monitor" arity="0"/>
+ <fsummary>Current system performance monitoring settings.</fsummary>
<type name="system_monitor_option"/>
- <fsummary>Current system performance monitoring settings</fsummary>
<desc>
<p>Returns the current system monitoring settings set by
<seealso marker="#system_monitor/2">erlang:system_monitor/2</seealso>
- as <c>{<anno>MonitorPid</anno>, <anno>Options</anno>}</c>, or <c>undefined</c> if there
- are no settings. The order of the options may be different
+ as <c>{<anno>MonitorPid</anno>, <anno>Options</anno>}</c>,
+ or <c>undefined</c> if there
+ are no settings. The order of the options can be different
from the one that was set.</p>
</desc>
</func>
<func>
<name name="system_monitor" arity="1"/>
+ <fsummary>Sets or clears system performance monitoring options.</fsummary>
<type name="system_monitor_option"/>
- <fsummary>Set or clear system performance monitoring options</fsummary>
<desc>
- <p>When called with the argument <c>undefined</c>, all
+ <p>When called with argument <c>undefined</c>, all
system performance monitoring settings are cleared.</p>
- <p>Calling the function with <c>{<anno>MonitorPid</anno>, <anno>Options</anno>}</c> as
- argument, is the same as calling
- <seealso marker="#system_monitor/2">erlang:system_monitor(<anno>MonitorPid</anno>, <anno>Options</anno>)</seealso>.</p>
+ <p>Calling the function with <c>{<anno>MonitorPid</anno>,
+ <anno>Options</anno>}</c> as argument is the same as calling
+ <seealso marker="#system_monitor/2"><c>erlang:system_monitor(<anno>MonitorPid</anno>, <anno>Options</anno>)</c></seealso>.</p>
<p>Returns the previous system monitor settings just like
<seealso marker="#system_monitor/0">erlang:system_monitor/0</seealso>.</p>
</desc>
@@ -6411,102 +7581,101 @@ ok
<func>
<name name="system_monitor" arity="2"/>
+ <fsummary>Sets system performance monitoring options.</fsummary>
<type name="system_monitor_option"/>
- <fsummary>Set system performance monitoring options</fsummary>
<desc>
- <p>Sets system performance monitoring options. <c><anno>MonitorPid</anno></c>
- is a local pid that will receive system monitor messages, and
- the second argument is a list of monitoring options:</p>
+ <p>Sets the system performance monitoring options.
+ <c><anno>MonitorPid</anno></c> is a local process identifier (pid)
+ receiving system monitor messages. The
+ second argument is a list of monitoring options:</p>
<taglist>
<tag><c>{long_gc, Time}</c></tag>
<item>
<p>If a garbage collection in the system takes at least
- <c>Time</c> wallclock milliseconds, a message
+ <c>Time</c> wall clock milliseconds, a message
<c>{monitor, GcPid, long_gc, Info}</c> is sent to
- <c><anno>MonitorPid</anno></c>. <c>GcPid</c> is the pid that was
- garbage collected and <c>Info</c> is a list of two-element
- tuples describing the result of the garbage collection.
- One of the tuples is <c>{timeout, GcTime}</c> where
- <c>GcTime</c> is the actual time for the garbage
+ <c><anno>MonitorPid</anno></c>. <c>GcPid</c> is the pid that
+ was garbage collected. <c>Info</c> is a list of two-element
+ tuples describing the result of the garbage collection.</p>
+ <p>One of the tuples is <c>{timeout, GcTime}</c>, where
+ <c>GcTime</c> is the time for the garbage
collection in milliseconds. The other tuples are
- tagged with <c>heap_size</c>, <c>heap_block_size</c>,
- <c>stack_size</c>, <c>mbuf_size</c>, <c>old_heap_size</c>,
- and <c>old_heap_block_size</c>. These tuples are
- explained in the documentation of the
- <seealso marker="#gc_start">gc_start</seealso>
- trace message (see
- <seealso marker="#trace/3">erlang:trace/3</seealso>).
- New tuples may be added, and the order of the tuples in
- the <c>Info</c> list may be changed at any time without prior
- notice.
- </p>
+ tagged with <c>heap_size</c>, <c>heap_block_size</c>
+ <c>stack_size</c>, <c>mbuf_size</c>, <c>old_heap_size</c>,
+ and <c>old_heap_block_size</c>. These tuples are
+ explained in the description of trace message
+ <seealso marker="#gc_start">gc_start</seealso> (see
+ <seealso marker="#trace/3">erlang:trace/3</seealso>).
+ New tuples can be added, and the order of the tuples in
+ the <c>Info</c> list can be changed at any time without
+ prior notice.</p>
</item>
<tag><c>{long_schedule, Time}</c></tag>
<item>
- <p>If a process or port in the system runs uninterrupted
+ <p>If a process or port in the system runs uninterrupted
for at least <c>Time</c> wall clock milliseconds, a
message <c>{monitor, PidOrPort, long_schedule, Info}</c>
is sent to <c>MonitorPid</c>. <c>PidOrPort</c> is the
- process or port that was running and <c>Info</c> is a
- list of two-element tuples describing the event. In case
- of a <c>pid()</c>, the tuples <c>{timeout, Millis}</c>,
- <c>{in, Location}</c> and <c>{out, Location}</c> will be
+ process or port that was running. <c>Info</c> is a
+ list of two-element tuples describing the event.</p>
+ <p>If a <c>pid()</c>, the tuples <c>{timeout, Millis}</c>,
+ <c>{in, Location}</c>, and <c>{out, Location}</c> are
present, where <c>Location</c> is either an MFA
(<c>{Module, Function, Arity}</c>) describing the
function where the process was scheduled in/out, or the
- atom <c>undefined</c>. In case of a <c>port()</c>, the
+ atom <c>undefined</c>.</p>
+ <p>If a <c>port()</c>, the
tuples <c>{timeout, Millis}</c> and <c>{port_op,Op}</c>
- will be present. <c>Op</c> will be one of <c>proc_sig</c>,
+ are present. <c>Op</c> is one of <c>proc_sig</c>,
<c>timeout</c>, <c>input</c>, <c>output</c>,
- <c>event</c> or <c>dist_cmd</c>, depending on which
- driver callback was executing. <c>proc_sig</c> is an
- internal operation and should never appear, while the
+ <c>event</c>, or <c>dist_cmd</c>, depending on which
+ driver callback was executing.</p>
+ <p><c>proc_sig</c> is an
+ internal operation and is never to appear, while the
others represent the corresponding driver callbacks
<c>timeout</c>, <c>ready_input</c>, <c>ready_output</c>,
- <c>event</c> and finally <c>outputv</c> (when the port
- is used by distribution). The <c>Millis</c> value in
- the <c>timeout</c> tuple will tell you the actual
- uninterrupted execution time of the process or port,
- which will always be <c>&gt;=</c> the <c>Time</c> value
- supplied when starting the trace. New tuples may be
- added to the <c>Info</c> list in the future, and the
- order of the tuples in the list may be changed at any
- time without prior notice.
- </p>
- <p>This can be used to detect problems with NIF's or
- drivers that take too long to execute. Generally, 1 ms
- is considered a good maximum time for a driver callback
- or a NIF. However, a time sharing system should usually
- consider everything below 100 ms as "possible" and
- fairly "normal". Schedule times above that might however
- indicate swapping or a NIF/driver that is
- misbehaving. Misbehaving NIF's and drivers could cause
- bad resource utilization and bad overall performance of
- the system.</p>
+ <c>event</c>, and <c>outputv</c> (when the port
+ is used by distribution). Value <c>Millis</c> in
+ the <c>timeout</c> tuple informs about the
+ uninterrupted execution time of the process or port, which
+ always is equal to or higher than the <c>Time</c> value
+ supplied when starting the trace. New tuples can be
+ added to the <c>Info</c> list in a future release. The
+ order of the tuples in the list can be changed at any
+ time without prior notice.</p>
+ <p>This can be used to detect problems with NIFs or
+ drivers that take too long to execute. 1 ms is
+ considered a good maximum time for a driver callback
+ or a NIF. However, a time-sharing system is usually to
+ consider everything below 100 ms as "possible" and
+ fairly "normal". However, longer schedule times can
+ indicate swapping or a misbehaving NIF/driver.
+ Misbehaving NIFs and drivers can cause bad resource
+ utilization and bad overall system performance.</p>
</item>
<tag><c>{large_heap, Size}</c></tag>
<item>
<p>If a garbage collection in the system results in
the allocated size of a heap being at least <c>Size</c>
words, a message <c>{monitor, GcPid, large_heap, Info}</c>
- is sent to <c><anno>MonitorPid</anno></c>. <c>GcPid</c> and <c>Info</c>
- are the same as for <c>long_gc</c> above, except that
- the tuple tagged with <c>timeout</c> is not present.
- <em>Note</em>: As of erts version 5.6 the monitor message
- is sent if the sum of the sizes of all memory blocks allocated
- for all heap generations is equal to or larger than <c>Size</c>.
- Previously the monitor message was sent if the memory block
- allocated for the youngest generation was equal to or larger
- than <c>Size</c>.
- </p>
+ is sent to <c><anno>MonitorPid</anno></c>.
+ <c>GcPid</c> and <c>Info</c>
+ are the same as for <c>long_gc</c> earlier, except that
+ the tuple tagged with <c>timeout</c> is not present.</p>
+ <p>As of <c>ERTS</c> 5.6, the monitor message is sent
+ if the sum of the sizes of all memory blocks allocated
+ for all heap generations is equal to or higher than <c>Size</c>.
+ Previously the monitor message was sent if the memory block
+ allocated for the youngest generation was equal to or higher
+ than <c>Size</c>.</p>
</item>
<tag><c>busy_port</c></tag>
<item>
<p>If a process in the system gets suspended because it
sends to a busy port, a message
<c>{monitor, SusPid, busy_port, Port}</c> is sent to
- <c><anno>MonitorPid</anno></c>. <c>SusPid</c> is the pid that got
- suspended when sending to <c>Port</c>.</p>
+ <c><anno>MonitorPid</anno></c>. <c>SusPid</c> is the pid
+ that got suspended when sending to <c>Port</c>.</p>
</item>
<tag><c>busy_dist_port</c></tag>
<item>
@@ -6514,8 +7683,8 @@ ok
sends to a process on a remote node whose inter-node
communication was handled by a busy port, a message
<c>{monitor, SusPid, busy_dist_port, Port}</c> is sent to
- <c><anno>MonitorPid</anno></c>. <c>SusPid</c> is the pid that got
- suspended when sending through the inter-node
+ <c><anno>MonitorPid</anno></c>. <c>SusPid</c> is the pid
+ that got suspended when sending through the inter-node
communication port <c>Port</c>.</p>
</item>
</taglist>
@@ -6524,85 +7693,152 @@ ok
<note>
<p>If a monitoring process gets so large that it itself
starts to cause system monitor messages when garbage
- collecting, the messages will enlarge the process's
+ collecting, the messages enlarge the process
message queue and probably make the problem worse.</p>
<p>Keep the monitoring process neat and do not set the system
monitor limits too tight.</p>
</note>
- <p>Failure: <c>badarg</c> if <c><anno>MonitorPid</anno></c> does not exist or is not a local process.</p>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>MonitorPid</anno></c> does not exist.</item>
+ <tag><c>badarg</c></tag>
+ <item>If <c><anno>MonitorPid</anno></c> is not a local process.</item>
+ </taglist>
</desc>
</func>
<func>
<name name="system_profile" arity="0"/>
+ <fsummary>Current system profiling settings.</fsummary>
<type name="system_profile_option"/>
- <fsummary>Current system profiling settings</fsummary>
<desc>
<p>Returns the current system profiling settings set by
<seealso marker="#system_profile/2">erlang:system_profile/2</seealso>
- as <c>{<anno>ProfilerPid</anno>, <anno>Options</anno>}</c>, or <c>undefined</c> if there
- are no settings. The order of the options may be different
+ as <c>{<anno>ProfilerPid</anno>, <anno>Options</anno>}</c>,
+ or <c>undefined</c> if there
+ are no settings. The order of the options can be different
from the one that was set.</p>
</desc>
</func>
<func>
<name name="system_profile" arity="2"/>
+ <fsummary>Current system profiling settings.</fsummary>
<type name="system_profile_option"/>
- <fsummary>Current system profiling settings</fsummary>
<desc>
<p>Sets system profiler options. <c><anno>ProfilerPid</anno></c>
- is a local pid or port that will receive profiling messages. The
- receiver is excluded from all profiling.
+ is a local process identifier (pid) or port receiving profiling
+ messages. The receiver is excluded from all profiling.
The second argument is a list of profiling options:</p>
<taglist>
<tag><c>exclusive</c></tag>
<item>
- <p>
- If a synchronous call to a port from a process is done, the
+ <p>If a synchronous call to a port from a process is done, the
calling process is considered not runnable during the call
runtime to the port. The calling process is notified as
- <c>inactive</c> and subsequently <c>active</c> when the port
- callback returns.
- </p>
+ <c>inactive</c>, and later <c>active</c> when the port
+ callback returns.</p>
+ </item>
+ <tag><c>monotonic_timestamp</c></tag>
+ <item>
+ <p>Timestamps in profile messages will use
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ monotonic time</seealso>. The time-stamp (Ts) has the same
+ format and value as produced by
+ <c>erlang:monotonic_time(nano_seconds)</c>.</p>
</item>
<tag><c>runnable_procs</c></tag>
<item>
- <p>If a process is put into or removed from the run queue a message,
- <c>{profile, Pid, State, Mfa, Ts}</c>, is sent to
- <c><anno>ProfilerPid</anno></c>. Running processes that is reinserted into the
- run queue after having been preemptively scheduled out will not trigger this
- message.
- </p>
+ <p>If a process is put into or removed from the run queue, a
+ message, <c>{profile, Pid, State, Mfa, Ts}</c>, is sent to
+ <c><anno>ProfilerPid</anno></c>. Running processes that
+ are reinserted into the run queue after having been
+ preempted do not trigger this message.</p>
</item>
<tag><c>runnable_ports</c></tag>
<item>
- <p>If a port is put into or removed from the run queue a message,
- <c>{profile, Port, State, 0, Ts}</c>, is sent to
- <c><anno>ProfilerPid</anno></c>.
- </p>
+ <p>If a port is put into or removed from the run queue, a
+ message, <c>{profile, Port, State, 0, Ts}</c>, is sent to
+ <c><anno>ProfilerPid</anno></c>.</p>
</item>
<tag><c>scheduler</c></tag>
<item>
- <p>If a scheduler is put to sleep or awoken a message,
- <c>{profile, scheduler, Id, State, NoScheds, Ts}</c>, is sent
- to <c><anno>ProfilerPid</anno></c>.
- </p>
+ <p>If a scheduler is put to sleep or awoken, a message,
+ <c>{profile, scheduler, Id, State, NoScheds, Ts}</c>, is
+ sent to <c><anno>ProfilerPid</anno></c>.</p>
+ </item>
+ <tag><c>strict_monotonic_timestamp</c></tag>
+ <item>
+ <p>Timestamps in profile messages will consisting of
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ monotonic time</seealso> and a monotonically increasing
+ integer. The time-stamp (Ts) has the same format and value
+ as produced by <c>{erlang:monotonic_time(nano_seconds),
+ erlang:unique_integer([monotonic])}</c>.</p>
+ </item>
+ <tag><c>timestamp</c></tag>
+ <item>
+ <p>Timestamps in profile messages will include a
+ time-stamp (Ts) that has the same form as returned by
+ <c>erlang:now()</c>. This is also the default if no
+ timestamp flag is given. If <c>cpu_timestamp</c> has
+ been enabled via <c>erlang:trace/3</c>, this will also
+ effect the timestamp produced in profiling messages
+ when <c>timestamp</c> flag is enabled.</p>
</item>
</taglist>
- <note><p><c>erlang:system_profile</c> is considered experimental and
- its behaviour may change in the future.</p>
+ <note><p><c>erlang:system_profile</c> is considered experimental
+ and its behavior can change in a future release.</p>
</note>
</desc>
</func>
+ <func>
+ <name name="system_time" arity="0"/>
+ <fsummary>Current Erlang system time</fsummary>
+ <desc>
+ <p>Returns current
+ <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+ in <c>native</c>
+ <seealso marker="#type_time_unit">time unit</seealso>.</p>
+ <p>Calling <c>erlang:system_time()</c> is equivalent to:
+ <seealso marker="#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso><c>
+ +
+ </c><seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso>.</p>
+
+ <note><p>This time is <em>not</em> a monotonically increasing time
+ in the general case. For more information, see the documentation of
+ <seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the
+ ERTS User's Guide.</p></note>
+ </desc>
+ </func>
+ <func>
+ <name name="system_time" arity="1"/>
+ <fsummary>Current Erlang system time</fsummary>
+ <desc>
+ <p>Returns current
+ <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+ converted into the <c><anno>Unit</anno></c> passed as argument.</p>
+
+ <p>Calling <c>erlang:system_time(<anno>Unit</anno>)</c> is equivalent to:
+ <seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#system_time/0"><c>erlang:system_time()</c></seealso><c>,
+ native, <anno>Unit</anno>)</c>.</p>
+
+ <note><p>This time is <em>not</em> a monotonically increasing time
+ in the general case. For more information, see the documentation of
+ <seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the
+ ERTS User's Guide.</p></note>
+ </desc>
+ </func>
<func>
<name name="term_to_binary" arity="1"/>
- <fsummary>Encode a term to an Erlang external term format binary</fsummary>
+ <fsummary>Encodes a term to an Erlang external term format binary.</fsummary>
<desc>
- <p>Returns a binary data object which is the result of encoding
- <c><anno>Term</anno></c> according to the Erlang external term format.</p>
- <p>This can be used for a variety of purposes, for example
+ <p>Returns a binary data object that is the result of encoding
+ <c><anno>Term</anno></c> according to the Erlang external
+ term format.</p>
+ <p>This can be used for various purposes, for example,
writing a term to a file in an efficient way, or sending an
Erlang term to some type of communications channel not
supported by distributed Erlang.</p>
@@ -6610,247 +7846,372 @@ ok
<seealso marker="#binary_to_term/1">binary_to_term/1</seealso>.</p>
</desc>
</func>
+
<func>
<name name="term_to_binary" arity="2"/>
- <fsummary>Encode a term to en Erlang external term format binary</fsummary>
- <desc>
- <p>Returns a binary data object which is the result of encoding
- <c><anno>Term</anno></c> according to the Erlang external term format.</p>
- <p>If the option <c>compressed</c> is provided, the external
- term format will be compressed. The compressed format is
- automatically recognized by <c>binary_to_term/1</c> in R7B and later.</p>
- <p>It is also possible to specify a compression level by giving
- the option <c>{compressed, <anno>Level</anno>}</c>, where <c><anno>Level</anno></c> is an
- integer from 0 through 9. <c>0</c> means that no compression
- will be done (it is the same as not giving any <c>compressed</c> option);
- <c>1</c> will take the least time but may not compress as well as
- the higher levels; <c>9</c> will take the most time and may produce
- a smaller result. Note the "mays" in the preceding sentence; depending
- on the input term, level 9 compression may or may not produce a smaller
- result than level 1 compression.</p>
- <p>Currently, <c>compressed</c> gives the same result as
- <c>{compressed, 6}</c>.</p>
- <p>The option <c>{minor_version, <anno>Version</anno>}</c> can be use to control
- some details of the encoding. This option was
- introduced in R11B-4. Currently, the allowed values for <c><anno>Version</anno></c>
- are <c>0</c> and <c>1</c>.</p>
- <p><c>{minor_version, 1}</c> is since 17.0 the default, it forces any floats in
- the term to be encoded
- in a more space-efficient and exact way (namely in the 64-bit IEEE format,
- rather than converted to a textual representation). <c>binary_to_term/1</c>
- in R11B-4 and later is able decode this representation.</p>
- <p><c>{minor_version, 0}</c> meaning that floats
- will be encoded using a textual representation; this option is useful if
- you want to ensure that releases prior to R11B-4 can decode resulting
+ <fsummary>Encodes a term to en Erlang external term format binary.</fsummary>
+ <desc>
+ <p>Returns a binary data object that is the result of encoding
+ <c><anno>Term</anno></c> according to the Erlang external
+ term format.</p>
+ <p>If option <c>compressed</c> is provided, the external term
+ format is compressed. The compressed format is automatically
+ recognized by <c>binary_to_term/1</c> as from Erlang R7B.</p>
+ <p>A compression level can be specified by giving option
+ <c>{compressed, <anno>Level</anno>}</c>.
+ <c><anno>Level</anno></c> is an integer
+ with range 0..9, where:</p>
+ <list type="bulleted">
+ <item><c>0</c> - No compression is done (it is the same as
+ giving no <c>compressed</c> option).</item>
+ <item><c>1</c> - Takes least time but may not compress
+ as well as the higher levels.</item>
+ <item><c>6</c> - Default level when option <c>compressed</c>
+ is provided.</item>
+ <item><c>9</c> - Takes most time and tries to produce a smaller
+ result. Notice "tries" in the preceding sentence; depending
+ on the input term, level 9 compression either does or does
+ not produce a smaller result than level 1 compression.</item>
+ </list>
+ <p>Option <c>{minor_version, <anno>Version</anno>}</c>
+ can be used to control
+ some encoding details. This option was introduced in OTP R11B-4.
+ The valid values for <c><anno>Version</anno></c> are
+ <c>0</c> and <c>1</c>.</p>
+ <p>As from OTP 17.0, <c>{minor_version, 1}</c> is the default. It
+ forces any floats in the term to be encoded in a more
+ space-efficient and exact way (namely in the 64-bit IEEE format,
+ rather than converted to a textual representation).</p>
+ <p>As from OTP R11B-4, <c>binary_to_term/1</c> can decode this
+ representation.</p>
+ <p><c>{minor_version, 0}</c> means that floats are encoded
+ using a textual representation. This option is useful to
+ ensure that releases before OTP R11B-4 can decode resulting
binary.</p>
<p>See also
<seealso marker="#binary_to_term/1">binary_to_term/1</seealso>.</p>
</desc>
</func>
+
<func>
<name name="throw" arity="1"/>
- <fsummary>Throw an exception</fsummary>
+ <fsummary>Throws an exception.</fsummary>
<desc>
<p>A non-local return from a function. If evaluated within a
- <c>catch</c>, <c>catch</c> will return the value <c><anno>Any</anno></c>.</p>
+ <c>catch</c>, <c>catch</c> returns value <c><anno>Any</anno></c>.</p>
+ <p>Example:</p>
<pre>
> <input>catch throw({hello, there}).</input>
{hello,there}</pre>
<p>Failure: <c>nocatch</c> if not evaluated within a catch.</p>
</desc>
</func>
+
<func>
<name name="time" arity="0"/>
- <fsummary>Current time</fsummary>
+ <fsummary>Current time.</fsummary>
<desc>
<p>Returns the current time as <c>{Hour, Minute, Second}</c>.</p>
- <p>The time zone and daylight saving time correction depend on
+ <p>The time zone and Daylight Saving Time correction depend on
the underlying OS.</p>
+ <p>Example:</p>
<pre>
> <input>time().</input>
{9,42,44}</pre>
</desc>
</func>
+
+ <func>
+ <name name="time_offset" arity="0"/>
+ <fsummary>Current time offset</fsummary>
+ <desc>
+ <p>Returns the current time offset between
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso>
+ and
+ <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> in
+ <c>native</c> <seealso marker="#type_time_unit">time unit</seealso>.
+ Current time offset added to an Erlang monotonic time gives
+ corresponding Erlang system time.</p>
+
+ <p>The time offset may or may not change during operation depending
+ on the <seealso marker="time_correction#Time_Warp_Modes">time
+ warp mode</seealso> used.</p>
+
+ <note>
+ <p>A change in time offset may be observed at slightly
+ different points in time by different processes.</p>
+
+ <p>If the runtime system is in
+ <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+ time warp mode</seealso>, the time offset will be changed when
+ the runtime system detects that the
+ <seealso marker="time_correction#OS_System_Time">OS system
+ time</seealso> has changed. The runtime system will, however,
+ not detect this immediately when it happens. A task checking
+ the time offset is scheduled to execute at least once a minute,
+ so under normal operation this should be detected within a
+ minute, but during heavy load it might take longer time.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name name="time_offset" arity="1"/>
+ <fsummary>Current time offset</fsummary>
+ <desc>
+ <p>Returns the current time offset between
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso>
+ and
+ <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+ converted into the <c><anno>Unit</anno></c> passed as argument.</p>
+
+ <p>Same as calling
+ <seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso><c>, native, <anno>Unit</anno>)</c>
+ however optimized for commonly used <c><anno>Unit</anno></c>s.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="timestamp" arity="0"/>
+ <fsummary>Current Erlang System time</fsummary>
+ <type name="timestamp"/>
+ <desc>
+ <p>Returns current
+ <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+ on the format <c>{MegaSecs, Secs, MicroSecs}</c>. This format is
+ the same as <seealso marker="kernel:os#timestamp/0"><c>os:timestamp/0</c></seealso>
+ and the deprecated <seealso marker="#now/0"><c>erlang:now/0</c></seealso>
+ uses. The reason for the existence of <c>erlang:timestamp()</c> is
+ purely to simplify usage for existing code that assumes this timestamp
+ format. Current Erlang system time can more efficiently be retrieved in
+ the time unit of your choice using
+ <seealso marker="#system_time/1"><c>erlang:system_time/1</c></seealso>.</p>
+
+ <p>The <c>erlang:timestamp()</c> BIF is equivalent to:</p><code type="none">
+timestamp() ->
+ ErlangSystemTime = erlang:system_time(micro_seconds),
+ MegaSecs = ErlangSystemTime div 1000000000000,
+ Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000,
+ MicroSecs = ErlangSystemTime rem 1000000,
+ {MegaSecs, Secs, MicroSecs}.</code>
+ <p>It, however, uses a native implementation which does
+ not build garbage on the heap and with slightly better
+ performance.</p>
+
+ <note><p>This time is <em>not</em> a monotonically increasing time
+ in the general case. For more information, see the documentation of
+ <seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the
+ ERTS User's Guide.</p></note>
+ </desc>
+
+ </func>
<func>
<name name="tl" arity="1"/>
- <fsummary>Tail of a list</fsummary>
+ <fsummary>Tail of a list.</fsummary>
<desc>
- <p>Returns the tail of <c><anno>List</anno></c>, that is, the list minus
- the first element.</p>
+ <p>Returns the tail of <c><anno>List</anno></c>, that is,
+ the list minus the first element, for example:</p>
<pre>
> <input>tl([geesties, guilies, beasties]).</input>
[guilies, beasties]</pre>
<p>Allowed in guard tests.</p>
- <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty list [].</p>
+ <p>Failure: <c>badarg</c> if <c><anno>List</anno></c>
+ is the empty list <c>[]</c>.</p>
</desc>
</func>
+
<func>
<name name="trace" arity="3"/>
+ <fsummary>Sets trace flags for a process or processes.</fsummary>
<type name="trace_flag"/>
- <fsummary>Set trace flags for a process or processes</fsummary>
<desc>
<p>Turns on (if <c><anno>How</anno> == true</c>) or off (if
- <c><anno>How</anno> == false</c>) the trace flags in <c><anno>FlagList</anno></c> for
- the process or processes represented by <c><anno>PidSpec</anno></c>.</p>
- <p><c><anno>PidSpec</anno></c> is either a pid for a local process, or one of
- the following atoms:</p>
+ <c><anno>How</anno> == false</c>) the trace flags in
+ <c><anno>FlagList</anno></c> for
+ the process or processes represented by
+ <c><anno>PidSpec</anno></c>.</p>
+ <p><c><anno>PidSpec</anno></c> is either a process identifier
+ (pid) for a local process, or one of the following atoms:</p>
<taglist>
<tag><c>existing</c></tag>
<item>
- <p>All processes currently existing.</p>
+ <p>All currently existing processes.</p>
</item>
<tag><c>new</c></tag>
<item>
- <p>All processes that will be created in the future.</p>
+ <p>All processes that are created in the future.</p>
</item>
<tag><c>all</c></tag>
<item>
<p>All currently existing processes and all processes that
- will be created in the future.</p>
+ are created in the future.</p>
</item>
</taglist>
- <p><c><anno>FlagList</anno></c> can contain any number of the following
- flags (the "message tags" refers to the list of messages
- following below):</p>
+ <p><c><anno>FlagList</anno></c> can contain any number of the
+ following flags (the "message tags" refers to the list of
+ <seealso marker="#trace_3_trace_messages">trace messages</seealso>):</p>
<taglist>
<tag><c>all</c></tag>
<item>
- <p>Set all trace flags except <c>{tracer, Tracer}</c> and
- <c>cpu_timestamp</c> that are in their nature different
+ <p>Sets all trace flags except <c>{tracer, Tracer}</c> and
+ <c>cpu_timestamp</c>, which are in their nature different
than the others.</p>
</item>
<tag><c>send</c></tag>
<item>
- <p>Trace sending of messages.</p>
- <p>Message tags: <c>send</c>,
+ <p>Traces sending of messages.</p>
+ <p>Message tags: <c>send</c> and
<c>send_to_non_existing_process</c>.</p>
</item>
<tag><c>'receive'</c></tag>
<item>
- <p>Trace receiving of messages.</p>
+ <p>Traces receiving of messages.</p>
<p>Message tags: <c>'receive'</c>.</p>
</item>
<tag><c>procs</c></tag>
<item>
- <p>Trace process related events.</p>
+ <p>Traces process-related events.</p>
<p>Message tags: <c>spawn</c>, <c>exit</c>,
<c>register</c>, <c>unregister</c>, <c>link</c>,
- <c>unlink</c>, <c>getting_linked</c>,
+ <c>unlink</c>, <c>getting_linked</c>, and
<c>getting_unlinked</c>.</p>
</item>
<tag><c>call</c></tag>
<item>
- <p>Trace certain function calls. Specify which function
+ <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>call</c>, <c>return_from</c>.</p>
+ <p>Message tags: <c>call</c> and <c>return_from</c>.</p>
</item>
<tag><c>silent</c></tag>
<item>
- <p>Used in conjunction with the <c>call</c> trace flag.
- The <c>call</c>, <c>return_from</c> and <c>return_to</c>
- trace messages are inhibited if this flag is set,
- but if there are match specs they are executed as normal.</p>
+ <p>Used with the <c>call</c> trace flag.
+ The <c>call</c>, <c>return_from</c>, and <c>return_to</c>
+ trace messages are inhibited if this flag is set, but they
+ are executed as normal if there are match specifications.</p>
<p>Silent mode is inhibited by executing
<c>erlang:trace(_, false, [silent|_])</c>,
- or by a match spec executing the <c>{silent, false}</c>
- function.</p>
+ or by a match specification executing the function
+ <c>{silent, false}</c>.</p>
<p>The <c>silent</c> trace flag facilitates setting up
a trace on many or even all processes in the system.
- Then the interesting trace can be activated and
- deactivated using the <c>{silent,Bool}</c>
- match spec function, giving a high degree
- of control of which functions with which
- arguments that triggers the trace.</p>
- <p>Message tags: <c>call</c>, <c>return_from</c>,
+ The trace can then be activated and deactivated using the match
+ 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>call</c>, <c>return_from</c>, and
<c>return_to</c>. Or rather, the absence of.</p>
</item>
<tag><c>return_to</c></tag>
<item>
- <p>Used in conjunction with the <c>call</c> trace flag.
- Trace the actual return from a traced function back to
+ <p>Used with the <c>call</c> trace flag.
+ Traces the return from a traced function back to
its caller. Only works for functions traced with
- the <c>local</c> option to
+ option <c>local</c> to
<seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
<p>The semantics is that a trace message is sent when a
- call traced function actually returns, that is, when a
- chain of tail recursive calls is ended. There will be
- only one trace message sent per chain of tail recursive
- calls, why the properties of tail recursiveness for
+ call traced function returns, that is, when a
+ chain of tail recursive calls ends. Only one trace
+ message is sent per chain of tail recursive calls,
+ so the properties of tail recursiveness for
function calls are kept while tracing with this flag.
Using <c>call</c> and <c>return_to</c> trace together
makes it possible to know exactly in which function a
process executes at any time.</p>
<p>To get trace messages containing return values from
- functions, use the <c>{return_trace}</c> match_spec
- action instead.</p>
+ functions, use the <c>{return_trace}</c> match
+ specification action instead.</p>
<p>Message tags: <c>return_to</c>.</p>
</item>
<tag><c>running</c></tag>
<item>
- <p>Trace scheduling of processes.</p>
- <p>Message tags: <c>in</c>, and <c>out</c>.</p>
+ <p>Traces scheduling of processes.</p>
+ <p>Message tags: <c>in</c> and <c>out</c>.</p>
</item>
<tag><c>exiting</c></tag>
<item>
- <p>Trace scheduling of an exiting processes.</p>
+ <p>Traces scheduling of exiting processes.</p>
<p>Message tags: <c>in_exiting</c>, <c>out_exiting</c>, and
<c>out_exited</c>.</p>
</item>
<tag><c>garbage_collection</c></tag>
<item>
- <p>Trace garbage collections of processes.</p>
- <p>Message tags: <c>gc_start</c>, <c>gc_end</c>.</p>
+ <p>Traces garbage collections of processes.</p>
+ <p>Message tags: <c>gc_start</c> and <c>gc_end</c>.</p>
</item>
<tag><c>timestamp</c></tag>
<item>
- <p>Include a time stamp in all trace messages. The time
- stamp (Ts) is of the same form as returned by
+ <p>Includes a time-stamp in all trace messages. The
+ time-stamp (Ts) has the same form as returned by
<c>erlang:now()</c>.</p>
</item>
<tag><c>cpu_timestamp</c></tag>
<item>
<p>A global trace flag for the Erlang node that makes all
- trace timestamps be in CPU time, not wallclock. It is
- only allowed with <c>PidSpec==all</c>. If the host
- machine operating system does not support high resolution
+ trace time-stamps using the <c>timestamp</c> flag to be
+ in CPU time, not wall clock time. That is, <c>cpu_timestamp</c>
+ will not be used if <c>monotonic_timestamp</c>, or
+ <c>strict_monotonic_timestamp</c> is enabled.
+ Only allowed with <c>PidSpec==all</c>. If the host
+ machine OS does not support high-resolution
CPU time measurements, <c>trace/3</c> exits with
- <c>badarg</c>.</p>
+ <c>badarg</c>. Notice that most OS do
+ not synchronize this value across cores, so be prepared
+ that time might seem to go backwards when using this option.</p>
+ </item>
+ <tag><c>monotonic_timestamp</c></tag>
+ <item>
+ <p>Includes an
+ <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>erlang:monotonic_time(nano_seconds)</c>. This flag overrides
+ the <c>cpu_timestamp</c> flag.</p>
+ </item>
+ <tag><c>strict_monotonic_timestamp</c></tag>
+ <item>
+ <p>Includes an timestamp consisting of
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ 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>{erlang:monotonic_time(nano_seconds),
+ erlang:unique_integer([monotonic])}</c>. This flag overrides
+ the <c>cpu_timestamp</c> flag.</p>
</item>
<tag><c>arity</c></tag>
<item>
- <p>Used in conjunction with the <c>call</c> trace flag.
- <c>{M, F, Arity}</c> will be specified instead of
+ <p>Used with the <c>call</c> trace flag.
+ <c>{M, F, Arity}</c> is specified instead of
<c>{M, F, Args}</c> in call trace messages.</p>
</item>
<tag><c>set_on_spawn</c></tag>
<item>
<p>Makes any process created by a traced process inherit
- its trace flags, including the <c>set_on_spawn</c> flag.</p>
+ its trace flags, including flag <c>set_on_spawn</c>.</p>
</item>
<tag><c>set_on_first_spawn</c></tag>
<item>
<p>Makes the first process created by a traced process
- inherit its trace flags, excluding
- the <c>set_on_first_spawn</c> flag.</p>
+ inherit its trace flags, excluding flag
+ <c>set_on_first_spawn</c>.</p>
</item>
<tag><c>set_on_link</c></tag>
<item>
<p>Makes any process linked by a traced process inherit its
- trace flags, including the <c>set_on_link</c> flag.</p>
+ trace flags, including flag <c>set_on_link</c>.</p>
</item>
<tag><c>set_on_first_link</c></tag>
<item>
<p>Makes the first process linked to by a traced process
- inherit its trace flags, excluding
- the <c>set_on_first_link</c> flag.</p>
+ inherit its trace flags, excluding flag
+ <c>set_on_first_link</c>.</p>
</item>
<tag><c>{tracer, Tracer}</c></tag>
<item>
- <p>Specify where to send the trace messages. <c>Tracer</c>
- must be the pid of a local process or the port identifier
+ <p>Specifies where to send the trace messages. <c>Tracer</c>
+ must be the process identifier of a local process
+ or the port identifier
of a local port. If this flag is not given, trace
- messages will be sent to the process that called
+ messages are sent to the process that called
<c>erlang:trace/3</c>.</p>
</item>
</taglist>
@@ -6858,27 +8219,34 @@ ok
<c>set_on_link</c> is the same as having
<c>set_on_first_link</c> alone. Likewise for
<c>set_on_spawn</c> and <c>set_on_first_spawn</c>.</p>
- <p>If the <c>timestamp</c> flag is not given, the tracing
- process will receive the trace messages described below.
- <c>Pid</c> is the pid of the traced process in which
- the traced event has occurred. The third element of the tuple
- is the message tag.</p>
- <p>If the <c>timestamp</c> flag is given, the first element of
- the tuple will be <c>trace_ts</c> instead and the timestamp
- is added last in the tuple.</p>
+ <p>The tracing process receives the <em>trace messages</em> described
+ in the following list. <c>Pid</c> is the process identifier of the
+ traced process in which the traced event has occurred. The
+ third tuple element is the message tag.</p>
+ <p>If flag <c>timestamp</c>, <c>strict_monotonic_timestamp</c>, or
+ <c>monotonic_timestamp</c> is given, the first tuple
+ element is <c>trace_ts</c> instead, and the time-stamp
+ is added as an extra element last in the message tuple. If
+ multiple timestamp flags are passed, <c>timestamp</c> has
+ precedence over <c>strict_monotonic_timestamp</c> which
+ in turn has precedence over <c>monotonic_timestamp</c>. All
+ timestamp flags are remembered, so if two are passed
+ and the one with highest precedence later is disabled
+ the other one will become active.</p>
+ <marker id="trace_3_trace_messages"></marker>
<taglist>
<tag><c>{trace, Pid, 'receive', Msg}</c></tag>
<item>
- <p>When <c>Pid</c> receives the message <c>Msg</c>.</p>
+ <p>When <c>Pid</c> receives message <c>Msg</c>.</p>
</item>
<tag><c>{trace, Pid, send, Msg, To}</c></tag>
<item>
- <p>When <c>Pid</c> sends the message <c>Msg</c> to
- the process <c>To</c>.</p>
+ <p>When <c>Pid</c> sends message <c>Msg</c> to
+ process <c>To</c>.</p>
</item>
<tag><c>{trace, Pid, send_to_non_existing_process, Msg, To}</c></tag>
<item>
- <p>When <c>Pid</c> sends the message <c>Msg</c> to
+ <p>When <c>Pid</c> sends message <c>Msg</c> to
the non-existing process <c>To</c>.</p>
</item>
<tag><c>{trace, Pid, call, {M, F, Args}}</c></tag>
@@ -6886,7 +8254,7 @@ ok
<p>When <c>Pid</c> calls a traced function. The return
values of calls are never supplied, only the call and its
arguments.</p>
- <p>Note that the trace flag <c>arity</c> can be used to
+ <p>Trace flag <c>arity</c> can be used to
change the contents of this message, so that <c>Arity</c>
is specified instead of <c>Args</c>.</p>
</item>
@@ -6894,35 +8262,34 @@ ok
<item>
<p>When <c>Pid</c> returns <em>to</em> the specified
function. This trace message is sent if both
- the <c>call</c> and the <c>return_to</c> flags are set,
+ the flags <c>call</c> and <c>return_to</c> are set,
and the function is set to be traced on <em>local</em>
function calls. The message is only sent when returning
- from a chain of tail recursive function calls where at
+ from a chain of tail recursive function calls, where at
least one call generated a <c>call</c> trace message
- (that is, the functions match specification matched and
+ (that is, the functions match specification matched, and
<c>{message, false}</c> was not an action).</p>
</item>
<tag><c>{trace, Pid, return_from, {M, F, Arity}, ReturnValue}</c></tag>
<item>
<p>When <c>Pid</c> returns <em>from</em> the specified
- function. This trace message is sent if the <c>call</c>
- flag is set, and the function has a match specification
+ function. This trace message is sent if flag <c>call</c>
+ is set, and the function has a match specification
with a <c>return_trace</c> or <c>exception_trace</c> action.</p>
</item>
<tag><c>{trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}</c></tag>
<item>
<p>When <c>Pid</c> exits <em>from</em> the specified
- function due to an exception. This trace message is sent
- if the <c>call</c> flag is set, and the function has
+ function because of an exception. This trace message is
+ sent if flag <c>call</c> is set, and the function has
a match specification with an <c>exception_trace</c> action.</p>
</item>
<tag><c>{trace, Pid, spawn, Pid2, {M, F, Args}}</c></tag>
<item>
<p>When <c>Pid</c> spawns a new process <c>Pid2</c> with
the specified function call as entry point.</p>
- <p>Note that <c>Args</c> is supposed to be the argument
- list, but may be any term in the case of an erroneous
- spawn.</p>
+ <p><c>Args</c> is supposed to be the argument list,
+ but can be any term if the spawn is erroneous.</p>
</item>
<tag><c>{trace, Pid, exit, Reason}</c></tag>
<item>
@@ -6952,148 +8319,158 @@ ok
<tag><c>{trace, Pid, unregister, RegName}</c></tag>
<item>
<p>When <c>Pid</c> gets the name <c>RegName</c> unregistered.
- Note that this is done automatically when a registered
+ This is done automatically when a registered
process exits.</p>
</item>
<tag><c>{trace, Pid, in, {M, F, Arity} | 0}</c></tag>
<item>
- <p>When <c>Pid</c> is scheduled to run. The process will
- run in function <c>{M, F, Arity}</c>. On some rare
- occasions the current function cannot be determined, then
- the last element <c>Arity</c> is 0.</p>
+ <p>When <c>Pid</c> is scheduled to run. The process
+ runs in function <c>{M, F, Arity}</c>. On some rare
+ occasions, the current function cannot be determined,
+ then the last element is <c>0</c>.</p>
</item>
<tag><c>{trace, Pid, out, {M, F, Arity} | 0}</c></tag>
<item>
<p>When <c>Pid</c> is scheduled out. The process was
- running in function {M, F, Arity}. On some rare occasions
+ running in function {M, F, Arity}. On some rare occasions,
the current function cannot be determined, then the last
- element <c>Arity</c> is 0.</p>
+ element is <c>0</c>.</p>
</item>
- <tag><marker id="gc_start"><c>{trace, Pid, gc_start, Info}</c></marker></tag>
+ <tag><c>{trace, Pid, gc_start, Info}</c></tag>
<item>
+ <marker id="gc_start"></marker>
<p>Sent when garbage collection is about to be started.
<c>Info</c> is a list of two-element tuples, where
the first element is a key, and the second is the value.
- You should not depend on the tuples have any defined
- order. Currently, the following keys are defined:</p>
+ Do not depend on any order of the tuples.
+ The following keys are defined:</p>
<taglist>
<tag><c>heap_size</c></tag>
<item>The size of the used part of the heap.</item>
<tag><c>heap_block_size</c></tag>
<item>The size of the memory block used for storing
- the heap and the stack.</item>
+ the heap and the stack.</item>
<tag><c>old_heap_size</c></tag>
<item>The size of the used part of the old heap.</item>
<tag><c>old_heap_block_size</c></tag>
<item>The size of the memory block used for storing
- the old heap.</item>
+ the old heap.</item>
<tag><c>stack_size</c></tag>
- <item>The actual size of the stack.</item>
+ <item>The size of the stack.</item>
<tag><c>recent_size</c></tag>
<item>The size of the data that survived the previous garbage
- collection.</item>
+ collection.</item>
<tag><c>mbuf_size</c></tag>
<item>The combined size of message buffers associated with
- the process.</item>
-
+ the process.</item>
<tag><c>bin_vheap_size</c></tag>
- <item>The total size of unique off-heap binaries referenced from the process heap.</item>
+ <item>The total size of unique off-heap binaries referenced
+ from the process heap.</item>
<tag><c>bin_vheap_block_size</c></tag>
- <item>The total size of binaries, in words, allowed in the virtual
- heap in the process before doing a garbage collection. </item>
+ <item>The total size of binaries allowed in the virtual
+ heap in the process before doing a garbage collection.</item>
<tag><c>bin_old_vheap_size</c></tag>
- <item>The total size of unique off-heap binaries referenced from the process old heap.</item>
- <tag><c>bin_vheap_block_size</c></tag>
- <item>The total size of binaries, in words, allowed in the virtual
- old heap in the process before doing a garbage collection. </item>
-
-
+ <item>The total size of unique off-heap binaries referenced
+ from the process old heap.</item>
+ <tag><c>bin_old_vheap_block_size</c></tag>
+ <item>The total size of binaries allowed in the virtual
+ old heap in the process before doing a garbage collection.</item>
</taglist>
<p>All sizes are in words.</p>
</item>
<tag><c>{trace, Pid, gc_end, Info}</c></tag>
<item>
<p>Sent when garbage collection is finished. <c>Info</c>
- contains the same kind of list as in the <c>gc_start</c>
- message, but the sizes reflect the new sizes after
+ contains the same kind of list as in message <c>gc_start</c>,
+ but the sizes reflect the new sizes after
garbage collection.</p>
</item>
</taglist>
- <p>If the tracing process dies, the flags will be silently
+ <p>If the tracing process dies, the flags are silently
removed.</p>
- <p>Only one process can trace a particular process. For this
- reason, attempts to trace an already traced process will fail.</p>
+ <p>Only one process can trace a particular process. Therefore,
+ attempts to trace an already traced process fail.</p>
<p>Returns: A number indicating the number of processes that
- matched <c><anno>PidSpec</anno></c>. If <c><anno>PidSpec</anno></c> is a pid,
- the return value will be <c>1</c>. If <c><anno>PidSpec</anno></c> is
- <c>all</c> or <c>existing</c> the return value will be
+ matched <c><anno>PidSpec</anno></c>.
+ If <c><anno>PidSpec</anno></c> is a process
+ identifier, the return value is <c>1</c>.
+ If <c><anno>PidSpec</anno></c>
+ is <c>all</c> or <c>existing</c>, the return value is
the number of processes running, excluding tracer processes.
- If <c><anno>PidSpec</anno></c> is <c>new</c>, the return value will be
+ If <c><anno>PidSpec</anno></c> is <c>new</c>, the return value is
<c>0</c>.</p>
- <p>Failure: If specified arguments are not supported. For
- example <c>cpu_timestamp</c> is not supported on all
- platforms.</p>
+ <p>Failure: <c>badarg</c> if the specified arguments are
+ not supported. For example, <c>cpu_timestamp</c> is not
+ supported on all platforms.</p>
</desc>
</func>
+
<func>
<name name="trace_delivered" arity="1"/>
- <fsummary>Notification when trace has been delivered</fsummary>
+ <fsummary>Notification when trace has been delivered.</fsummary>
<desc>
<p>The delivery of trace messages is dislocated on the time-line
- compared to other events in the system. If you know that the
- <c><anno>Tracee</anno></c> has passed some specific point in its execution,
+ compared to other events in the system. If you know that
+ <c><anno>Tracee</anno></c> has passed some specific point
+ in its execution,
and you want to know when at least all trace messages
- corresponding to events up to this point have reached the tracer
- you can use <c>erlang:trace_delivered(<anno>Tracee</anno>)</c>. A
+ corresponding to events up to this point have reached the
+ tracer, use <c>erlang:trace_delivered(<anno>Tracee</anno>)</c>. A
<c>{trace_delivered, <anno>Tracee</anno>, <anno>Ref</anno>}</c> message is sent to
the caller of <c>erlang:trace_delivered(<anno>Tracee</anno>)</c> when it
- is guaranteed that all trace messages have been delivered to
- the tracer up to the point that the <c><anno>Tracee</anno></c> had reached
+ is guaranteed that all trace messages are delivered to
+ the tracer up to the point that <c><anno>Tracee</anno></c> reached
at the time of the call to
<c>erlang:trace_delivered(<anno>Tracee</anno>)</c>.</p>
- <p>Note that the <c>trace_delivered</c> message does <em>not</em>
- imply that trace messages have been delivered; instead, it implies
- that all trace messages that <em>should</em> be delivered have
- been delivered. It is not an error if <c><anno>Tracee</anno></c> isn't, and
- hasn't been traced by someone, but if this is the case,
- <em>no</em> trace messages will have been delivered when the
+ <p>Notice that message <c>trace_delivered</c> does <em>not</em>
+ imply that trace messages have been delivered.
+ Instead it implies that all trace messages that
+ <em>are to be delivered</em> have been delivered.
+ It is not an error if <c><anno>Tracee</anno></c> is not, and
+ has not been traced by someone, but if this is the case,
+ <em>no</em> trace messages have been delivered when the
<c>trace_delivered</c> message arrives.</p>
- <p>Note that <c><anno>Tracee</anno></c> has to refer to a process currently,
+ <p>Notice that that <c><anno>Tracee</anno></c> must refer
+ to a process currently,
or previously existing on the same node as the caller of
<c>erlang:trace_delivered(<anno>Tracee</anno>)</c> resides on.
- The special <c><anno>Tracee</anno></c> atom <c>all</c> denotes all processes
+ The special <c><anno>Tracee</anno></c> atom <c>all</c>
+ denotes all processes
that currently are traced in the node.</p>
- <p>An example: Process <c>A</c> is <c><anno>Tracee</anno></c>, port <c>B</c> is
- tracer, and process <c>C</c> is the port owner of <c>B</c>.
- <c>C</c> wants to close <c>B</c> when <c>A</c> exits. <c>C</c>
- can ensure that the trace isn't truncated by calling
- <c>erlang:trace_delivered(A)</c> when <c>A</c> exits and wait
- for the <c>{trace_delivered, A, <anno>Ref</anno>}</c> message before closing
- <c>B</c>.</p>
- <p>Failure: <c>badarg</c> if <c><anno>Tracee</anno></c> does not refer to a
+ <p>Example: Process <c>A</c> is <c><anno>Tracee</anno></c>,
+ port <c>B</c> is tracer, and process <c>C</c> is the port
+ owner of <c>B</c>. <c>C</c> wants to close <c>B</c> when
+ <c>A</c> exits. To ensure that the trace is not truncated,
+ <c>C</c> can call <c>erlang:trace_delivered(A)</c>, when
+ <c>A</c> exits, and wait for message <c>{trace_delivered, A,
+ <anno>Ref</anno>}</c> before closing <c>B</c>.</p>
+ <p>Failure: <c>badarg</c> if <c><anno>Tracee</anno></c>
+ does not refer to a
process (dead or alive) on the same node as the caller of
<c>erlang:trace_delivered(<anno>Tracee</anno>)</c> resides on.</p>
</desc>
</func>
+
<func>
<name name="trace_info" arity="2"/>
+ <fsummary>Trace information about a process or function.</fsummary>
<type name="trace_info_return"/>
<type name="trace_info_item_result"/>
<type name="trace_info_flag"/>
<type name="trace_match_spec"/>
- <fsummary>Trace information about a process or function</fsummary>
<desc>
<p>Returns trace information about a process or function.</p>
- <p>To get information about a process, <c><anno>PidOrFunc</anno></c> should
- be a pid or the atom <c>new</c>. The atom <c>new</c> means
- that the default trace state for processes to be created will
- be returned. <c><anno>Item</anno></c> must have one of the following
- values:</p>
+ <p>To get information about a process,
+ <c><anno>PidOrFunc</anno></c> is to
+ be a process identifier (pid) or the atom <c>new</c>.
+ The atom <c>new</c> means that the default trace state for
+ processes to be created is returned.</p>
+ <p>The following <c>Item</c>s are valid:</p>
<taglist>
<tag><c>flags</c></tag>
<item>
- <p>Return a list of atoms indicating what kind of traces is
- enabled for the process. The list will be empty if no
+ <p>Returns a list of atoms indicating what kind of traces is
+ enabled for the process. The list is empty if no
traces are enabled, and one or more of the followings
atoms if traces are enabled: <c>send</c>,
<c>'receive'</c>, <c>set_on_spawn</c>, <c>call</c>,
@@ -7104,358 +8481,474 @@ ok
</item>
<tag><c>tracer</c></tag>
<item>
- <p>Return the identifier for process or port tracing this
+ <p>Returns the identifier for process or port tracing this
process. If this process is not being traced, the return
- value will be <c>[]</c>.</p>
+ value is <c>[]</c>.</p>
</item>
</taglist>
- <p>To get information about a function, <c>PidOrFunc</c> should
- be a three-element tuple: <c>{Module, Function, Arity}</c> or
- the atom <c>on_load</c>. No wildcards are allowed. Returns
- <c>undefined</c> if the function does not exist or
- <c>false</c> if the function is not traced at all. <c>Item</c>
- must have one of the following values:</p>
+ <p>To get information about a function, <c>PidOrFunc</c> is to
+ be the three-element tuple <c>{Module, Function, Arity}</c> or
+ the atom <c>on_load</c>. No wild cards are allowed. Returns
+ <c>undefined</c> if the function does not exist, or
+ <c>false</c> if the function is not traced.</p>
+ <p>The following <c>Item</c>s are valid::</p>
<taglist>
<tag><c>traced</c></tag>
<item>
- <p>Return <c>global</c> if this function is traced on
+ <p>Returns <c>global</c> if this function is traced on
global function calls, <c>local</c> if this function is
- traced on local function calls (i.e local and global
- function calls), and <c>false</c> if neither local nor
- global function calls are traced.</p>
+ traced on local function calls (that is, local and global
+ function calls), and <c>false</c> if local or
+ global function calls are not traced.</p>
</item>
<tag><c>match_spec</c></tag>
<item>
- <p>Return the match specification for this function, if it
+ <p>Returns the match specification for this function, if it
has one. If the function is locally or globally traced but
has no match specification defined, the returned value
is <c>[]</c>.</p>
</item>
<tag><c>meta</c></tag>
<item>
- <p>Return the meta trace tracer process or port for this
- function, if it has one. If the function is not meta
- traced the returned value is <c>false</c>, and if
- the function is meta traced but has once detected that
- the tracer proc is invalid, the returned value is [].</p>
+ <p>Returns the meta-trace tracer process or port for this
+ function, if it has one. If the function is not
+ meta-traced, the returned value is <c>false</c>. If
+ the function is meta-traced but has once detected that
+ the tracer process is invalid, the returned value is [].</p>
</item>
<tag><c>meta_match_spec</c></tag>
<item>
- <p>Return the meta trace match specification for this
- function, if it has one. If the function is meta traced
+ <p>Returns the meta-trace match specification for this
+ function, if it has one. If the function is meta-traced
but has no match specification defined, the returned
value is <c>[]</c>.</p>
</item>
<tag><c>call_count</c></tag>
<item>
- <p>Return the call count value for this function or
+ <p>Returns the call count value for this function or
<c>true</c> for the pseudo function <c>on_load</c> if call
- count tracing is active. Return <c>false</c> otherwise.
+ count tracing is active. Otherwise <c>false</c> is returned.
See also
<seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
</item>
<tag><c>call_time</c></tag>
<item>
- <p>Return the call time values for this function or
+ <p>Returns the call time values for this function or
<c>true</c> for the pseudo function <c>on_load</c> if call
- time tracing is active. Returns <c>false</c> otherwise.
+ time tracing is active. Otherwise <c>false</c> is returned.
The call time values returned, <c>[{Pid, Count, S, Us}]</c>,
- is a list of each process that has executed the function and its specific counters.
- See also
+ is a list of each process that executed the function
+ and its specific counters. See also
<seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
</item>
<tag><c>all</c></tag>
<item>
- <p>Return a list containing the <c>{<anno>Item</anno>, Value}</c> tuples
- for all other items, or return <c>false</c> if no tracing
+ <p>Returns a list containing the
+ <c>{<anno>Item</anno>, Value}</c> tuples
+ for all other items, or returns <c>false</c> if no tracing
is active for this function.</p>
</item>
</taglist>
- <p>The actual return value will be <c>{<anno>Item</anno>, Value}</c>, where
- <c>Value</c> is the requested information as described above.
+ <p>The return value is <c>{<anno>Item</anno>, Value}</c>, where
+ <c>Value</c> is the requested information as described earlier.
If a pid for a dead process was given, or the name of a
- non-existing function, <c>Value</c> will be <c>undefined</c>.</p>
- <p>If <c><anno>PidOrFunc</anno></c> is the <c>on_load</c>, the information
+ non-existing function, <c>Value</c> is <c>undefined</c>.</p>
+ <p>If <c><anno>PidOrFunc</anno></c> is <c>on_load</c>, the information
returned refers to the default value for code that will be
loaded.</p>
</desc>
</func>
+
<func>
<name name="trace_pattern" arity="2" clause_i="1"/>
+ <fsummary>Sets trace patterns for global call tracing.</fsummary>
<type name="trace_pattern_mfa"/>
<type name="trace_match_spec"/>
- <fsummary>Set trace patterns for global call tracing</fsummary>
<desc>
<p>The same as
<seealso marker="#trace_pattern/3">erlang:trace_pattern(MFA, MatchSpec, [])</seealso>,
retained for backward compatibility.</p>
</desc>
</func>
+
<func>
<name name="trace_pattern" arity="3"/>
+ <fsummary>Sets trace patterns for tracing of function calls.</fsummary>
<type name="trace_pattern_mfa"/>
<type name="trace_match_spec"/>
<type name="trace_pattern_flag"/>
- <fsummary>Set trace patterns for tracing of function calls</fsummary>
<desc>
- <p>This BIF is used to enable or disable call tracing for
- exported functions. It must be combined with
+ <p>Enables or disables call tracing for
+ one or more functions. Must be combined with
<seealso marker="#trace/3">erlang:trace/3</seealso>
to set the <c>call</c> trace flag for one or more processes.</p>
- <p>Conceptually, call tracing works like this: Inside
- the Erlang virtual machine there is a set of processes to be
- traced and a set of functions to be traced. Tracing will be
- enabled on the intersection of the set. That is, if a process
- included in the traced process set calls a function included
- in the traced function set, the trace action will be taken.
- Otherwise, nothing will happen.</p>
- <p>Use
- <seealso marker="#trace/3">erlang:trace/3</seealso> to
- add or remove one or more processes to the set of traced
- processes. Use <c>erlang:trace_pattern/2</c> to add or remove
- exported functions to the set of traced functions.</p>
- <p>The <c>erlang:trace_pattern/3</c> BIF can also add match
- specifications to an exported function. A match specification
- comprises a pattern that the arguments to the function must
- match, a guard expression which must evaluate to <c>true</c>
+ <p>Conceptually, call tracing works as follows. Inside
+ the Erlang Virtual Machine, a set of processes and
+ a set of functions are to be traced. If a traced process
+ calls a traced function, the trace action is taken.
+ Otherwise, nothing happens.</p>
+ <p>To add or remove one or more processes to the set of traced
+ processes, use
+ <seealso marker="#trace/3">erlang:trace/3</seealso>.</p>
+ <p>To add or remove functions to the set of traced
+ functions, use <c>erlang:trace_pattern/3</c>.</p>
+ <p>The BIF <c>erlang:trace_pattern/3</c> can also add match
+ specifications to a function. A match specification
+ comprises a pattern that the function arguments must
+ match, a guard expression that must evaluate to <c>true</c>,
and an action to be performed. The default action is to send a
trace message. If the pattern does not match or the guard
- fails, the action will not be executed.</p>
- <p>The <c><anno>MFA</anno></c> argument should be a tuple like
- <c>{Module, Function, Arity}</c> or the atom <c>on_load</c>
- (described below). It can be the module, function, and arity
- for an exported function (or a BIF in any module).
- The <c>'_'</c> atom can be used to mean any of that kind.
- Wildcards can be used in any of the following ways:</p>
+ fails, the action is not executed.</p>
+ <p>Argument <c><anno>MFA</anno></c> is to be a tuple, such as
+ <c>{Module, Function, Arity}</c>, or the atom <c>on_load</c>
+ (described in the following). It can be the module, function,
+ and arity for a function (or a BIF in any module).
+ The atom <c>'_'</c> can be used as a wild card in any of the
+ following ways:</p>
<taglist>
<tag><c>{Module,Function,'_'}</c></tag>
<item>
- <p>All exported functions of any arity named <c>Function</c>
+ <p>All functions of any arity named <c>Function</c>
in module <c>Module</c>.</p>
</item>
<tag><c>{Module,'_','_'}</c></tag>
<item>
- <p>All exported functions in module <c>Module</c>.</p>
+ <p>All functions in module <c>Module</c>.</p>
</item>
<tag><c>{'_','_','_'}</c></tag>
<item>
- <p>All exported functions in all loaded modules.</p>
+ <p>All functions in all loaded modules.</p>
</item>
</taglist>
<p>Other combinations, such as <c>{Module,'_',Arity}</c>, are
- not allowed. Local functions will match wildcards only if
- the <c>local</c> option is in the <c><anno>FlagList</anno></c>.</p>
- <p>If the <c><anno>MFA</anno></c> argument is the atom <c>on_load</c>,
- the match specification and flag list will be used on all
+ not allowed. Local functions match wild cards only if
+ option <c>local</c> is in <c><anno>FlagList</anno></c>.</p>
+ <p>If argument <c><anno>MFA</anno></c> is the atom <c>on_load</c>,
+ the match specification and flag list are used on all
modules that are newly loaded.</p>
- <p>The <c><anno>MatchSpec</anno></c> argument can take any of the following
- forms:</p>
+ <p>Argument <c><anno>MatchSpec</anno></c> can take the
+ following forms:</p>
<taglist>
<tag><c>false</c></tag>
<item>
- <p>Disable tracing for the matching function(s). Any match
- specification will be removed.</p>
+ <p>Disables tracing for the matching functions.
+ Any match specification is removed.</p>
</item>
<tag><c>true</c></tag>
<item>
- <p>Enable tracing for the matching function(s).</p>
+ <p>Enables tracing for the matching functions.</p>
</item>
<tag><c><anno>MatchSpecList</anno></c></tag>
<item>
<p>A list of match specifications. An empty list is
- equivalent to <c>true</c>. See the ERTS User's Guide
- for a description of match specifications.</p>
+ equivalent to <c>true</c>. For a description of match
+ specifications, see the User's Guide.</p>
</item>
<tag><c>restart</c></tag>
<item>
- <p>For the <c><anno>FlagList</anno></c> option <c>call_count</c> and <c>call_time</c>:
- restart the existing counters. The behaviour is undefined
+ <p>For the <c><anno>FlagList</anno></c> options <c>call_count</c>
+ and <c>call_time</c>: restarts
+ the existing counters. The behavior is undefined
for other <c><anno>FlagList</anno></c> options.</p>
</item>
<tag><c>pause</c></tag>
<item>
- <p>For the <c><anno>FlagList</anno></c> option <c>call_count</c> and <c>call_time</c>: pause
- the existing counters. The behaviour is undefined for
- other <c>FlagList</c> options.</p>
+ <p>For the <c><anno>FlagList</anno></c> options
+ <c>call_count</c> and <c>call_time</c>: pauses
+ the existing counters. The behavior is undefined for
+ other <c><anno>FlagList</anno></c> options.</p>
</item>
</taglist>
- <p>The <c><anno>FlagList</anno></c> parameter is a list of options.
- The following options are allowed:</p>
+ <p>Parameter <c><anno>FlagList</anno></c> is a list of options.
+ The following are the valid options:</p>
<taglist>
<tag><c>global</c></tag>
<item>
- <p>Turn on or off call tracing for global function calls
+ <p>Turns on or off call tracing for global function calls
(that is, calls specifying the module explicitly). Only
- exported functions will match and only global calls will
- generate trace messages. This is the default.</p>
+ exported functions match and only global calls
+ generate trace messages. <em>This is the default</em>.</p>
</item>
<tag><c>local</c></tag>
<item>
- <p>Turn on or off call tracing for all types of function
- calls. Trace messages will be sent whenever any of
+ <p>Turns on or off call tracing for all types of function
+ calls. Trace messages are sent whenever any of
the specified functions are called, regardless of how they
- are called. If the <c>return_to</c> flag is set for
- the process, a <c>return_to</c> message will also be sent
+ are called. If flag <c>return_to</c> is set for
+ the process, a <c>return_to</c> message is also sent
when this function returns to its caller.</p>
</item>
<tag><c>meta | {meta, <anno>Pid</anno>}</c></tag>
<item>
- <p>Turn on or off meta tracing for all types of function
- calls. Trace messages will be sent to the tracer process
+ <p>Turns on or off meta-tracing for all types of function
+ calls. Trace messages are sent to the tracer process
or port <c><anno>Pid</anno></c> whenever any of the specified
functions are called, regardless of how they are called.
- If no <c><anno>Pid</anno></c> is specified, <c>self()</c> is used as a
- default tracer process.</p>
- <p>Meta tracing traces all processes and does not care
+ If no <c><anno>Pid</anno></c> is specified,
+ <c>self()</c> is used as a default tracer process.</p>
+ <p>Meta-tracing traces all processes and does not care
about the process trace flags set by <c>trace/3</c>,
the trace flags are instead fixed to
<c>[call, timestamp]</c>.</p>
- <p>The match spec function <c>{return_trace}</c> works with
- meta trace and send its trace message to the same tracer
- process.</p>
+ <p>The match specification function <c>{return_trace}</c>
+ works with meta-trace and sends its trace message to the
+ same tracer process.</p>
</item>
<tag><c>call_count</c></tag>
<item>
<p>Starts (<c><anno>MatchSpec</anno> == true</c>) or stops
- (<c><anno>MatchSpec</anno> == false</c>) call count tracing for all
- types of function calls. For every function a counter is
+ (<c><anno>MatchSpec</anno> == false</c>)
+ call count tracing for all
+ types of function calls. For every function, a counter is
incremented when the function is called, in any process.
No process trace flags need to be activated.</p>
<p>If call count tracing is started while already running,
- the count is restarted from zero. Running counters can be
- paused with <c><anno>MatchSpec</anno> == pause</c>. Paused and running
- counters can be restarted from zero with
+ the count is restarted from zero. To pause running
+ counters, use <c><anno>MatchSpec</anno> == pause</c>.
+ Paused and running counters can be restarted from zero with
<c><anno>MatchSpec</anno> == restart</c>.</p>
- <p>The counter value can be read with
+ <p>To read the counter value, use
<seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p>
</item>
<tag><c>call_time</c></tag>
<item>
<p>Starts (<c><anno>MatchSpec</anno> == true</c>) or stops
- (<c><anno>MatchSpec</anno> == false</c>) call time tracing for all
- types of function calls. For every function a counter is
- incremented when the function is called. Time spent in the function
- is accumulated in two other counters, seconds and micro-seconds.
+ (<c><anno>MatchSpec</anno> == false</c>) call time
+ tracing for all
+ types of function calls. For every function, a counter is
+ incremented when the function is called.
+ Time spent in the function is accumulated in
+ two other counters, seconds and microseconds.
The counters are stored for each call traced process.</p>
<p>If call time tracing is started while already running,
- the count and time is restarted from zero. Running counters can be
- paused with <c><anno>MatchSpec</anno> == pause</c>. Paused and running
- counters can be restarted from zero with
+ the count and time is restarted from zero. To pause
+ running counters, use <c><anno>MatchSpec</anno> == pause</c>.
+ Paused and running counters can be restarted from zero with
<c><anno>MatchSpec</anno> == restart</c>.</p>
- <p>The counter value can be read with
+ <p>To read the counter value, use
<seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p>
</item>
-
</taglist>
- <p>The <c>global</c> and <c>local</c> options are mutually
- exclusive and <c>global</c> is the default (if no options are
- specified). The <c>call_count</c> and <c>meta</c> options
- perform a kind of local tracing, and can also not be combined
- with <c>global</c>. A function can be either globally or
+ <p>The options <c>global</c> and <c>local</c> are mutually
+ exclusive, and <c>global</c> is the default (if no options are
+ specified). The options <c>call_count</c> and <c>meta</c>
+ perform a kind of local tracing, and cannot be combined
+ with <c>global</c>. A function can be globally or
locally traced. If global tracing is specified for a
- specified set of functions; local, meta, call time and call count
- tracing for the matching set of local functions will be
- disabled, and vice versa.</p>
+ set of functions, then local, meta, call time, and call count
+ tracing for the matching set of local functions is
+ disabled, and conversely.</p>
<p>When disabling trace, the option must match the type of trace
- that is set on the function, so that local tracing must be
- disabled with the <c>local</c> option and global tracing with
- the <c>global</c> option (or no option at all), and so forth.</p>
- <p>There is no way to directly change part of a match
- specification list. If a function has a match specification,
- you can replace it with a completely new one. If you need to
- change an existing match specification, use the
+ set on the function. That is, local tracing must be
+ disabled with option <c>local</c> and global tracing with
+ option <c>global</c> (or no option), and so forth.</p>
+ <p>Part of a match specification list cannot be changed directly.
+ If a function has a match specification, it can be replaced
+ with a new one. To change an existing match specification,
+ use the BIF
<seealso marker="#trace_info/2">erlang:trace_info/2</seealso>
- BIF to retrieve the existing match specification.</p>
- <p>Returns the number of exported functions that matched
- the <c><anno>MFA</anno></c> argument. This will be zero if none matched at
- all.</p>
+ to retrieve the existing match specification.</p>
+ <p>Returns the number of functions matching
+ argument <c><anno>MFA</anno></c>. This is zero if none matched.</p>
</desc>
</func>
+
<func>
<name name="trunc" arity="1"/>
- <fsummary>Return an integer by the truncating a number</fsummary>
+ <fsummary>Returns an integer by truncating a number</fsummary>
<desc>
- <p>Returns an integer by the truncating <c><anno>Number</anno></c>.</p>
+ <p>Returns an integer by truncating <c><anno>Number</anno></c>,
+ for example:</p>
<pre>
> <input>trunc(5.5).</input>
5</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="tuple_size" arity="1"/>
- <fsummary>Return the size of a tuple</fsummary>
+ <fsummary>Returns the size of a tuple.</fsummary>
<desc>
- <p>Returns an integer which is the number of elements in <c><anno>Tuple</anno></c>.</p>
+ <p>Returns an integer that is the number of elements in
+ <c><anno>Tuple</anno></c>, for example:</p>
<pre>
> <input>tuple_size({morni, mulle, bwange}).</input>
3</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
+
<func>
<name name="tuple_to_list" arity="1"/>
- <fsummary>Convert a tuple to a list</fsummary>
+ <fsummary>Converts a tuple to a list.</fsummary>
<desc>
- <p>Returns a list which corresponds to <c><anno>Tuple</anno></c>.
- <c><anno>Tuple</anno></c> may contain any Erlang terms.</p>
+ <p>Returns a list corresponding to <c><anno>Tuple</anno></c>.
+ <c><anno>Tuple</anno></c> can contain any Erlang terms.</p>
+ <p>Example:</p>
<pre>
> <input>tuple_to_list({share, {'Ericsson_B', 163}}).</input>
[share,{'Ericsson_B',163}]</pre>
</desc>
</func>
+
<func>
<name name="universaltime" arity="0"/>
- <fsummary>Current date and time according to Universal Time Coordinated (UTC)</fsummary>
+ <fsummary>Current date and time according to Universal Time Coordinated (UTC).</fsummary>
<desc>
<p>Returns the current date and time according to Universal
- Time Coordinated (UTC), also called GMT, in the form
+ Time Coordinated (UTC) in the form
<c>{{Year, Month, Day}, {Hour, Minute, Second}}</c> if
- supported by the underlying operating system. If not,
- <c>erlang:universaltime()</c> is equivalent to
+ supported by the underlying OS.
+ Otherwise <c>erlang:universaltime()</c> is equivalent to
<c>erlang:localtime()</c>.</p>
+ <p>Example:</p>
<pre>
> <input>erlang:universaltime().</input>
{{1996,11,6},{14,18,43}}</pre>
</desc>
</func>
+
<func>
<name name="universaltime_to_localtime" arity="1"/>
- <fsummary>Convert from Universal Time Coordinated (UTC) to local date and time</fsummary>
+ <fsummary>Converts from Universal Time Coordinated (UTC) to local date and time.</fsummary>
<desc>
<p>Converts Universal Time Coordinated (UTC) date and time to
- local date and time, if this is supported by the underlying
- OS. Otherwise, no conversion is done, and
+ local date and time in the form
+ <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c> if
+ supported by the underlying OS.
+ Otherwise no conversion is done, and
<c><anno>Universaltime</anno></c> is returned.</p>
+ <p>Example:</p>
<pre>
> <input>erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).</input>
{{1996,11,7},{15,18,43}}</pre>
- <p>Failure: <c>badarg</c> if <c>Universaltime</c> does not denote
- a valid date and time.</p>
+ <p>Failure: <c>badarg</c> if <c>Universaltime</c> denotes
+ an invalid date and time.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="unique_integer" arity="0"/>
+ <fsummary>Get a unique integer value</fsummary>
+ <desc>
+ <p>Generates and returns an
+ <seealso marker="doc/efficiency_guide:advanced#unique_integers">integer
+ unique on current runtime system instance</seealso>. The same as calling
+ <seealso marker="#unique_integer/1"><c>erlang:unique_integer([])</c></seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="unique_integer" arity="1"/>
+ <fsummary>Get a unique integer value</fsummary>
+ <desc>
+ <p>Generates and returns an
+ <seealso marker="doc/efficiency_guide:advanced#unique_integers">integer
+ unique on current runtime system
+ instance</seealso>. The integer is unique in the
+ sense that this BIF, using the same set of
+ modifiers, will not return the same integer more
+ than once on the current runtime system instance.
+ Each integer value can of course be constructed
+ by other means.</p>
+
+ <p>By default, when <c>[]</c> is passed as
+ <c><anno>ModifierList</anno></c>, both negative and
+ positive integers can be returned. This in order
+ to utilize the range of integers that do
+ not need heap memory allocation as much as possible.
+ By default the returned integers are also only
+ guaranteed to be unique, that is, any returned integer
+ can be smaller or larger than previously
+ returned integers.</p>
+
+ <p>Valid <c><anno>Modifier</anno></c>s:</p>
+ <taglist>
+
+ <tag>positive</tag>
+ <item><p>Return only positive integers.</p>
+ <p>Note that by passing the <c>positive</c> modifier
+ you will get heap allocated integers (bignums)
+ quicker.</p>
+ </item>
+
+ <tag>monotonic</tag>
+ <item><p>Return
+ <seealso marker="time_correction#Strictly_Monotonically_Increasing">strictly
+ monotonically increasing</seealso> integers
+ corresponding to creation time. That is, the integer
+ returned will always be larger than previously
+ returned integers on the current runtime system
+ instance.</p>
+ <p>These values can be used to determine order between events
+ on the runtime system instance. That is, if both
+ <c>X = erlang:unique_integer([monotonic])</c> and
+ <c>Y = erlang:unique_integer([monotonic])</c> are
+ executed by different processes (or the same
+ process) on the same runtime system instance and
+ <c>X &lt; Y</c> we know that <c>X</c> was created
+ before <c>Y</c>.</p>
+ <warning><p>Strictly monotonically increasing values
+ are inherently quite expensive to generate and scales
+ poorly. This is because the values need to be
+ synchronized between cpu cores. That is, do not pass the <c>monotonic</c>
+ modifier unless you really need strictly monotonically
+ increasing values.</p></warning>
+ </item>
+
+ </taglist>
+
+ <p>All valid <c><anno>Modifier</anno></c>s
+ can be combined. Repeated (valid)
+ <c><anno>Modifier</anno></c>s in the <c>ModifierList</c>
+ are ignored.</p>
+
+ <note><p>Note that the set of integers returned by
+ <c>unique_integer/1</c> using different sets of
+ <c><anno>Modifier</anno></c>s <em>will overlap</em>.
+ For example, by calling <c>unique_integer([monotonic])</c>,
+ and <c>unique_integer([positive, monotonic])</c>
+ repeatedly, you will eventually see some integers being
+ returned by both calls.</p></note>
+
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>if <c><anno>ModifierList</anno></c> is not a
+ proper list.</item>
+ <tag><c>badarg</c></tag>
+ <item>if <c><anno>Modifier</anno></c> is not a
+ valid modifier.</item>
+ </taglist>
</desc>
</func>
<func>
<name name="unlink" arity="1"/>
- <fsummary>Remove a link, if there is one, to another process or port</fsummary>
+ <fsummary>Removes a link to another process or port.</fsummary>
<desc>
<p>Removes the link, if there is one, between the calling
- process and the process or port referred to by <c><anno>Id</anno></c>.</p>
+ process and the process or port referred to by
+ <c><anno>Id</anno></c>.</p>
<p>Returns <c>true</c> and does not fail, even if there is no
- link to <c><anno>Id</anno></c>, or if <c><anno>Id</anno></c> does not exist.</p>
- <p>Once <c>unlink(<anno>Id</anno>)</c> has returned it is guaranteed that
+ link to <c><anno>Id</anno></c>, or if <c><anno>Id</anno></c>
+ does not exist.</p>
+ <p>Once <c>unlink(<anno>Id</anno>)</c> has returned,
+ it is guaranteed that
the link between the caller and the entity referred to by
- <c><anno>Id</anno></c> has no effect on the caller in the future (unless
- the link is setup again). If caller is trapping exits, an
- <c>{'EXIT', <anno>Id</anno>, _}</c> message due to the link might have
- been placed in the caller's message queue prior to the call,
- though. Note, the <c>{'EXIT', <anno>Id</anno>, _}</c> message can be the
- result of the link, but can also be the result of <c><anno>Id</anno></c>
- calling <c>exit/2</c>. Therefore, it <em>may</em> be
- appropriate to cleanup the message queue when trapping exits
- after the call to <c>unlink(<anno>Id</anno>)</c>, as follow:</p>
+ <c><anno>Id</anno></c> has no effect on the caller
+ in the future (unless
+ the link is setup again). If the caller is trapping exits, an
+ <c>{'EXIT', <anno>Id</anno>, _}</c> message from the link
+ can have been placed in the caller's message queue before
+ the call.</p>
+ <p>Notice that the <c>{'EXIT', <anno>Id</anno>, _}</c>
+ message can be the
+ result of the link, but can also be the result of <c>Id</c>
+ calling <c>exit/2</c>. Therefore, it <em>can</em> be
+ appropriate to clean up the message queue when trapping exits
+ after the call to <c>unlink(<anno>Id</anno>)</c>, as follows:</p>
<code type="none">
-
unlink(Id),
receive
{'EXIT', Id, _} ->
@@ -7464,23 +8957,25 @@ ok
true
end</code>
<note>
- <p>Prior to OTP release R11B (erts version 5.5) <c>unlink/1</c>
- behaved completely asynchronous, i.e., the link was active
+ <p>Prior to OTP release R11B (ERTS version 5.5) <c>unlink/1</c>
+ behaved completely asynchronously, i.e., the link was active
until the "unlink signal" reached the linked entity. This
- had one undesirable effect, though. You could never know when
+ had an undesirable effect, as you could never know when
you were guaranteed <em>not</em> to be effected by the link.</p>
- <p>Current behavior can be viewed as two combined operations:
+ <p>The current behavior can be viewed as two combined operations:
asynchronously send an "unlink signal" to the linked entity
and ignore any future results of the link.</p>
</note>
</desc>
</func>
+
<func>
<name name="unregister" arity="1"/>
- <fsummary>Remove the registered name for a process (or port)</fsummary>
+ <fsummary>Removes the registered name for a process (or port).</fsummary>
<desc>
- <p>Removes the registered name <c><anno>RegName</anno></c>, associated with a
- pid or a port identifier.</p>
+ <p>Removes the registered name <c><anno>RegName</anno></c>
+ associated with a
+ process identifier or a port identifier, for example:</p>
<pre>
> <input>unregister(db).</input>
true</pre>
@@ -7489,31 +8984,34 @@ true</pre>
name.</p>
</desc>
</func>
+
<func>
<name name="whereis" arity="1"/>
- <fsummary>Get the pid (or port) with a given registered name</fsummary>
+ <fsummary>Gets the pid (or port) with a given registered name.</fsummary>
<desc>
- <p>Returns the pid or port identifier with the registered name
- <c>RegName</c>. Returns <c>undefined</c> if the name is not
- registered.</p>
+ <p>Returns the process identifier or port identifier with
+ the registered name <c>RegName</c>. Returns <c>undefined</c>
+ if the name is not registered.</p>
+ <p>Example:</p>
<pre>
> <input>whereis(db).</input>
&lt;0.43.0></pre>
</desc>
</func>
+
<func>
<name name="yield" arity="0"/>
- <fsummary>Let other processes get a chance to execute</fsummary>
+ <fsummary>Lets other processes get a chance to execute.</fsummary>
<desc>
- <p>Voluntarily let other processes (if any) get a chance to
+ <p>Voluntarily lets other processes (if any) get a chance to
execute. Using <c>erlang:yield()</c> is similar to
<c>receive after 1 -> ok end</c>, except that <c>yield()</c>
is faster.</p>
<warning><p>There is seldom or never any need to use this BIF,
- especially in the SMP-emulator as other processes will have a
- chance to run in another scheduler thread anyway.
- Using this BIF without a thorough grasp of how the scheduler
- works may cause performance degradation.</p></warning>
+ especially in the SMP emulator, as other processes have a
+ chance to run in another scheduler thread anyway.
+ Using this BIF without a thorough grasp of how the scheduler
+ works can cause performance degradation.</p></warning>
</desc>
</func>
</funcs>