diff options
Diffstat (limited to 'erts/doc')
| -rw-r--r-- | erts/doc/src/Makefile | 5 | ||||
| -rw-r--r-- | erts/doc/src/absform.xml | 9 | ||||
| -rw-r--r-- | erts/doc/src/communication.xml | 89 | ||||
| -rw-r--r-- | erts/doc/src/driver_entry.xml | 16 | ||||
| -rw-r--r-- | erts/doc/src/erl.xml | 187 | ||||
| -rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 301 | ||||
| -rw-r--r-- | erts/doc/src/erl_driver.xml | 253 | ||||
| -rw-r--r-- | erts/doc/src/erl_ext_dist.xml | 123 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 39 | ||||
| -rw-r--r-- | erts/doc/src/erl_set_memory_block.xml | 172 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 4249 | ||||
| -rw-r--r-- | erts/doc/src/erts_alloc.xml | 10 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 905 | ||||
| -rw-r--r-- | erts/doc/src/part.xml | 3 | ||||
| -rw-r--r-- | erts/doc/src/ref_man.xml | 3 |
15 files changed, 3841 insertions, 2523 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index da245d7fe8..89d7c85a86 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -55,7 +55,6 @@ XML_REF3_EFILES = \ XML_REF3_FILES = \ driver_entry.xml \ erl_nif.xml \ - erl_set_memory_block.xml \ erl_driver.xml \ erl_prim_loader.xml \ erlang.xml \ @@ -78,6 +77,7 @@ XML_CHAPTER_FILES = \ inet_cfg.xml \ erl_ext_dist.xml \ erl_dist_protocol.xml \ + communication.xml \ notes.xml \ notes_history.xml @@ -158,9 +158,6 @@ $(SPECDIR)/specs_driver_entry.xml: $(SPECDIR)/specs_erl_nif.xml: escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ -o$(dir $@) -module erl_nif -$(SPECDIR)/specs_erl_set_memory_block.xml: - escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ - -o$(dir $@) -module erl_set_memory_block $(SPECDIR)/specs_erl_driver.xml: escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ -o$(dir $@) -module erl_driver diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index 4455d0ac92..e512c19e05 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2001</year><year>2011</year> + <year>2001</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -290,13 +290,6 @@ <item>If E is <c><![CDATA[fun Fc_1 ; ... ; Fc_k end]]></c> where each <c><![CDATA[Fc_i]]></c> is a function clause then Rep(E) = <c><![CDATA[{'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}]]></c>.</item> - <item>If E is <c><![CDATA[query [E_0 || W_1, ..., W_k] end]]></c>, - where each <c><![CDATA[W_i]]></c> is a generator or a filter, then - Rep(E) = <c><![CDATA[{'query',LINE,{lc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}}]]></c>. - For Rep(W), see below.</item> - <item>If E is <c><![CDATA[E_0.Field]]></c>, a Mnesia record access - inside a query, then - Rep(E) = <c><![CDATA[{record_field,LINE,Rep(E_0),Rep(Field)}]]></c>.</item> <item>If E is <c><![CDATA[( E_0 )]]></c>, then Rep(E) = <c><![CDATA[Rep(E_0)]]></c>, i.e., parenthesized expressions cannot be distinguished from their bodies.</item> diff --git a/erts/doc/src/communication.xml b/erts/doc/src/communication.xml new file mode 100644 index 0000000000..61a9b0e716 --- /dev/null +++ b/erts/doc/src/communication.xml @@ -0,0 +1,89 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2012</year><year>2013</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/. + + 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. + + </legalnotice> + + <title>Communication in Erlang</title> + <prepared>Rickard Green</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>2012-12-03</date> + <rev>PA1</rev> + <file>communication.xml</file> + </header> + <p>Communication in Erlang is conceptually performed using + asynchronous signaling. All different executing entities + such as processes, and ports communicate via asynchronous + signals. The most commonly used signal is a message. Other + common signals are exit, link, unlink, monitor, demonitor + signals.</p> + <section> + <title>Passing of Signals</title> + <p>The amount of time that passes between a signal being sent + and the arrival of the signal at the destination is unspecified + but positive. If the receiver has terminated, the signal will + not arrive, but it is possible that it triggers another signal. + For example, a link signal sent to a non-existing process will + trigger an exit signal which will be sent back to where the link + signal originated from. When communicating over the distribution, + signals may be lost if the distribution channel goes down.</p> + <p>The only signal ordering guarantee given is the following. If + an entity sends multiple signals to the same destination entity, + the order will be preserved. That is, if <c>A</c> sends + a signal <c>S1</c> to <c>B</c>, and later sends + the signal <c>S2</c> to <c>B</c>, <c>S1</c> is guaranteed not to + arrive after <c>S2</c>.</p> + </section> + <section> + <title>Synchronous Communication</title> + <p>Some communication is synchronous. If broken down into pieces, + a synchronous communication operation, consists of two asynchronous + signals. One request signal and one reply signal. An example of + such a synchronous communication is a call to <c>process_info/2</c> + when the first argument is not <c>self()</c>. The caller will send + an asynchronous signal requesting information, and will then + wait for the reply signal containing the requested information. When + the request signal reaches its destination the destination process + replies with the requested information.</p> + </section> + <section> + <title>Implementation</title> + <p>The implementation of different asynchronous signals in the + VM may vary over time, but the behaviour will always respect this + concept of asynchronous signals being passed between entities + as described above.</p> + <p>By inspecting the implementation you might notice that some + specific signal actually gives a stricter guarantee than described + above. It is of vital importance that such knowledge about the + implementation is <em>not</em> used by Erlang code, since the + implementation might change at any time without prior notice.</p> + <p>Some example of major implementation changes:</p> + <list type="bulleted"> + <item>As of ERTS version 5.5.2 exit signals to processes are truly + asynchronously delivered.</item> + <item>As of ERTS version 5.10 all signals from processes to ports + are truly asynchronously delivered.</item> + </list> + </section> +</chapter> + diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index f31b0cb18b..c37138e7b1 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -400,11 +400,11 @@ typedef struct erl_drv_entry { <tag><marker id="driver_flags"/>int driver_flags</tag> <item> - <p>This field is used to pass driver capability information to the - runtime system. If the <c>extended_marker</c> field equals - <c>ERL_DRV_EXTENDED_MARKER</c>, it should contain <c>0</c> or - driver flags (<c>ERL_DRV_FLAG_*</c>) ored bitwise. Currently - the following driver flags exist: + <p>This field is used to pass driver capability and other + information to the runtime system. If the + <c>extended_marker</c> field equals <c>ERL_DRV_EXTENDED_MARKER</c>, + it should contain <c>0</c> or driver flags (<c>ERL_DRV_FLAG_*</c>) + ored bitwise. Currently the following driver flags exist: </p> <taglist> <tag><c>ERL_DRV_FLAG_USE_PORT_LOCKING</c></tag> @@ -427,6 +427,12 @@ typedef struct erl_drv_entry { by the Erlang distribution (the behaviour has always been required by drivers used by the distribution). </item> + <tag><c>ERL_DRV_FLAG_NO_BUSY_MSGQ</c></tag> + <item>Disable busy port message queue functionality. For + more information, see the documentation of the + <seealso marker="erl_driver#erl_drv_busy_msgq_limits">erl_drv_busy_msgq_limits()</seealso> + function. + </item> </taglist> </item> <tag>void *handle2</tag> diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index f931445a3e..9f5de8a9ae 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -479,7 +479,7 @@ <tag><marker id="async_thread_pool_size"><c><![CDATA[+A size]]></c></marker></tag> <item> <p>Sets the number of threads in async thread pool, valid range - is 0-1024. Default is 0.</p> + is 0-1024. If thread support is available, the default is 10.</p> </item> <tag><c><![CDATA[+B [c | d | i]]]></c></tag> <item> @@ -582,11 +582,95 @@ <seealso marker="erts_alloc">erts_alloc(3)</seealso> for further information.</p> </item> - <tag><marker id="max_processes"><c><![CDATA[+P Number]]></c></marker></tag> - <item> - <p>Sets the maximum number of concurrent processes for this - system. <c><![CDATA[Number]]></c> must be in the range 16..134217727. - Default is 32768.</p> + <tag><marker id="+n"/><c><![CDATA[+n Behavior]]></c></tag> + <item> + <p>Control behavior of signals to ports.</p> + <p>As of OTP-R16 signals to ports are truly asynchronously + delivered. Note that signals always have been documented as + asynchronous. The underlying implementation has, however, + previously delivered these signals synchronously. Correctly + written Erlang programs should be able to handle this without + any issues. Bugs in existing Erlang programs that make false + assumptions about signals to ports may, however, be tricky to + find. This switch has been introduced in order to at least + make it easier to compare behaviors during a transition period. + Note that <em>this flag is deprecated</em> as of its + introduction, and is scheduled for removal in OTP-R17. + <c>Behavior</c> should be one of the following characters:</p> + <taglist> + <tag><c>d</c></tag> + <item>The default. Asynchronous signals. A process that sends + a signal to a port may continue execution before the signal + has been delivered to the port.</item> + <tag><c>s</c></tag> + <item>Synchronous signals. A processes that sends a signal + to a port will not continue execution until the signal has + been delivered. Should <em>only</em> be used for testing and + debugging.</item> + <tag><c>a</c></tag> + <item>Asynchronous signals. As the default, but a processes + that sends a signal will even more frequently continue + execution before the signal has been delivered to the + port. Should <em>only</em> be used for testing and + debugging.</item> + </taglist> + </item> + <tag><marker id="+pc"/><marker id="max_processes"><c><![CDATA[+pc Range]]></c></marker></tag> + <item> + <p>Sets the range of characters that the system will consider printable in heuristic detection of strings. This typically affects the shell, debugger and io:format functions (when ~tp is used in the format string).</p> + <p>Currently two values for the <c>Range</c> are supported: + <taglist> + <tag><c>latin1</c></tag> <item>The default. Only characters + in the ISO-latin-1 range can be considered printable, which means + that a character with a code point > 255 will never be + considered printable and that lists containing such + characters will be displayed as lists of integers rather + than text strings by tools.</item> + <tag><c>unicode</c></tag> + <item>All printable Unicode characters are considered when + determining if a list of integers is to be displayed in + string syntax. This may give unexpected results if for + example your font does not cover all Unicode + characters.</item> + </taglist> + </p> + <p>Se also <seealso marker="stdlib:io#printable_range/0"> + io:printable_range/0</seealso>.</p> + </item> + <tag><marker id="+P"/><marker id="max_processes"><c><![CDATA[+P Number]]></c></marker></tag> + <item> + <p>Sets the maximum number of simultaneously existing processes for this + system. Valid range for <c>Number</c> is <c>[1024-134217727]</c></p> + <p><em>NOTE</em>: The actual maximum chosen may be much larger than + the <c>Number</c> passed. Currently the runtime system often, + but not always, chooses a value that is a power of 2. This might, + however, be changed in the future. The actual value chosen can be + checked by calling + <seealso marker="erlang#system_info_process_limit">erlang:system_info(process_limit)</seealso>.</p> + <p>The default value is <c>262144</c></p> + </item> + <tag><marker id="+Q"/><marker id="max_ports"><c><![CDATA[+Q Number]]></c></marker></tag> + <item> + <p>Sets the maximum number of simultaneously existing ports for this + system. Valid range for <c>Number</c> is <c>[1024-134217727]</c></p> + <p><em>NOTE</em>: The actual maximum chosen may be much larger than + the actual <c>Number</c> passed. Currently the runtime system often, + but not always, chooses a value that is a power of 2. This might, + however, be changed in the future. The actual value chosen can be + checked by calling + <seealso marker="erlang#system_info_port_limit">erlang:system_info(port_limit)</seealso>.</p> + <p>The default value used is normally <c>65536</c>. However, if + the runtime system is able to determine maximum amount of file + descriptors that it is allowed to open and this value is larger + than <c>65536</c>, the chosen value will increased to a value + larger or equal to the maximum amount of file descriptors that + can be opened.</p> + <p>On Windows the default value is set to <c>8196</c> because the + normal OS limitations are set higher than most machines can handle.</p> + <p>Previously the environment variable <c>ERL_MAX_PORTS</c> was used + for setting the maximum number of simultaneously existing ports. This + environment variable is deprecated, and scheduled for removal in + OTP-R17, but can still be used.</p> </item> <tag><marker id="compat_rel"><c><![CDATA[+R ReleaseNumber]]></c></marker></tag> <item> @@ -595,21 +679,14 @@ default. This flags sets the emulator in compatibility mode with an earlier Erlang/OTP release <c><![CDATA[ReleaseNumber]]></c>. The release number must be in the range - <c><![CDATA[7..<current release>]]></c>. This limits the emulator, - making it possible for it to communicate with Erlang nodes - (as well as C- and Java nodes) running that earlier release.</p> - <p>For example, an R10 node is not automatically compatible - with an R9 node, but R10 nodes started with the <c><![CDATA[+R 9]]></c> - flag can co-exist with R9 nodes in the same distributed - Erlang system, they are R9-compatible.</p> + <c><![CDATA[<current release>-2..<current release>]]></c>. This + limits the emulator, making it possible for it to communicate + with Erlang nodes (as well as C- and Java nodes) running that + earlier release.</p> <p>Note: Make sure all nodes (Erlang-, C-, and Java nodes) of a distributed Erlang system is of the same Erlang/OTP release, or from two different Erlang/OTP releases X and Y, where <em>all</em> Y nodes have compatibility mode X.</p> - <p>For example: A distributed Erlang system can consist of - R10 nodes, or of R9 nodes and R9-compatible R10 nodes, but - not of R9 nodes, R9-compatible R10 nodes and "regular" R10 - nodes, as R9 and "regular" R10 nodes are not compatible.</p> </item> <tag><c><![CDATA[+r]]></c></tag> <item> @@ -619,7 +696,7 @@ <item> <p>Limits the amount of reader groups used by read/write locks optimized for read operations in the Erlang runtime system. By - default the reader groups limit equals 8.</p> + default the reader groups limit equals 64.</p> <p>When the amount of schedulers is less than or equal to the reader groups limit, each scheduler has its own reader group. When the amount of schedulers is larger than the reader groups limit, @@ -657,7 +734,24 @@ <taglist> <tag><marker id="+sbt"><c>+sbt BindType</c></marker></tag> <item> - <p>Set scheduler bind type. Currently valid <c>BindType</c>s: + <p>Set scheduler bind type.</p> + <p>Schedulers can also be bound using the + <seealso marker="#+stbt">+stbt</seealso> flag. The only difference + between these two flags is how the following errors are handled:</p> + <list> + <item>Binding of schedulers is not supported on the specific + platform.</item> + <item>No available CPU topology. That is the runtime system + was not able to automatically detected the CPU topology, and + no <seealso marker="#+sct">user defined CPU topology</seealso> + was set.</item> + </list> + <p>If any of these errors occur when <c>+sbt</c> has been passed, + the runtime system will print an error message, and refuse to + start. If any of these errors occur when <c>+stbt</c> has been + passed, the runtime system will silently ignore the error, and + start up using unbound schedulers.</p> + <p>Currently valid <c>BindType</c>s: </p> <taglist> <tag><c>u</c></tag> @@ -907,15 +1001,34 @@ <p>For more information, see <seealso marker="erlang#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>.</p> </item> - <tag><marker id="+sws"><c>+sws default|legacy|proposal</c></marker></tag> + <tag><marker id="+stbt"><c>+stbt BindType</c></marker></tag> + <item> + <p>Try to set scheduler bind type. The same as the + <seealso marker="#+sbt">+sbt</seealso> flag with the exception of + how some errors are handled. For more information, see the + documentation of the <seealso marker="#+sbt">+sbt</seealso> flag. + </p> + </item> + <tag><marker id="+swct"><c>+sws very_eager|eager|medium|lazy|very_lazy</c></marker></tag> <item> - <p>Set scheduler wakeup strategy. Default is <c>legacy</c> (has been - used since OTP-R13B). The <c>proposal</c> strategy is the currently - proposed strategy for OTP-R16. Note that the <c>proposal</c> strategy - might change during OTP-R15. + <p> + Set scheduler wake cleanup threshold. Default is <c>medium</c>. + This flag controls how eager schedulers should be requesting + wake up due to certain cleanup operations. When a lazy setting + is used, more outstanding cleanup operations can be left undone + while a scheduler is idling. When an eager setting is used, + schedulers will more frequently be woken, potentially increasing + CPU-utilization. </p> - <p><em>NOTE:</em> This flag may be removed or changed at any time - without prior notice. + <p><em>NOTE:</em> This flag may be removed or changed at any time without prior notice. + </p> + </item> + <tag><marker id="+sws"><c>+sws default|legacy</c></marker></tag> + <item> + <p> + Set scheduler wakeup strategy. Default strategy changed in erts-5.10/OTP-R16A. This strategy was previously known as <c>proposal</c> in OTP-R15. The <c>legacy</c> strategy was used as default from R13 up to and including R15. + </p> + <p><em>NOTE:</em> This flag may be removed or changed at any time without prior notice. </p> </item> <tag><marker id="+swt"><c>+swt very_low|low|medium|high|very_high</c></marker></tag> @@ -932,6 +1045,22 @@ without prior notice. </p> </item> + <tag><marker id="+spp"><c>+spp Bool</c></marker></tag> + <item> + <p>Set default scheduler hint for port parallelism. If set to + <c>true</c>, the VM will schedule port tasks when it by this can + improve the parallelism in the system. If set to <c>false</c>, + the VM will try to perform port tasks immediately and by this + improve latency at the expense of parallelism. If this + flag has not been passed, the default scheduler hint for port + parallelism is currently <c>false</c>. The default used can be + inspected in runtime by calling + <seealso marker="erlang#system_info_port_parallelism">erlang:system_info(port_parallelism)</seealso>. + The default can be overriden on port creation by passing the + <seealso marker="erlang#open_port_parallelism">parallelism</seealso> + option to + <seealso marker="erlang#open_port/2">open_port/2</seealso></p>. + </item> <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag> <item> <p>Suggested stack size, in kilowords, for scheduler threads. @@ -1072,7 +1201,7 @@ </item> </taglist> </item> - <tag><c><![CDATA[ERL_AFLAGS]]></c></tag> + <tag><marker id="ERL_AFLAGS"><c><![CDATA[ERL_AFLAGS]]></c></marker></tag> <item> <p>The content of this environment variable will be added to the beginning of the command line for <c><![CDATA[erl]]></c>.</p> @@ -1082,7 +1211,7 @@ the <c><![CDATA[-extra]]></c> section, i.e. the end of the command line following after an <c><![CDATA[-extra]]></c> flag.</p> </item> - <tag><c><![CDATA[ERL_ZFLAGS]]></c> and <c><![CDATA[ERL_FLAGS]]></c></tag> + <tag><marker id="ERL_ZFLAGS"><c><![CDATA[ERL_ZFLAGS]]></c></marker> and <marker id="ERL_FLAGS"><c><![CDATA[ERL_FLAGS]]></c></marker></tag> <item> <p>The content of these environment variables will be added to the end of the command line for <c><![CDATA[erl]]></c>.</p> diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index 6c725fc82d..84f4be208d 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2007</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -162,11 +162,12 @@ By default EPMD listens on port 4369. </item> <tag><c>Nlen</c></tag> <item> - The length of the <c>NodeName</c>. + The length (in bytes) of the <c>NodeName</c> field. </item> <tag><c>NodeName</c></tag> <item> - The NodeName as a string of length <c>Nlen</c>. + The NodeName as an UTF-8 encoded string of + <c>Nlen</c> bytes. </item> <tag><c>Elen</c></tag> <item> @@ -322,7 +323,7 @@ If Result > 0, the packet only consists of [119, Result]. NodeInfo is, as expressed in Erlang: </p> <code> - io:format("name ~s at port ~p~n", [NodeName, Port]). + io:format("name ~ts at port ~p~n", [NodeName, Port]). </code> </section> @@ -362,14 +363,14 @@ If Result > 0, the packet only consists of [119, Result]. NodeInfo is, as expressed in Erlang: </p> <code> - io:format("active name ~s at port ~p, fd = ~p ~n", + io:format("active name ~ts at port ~p, fd = ~p ~n", [NodeName, Port, Fd]). </code> <p> or </p> <code> - io:format("old/unused name ~s at port ~p, fd = ~p~n", + io:format("old/unused name ~ts at port ~p, fd = ~p~n", [NodeName, Port, Fd]). </code> @@ -547,13 +548,289 @@ If Result > 0, the packet only consists of [119, Result]. --> </section> - + <marker id="distribution_handshake"/> <section> - <title>Handshake</title> - <p> - The handshake is discussed in detail in the internal documentation for - the kernel (Erlang) application. - </p> + <title>Distribution Handshake</title> + <p> + This section describes the distribution handshake protocol + introduced in the OTP-R6 release of Erlang/OTP. This + description was previously located in + <c>$ERL_TOP/lib/kernel/internal_doc/distribution_handshake.txt</c>, + and has more or less been copied and "formatted" here. It has been + more or less unchanged since the year 1999, but the handshake + should not have changed much since then either. + </p> + <section> + <title>General</title> + <p> + The TCP/IP distribution uses a handshake which expects a + connection based protocol, i.e. the protocol does not include + any authentication after the handshake procedure. + </p> + <p> + This is not entirely safe, as it is vulnerable against takeover + attacks, but it is a tradeoff between fair safety and performance. + </p> + <p> + The cookies are never sent in cleartext and the handshake procedure + expects the client (called A) to be the first one to prove that it can + generate a sufficient digest. The digest is generated with the + MD5 message digest algorithm and the challenges are expected to be very + random numbers. + </p> + </section> + <section> + <title>Definitions</title> + <p> + A challenge is a 32 bit integer number in big endian order. Below the function + <c>gen_challenge()</c> returns a random 32 bit integer used as a challenge. + </p> + <p> + A digest is a (16 bytes) MD5 hash of the Challenge (as text) concatenated + with the cookie (as text). Below, the function <c>gen_digest(Challenge, Cookie)</c> + generates a digest as described above. + </p> + <p> + An out_cookie is the cookie used in outgoing communication to a certain node, + so that A's out_cookie for B should correspond with B's in_cookie for A and + the other way around. A's out_cookie for B and A's in_cookie for B need <em>NOT</em> + be the same. Below the function <c>out_cookie(Node)</c> returns the current + node's out_cookie for <c>Node</c>. + </p> + <p> + An in_cookie is the cookie expected to be used by another node when + communicating with us, so that A's in_cookie for B corresponds with B's + out_cookie for A. Below the function <c>in_cookie(Node)</c> returns the current + node's <c>in_cookie</c> for <c>Node</c>. + </p> + <p> + The cookies are text strings that can be viewed as passwords. + </p> + <p> + Every message in the handshake starts with a 16 bit big endian integer + which contains the length of the message (not counting the two initial bytes). + In erlang this corresponds to the <c>gen_tcp</c> option <c>{packet, 2}</c>. Note that after + the handshake, the distribution switches to 4 byte packet headers. + </p> + + </section> + <section> + <title>The Handshake in Detail</title> + <p> + Imagine two nodes, node A, which initiates the handshake and node B, which + accepts the connection. + </p> + <taglist> + <tag>1) connect/accept</tag> + <item><p>A connects to B via TCP/IP and B accepts the connection.</p></item> + <tag>2) send_name/receive_name</tag> + <item><p>A sends an initial identification to B. B receives the message. + The message looks like this (every "square" being one byte and the packet + header removed): + </p> +<pre> ++---+--------+--------+-----+-----+-----+-----+-----+-----+-...-+-----+ +|'n'|Version0|Version1|Flag0|Flag1|Flag2|Flag3|Name0|Name1| ... |NameN| ++---+--------+--------+-----+-----+-----+-----+-----+-----+-... +-----+ +</pre> + <p> + The 'n' is just a message tag. + Version0 and Version1 is the distribution version selected by node A, + based on information from EPMD. (16 bit big endian) + Flag0 ... Flag3 are capability flags, the capabilities defined in + <c>$ERL_TOP/lib/kernel/include/dist.hrl</c>. + (32 bit big endian) + Name0 ... NameN is the full nodename of A, as a string of bytes (the + packet length denotes how long it is). + </p></item> + <tag>3) recv_status/send_status</tag> + <item><p>B sends a status message to A, which indicates + if the connection is allowed. The following status codes are defined:</p> + <taglist> + <tag><c>ok</c></tag> + <item>The handshake will continue.</item> + <tag><c>ok_simultaneous</c></tag> + <item>The handshake will continue, but A is informed that B + has another ongoing connection attempt that will be + shut down (simultaneous connect where A's name is + greater than B's name, compared literally).</item> + <tag><c>nok</c></tag> + <item>The handshake will not continue, as B already has an ongoing handshake + which it itself has initiated. (simultaneous connect where B's name is + greater than A's).</item> + <tag><c>not_allowed</c></tag> + <item>The connection is disallowed for some (unspecified) security + reason.</item> + <tag><c>alive</c></tag> + <item>A connection to the node is already active, which either means + that node A is confused or that the TCP connection breakdown + of a previous node with this name has not yet reached node B. + See 3B below.</item> + </taglist> + <p>This is the format of the status message:</p> +<pre> ++---+-------+-------+-...-+-------+ +|'s'|Status0|Status1| ... |StatusN| ++---+-------+-------+-...-+-------+ +</pre> + <p> + 's' is the message tag Status0 ... StatusN is the status as a string (not terminated) + </p> + </item> + <tag>3B) send_status/recv_status</tag> + <item><p>If status was 'alive', node A will answer with + another status message containing either 'true' which means that the + connection should continue (The old connection from this node is broken), or + <c>'false'</c>, which simply means that the connection should be closed, the + connection attempt was a mistake.</p></item> + <tag>4) recv_challenge/send_challenge</tag> + <item><p>If the status was <c>ok</c> or <c>ok_simultaneous</c>, + The handshake continues with B sending A another message, the challenge. + The challenge contains the same type of information as the "name" message + initially sent from A to B, with the addition of a 32 bit challenge:</p> +<pre> ++---+--------+--------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-...-+-----+ +|'n'|Version0|Version1|Flag0|Flag1|Flag2|Flag3|Chal0|Chal1|Chal2|Chal3|Name0|Name1| ... |NameN| ++---+--------+--------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-... +-----+ +</pre> + <p> + Where Chal0 ... Chal3 is the challenge as a 32 bit big endian integer + and the other fields are B's version, flags and full nodename. + </p></item> + <tag>5) send_challenge_reply/recv_challenge_reply</tag> + <item><p>Now A has generated a digest and its own challenge. Those are + sent together in a package to B:</p> +<pre> ++---+-----+-----+-----+-----+-----+-----+-----+-----+-...-+------+ +|'r'|Chal0|Chal1|Chal2|Chal3|Dige0|Dige1|Dige2|Dige3| ... |Dige15| ++---+-----+-----+-----+-----+-----+-----+-----+-----+-...-+------+ +</pre> + <p> + Where 'r' is the tag, Chal0 ... Chal3 is A's challenge for B to handle and + Dige0 ... Dige15 is the digest that A constructed from the challenge B sent + in the previous step. + </p></item> + <tag>6) recv_challenge_ack/send_challenge_ack</tag> + <item><p>B checks that the digest received from A is correct and generates a + digest from the challenge received from A. The digest is then sent to A. The + message looks like this:</p> +<pre> ++---+-----+-----+-----+-----+-...-+------+ +|'a'|Dige0|Dige1|Dige2|Dige3| ... |Dige15| ++---+-----+-----+-----+-----+-...-+------+ +</pre> + <p> + Where 'a' is the tag and Dige0 ... Dige15 is the digest calculated by B + for A's challenge.</p></item> + <tag>7)</tag> + <item><p>A checks the digest from B and the connection is up.</p></item> + </taglist> + </section> + <section> + <title>Semigraphic View</title> +<pre> +A (initiator) B (acceptor) + +TCP connect -----------------------------------------> + TCP accept + +send_name -----------------------------------------> + recv_name + + <---------------------------------------- send_status +recv_status +(if status was 'alive' + send_status - - - - - - - - - - - - - - - - - - - -> + recv_status) + ChB = gen_challenge() + (ChB) + <---------------------------------------- send_challenge +recv_challenge + +ChA = gen_challenge(), +OCA = out_cookie(B), +DiA = gen_digest(ChB,OCA) + (ChA, DiA) +send_challenge_reply --------------------------------> + recv_challenge_reply + ICB = in_cookie(A), + check: + DiA == gen_digest + (ChB, ICB) ? + - if OK: + OCB = out_cookie(A), + DiB = gen_digest + (DiB) (ChA, OCB) + <----------------------------------------- send_challenge_ack +recv_challenge_ack DONE +ICA = in_cookie(B), - else +check: CLOSE +DiB == gen_digest(ChA,ICA) ? +- if OK + DONE +- else + CLOSE +</pre> + </section> + <marker id="dflags"/> + <section> + <title>The Currently Defined Distribution Flags</title> + <p> + Currently (OTP-R16) the following capability flags are defined: + </p> +<pre> +%% The node should be published and part of the global namespace +-define(DFLAG_PUBLISHED,1). + +%% The node implements an atom cache (obsolete) +-define(DFLAG_ATOM_CACHE,2). + +%% The node implements extended (3 * 32 bits) references. This is +%% required today. If not present connection will be refused. +-define(DFLAG_EXTENDED_REFERENCES,4). + +%% The node implements distributed process monitoring. +-define(DFLAG_DIST_MONITOR,8). + +%% The node uses separate tag for fun's (lambdas) in the distribution protocol. +-define(DFLAG_FUN_TAGS,16#10). + +%% The node implements distributed named process monitoring. +-define(DFLAG_DIST_MONITOR_NAME,16#20). + +%% The (hidden) node implements atom cache (obsolete) +-define(DFLAG_HIDDEN_ATOM_CACHE,16#40). + +%% The node understand new fun-tags +-define(DFLAG_NEW_FUN_TAGS,16#80). + +%% The node is capable of handling extended pids and ports. This is +%% required today. If not present connection will be refused. +-define(DFLAG_EXTENDED_PIDS_PORTS,16#100). + +%% +-define(DFLAG_EXPORT_PTR_TAG,16#200). + +%% +-define(DFLAG_BIT_BINARIES,16#400). + +%% The node understands new float format +-define(DFLAG_NEW_FLOATS,16#800). + +%% +-define(DFLAG_UNICODE_IO,16#1000). + +%% The node implements atom cache in distribution header. +-define(DFLAG_DIST_HDR_ATOM_CACHE,16#2000). + +%% The node understand the SMALL_ATOM_EXT tag +-define(DFLAG_SMALL_ATOM_TAGS, 16#4000). + +%% The node understand UTF-8 encoded atoms +-define(DFLAG_UTF8_ATOMS, 16#10000). + +</pre> + </section> </section> <section> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index e16fd744c0..efe0483b31 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2012</year> + <year>2001</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -145,12 +145,20 @@ different threads. This, however, is not a problem for any function in this API, since the emulator has control over these threads.</p> - <note> - <p>Functions not explicitly documented as thread-safe are - <em>not</em> thread-safe. Also note that some functions + <warning> + <p>Functions not explicitly documented as thread safe are + <em>not</em> thread safe. Also note that some functions are <em>only</em> thread safe when used in a runtime system with SMP support.</p> - </note> + <p>A function not explicitly documented as thread safe may at + some point in time have a thread safe implementation in the + runtime system. Such an implementation may however change to + a thread <em>unsafe</em> implementation at any time <em>without + any notice</em> at all. + </p> + <p><em>Only use functions explicitly documented as thread safe + from arbitrary threads.</em></p> + </warning> <p><marker id="lengthy_work"/> As mentioned in the <seealso marker="#WARNING">warning</seealso> text at the beginning of this document it is of vital importance that a driver callback @@ -162,10 +170,13 @@ callback, the best approach is to divide the work into multiple chunks of work and trigger multiple calls to the <seealso marker="driver_entry#timeout">timeout callback</seealso> using - zero timeouts. This might, however, not always be possible, e.g. when - calling third party libraries. In this case you typically want to dispatch - the work to another thread. Information about thread primitives can be - found below.</p> + zero timeouts. The + <seealso marker="#erl_drv_consume_timeslice"><c>erl_drv_consume_timeslice()</c></seealso> + function can be useful in order to determine when to trigger such + timeout callback calls. It might, however, not always be possible to + implement it this way, e.g. when calling third party libraries. In this + case you typically want to dispatch the work to another thread. + Information about thread primitives can be found below.</p> </description> <section> @@ -309,9 +320,9 @@ minor version used by the driver is greater than the one used by the runtime system.</p> <p>The emulator will refuse to load a driver that does not use - the extended driver interface since, + the extended driver interface, to allow for 64-bit capable drivers, - incompatible type changes for the callbacks + since incompatible type changes for the callbacks <seealso marker="driver_entry#output">output</seealso>, <seealso marker="driver_entry#control">control</seealso> and <seealso marker="driver_entry#call">call</seealso> @@ -1529,16 +1540,81 @@ typedef struct ErlIOVec { </desc> </func> <func> + <name><ret>void</ret><nametext>erl_drv_busy_msgq_limits(ErlDrvPort port, ErlDrvSizeT *low, ErlDrvSizeT *high)</nametext></name> + <fsummary>Set and get limits for busy port message queue</fsummary> + <desc> + <marker id="erl_drv_busy_msgq_limits"></marker> + <p>Sets and gets limits that will be used for controling the + busy state of the port message queue.</p> + <p>The port message queue will be set into a busy + state when the amount of command data queued on the + message queue reaches the <c>high</c> limit. The port + message queue will be set into a not busy state when the + amount of command data queued on the message queue falls + below the <c>low</c> limit. Command data is in this + context data passed to the port using either + <c>Port ! {Owner, {command, Data}}</c>, or + <c>port_command/[2,3]</c>. Note that these limits + only concerns command data that have not yet reached the + port. The <seealso marker="#set_busy_port">busy port</seealso> + feature can be used for data that has reached the port.</p> + + <p>Valid limits are values in the range + <c>[ERL_DRV_BUSY_MSGQ_LIM_MIN, ERL_DRV_BUSY_MSGQ_LIM_MAX]</c>. + Limits will be automatically adjusted to be sane. That is, + the system will adjust values so that the low limit used is + lower than or equal to the high limit used. By default the high + limit will be 8 kB and the low limit will be 4 kB.</p> + + <p>By passing a pointer to an integer variable containing + the value <c>ERL_DRV_BUSY_MSGQ_READ_ONLY</c>, currently used + limit will be read and written back to the integer variable. + A new limit can be set by passing a pointer to an integer + variable containing a valid limit. The passed value will be + written to the internal limit. The internal limit will then + be adjusted. After this the adjusted limit will be written + back to the integer variable from which the new value was + read. Values are in bytes.</p> + + <p>The busy message queue feature can be disabled either + by setting the <c>ERL_DRV_FLAG_NO_BUSY_MSGQ</c> + <seealso marker="driver_entry#driver_flags">driver flag</seealso> + in the <seealso marker="driver_entry">driver_entry</seealso> + used by the driver, or by calling this function with + <c>ERL_DRV_BUSY_MSGQ_DISABLED</c> as a limit (either low or + high). When this feature has been disabled it cannot be + enabled again. When reading the limits both of them + will be <c>ERL_DRV_BUSY_MSGQ_DISABLED</c>, if this + feature has been disabled.</p> + + <p>Processes sending command data to the port will be suspended + if either the port is busy or if the port message queue is + busy. Suspended processes will be resumed when neither the + port is busy, nor the port message queue is busy.</p> + + <p>For information about busy port functionality + see the documentation of the + <seealso marker="#set_busy_port">set_busy_port()</seealso> + function.</p> + </desc> + </func> + <func> <name><ret>void</ret><nametext>set_busy_port(ErlDrvPort port, int on)</nametext></name> <fsummary>Signal or unsignal port as busy</fsummary> <desc> <marker id="set_busy_port"></marker> - <p>This function set and resets the busy status of the port. If - <c>on</c> is 1, the port is set to busy, if it's 0 the port - is set to not busy.</p> - <p>When the port is busy, sending to it with <c>Port ! Data</c> - or <c>port_command/2</c>, will block the port owner process, - until the port is signaled as not busy.</p> + <p>This function set and unset the busy state of the port. If + <c>on</c> is non-zero, the port is set to busy, if it's zero the port + is set to not busy. You typically want to combine + this feature with the <seealso marker="#erl_drv_busy_msgq_limits">busy + port message queue</seealso> functionality.</p> + <p>Processes sending command data to the port will be suspended + if either the port is busy or if the port message queue + is busy. Suspended processes will be resumed when neither the + port is busy, nor the port message queue is busy. Command data + is in this context data passed to the port using either + <c>Port ! {Owner, {command, Data}}</c>, or + <c>port_command/[2,3]</c>.</p> <p>If the <seealso marker="driver_entry#driver_flags"><![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]></seealso> has been set in the @@ -1547,6 +1623,10 @@ typedef struct ErlIOVec { <seealso marker="erlang#port_command/3">port_command(Port, Data, [force])</seealso> even though the driver has signaled that it is busy. </p> + <p>For information about busy port message queue functionality + see the documentation of the + <seealso marker="#erl_drv_busy_msgq_limits">erl_drv_busy_msgq_limits()</seealso> + function.</p> </desc> </func> <func> @@ -1607,6 +1687,8 @@ typedef struct ErlIOVec { <desc> <marker id="driver_connected"></marker> <p>This function returns the port owner process.</p> + <p>Note that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> </desc> </func> <func> @@ -1634,22 +1716,32 @@ typedef struct ErlIOVec { <tag><seealso marker="driver_entry#call">call</seealso></tag> <item>Called from <c>erlang:port_call/3</c></item> </taglist> + <p>Note that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>driver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n)</nametext></name> + <name><ret>int</ret><nametext>erl_drv_output_term(ErlDrvTermData port, ErlDrvTermData* term, int n)</nametext></name> <fsummary>Send term data from driver to port owner</fsummary> <desc> - <marker id="driver_output_term"></marker> + <marker id="erl_drv_output_term"></marker> <p>This functions sends data in the special driver term - format. This is a fast way to deliver term data from a - driver. It also needs no binary conversion, so the port - owner process receives data as normal Erlang terms.</p> + format to the port owner process. This is a fast way to + deliver term data from a driver. It also needs no binary + conversion, so the port owner process receives data as + normal Erlang terms. The + <seealso marker="#erl_drv_send_term">erl_drv_send_term()</seealso> + functions can be used for sending to any arbitrary process + on the local node.</p> + <note><p>Note that the <c>port</c> parameter is <em>not</em> + an ordinary port handle, but a port handle converted using + <c>driver_mk_port()</c>.</p></note> <p>The <c>term</c> parameter points to an array of <c>ErlDrvTermData</c>, with <c>n</c> elements. This array contains terms described in the driver term format. Every term consists of one to four elements in the array. The - term first has a term type, and then arguments.</p> + term first has a term type, and then arguments. The + <c>port</c> parameter specifies the sending port.</p> <p>Tuple and lists (with the exception of strings, see below), are built in reverse polish notation, so that to build a tuple, the elements are given first, and then the tuple @@ -1701,17 +1793,17 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len ErlDrvPort port = ... ErlDrvTermData spec[] = { ERL_DRV_ATOM, driver_mk_atom("tcp"), - ERL_DRV_PORT, driver_mk_port(port), + ERL_DRV_PORT, driver_mk_port(drvport), ERL_DRV_INT, 100, ERL_DRV_BINARY, bin, 50, 0, ERL_DRV_LIST, 2, ERL_DRV_TUPLE, 3, }; - driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]> </code> <p>Where <c>bin</c> is a driver binary of length at least 50 - and <c>port</c> is a port handle. Note that the <c>ERL_DRV_LIST</c> + and <c>drvport</c> is a port handle. Note that the <c>ERL_DRV_LIST</c> comes after the elements of the list, likewise the <c>ERL_DRV_TUPLE</c>.</p> <p>The term <c>ERL_DRV_STRING_CONS</c> is a way to construct @@ -1732,7 +1824,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len ERL_DRV_NIL, ERL_DRV_LIST, 4 }; - driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> <p></p> <code type="none"><![CDATA[ @@ -1742,7 +1834,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len ERL_DRV_STRING_CONS, (ErlDrvTermData)"123", 3, ERL_DRV_STRING_CONS, (ErlDrvTermData)"abc", 3, }; - driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> <p>The <c>ERL_DRV_EXT2TERM</c> term type is used for passing a term encoded with the @@ -1762,7 +1854,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len ERL_DRV_EXT2TERM, (ErlDrvTermData) binp->orig_bytes, binp->orig_size ERL_DRV_TUPLE, 2, }; - driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> <p>If you want to pass a binary and don't already have the content of the binary in an <c>ErlDrvBinary</c>, you can benefit from using @@ -1778,6 +1870,22 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <c>ERL_DRV_EXT2TERM</c> term types were introduced in the 5.6 version of erts. </p> + <p>This function is only thread-safe when the emulator with SMP + support is used.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>driver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n)</nametext></name> + <fsummary>Send term data from driver to port owner</fsummary> + <desc> + <marker id="driver_output_term"></marker> + <warning><p><c>driver_output_term()</c> is deferred and will + be removed in the OTP-R17 release. Use + <seealso marker="#erl_drv_send_term">erl_drv_output_term()</seealso> + instead.</p> + </warning> + <p>The parameters <c>term</c> and <c>n</c> do the same thing + as in <seealso marker="#erl_drv_output_term">erl_drv_output_term()</seealso>.</p> <p>Note that this function is <em>not</em> thread-safe, not even when the emulator with SMP support is used.</p> </desc> @@ -1791,6 +1899,8 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <c>string</c>. The atom is created and won't change, so the return value may be saved and reused, which is faster than looking up the atom several times.</p> + <p>Note that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> </desc> </func> <func> @@ -1799,20 +1909,46 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <desc> <marker id="driver_mk_port"></marker> <p>This function converts a port handle to the erlang term - format, usable in the <c>driver_output_send</c> function.</p> + format, usable in the <seealso marker="#erl_drv_output_term">erl_drv_output_term()</seealso>, and <seealso marker="#erl_drv_send_term">erl_drv_send_term()</seealso> functions.</p> + <p>Note that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>driver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> + <name><ret>int</ret><nametext>erl_drv_send_term(ErlDrvTermData port, ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> <fsummary>Send term data to other process than port owner process</fsummary> <desc> - <marker id="driver_send_term"></marker> + <marker id="erl_drv_send_term"></marker> <p>This function is the only way for a driver to send data to <em>other</em> processes than the port owner process. The <c>receiver</c> parameter specifies the process to receive the data.</p> + <note><p>Note that the <c>port</c> parameter is <em>not</em> + an ordinary port handle, but a port handle converted using + <c>driver_mk_port()</c>.</p></note> + <p>The parameters <c>port</c>, <c>term</c> and <c>n</c> do the same thing + as in <seealso marker="#erl_drv_output_term">erl_drv_output_term()</seealso>.</p> + <p>This function is only thread-safe when the emulator with SMP + support is used.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>driver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> + <fsummary>Send term data to other process than port owner process</fsummary> + <desc> + <marker id="driver_send_term"></marker> + <warning><p><c>driver_send_term()</c> is deferred and will + be removed in the OTP-R17 release. Use + <seealso marker="#erl_drv_send_term">erl_drv_send_term()</seealso> + instead.</p> + <p>Also note that parameters of <c>driver_send_term()</c> + cannot be properly checked by the runtime system when + executed by arbitrary threads. This may cause the + <c>driver_send_term()</c> function not to fail when + it should.</p> + </warning> <p>The parameters <c>term</c> and <c>n</c> do the same thing - as in <seealso marker="#driver_output_term">driver_output_term</seealso>.</p> + as in <seealso marker="#erl_drv_output_term">erl_drv_output_term()</seealso>.</p> <p>This function is only thread-safe when the emulator with SMP support is used.</p> </desc> @@ -1827,9 +1963,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len emulator thread. This enables the driver to perform time-consuming, blocking operations without blocking the emulator.</p> - <p>Erlang is by default started without an async thread pool. The - number of async threads that the runtime system should use - is specified by the + <p>The async thread pool size can be set with the <seealso marker="erl#async_thread_pool_size">+A</seealso> command line argument of <seealso marker="erl">erl(1)</seealso>. If no async thread pool is available, the call is made @@ -2674,7 +2808,6 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <p>This function is thread-safe.</p> </desc> </func> - <func> <name><ret>int</ret><nametext>erl_drv_getenv(char *key, char *value, size_t *value_size)</nametext></name> <fsummary>Get the value of an environment variable</fsummary> @@ -2710,6 +2843,52 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <p>This function is thread-safe.</p> </desc> </func> + <func> + <name><ret>int</ret><nametext>erl_drv_consume_timeslice(ErlDrvPort port, int percent)</nametext></name> + <fsummary>Give the runtime system a hint about how much CPU time the + current driver callback call has consumed</fsummary> + <desc> + <marker id="erl_drv_consume_timeslice"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>port</c></tag> + <item>Port handle of the executing port.</item> + <tag><c>percent</c></tag> + <item>Approximate consumed fraction of a full + time-slice in percent.</item> + </taglist> + <p>Give the runtime system a hint about how much CPU time the + current driver callback call has consumed since last hint, or + since the start of the callback if no previous hint has been given. + The time is given as a fraction, in percent, of a full time-slice + that a port is allowed to execute before it should surrender the + CPU to other runnable ports or processes. Valid range is + <c>[1, 100]</c>. The scheduling time-slice is not an exact entity, + but can usually be approximated to about 1 millisecond.</p> + + <p>Note that it is up to the runtime system to determine if and + how to use this information. Implementations on some platforms + may use other means in order to determine the consumed fraction + of the time-slice. Lengthy driver callbacks should regardless of + this frequently call the <c>erl_drv_consume_timeslice()</c> + function in order to determine if it is allowed to continue + execution or not.</p> + + <p><c>erl_drv_consume_timeslice()</c> returns a non-zero value + if the time-slice has been exhausted, and zero if the callback is + allowed to continue execution. If a non-zero value is + returned the driver callback should return as soon as possible in + order for the port to be able to yield.</p> + + <p>This function is provided to better support co-operative scheduling, + improve system responsiveness, and to make it easier to prevent + misbehaviors of the VM due to a port monopolizing a scheduler thread. + It can be used when dividing length work into a number of repeated + driver callback calls without the need to use threads. Also see the + important <seealso marker="#WARNING">warning</seealso> text at the + beginning of this document.</p> + </desc> + </func> </funcs> <section> diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index fd2da2cfe3..c6849f3326 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2007</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -119,10 +119,39 @@ <cell align="center">Data</cell> </row> <tcaption></tcaption></table> + <marker id="utf8_atoms"/> + <note> + <p>As of ERTS version 5.10 (OTP-R16) support + for UTF-8 encoded atoms has been introduced in the external format. + However, only characters that can be encoded using Latin1 (ISO-8859-1) + are currently supported in atoms. The support for UTF-8 encoded atoms + in the external format has been implemented in order to be able to support + all Unicode characters in atoms in <em>some future release</em>. Full + support for Unicode atoms will not happen before OTP-R18, and might + be introduced even later than that. Until full Unicode support for + atoms has been introduced, it is an <em>error</em> to pass atoms containing + characters that cannot be encoded in Latin1, and <em>the behavior is + undefined</em>.</p> + <p>When the + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_UTF8_ATOMS</c></seealso> + distribution flag has been exchanged between both nodes in the + <seealso marker="erl_dist_protocol#distribution_handshake">distribution handshake</seealso>, + all atoms in the distribution header will be encoded in UTF-8; otherwise, + all atoms in the distribution header will be encoded in Latin1. The two + new tags <seealso marker="#ATOM_UTF8_EXT">ATOM_UTF8_EXT</seealso>, and + <seealso marker="#SMALL_ATOM_UTF8_EXT">SMALL_ATOM_UTF8_EXT</seealso> + will only be used if the <c>DFLAG_UTF8_ATOMS</c> distribution flag has + been exchanged between nodes, or if an atom containing characters + that cannot be encoded in Latin1 is encountered. + </p> + <p>The maximum number of allowed characters in an atom is 255. In the + UTF-8 case each character may need 4 bytes to be encoded. + </p> + </note> </section> - <section> - <marker id="distribution_header"/> + <marker id="distribution_header"/> + <section> <title>Distribution header</title> <p> As of erts version 5.7.2 the old atom cache protocol was @@ -219,8 +248,7 @@ <p> The least significant bit in that half byte is the <c>LongAtoms</c> flag. If it is set, 2 bytes are used for atom lengths instead of - 1 byte in the distribution header. However, the current emulator - cannot handle long atoms, so it will currently always be 0. + 1 byte in the distribution header. </p> <p> After the <c>Flags</c> field follow the <c>AtomCacheRefs</c>. The @@ -247,16 +275,26 @@ <p> <c>InternalSegmentIndex</c> together with the <c>SegmentIndex</c> completely identify the location of an atom cache entry in the - atom cache. <c>Length</c> is number of one byte characters that - the atom text consists of. Length is a two byte big endian integer + atom cache. <c>Length</c> is number of bytes that <c>AtomText</c> + consists of. Length is a two byte big endian integer if the <c>LongAtoms</c> flag has been set, otherwise a one byte - integer. Subsequent <c>CachedAtomRef</c>s with the same + integer. When the + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_UTF8_ATOMS</c></seealso> + distribution flag has been exchanged between both nodes in the + <seealso marker="erl_dist_protocol#distribution_handshake">distribution handshake</seealso>, + characters in <c>AtomText</c> is encoded in UTF-8; otherwise, + encoded in Latin1. Subsequent <c>CachedAtomRef</c>s with the same <c>SegmentIndex</c> and <c>InternalSegmentIndex</c> as this <c>NewAtomCacheRef</c> will refer to this atom until a new <c>NewAtomCacheRef</c> with the same <c>SegmentIndex</c> and <c>InternalSegmentIndex</c> appear. </p> <p> + For more information on encoding of atoms, see + <seealso marker="#utf8_atoms">note on UTF-8 encoded atoms</seealso> + in the beginning of this document. + </p> + <p> If the <c>NewCacheEntryFlag</c> for the next <c>AtomCacheRef</c> has not been set, a <c>CachedAtomRef</c> on the following format will follow: @@ -383,9 +421,9 @@ <tcaption></tcaption></table> <p> An atom is stored with a 2 byte unsigned length in big-endian order, - followed by <c>Len</c> numbers of 8 bit characters that forms the - <c>AtomName</c>. - Note: The maximum allowed value for <c>Len</c> is 255. + followed by <c>Len</c> numbers of 8 bit Latin1 characters that forms + the <c>AtomName</c>. + <em>Note</em>: The maximum allowed value for <c>Len</c> is 255. </p> </section> @@ -754,12 +792,14 @@ <tcaption></tcaption></table> <p> An atom is stored with a 1 byte unsigned length, - followed by <c>Len</c> numbers of 8 bit characters that + followed by <c>Len</c> numbers of 8 bit Latin1 characters that forms the <c>AtomName</c>. Longer atoms can be represented by <seealso marker="#ATOM_EXT">ATOM_EXT</seealso>. <em>Note</em> the <c>SMALL_ATOM_EXT</c> was introduced in erts version 5.7.2 and - require a small atom distribution flag exchanged in the distribution - handshake. + require an exchange of the + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_SMALL_ATOM_TAGS</c></seealso> + distribution flag in the + <seealso marker="erl_dist_protocol#distribution_handshake">distribution handshake</seealso>. </p> </section> @@ -1007,7 +1047,62 @@ This term is used in minor version 1 of the external format. </p> </section> + <section> + <marker id="ATOM_UTF8_EXT"/> + <title>ATOM_UTF8_EXT</title> + + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">2</cell> + <cell align="center">Len</cell> + </row> + <row> + <cell align="center"><c>118</c></cell> + <cell align="center"><c>Len</c></cell> + <cell align="center"><c>AtomName</c></cell> + </row> + <tcaption></tcaption></table> + <p> + An atom is stored with a 2 byte unsigned length in big-endian order, + followed by <c>Len</c> bytes containing the <c>AtomName</c> encoded + in UTF-8. + </p> + <p> + For more information on encoding of atoms, see + <seealso marker="#utf8_atoms">note on UTF-8 encoded atoms</seealso> + in the beginning of this document. + </p> + </section> + <section> + <marker id="SMALL_ATOM_UTF8_EXT"/> + <title>SMALL_ATOM_UTF8_EXT</title> + + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">1</cell> + <cell align="center">Len</cell> + </row> + <row> + <cell align="center"><c>119</c></cell> + <cell align="center"><c>Len</c></cell> + <cell align="center"><c>AtomName</c></cell> + </row> + <tcaption></tcaption></table> + <p> + An atom is stored with a 1 byte unsigned length, + followed by <c>Len</c> bytes containing the <c>AtomName</c> encoded + in UTF-8. Longer atoms encoded in UTF-8 can be represented using + <seealso marker="#ATOM_UTF8_EXT">ATOM_UTF8_EXT</seealso>. + </p> + <p> + For more information on encoding of atoms, see + <seealso marker="#utf8_atoms">note on UTF-8 encoded atoms</seealso> + in the beginning of this document. + </p> + </section> </chapter> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index f00f7b9f46..864b91946a 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2012</year> + <year>2001</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -174,9 +174,11 @@ ok millisecond has passed. This can be achieved using different approaches. If you have full control over the code that are to execute in the native function, the best approach is to divide the work into multiple chunks of - work and call the native function multiple times. This might, however, - not always be possible, e.g. when calling third party libraries. In this - case you typically want to dispatch the work to another thread, return + work and call the native function multiple times. Function + <seealso marker="#enif_consume_timeslice">enif_consume_timeslice</seealso> can be + used this facilitate such work division. In some cases, however, this might not + be possible, e.g. when calling third party libraries. Then you typically want + to dispatch the work to another thread, return from the native function, and wait for the result. The thread can send the result back to the calling thread using message passing. Information about thread primitives can be found below.</p> @@ -227,8 +229,8 @@ ok bit length have no support yet.</p> </item> <tag>Resource objects</tag> - <item><p>The use of resource objects is a way to return pointers to - native data structures from a NIF in a safe way. A resource object is + <item><p>The use of resource objects is a safe way to return pointers to + native data structures from a NIF. A resource object is just a block of memory allocated with <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of @@ -581,6 +583,31 @@ typedef enum { <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_wait">erl_drv_cond_wait</seealso>. </p></desc> </func> + <func><name><ret>int</ret><nametext>enif_consume_timeslice(ErlNifEnv *env, int percent)</nametext></name> + <fsummary></fsummary> + <desc><p>Give the runtime system a hint about how much CPU time the current NIF call has consumed + since last hint, or since the start of the NIF if no previous hint has been given. + The time is given as a <c>percent</c> of the timeslice that a process is allowed to execute Erlang + code until it may be suspended to give time for other runnable processes. + The scheduling timeslice is not an exact entity, but can usually be + approximated to about 1 millisecond.</p> + <p>Note that it is up to the runtime system to determine if and how to use this information. + Implementations on some platforms may use other means in order to determine consumed + CPU time. Lengthy NIFs should regardless of this frequently call <c>enif_consume_timeslice</c> + in order to determine if it is allowed to continue execution or not.</p> + + <p>Returns 1 if the timeslice is exhausted, or 0 otherwise. If 1 is returned the NIF should return + as soon as possible in order for the process to yield.</p> + <p>Argument <c>percent</c> must be an integer between 1 and 100. This function + must only be called from a NIF-calling thread and argument <c>env</c> must be + the environment of the calling process.</p> + <p>This function is provided to better support co-operative scheduling, improve system responsiveness, + and make it easier to prevent misbehaviors of the VM due to a NIF monopolizing a scheduler thread. + It can be used to divide <seealso marker="#lengthy_work">length work</seealso> into + a number of repeated NIF-calls without the need to create threads. + See also the <seealso marker="#WARNING">warning</seealso> text at the beginning of this document.</p> + </desc> + </func> <func><name><ret>int</ret><nametext>enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)</nametext></name> <fsummary></fsummary> <desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids</seealso>. diff --git a/erts/doc/src/erl_set_memory_block.xml b/erts/doc/src/erl_set_memory_block.xml deleted file mode 100644 index d77da56d95..0000000000 --- a/erts/doc/src/erl_set_memory_block.xml +++ /dev/null @@ -1,172 +0,0 @@ -<?xml version="1.0" encoding="latin1" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1998</year><year>2009</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/. - - 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. - - </legalnotice> - - <title>erl_set_memory_block</title> - <prepared>Patrik Nyblom</prepared> - <responsible></responsible> - <docno></docno> - <approved></approved> - <checked></checked> - <date>98-08-05</date> - <rev>A</rev> - <file>erl_set_memory_block.xml</file> - </header> - <lib>erl_set_memory_block</lib> - <libsummary>Custom memory allocation for Erlang on VxWorks®</libsummary> - <description> - <p>This documentation is specific to VxWorks.</p> - <p>The <c><![CDATA[erl_set_memory_block]]></c> function/command initiates custom - memory allocation for the Erlang emulator. It has to be called - before the Erlang emulator is started and makes Erlang use one - single large memory block for all memory allocation.</p> - <p>The memory within the block can be utilized by other tasks than - Erlang. This is accomplished by calling the functions - <c><![CDATA[sys_alloc]]></c>, <c><![CDATA[sys_realloc]]></c> and <c><![CDATA[sys_free]]></c> instead - of <c><![CDATA[malloc]]></c>, <c><![CDATA[realloc]]></c> and <c><![CDATA[free]]></c> respectively.</p> - <p>The purpose of this is to avoid problems inherent in the - VxWorks systems <c><![CDATA[malloc]]></c> library. The memory allocation within the - large memory block avoids fragmentation by using an "address - order first fit" algorithm. Another advantage of using a - separate memory block is that resource reclamation can be made - more easily when Erlang is stopped.</p> - <p>The <c><![CDATA[erl_set_memory_block]]></c> function is callable from any C - program as an ordinary 10 argument function as well as - from the commandline.</p> - </description> - <funcs> - <func> - <name><ret>int</ret><nametext>erl_set_memory_block(size_t size, void *ptr, int warn_mixed_malloc, int realloc_always_moves, int use_reclaim, ...)</nametext></name> - <fsummary>Specify parameters for Erlang internal memory allocation.</fsummary> - <desc> - <p>The function is called before Erlang is - started to specify a large memory block where Erlang can - maintain memory internally.</p> - <p>Parameters:</p> - <taglist> - <tag>size_t size</tag> - <item>The size in bytes of Erlang's internal memory block. Has to - be specified. Note that the VxWorks system uses dynamic - memory allocation heavily, so leave some memory to the system.</item> - <tag>void *ptr</tag> - <item> - <p>A pointer to the actual memory block of size - <c><![CDATA[size]]></c>. If this is specified as 0 (NULL), Erlang will - allocate the memory when starting and will reclaim the - memory block (as a whole) when stopped.</p> - <p>If a memory block is allocated and provided here, the - <c><![CDATA[sys_alloc]]></c> etc routines can still be used after - the Erlang emulator is stopped. The Erlang emulator can - also be restarted while other tasks using the memory - block are running without destroying the memory. If - Erlang is to be restarted, also set the - <c><![CDATA[use_reclaim]]></c> flag.</p> - <p>If 0 is specified here, the Erlang system should not - be stopped while some other task uses the memory block - (has called <c><![CDATA[sys_alloc]]></c>).</p> - </item> - <tag>int warn_mixed_malloc</tag> - <item> - <p>If this flag is set to true (anything else than 0), the - system will write a warning message on the console if a - program is mixing normal <c><![CDATA[malloc]]></c> with - <c><![CDATA[sys_realloc]]></c> or <c><![CDATA[sys_free]]></c>.</p> - </item> - <tag>int realloc_always_moves</tag> - <item> - <p>If this flag is set to true (anything else than 0), all - calls to <c><![CDATA[sys_realloc]]></c> result in a moved memory - block. This can in certain conditions give less - fragmentation. This flag may be removed in future releases.</p> - </item> - <tag>int use_reclaim</tag> - <item> - <p>If this flag is set to true (anything else than 0), all - memory allocated with <c><![CDATA[sys_alloc]]></c> is automatically - reclaimed as soon as a task exits. This is very useful - to make writing port programs (and other programs as - well) easier. Combine this with using the routines - <c><![CDATA[save_open]]></c> etc. specified in the reclaim.h - file delivered in the Erlang distribution.</p> - </item> - </taglist> - <p>Return Value:</p> - <p>Returns 0 (OK) on success, otherwise a value <> 0.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_memory_show(...)</nametext></name> - <fsummary>A utility similar to VxWorks <c><![CDATA[memShow]]></c>, but for the Erlang memory area.</fsummary> - <desc> - <p>Return Value:</p> - <p>Returns 0 (OK) on success, otherwise a value <> 0.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_mem_info_get(MEM_PART_STATS *stats)</nametext></name> - <fsummary>A utility similar to VxWorks <c><![CDATA[memPartInfoGet]]></c>, but for the Erlang memory area.</fsummary> - <desc> - <p>Parameter:</p> - <taglist> - <tag>MEM_PART_STATS *stats</tag> - <item>A pointer to a MEM_PART_STATS structure as defined in - <c><![CDATA[<memLib.h>]]></c>. A successful call will fill in all - fields of the structure, on error all fields are left untouched. </item> - </taglist> - <p>Return Value:</p> - <p>Returns 0 (OK) on success, otherwise a value <> 0</p> - </desc> - </func> - </funcs> - - <section> - <title>NOTES</title> - <p>The memory block used by Erlang actually does not need to be - inside the area known to ordinary <c><![CDATA[malloc]]></c>. It is possible - to set the <c><![CDATA[USER_RESERVED_MEM]]></c> preprocessor symbol when compiling - the wind kernel and then use user reserved memory for - Erlang. Erlang can therefor utilize memory above the 32 Mb limit - of VxWorks on the PowerPC architecture.</p> - <p>Example:</p> - <p>In config.h for the wind kernel:</p> - <code type="none"><![CDATA[ - #undef LOCAL_MEM_AUTOSIZE - #undef LOCAL_MEM_SIZE - #undef USER_RESERVED_MEM - - #define LOCAL_MEM_SIZE 0x05000000 - #define USER_RESERVED_MEM 0x03000000 - ]]></code> - <p>In the start-up script/code for the VxWorks node:</p> - <code type="none"><![CDATA[ -erl_set_memory_block(sysPhysMemTop()-sysMemTop(),sysMemTop(),0,0,1); - ]]></code> - <p>Setting the <c><![CDATA[use_reclaim]]></c> flag decreases performance of the - system, but makes programming much easier. Other similar - facilities are present in the Erlang system even without using a - separate memory block. The routines called <c><![CDATA[save_malloc]]></c>, - <c><![CDATA[save_realloc]]></c> and <c><![CDATA[save_free]]></c> provide the same - facilities by using VxWorks own <c><![CDATA[malloc]]></c>. Similar routines - exist for files, see the file <c><![CDATA[reclaim.h]]></c> in the distribution.</p> - </section> -</cref> - diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index d85dff2c0c..06fefa8efb 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -65,14 +65,14 @@ <funcs> <func> - <name>abs(Number) -> integer() | float()</name> + <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> - <type> - <v>Number = number()</v> - </type> <desc> <p>Returns an integer or float which is the arithmetical - absolute value of <c>Number</c>.</p> + absolute value of <c><anno>Float</anno></c> or <c><anno>Int</anno></c>.</p> <pre> > <input>abs(-3.33).</input> 3.33 @@ -82,26 +82,19 @@ </desc> </func> <func> - <name>erlang:adler32(Data) -> integer()</name> + <name name="adler32" arity="1"/> <fsummary>Compute adler32 checksum</fsummary> - <type> - <v>Data = iodata()</v> - </type> <desc> - <p>Computes and returns the adler32 checksum for <c>Data</c>.</p> + <p>Computes and returns the adler32 checksum for <c><anno>Data</anno></c>.</p> </desc> </func> <func> - <name>erlang:adler32(OldAdler, Data) -> integer()</name> + <name name="adler32" arity="2"/> <fsummary>Compute adler32 checksum</fsummary> - <type> - <v>OldAdler = integer()</v> - <v>Data = iodata()</v> - </type> <desc> <p>Continue computing the adler32 checksum by combining - the previous checksum, <c>OldAdler</c>, with the checksum of - <c>Data</c>.</p> + 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), @@ -114,12 +107,8 @@ </desc> </func> <func> - <name>erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) -> integer()</name> + <name name="adler32_combine" arity="3"/> <fsummary>Combine two adler32 checksums</fsummary> - <type> - <v>FirstAdler = SecondAdler = integer()</v> - <v>SecondSize = integer()</v> - </type> <desc> <p>Combines two previously computed adler32 checksums. This computation requires the size of the data object for @@ -138,18 +127,14 @@ </desc> </func> <func> - <name>erlang:append_element(Tuple1, Term) -> Tuple2</name> + <name name="append_element" arity="2"/> <fsummary>Append an extra element to a tuple</fsummary> - <type> - <v>Tuple1 = Tuple2 = tuple()</v> - <v>Term = term()</v> - </type> <desc> <p>Returns a new tuple which has one element more than - <c>Tuple1</c>, and contains the elements in <c>Tuple1</c> - followed by <c>Term</c> as the last element. Semantically + <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(Tuple) ++ [Term])</c>, but much + <c>list_to_tuple(tuple_to_list(<anno>Tuple1</anno>) ++ [<anno>Term</anno>])</c>, but much faster.</p> <pre> > <input>erlang:append_element({one, two}, three).</input> @@ -204,27 +189,24 @@ </desc> </func> <func> - <name>atom_to_binary(Atom, Encoding) -> binary()</name> + <name name="atom_to_binary" arity="2"/> <fsummary>Return the binary representation of an atom</fsummary> - <type> - <v>Atom = atom()</v> - <v>Encoding = latin1 | utf8 | unicode</v> - </type> <desc> <p>Returns a binary which corresponds to the text - representation of <c>Atom</c>. If <c>Encoding</c> + 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>Encoding</c> is <c>utf8</c> or + 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(Atom, latin1)</c> can + <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(Atom, latin1)</c> will fail if the - text representation for the <c>Atom</c> contains a Unicode + 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> <pre> @@ -233,30 +215,21 @@ </desc> </func> <func> - <name>atom_to_list(Atom) -> string()</name> + <name name="atom_to_list" arity="1"/> <fsummary>Text representation of an atom</fsummary> - <type> - <v>Atom = atom()</v> - </type> <desc> <p>Returns a string which corresponds to the text - representation of <c>Atom</c>.</p> + representation of <c><anno>Atom</anno></c>.</p> <pre> > <input>atom_to_list('Erlang').</input> "Erlang"</pre> </desc> </func> <func> - <name>binary_part(Subject, PosLen) -> binary()</name> + <name name="binary_part" arity="2"/> <fsummary>Extracts a part of a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>PosLen = {Start,Length}</v> - <v>Start = integer() >= 0</v> - <v>Length = integer() >= 0</v> - </type> - <desc> - <p>Extracts the part of the binary described by <c>PosLen</c>.</p> + <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> @@ -266,54 +239,47 @@ <<6,7,8,9,10>> </code> - <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> + <p>If <c><anno>PosLen</anno></c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> - <p><c>Start</c> is zero-based, i.e.:</p> + <p><c><anno>Start</anno></c> is zero-based, i.e.:</p> <code> 1> Bin = <<1,2,3>> 2> binary_part(Bin,{0,2}). <<1,2>> </code> - <p>See the STDLIB module <c>binary</c> for details about the <c>PosLen</c> semantics.</p> + <p>See the STDLIB module <c>binary</c> for details about the <c><anno>PosLen</anno></c> semantics.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>binary_part(Subject, Start, Length) -> binary()</name> + <name name="binary_part" arity="3"/> <fsummary>Extracts a part of a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Start = integer() >= 0</v> - <v>Length = integer() >= 0</v> - </type> <desc> - <p>The same as <c>binary_part(Subject, {Pos, Len})</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>binary_to_atom(Binary, Encoding) -> atom()</name> + <name name="binary_to_atom" arity="2"/> <fsummary>Convert from text representation to an atom</fsummary> - <type> - <v>Binary = binary()</v> - <v>Encoding = latin1 | utf8 | unicode</v> - </type> <desc> <p>Returns the atom whose text representation is - <c>Binary</c>. If <c>Encoding</c> is <c>latin1</c>, no - translation of bytes in the binary is done. If <c>Encoding</c> + <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(Binary, utf8)</c> will fail if + <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(Binary, utf8)</c> - will not fail in that case.</p></note> + 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> <pre> > <input>binary_to_atom(<<"Erlang">>, latin1).</input> @@ -325,12 +291,8 @@ </desc> </func> <func> - <name>binary_to_existing_atom(Binary, Encoding) -> atom()</name> + <name name="binary_to_existing_atom" arity="2"/> <fsummary>Convert from text representation to an atom</fsummary> - <type> - <v>Binary = binary()</v> - <v>Encoding = latin1 | utf8 | unicode</v> - </type> <desc> <p>Works like <seealso marker="#binary_to_atom/2">binary_to_atom/2</seealso>, but the atom must already exist.</p> @@ -338,27 +300,59 @@ </desc> </func> <func> - <name>binary_to_list(Binary) -> [char()]</name> + <name name="binary_to_float" arity="1"/> + <fsummary>Convert from text representation to a float</fsummary> + <desc> + <p>Returns the float whose text representation is <c><anno>Binary</anno></c>.</p> + <pre> +> <input>binary_to_float(<<"2.2017764e+0">>).</input> +2.2017764</pre> + <p>Failure: <c>badarg</c> if <c><anno>Binary</anno></c> contains a bad + representation of a float.</p> + </desc> + </func> + <func> + <name name="binary_to_integer" arity="1"/> + <fsummary>Convert from text representation to an integer</fsummary> + <desc> + <p>Returns an integer whose text representation is + <c><anno>Binary</anno></c>.</p> + <pre> +> <input>binary_to_integer(<<"123">>).</input> +123</pre> + <p>Failure: <c>badarg</c> if <c><anno>Binary</anno></c> contains a bad + representation of an integer.</p> + </desc> + </func> + <func> + <name name="binary_to_integer" arity="2"/> + <fsummary>Convert 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> + <pre> +> <input>binary_to_integer(<<"3FF">>, 16).</input> +1023</pre> + <p>Failure: <c>badarg</c> if <c><anno>Binary</anno></c> contains a bad + representation of an integer.</p> + </desc> + </func> + <func> + <name name="binary_to_list" arity="1"/> <fsummary>Convert a binary to a list</fsummary> - <type> - <v>Binary = binary()</v> - </type> <desc> <p>Returns a list of integers which correspond to the bytes of - <c>Binary</c>.</p> + <c><anno>Binary</anno></c>.</p> </desc> </func> <func> - <name>binary_to_list(Binary, Start, Stop) -> [char()]</name> + <name name="binary_to_list" arity="3"/> <fsummary>Convert part of a binary to a list</fsummary> - <type> - <v>Binary = binary()</v> - <v>Start = Stop = 1..byte_size(Binary)</v> - </type> + <type_desc variable="Start">1..byte_size(<anno>Binary</anno>)</type_desc> <desc> <p>As <c>binary_to_list/1</c>, but returns a list of integers - corresponding to the bytes from position <c>Start</c> to - position <c>Stop</c> in <c>Binary</c>. Positions in the + 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 binary are numbered starting from 1.</p> <note><p>This function's indexing style of using one-based indices for @@ -368,27 +362,21 @@ </desc> </func> <func> - <name>bitstring_to_list(Bitstring) -> [char()|bitstring()]</name> + <name name="bitstring_to_list" arity="1"/> <fsummary>Convert a bitstring to a list</fsummary> - <type> - <v>Bitstring = bitstring()</v> - </type> <desc> <p>Returns a list of integers which correspond to the bytes of - <c>Bitstring</c>. If the number of bits in the binary is not + <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> </desc> </func> <func> - <name>binary_to_term(Binary) -> term()</name> + <name name="binary_to_term" arity="1"/> <fsummary>Decode an Erlang external term format binary</fsummary> - <type> - <v>Binary = <seealso marker="#type-ext_binary">ext_binary()</seealso></v> - </type> <desc> <p>Returns an Erlang term which is the result of decoding - the binary object <c>Binary</c>, which must be encoded + the 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 @@ -401,12 +389,8 @@ </desc> </func> <func> - <name>binary_to_term(Binary, Opts) -> term()</name> + <name name="binary_to_term" arity="2"/> <fsummary>Decode an Erlang external term format binary</fsummary> - <type> - <v>Opts = [safe]</v> - <v>Binary = <seealso marker="#type-ext_binary">ext_binary()</seealso></v> - </type> <desc> <p>As <c>binary_to_term/1</c>, but takes options that affect decoding of the binary.</p> @@ -436,13 +420,10 @@ </desc> </func> <func> - <name>bit_size(Bitstring) -> integer() >= 0</name> + <name name="bit_size" arity="1"/> <fsummary>Return the size of a bitstring</fsummary> - <type> - <v>Bitstring = bitstring()</v> - </type> <desc> - <p>Returns an integer which is the size in bits of <c>Bitstring</c>.</p> + <p>Returns an integer which is the size in bits of <c><anno>Bitstring</anno></c>.</p> <pre> > <input>bit_size(<<433:16,3:3>>).</input> 19 @@ -452,11 +433,8 @@ </desc> </func> <func> - <name>erlang:bump_reductions(Reductions) -> void()</name> + <name name="bump_reductions" arity="1"/> <fsummary>Increment the reduction counter</fsummary> - <type> - <v>Reductions = integer() >= 0</v> - </type> <desc> <p>This implementation-dependent function increments the reduction counter for the calling process. In the Beam @@ -472,14 +450,11 @@ </desc> </func> <func> - <name>byte_size(Bitstring) -> integer() >= 0</name> + <name name="byte_size" arity="1"/> <fsummary>Return the size of a bitstring (or binary)</fsummary> - <type> - <v>Bitstring = bitstring()</v> - </type> <desc> <p>Returns an integer which is the number of bytes needed to contain - <c>Bitstring</c>. (That is, if the number of bits in <c>Bitstring</c> is not + <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> <pre> > <input>byte_size(<<433:16,3:3>>).</input> @@ -490,21 +465,17 @@ </desc> </func> <func> - <name>erlang:cancel_timer(TimerRef) -> Time | false</name> + <name name="cancel_timer" arity="1"/> <fsummary>Cancel a timer</fsummary> - <type> - <v>TimerRef = reference()</v> - <v>Time = integer() >= 0</v> - </type> <desc> - <p>Cancels a timer, where <c>TimerRef</c> was returned by + <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>TimerRef</c> was + 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> <p>See also @@ -518,27 +489,20 @@ </func> <func> - <name>check_old_code(Module) -> boolean()</name> + <name name="check_old_code" arity="1"/> <fsummary>Check if a module has old code</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> - <p>Returns <c>true</c> if the <c>Module</c> has old code, + <p>Returns <c>true</c> if the <c><anno>Module</anno></c> has old code, and <c>false</c> otherwise.</p> <p>See also <seealso marker="kernel:code">code(3)</seealso>.</p> </desc> </func> <func> - <name>check_process_code(Pid, Module) -> boolean()</name> + <name name="check_process_code" arity="2"/> <fsummary>Check if a process is executing old code for a module</fsummary> - <type> - <v>Pid = pid()</v> - <v>Module = atom()</v> - </type> <desc> - <p>Returns <c>true</c> if the process <c>Pid</c> is executing - old code for <c>Module</c>. That is, if the current call of + <p>Returns <c>true</c> if the process <c><anno>Pid</anno></c> is executing + old code for <c><anno>Module</anno></c>. That is, if the current call of the process executes old code for this module, or if the process has references to old code for this module, or if the process contains funs that references old code for this @@ -550,26 +514,19 @@ false</pre> </desc> </func> <func> - <name>erlang:crc32(Data) -> integer() >= 0</name> + <name name="crc32" arity="1"/> <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary> - <type> - <v>Data = iodata()</v> - </type> <desc> - <p>Computes and returns the crc32 (IEEE 802.3 style) checksum for <c>Data</c>.</p> + <p>Computes and returns the crc32 (IEEE 802.3 style) checksum for <c><anno>Data</anno></c>.</p> </desc> </func> <func> - <name>erlang:crc32(OldCrc, Data) -> integer() >= 0</name> + <name name="crc32" arity="2"/> <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary> - <type> - <v>OldCrc = integer() >= 0</v> - <v>Data = iodata()</v> - </type> <desc> <p>Continue computing the crc32 checksum by combining - the previous checksum, <c>OldCrc</c>, with the checksum of - <c>Data</c>.</p> + 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), @@ -582,12 +539,8 @@ false</pre> </desc> </func> <func> - <name>erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) -> integer() >= 0</name> + <name name="crc32_combine" arity="3"/> <fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary> - <type> - <v>FirstCrc = SecondCrc = integer() >= 0</v> - <v>SecondSize = integer() >= 0</v> - </type> <desc> <p>Combines two previously computed crc32 checksums. This computation requires the size of the data object for @@ -606,11 +559,8 @@ false</pre> </desc> </func> <func> - <name>date() -> Date</name> + <name name="date" arity="0"/> <fsummary>Current date</fsummary> - <type> - <v>Date = <seealso marker="calendar#type-date">calendar:date()</seealso></v> - </type> <desc> <p>Returns the current date as <c>{Year, Month, Day}</c>.</p> <p>The time zone and daylight saving time correction depend on @@ -621,47 +571,24 @@ false</pre> </desc> </func> <func> - <name>erlang:decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name> + <name name="decode_packet" arity="3"/> <fsummary>Extracts a protocol packet from a binary</fsummary> - <type> - <v>Bin = binary()</v> - <v>Options = [Opt]</v> - <v>Packet = binary() | HttpPacket</v> - <v>Rest = binary()</v> - <v>Length = integer() > 0 | undefined</v> - <v>Reason = term()</v> - <v> Type, Opt -- see below</v> - <v></v> - <v>HttpPacket = HttpRequest | HttpResponse | HttpHeader | http_eoh | HttpError</v> - <v>HttpRequest = {http_request, HttpMethod, HttpUri, HttpVersion}</v> - <v>HttpResponse = {http_response, HttpVersion, integer(), HttpString}</v> - <v>HttpHeader = {http_header, integer(), HttpField, Reserved=term(), Value=HttpString}</v> - <v>HttpError = {http_error, HttpString}</v> - <v>HttpMethod = HttpMethodAtom | HttpString</v> - <v>HttpMethodAtom = 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE'</v> - <v>HttpUri = '*' | {absoluteURI, http|https, Host=HttpString, Port=integer()|undefined, Path=HttpString} | - {scheme, Scheme=HttpString, HttpString} | {abs_path, HttpString} | HttpString</v> - <v>HttpVersion = {Major=integer(), Minor=integer()}</v> - <v>HttpString = string() | binary()</v> - <v>HttpField = HttpFieldAtom | HttpString</v> - <v>HttpFieldAtom = 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' | 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' | 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language' | 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' | 'If-Match' | 'If-None-Match' | 'If-Range' | 'If-Unmodified-Since' | 'Max-Forwards' | 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-Agent' | 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' | 'Retry-After' | 'Server' | 'Vary' | 'Warning' | 'Www-Authenticate' | 'Allow' | 'Content-Base' | 'Content-Encoding' | 'Content-Language' | 'Content-Length' | 'Content-Location' | 'Content-Md5' | 'Content-Range' | 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' | 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' | 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' | 'Proxy-Connection'</v> - <v></v> - </type> - <desc> - <p>Decodes the binary <c>Bin</c> according to the packet - protocol specified by <c>Type</c>. Very similar to the packet - handling done by sockets with the option {packet,Type}.</p> - <p>If an entire packet is contained in <c>Bin</c> it is + <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 returned together with the remainder of the binary as - <c>{ok,Packet,Rest}</c>.</p> - <p>If <c>Bin</c> does not contain the entire packet, - <c>{more,Length}</c> is returned. <c>Length</c> is either the + <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> can then be called again with more data added.</p> <p>If the packet does not conform to the protocol format - <c>{error,Reason}</c> is returned.</p> - <p>The following values of <c>Type</c> are valid:</p> + <c>{error,<anno>Reason</anno>}</c> is returned.</p> + <p>The following values of <c><anno>Type</anno></c> are valid:</p> <taglist> <tag><c>raw | 0</c></tag> <item> @@ -699,15 +626,17 @@ false</pre> <item> <p>The Hypertext Transfer Protocol. The packets are returned with the format according to - <c>HttpPacket</c> described above. A packet is either a + <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>HttpError</c>.</p> + 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.</p> + 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>HttpRequest</c> or a - <c>HttpResponse</c> is expected. The following calls - should use <c>httph</c> to get <c>HttpHeader</c>'s until + 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 headers and the beginning of any following message body.</p> <p>The variants <c>http_bin</c> and <c>httph_bin</c> will return @@ -716,14 +645,14 @@ false</pre> </taglist> <p>The following options are available:</p> <taglist> - <tag><c>{packet_size, integer()}</c></tag> + <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> - <tag><c>{line_length, integer()}</c></tag> + <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> @@ -739,14 +668,27 @@ false</pre> {more,6}</pre> </desc> </func> + <func> - <name>delete_module(Module) -> true | undefined</name> + <name name="delete_element" arity="2"/> + <fsummary>Delete 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> + <pre> +> <input>erlang:delete_element(2, {one, two, three}).</input> +{one,three}</pre> + </desc> + </func> + + <func> + <name name="delete_module" arity="1"/> <fsummary>Make the current code for a module old</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> - <p>Makes the current code for <c>Module</c> become old code, and + <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> @@ -760,27 +702,24 @@ false</pre> </desc> </func> <func> - <name>demonitor(MonitorRef) -> true</name> + <name name="demonitor" arity="1"/> <fsummary>Stop monitoring</fsummary> - <type> - <v>MonitorRef = reference()</v> - </type> <desc> - <p>If <c>MonitorRef</c> is a reference which the calling process + <p>If <c><anno>MonitorRef</anno></c> is a reference which 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(MonitorRef)</c> has returned it is - guaranteed that no <c>{'DOWN', MonitorRef, _, _, _}</c> message + <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', MonitorRef, _, _, _}</c> message + 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 to remove such a <c>'DOWN'</c> message from the message queue after monitoring has been stopped. - <seealso marker="#demonitor/2">demonitor(MonitorRef, [flush])</seealso> can be used instead of - <c>demonitor(MonitorRef)</c> if this cleanup is wanted.</p> + <seealso marker="#demonitor/2">demonitor(<anno>MonitorRef</anno>, [flush])</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 @@ -792,35 +731,30 @@ false</pre> asynchronously send a "demonitor signal" to the monitored entity and ignore any future results of the monitor. </p> </note> - <p>Failure: It is an error if <c>MonitorRef</c> refers to a + <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>MonitorRef</c> is a remote + <c>badarg</c> (for example if <c><anno>MonitorRef</anno></c> is a remote reference).</p> </desc> </func> <func> - <name>demonitor(MonitorRef, OptionList) -> boolean()</name> + <name name="demonitor" arity="2"/> <fsummary>Stop monitoring</fsummary> - <type> - <v>MonitorRef = reference()</v> - <v>OptionList = [Option]</v> - <v> Option = flush | info</v> - </type> <desc> <p>The returned value is <c>true</c> unless <c>info</c> is part - of <c>OptionList</c>. + of <c><anno>OptionList</anno></c>. </p> - <p><c>demonitor(MonitorRef, [])</c> is equivalent to - <seealso marker="#demonitor/1">demonitor(MonitorRef)</seealso>.</p> - <p>Currently the following <c>Option</c>s are valid:</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> <taglist> <tag><c>flush</c></tag> <item> - <p>Remove (one) <c>{_, MonitorRef, _, _, _}</c> message, + <p>Remove (one) <c>{_, <anno>MonitorRef</anno>, _, _, _}</c> message, if there is one, from the caller's message queue after monitoring has been stopped.</p> - <p>Calling <c>demonitor(MonitorRef, [flush])</c> + <p>Calling <c>demonitor(<anno>MonitorRef</anno>, [flush])</c> is equivalent to the following, but more efficient:</p> <code type="none"> @@ -860,8 +794,8 @@ false</pre> <note> <p>More options may be added in the future.</p> </note> - <p>Failure: <c>badarg</c> if <c>OptionList</c> is not a list, or - if <c>Option</c> is not a valid option, or the same failure as for + <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> </desc> </func> @@ -878,13 +812,10 @@ false</pre> </desc> </func> <func> - <name>erlang:display(Term) -> true</name> + <name name="display" arity="1"/> <fsummary>Print a term on standard output</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Prints a text representation of <c>Term</c> on the standard + <p>Prints a text representation of <c><anno>Term</anno></c> on the standard output.</p> <warning> <p>This BIF is intended for debugging only.</p> @@ -892,15 +823,12 @@ false</pre> </desc> </func> <func> - <name>element(N, Tuple) -> term()</name> + <name name="element" arity="2"/> + <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <fsummary>Get Nth element of a tuple</fsummary> - <type> - <v>N = 1..tuple_size(Tuple)</v> - <v>Tuple = tuple()</v> - </type> <desc> - <p>Returns the <c>N</c>th element (numbering from 1) of - <c>Tuple</c>.</p> + <p>Returns the <c><anno>N</anno></c>th element (numbering from 1) of + <c><anno>Tuple</anno></c>.</p> <pre> > <input>element(2, {a, b, c}).</input> b</pre> @@ -908,11 +836,8 @@ b</pre> </desc> </func> <func> - <name>erase() -> [{Key, Val}]</name> + <name name="erase" arity="0"/> <fsummary>Return and delete the process dictionary</fsummary> - <type> - <v>Key = Val = term()</v> - </type> <desc> <p>Returns the process dictionary and deletes it.</p> <pre> @@ -923,15 +848,12 @@ b</pre> </desc> </func> <func> - <name>erase(Key) -> Val | undefined</name> + <name name="erase" arity="1"/> <fsummary>Return and delete a value from the process dictionary</fsummary> - <type> - <v>Key = Val = term()</v> - </type> <desc> - <p>Returns the value <c>Val</c> associated with <c>Key</c> and + <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>Key</c>.</p> + <c>undefined</c> if no value is associated with <c><anno>Key</anno></c>.</p> <pre> > <input>put(key1, {merry, lambs, are, playing}),</input> <input>X = erase(key1),</input> @@ -940,15 +862,12 @@ b</pre> </desc> </func> <func> - <name>error(Reason)</name> + <name name="error" arity="1"/> <fsummary>Stop execution with a given reason</fsummary> - <type> - <v>Reason = term()</v> - </type> <desc> <p>Stops the execution of the calling process with the reason - <c>Reason</c>, where <c>Reason</c> is any term. The actual - exit reason will be <c>{Reason, Where}</c>, where <c>Where</c> + <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> 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> @@ -962,18 +881,14 @@ b</pre> </desc> </func> <func> - <name>error(Reason, Args)</name> + <name name="error" arity="2"/> <fsummary>Stop execution with a given reason</fsummary> - <type> - <v>Reason = term()</v> - <v>Args = [term()]</v> - </type> <desc> <p>Stops the execution of the calling process with the reason - <c>Reason</c>, where <c>Reason</c> is any term. The actual - exit reason will be <c>{Reason, Where}</c>, where <c>Where</c> + <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> is a list of the functions most recently called (the current - function first). <c>Args</c> is expected to be the list of + 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 @@ -981,14 +896,11 @@ b</pre> </desc> </func> <func> - <name>exit(Reason)</name> + <name name="exit" arity="1"/> <fsummary>Stop execution with a given reason</fsummary> - <type> - <v>Reason = term()</v> - </type> <desc> <p>Stops the execution of the calling process with the exit - reason <c>Reason</c>, where <c>Reason</c> is any term. Since + 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> <pre> @@ -999,78 +911,67 @@ b</pre> </desc> </func> <func> - <name>exit(Pid, Reason) -> true</name> - <fsummary>Send an exit signal to a process</fsummary> - <type> - <v>Pid = pid()</v> - <v>Reason = term()</v> - </type> + <name name="exit" arity="2"/> + <fsummary>Send an exit signal to a process or a port</fsummary> <desc> - <p>Sends an exit signal with exit reason <c>Reason</c> to - the process <c>Pid</c>.</p> - <p>The following behavior apply if <c>Reason</c> is any term + <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>Pid</c> is not trapping exits, <c>Pid</c> itself will - exit with exit reason <c>Reason</c>. If <c>Pid</c> is trapping + <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, Reason}</c> and delivered to the message - queue of <c>Pid</c>. <c>From</c> is the pid of the process + <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>Reason</c> is the atom <c>normal</c>, <c>Pid</c> will + <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>Reason</c> is the atom <c>kill</c>, that is if - <c>exit(Pid, kill)</c> is called, an untrappable exit signal - is sent to <c>Pid</c> which will unconditionally exit with + <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> </desc> </func> <func> - <name>erlang:external_size(Term) -> integer() >= 0</name> + <name name="external_size" arity="1"/> <fsummary>Calculate the maximum size for a term encoded in the Erlang external term format</fsummary> - <type> - <v>Term = term()</v> - </type> <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(Term)),</input> -> <input>Size2 = erlang:external_size(Term),</input> +> <input>Size1 = byte_size(term_to_binary(<anno>Term</anno>)),</input> +> <input>Size2 = erlang:external_size(<anno>Term</anno>),</input> > <input>true = Size1 =< Size2.</input> true </pre> </p> - <p>This is equivalent to a call to: <code>erlang:external_size(Term, []) + <p>This is equivalent to a call to: <code>erlang:external_size(<anno>Term</anno>, []) </code></p> </desc> </func> <func> - <name>erlang:external_size(Term, [Option]) -> integer() >= 0</name> + <name name="external_size" arity="2"/> <fsummary>Calculate the maximum size for a term encoded in the Erlang external term format</fsummary> - <type> - <v>Term = term()</v> - <v>Option = {minor_version, Version}</v> - </type> <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(Term, Options)),</input> -> <input>Size2 = erlang:external_size(Term, Options),</input> +> <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 =< Size2.</input> true </pre> </p> - <p>The option <c>{minor_version, Version}</c> specifies how floats + <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. @@ -1078,13 +979,10 @@ true </desc> </func> <func> - <name>float(Number) -> float()</name> + <name name="float" arity="1"/> <fsummary>Convert a number to a float</fsummary> - <type> - <v>Number = number()</v> - </type> <desc> - <p>Returns a float by converting <c>Number</c> to a float.</p> + <p>Returns a float by converting <c><anno>Number</anno></c> to a float.</p> <pre> > <input>float(55).</input> 55.0</pre> @@ -1101,17 +999,58 @@ true </desc> </func> <func> - <name>float_to_list(Float) -> string()</name> + <name name="float_to_binary" arity="1"/> + <fsummary>Text representation of a float</fsummary> + <desc> + <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> + <desc> + <p>Returns a binary which corresponds 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> + <pre> +> <input>float_to_binary(7.12, [{decimals, 4}]).</input> +<<"7.1200">> +> <input>float_to_binary(7.12, [{decimals, 4}, compact]).</input> +<<"7.12">></pre> + </desc> + </func> + <func> + <name name="float_to_list" arity="1"/> <fsummary>Text representation of a float</fsummary> - <type> - <v>Float = float()</v> - </type> + <desc> + <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>.</p> + 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> <pre> -> <input>float_to_list(7.0).</input> -"7.00000000000000000000e+00"</pre> +> <input>float_to_list(7.12, [{decimals, 4}]).</input> +"7.1200" +> <input>float_to_list(7.12, [{decimals, 4}, compact]).</input> +"7.12"</pre> </desc> </func> <func> @@ -1213,18 +1152,15 @@ true </desc> </func> <func> - <name>erlang:fun_info(Fun, Item) -> {Item, Info}</name> + <name name="fun_info" arity="2"/> + <type name="fun_info_item"/> <fsummary>Information about a fun</fsummary> - <type> - <v>Fun = fun()</v> - <v>Item, Info -- see below</v> - </type> - <desc> - <p>Returns information about <c>Fun</c> as specified by - <c>Item</c>, in the form <c>{Item,Info}</c>.</p> - <p>For any fun, <c>Item</c> can be any of the atoms + <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> + <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>Item</c> can also be any of the atoms + <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> @@ -1233,33 +1169,26 @@ true </desc> </func> <func> - <name>erlang:fun_to_list(Fun) -> string()</name> + <name name="fun_to_list" arity="1"/> <fsummary>Text representation of a fun</fsummary> - <type> - <v>Fun = fun()</v> - </type> <desc> <p>Returns a string which corresponds to the text - representation of <c>Fun</c>.</p> + representation of <c><anno>Fun</anno></c>.</p> </desc> </func> <func> - <name>erlang:function_exported(Module, Function, Arity) -> boolean()</name> + <name name="function_exported" arity="3"/> <fsummary>Check if a function is exported and loaded</fsummary> - <type> - <v>Module = Function = atom()</v> - <v>Arity = arity()</v> - </type> <desc> - <p>Returns <c>true</c> if the module <c>Module</c> is loaded - and contains an exported function <c>Function/Arity</c>; + <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> </desc> </func> <func> - <name>garbage_collect() -> true</name> + <name name="garbage_collect" arity="0"/> <fsummary>Force an immediate garbage collection of the calling process</fsummary> <desc> <p>Forces an immediate garbage collection of the currently @@ -1276,26 +1205,20 @@ true </desc> </func> <func> - <name>garbage_collect(Pid) -> boolean()</name> + <name name="garbage_collect" arity="1"/> <fsummary>Force an immediate garbage collection of a process</fsummary> - <type> - <v>Pid = pid()</v> - </type> <desc> <p>Works like <c>erlang:garbage_collect()</c> but on any process. The same caveats apply. Returns <c>false</c> if - <c>Pid</c> refers to a dead process; <c>true</c> otherwise.</p> + <c><anno>Pid</anno></c> refers to a dead process; <c>true</c> otherwise.</p> </desc> </func> <func> - <name>get() -> [{Key, Val}]</name> + <name name="get" arity="0"/> <fsummary>Return the process dictionary</fsummary> - <type> - <v>Key = Val = term()</v> - </type> <desc> <p>Returns the process dictionary as a list of - <c>{Key, Val}</c> tuples.</p> + <c>{<anno>Key</anno>, <anno>Val</anno>}</c> tuples.</p> <pre> > <input>put(key1, merry),</input> <input>put(key2, lambs),</input> @@ -1305,14 +1228,11 @@ true </desc> </func> <func> - <name>get(Key) -> Val | undefined</name> + <name name="get" arity="1"/> <fsummary>Return a value from the process dictionary</fsummary> - <type> - <v>Key = Val = term()</v> - </type> <desc> - <p>Returns the value <c>Val</c>associated with <c>Key</c> in - the process dictionary, or <c>undefined</c> if <c>Key</c> + <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> <pre> > <input>put(key1, merry),</input> @@ -1331,14 +1251,11 @@ true </desc> </func> <func> - <name>get_keys(Val) -> [Key]</name> + <name name="get_keys" arity="1"/> <fsummary>Return a list of keys from the process dictionary</fsummary> - <type> - <v>Val = Key = term()</v> - </type> <desc> <p>Returns a list of keys which are associated with the value - <c>Val</c> in the process dictionary.</p> + <c><anno>Val</anno></c> in the process dictionary.</p> <pre> > <input>put(mary, {1, 2}),</input> <input>put(had, {1, 2}),</input> @@ -1351,28 +1268,23 @@ true </desc> </func> <func> - <name>erlang:get_stacktrace() -> [{Module, Function, Arity | Args, Location}]</name> + <name name="get_stacktrace" arity="0"/> <fsummary>Get the call stack back-trace of the last exception</fsummary> - <type> - <v>Module = Function = atom()</v> - <v>Arity = arity()</v> - <v>Args = [term()]</v> - <v>Location = [{atom(),term()}]</v> - </type> + <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 - <c>{Module,Function,Arity,Location}</c> tuples. - The <c>Arity</c> field in the first tuple may be the argument + <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, depending on the exception.</p> <p>If there has not been any exceptions in a process, the - stacktrace is []. After a code change for the process, + stacktrace is <c>[]</c>. After a code change for the process, the stacktrace may also be reset to [].</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>Location</c> is a (possibly empty) list of two-tuples that + <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 @@ -1397,11 +1309,8 @@ true </desc> </func> <func> - <name>group_leader() -> GroupLeader</name> + <name name="group_leader" arity="0"/> <fsummary>Get the group leader for the calling process</fsummary> - <type> - <v>GroupLeader = pid()</v> - </type> <desc> <p>Returns the pid of the group leader for the process which evaluates the function.</p> @@ -1414,13 +1323,10 @@ true </desc> </func> <func> - <name>group_leader(GroupLeader, Pid) -> true</name> + <name name="group_leader" arity="2"/> <fsummary>Set the group leader for a process</fsummary> - <type> - <v>GroupLeader = Pid = pid()</v> - </type> <desc> - <p>Sets the group leader of <c>Pid</c> to <c>GroupLeader</c>. + <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 <c>init</c>.</p> @@ -1429,7 +1335,7 @@ true </desc> </func> <func> - <name>halt()</name> + <name name="halt" arity="0"/> <fsummary>Halt the Erlang runtime system and indicate normal exit to the calling environment</fsummary> <desc> <p>The same as @@ -1440,14 +1346,11 @@ os_prompt% </pre> </desc> </func> <func> - <name>halt(Status)</name> + <name name="halt" arity="1"/> <fsummary>Halt the Erlang runtime system</fsummary> - <type> - <v>Status = integer() >= 0 | string() | abort</v> - </type> <desc> <p>The same as - <seealso marker="#halt/2"><c>halt(Status, [])</c></seealso>.</p> + <seealso marker="#halt/2"><c>halt(<anno>Status</anno>, [])</c></seealso>.</p> <pre> > <input>halt(17).</input> os_prompt% <input>echo $?</input> @@ -1456,26 +1359,21 @@ os_prompt% </pre> </desc> </func> <func> - <name>halt(Status, Options)</name> + <name name="halt" arity="2"/> <fsummary>Halt the Erlang runtime system</fsummary> - <type> - <v>Status = integer() >= 0 | string() | abort</v> - <v>Options = [Option]</v> - <v>Option = {flush,boolean()} | term()</v> - </type> <desc> - <p><c>Status</c> must be a non-negative integer, a string, + <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>Status</c>: + Depending on <c><anno>Status</anno></c>: </p> <taglist> <tag>integer()</tag> - <item>The runtime system exits with the integer value <c>Status</c> + <item>The runtime system exits with the integer value <c><anno>Status</anno></c> as status code to the calling environment (operating system). </item> <tag>string()</tag> - <item>An erlang crash dump is produced with <c>Status</c> as slogan, + <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> <tag><c>abort</c></tag> @@ -1487,10 +1385,10 @@ os_prompt% </pre> <p>Note that on many platforms, only the status codes 0-255 are supported by the operating system. </p> - <p>For integer <c>Status</c> the Erlang runtime system closes all ports + <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>Option</c> as <c>{flush,false}</c>. + <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. @@ -1498,11 +1396,11 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:hash(Term, Range) -> Hash</name> + <name name="hash" arity="2"/> <fsummary>Hash function (deprecated)</fsummary> <desc> - <p>Returns a hash value for <c>Term</c> within the range - <c>1..Range</c>. The allowed range is 1..2^27-1.</p> + <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> <warning> <p>This BIF is deprecated as the hash value may differ on different architectures. Also the hash values for integer @@ -1515,35 +1413,28 @@ os_prompt% </pre> </desc> </func> <func> - <name>hd(List) -> term()</name> + <name name="hd" arity="1"/> <fsummary>Head of a list</fsummary> - <type> - <v>List = [term()]</v> - </type> <desc> - <p>Returns the head of <c>List</c>, that is, the first element.</p> + <p>Returns the head of <c><anno>List</anno></c>, that is, the first element.</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>List</c> is the empty list [].</p> + <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty list [].</p> </desc> </func> <func> - <name>erlang:hibernate(Module, Function, Args)</name> + <name name="hibernate" arity="3"/> <fsummary>Hibernate a process until a message is sent to it</fsummary> - <type> - <v>Module = Function = atom()</v> - <v>Args = [term()]</v> - </type> <desc> <p>Puts the calling process into a wait state where its memory allocation has been reduced as much as possible, which 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>Module:Function</c> with - the arguments given by <c>Args</c> with the call stack + 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> @@ -1572,15 +1463,51 @@ os_prompt% </pre> 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> + <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> + <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> + <desc> + <p>Returns a binary which corresponds to the text + representation of <c><anno>Integer</anno></c>.</p> + <pre> +> <input>integer_to_binary(77).</input> +<<"77">></pre> + </desc> + </func> + <func> + <name name="integer_to_binary" arity="2"/> + <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> + <pre> +> <input>integer_to_binary(1023, 16).</input> +<<"3FF">></pre> + </desc> + </func> <func> - <name>integer_to_list(Integer) -> string()</name> + <name name="integer_to_list" arity="1"/> <fsummary>Text representation of an integer</fsummary> - <type> - <v>Integer = integer()</v> - </type> <desc> <p>Returns a string which corresponds to the text - representation of <c>Integer</c>.</p> + representation of <c><anno>Integer</anno></c>.</p> <pre> > <input>integer_to_list(77).</input> "77"</pre> @@ -1598,14 +1525,11 @@ os_prompt% </pre> </desc> </func> <func> - <name>iolist_to_binary(IoListOrBinary) -> binary()</name> + <name name="iolist_to_binary" arity="1"/> <fsummary>Convert an iolist to a binary</fsummary> - <type> - <v>IoListOrBinary = iolist() | binary()</v> - </type> <desc> <p>Returns a binary which is made from the integers and - binaries in <c>IoListOrBinary</c>.</p> + binaries in <c><anno>IoListOrBinary</anno></c>.</p> <pre> > <input>Bin1 = <<1,2,3>>.</input> <<1,2,3>> @@ -1618,22 +1542,19 @@ os_prompt% </pre> </desc> </func> <func> - <name>iolist_size(Item) -> integer() >= 0</name> + <name name="iolist_size" arity="1"/> <fsummary>Size of an iolist</fsummary> - <type> - <v>Item = iolist() | binary()</v> - </type> <desc> <p>Returns an integer which is the size in bytes of the binary that would be the result of - <c>iolist_to_binary(Item)</c>.</p> + <c>iolist_to_binary(<anno>Item</anno>)</c>.</p> <pre> > <input>iolist_size([1,2|<<3,4>>]).</input> 4</pre> </desc> </func> <func> - <name>is_alive() -> boolean()</name> + <name name="is_alive" arity="0"/> <fsummary>Check whether the local node is alive</fsummary> <desc> <p>Returns <c>true</c> if the local node is alive; that is, if @@ -1642,25 +1563,19 @@ os_prompt% </pre> </desc> </func> <func> - <name>is_atom(Term) -> boolean()</name> + <name name="is_atom" arity="1"/> <fsummary>Check whether a term is an atom</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is an atom; + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an atom; otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_binary(Term) -> boolean()</name> + <name name="is_binary" arity="1"/> <fsummary>Check whether a term is a binary</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a binary; + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a binary; otherwise returns <c>false</c>.</p> <p>A binary always contains a complete number of bytes.</p> @@ -1669,158 +1584,113 @@ os_prompt% </pre> </desc> </func> <func> - <name>is_bitstring(Term) -> boolean()</name> + <name name="is_bitstring" arity="1"/> <fsummary>Check whether a term is a bitstring</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a bitstring (including a binary); + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a bitstring (including a binary); otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_boolean(Term) -> boolean()</name> + <name name="is_boolean" arity="1"/> <fsummary>Check whether a term is a boolean</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is + <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>Allowed in guard tests.</p> </desc> </func> <func> - <name>erlang:is_builtin(Module, Function, Arity) -> boolean()</name> + <name name="is_builtin" arity="3"/> <fsummary>Check if a function is a BIF implemented in C</fsummary> - <type> - <v>Module = Function = atom()</v> - <v>Arity = arity()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Module:Function/Arity</c> is + <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> </desc> </func> <func> - <name>is_float(Term) -> boolean()</name> + <name name="is_float" arity="1"/> <fsummary>Check whether a term is a float</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a floating point + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a floating point number; otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_function(Term) -> boolean()</name> + <name name="is_function" arity="1"/> <fsummary>Check whether a term is a fun</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a fun; otherwise + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a fun; otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_function(Term, Arity) -> boolean()</name> + <name name="is_function" arity="2"/> <fsummary>Check whether a term is a fun with a given arity</fsummary> - <type> - <v>Term = term()</v> - <v>Arity = arity()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a fun that can be - applied with <c>Arity</c> number of arguments; otherwise + <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> <p>Allowed in guard tests.</p> - <warning> - <p>Currently, <c>is_function/2</c> will also return - <c>true</c> if the first argument is a tuple fun (a tuple - containing two atoms). In a future release, tuple funs will - no longer be supported and <c>is_function/2</c> will return - <c>false</c> if given a tuple fun.</p> - </warning> </desc> </func> <func> - <name>is_integer(Term) -> boolean()</name> + <name name="is_integer" arity="1"/> <fsummary>Check whether a term is an integer</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is an integer; + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer; otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_list(Term) -> boolean()</name> + <name name="is_list" arity="1"/> <fsummary>Check whether a term is a list</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a list with + <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> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_number(Term) -> boolean()</name> + <name name="is_number" arity="1"/> <fsummary>Check whether a term is a number</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is either an integer or a + <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>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_pid(Term) -> boolean()</name> + <name name="is_pid" arity="1"/> <fsummary>Check whether a term is a pid</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a pid (process + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a pid (process identifier); otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_port(Term) -> boolean()</name> + <name name="is_port" arity="1"/> <fsummary>Check whether a term is a port</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a port identifier; + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a port identifier; otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_process_alive(Pid) -> boolean()</name> + <name name="is_process_alive" arity="1"/> <fsummary>Check whether a process is alive</fsummary> - <type> - <v>Pid = pid()</v> - </type> <desc> <p> - <c>Pid</c> must refer to a process at the local node. + <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 <c>false</c>. @@ -1828,41 +1698,32 @@ os_prompt% </pre> </desc> </func> <func> - <name>is_record(Term, RecordTag) -> boolean()</name> + <name name="is_record" arity="2"/> <fsummary>Check whether a term appears to be a record</fsummary> - <type> - <v>Term = term()</v> - <v>RecordTag = atom()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a tuple and its first - element is <c>RecordTag</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>Term</c> is a - tuple, that its first element is <c>RecordTag</c>, and that - the size is correct. However, if the <c>RecordTag</c> is + 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> </note> - <p>Allowed in guard tests, if <c>RecordTag</c> is a literal + <p>Allowed in guard tests, if <c><anno>RecordTag</anno></c> is a literal atom.</p> </desc> </func> <func> - <name>is_record(Term, RecordTag, Size) -> boolean()</name> + <name name="is_record" arity="3"/> <fsummary>Check whether a term appears to be a record</fsummary> - <type> - <v>Term = term()</v> - <v>RecordTag = atom()</v> - <v>Size = integer()</v> - </type> - <desc> - <p><c>RecordTag</c> must be an atom. Returns <c>true</c> if - <c>Term</c> is a tuple, its first element is <c>RecordTag</c>, - and its size is <c>Size</c>. Otherwise, returns <c>false</c>.</p> - <p>Allowed in guard tests, provided that <c>RecordTag</c> is + <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 a literal atom and <c>Size</c> is a literal integer.</p> <note> <p>This BIF is documented for completeness. In most cases @@ -1871,37 +1732,28 @@ os_prompt% </pre> </desc> </func> <func> - <name>is_reference(Term) -> boolean()</name> + <name name="is_reference" arity="1"/> <fsummary>Check whether a term is a reference</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a reference; + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a reference; otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>is_tuple(Term) -> boolean()</name> + <name name="is_tuple" arity="1"/> <fsummary>Check whether a term is a tuple</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Term</c> is a tuple; + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple; otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> <func> - <name>length(List) -> integer() >= 0</name> + <name name="length" arity="1"/> <fsummary>Length of a list</fsummary> - <type> - <v>List = [term()]</v> - </type> <desc> - <p>Returns the length of <c>List</c>.</p> + <p>Returns the length of <c><anno>List</anno></c>.</p> <pre> > <input>length([1,2,3,4,5,6,7,8,9]).</input> 9</pre> @@ -1909,52 +1761,49 @@ os_prompt% </pre> </desc> </func> <func> - <name>link(Pid) -> true</name> + <name name="link" arity="1"/> <fsummary>Create a link to another process (or port)</fsummary> - <type> - <v>Pid = pid() | port()</v> - </type> <desc> <p>Creates a link between the calling process and another - process (or port) <c>Pid</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>Pid</c> does not exist, the behavior of the BIF depends + <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>Pid</c> is cheap -- that is, if <c>Pid</c> is + 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>Pid</c> is remote, <c>link/1</c> returns + 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>list_to_atom(String) -> atom()</name> + <name name="list_to_atom" arity="1"/> <fsummary>Convert from text representation to an atom</fsummary> - <type> - <v>String = string()</v> - </type> <desc> - <p>Returns the atom whose text representation is <c>String</c>.</p> + <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> <pre> > <input>list_to_atom("Erlang").</input> 'Erlang'</pre> </desc> </func> <func> - <name>list_to_binary(IoList) -> binary()</name> + <name name="list_to_binary" arity="1"/> <fsummary>Convert a list to a binary</fsummary> - <type> - <v>IoList = iolist()</v> - </type> <desc> <p>Returns a binary which is made from the integers and - binaries in <c>IoList</c>.</p> + binaries in <c><anno>IoList</anno></c>.</p> <pre> > <input>Bin1 = <<1,2,3>>.</input> <<1,2,3>> @@ -1967,14 +1816,12 @@ os_prompt% </pre> </desc> </func> <func> - <name>list_to_bitstring(BitstringList) -> bitstring()</name> + <name name="list_to_bitstring" arity="1"/> + <type name="bitstring_list"/> <fsummary>Convert a list to a bitstring</fsummary> - <type> - <v>BitstringList = [BitstringList | bitstring() | char()]</v> - </type> <desc> <p>Returns a bitstring which is made from the integers and - bitstrings in <c>BitstringList</c>. (The last tail in <c>BitstringList</c> + bitstrings in <c><anno>BitstringList</anno></c>. (The last tail in <c><anno>BitstringList</anno></c> is allowed to be a bitstring.)</p> <pre> > <input>Bin1 = <<1,2,3>>.</input> @@ -1983,51 +1830,42 @@ os_prompt% </pre> <<4,5>> > <input>Bin3 = <<6,7:4,>>.</input> <<6>> -> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input> +> <input>list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).</input> <<1,2,3,1,2,3,4,5,4,6,7:46>></pre> </desc> </func> <func> - <name>list_to_existing_atom(String) -> atom()</name> + <name name="list_to_existing_atom" arity="1"/> <fsummary>Convert from text representation to an atom</fsummary> - <type> - <v>String = string()</v> - </type> <desc> - <p>Returns the atom whose text representation is <c>String</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>String</c>.</p> + whose text representation is <c><anno>String</anno></c>.</p> </desc> </func> <func> - <name>list_to_float(String) -> float()</name> + <name name="list_to_float" arity="1"/> <fsummary>Convert from text representation to a float</fsummary> - <type> - <v>String = string()</v> - </type> <desc> - <p>Returns the float whose text representation is <c>String</c>.</p> + <p>Returns the float whose text representation is <c><anno>String</anno></c>.</p> <pre> > <input>list_to_float("2.2017764e+0").</input> 2.2017764</pre> - <p>Failure: <c>badarg</c> if <c>String</c> contains a bad + <p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad representation of a float.</p> </desc> </func> <func> - <name>list_to_integer(String) -> integer()</name> + <name name="list_to_integer" arity="1"/> <fsummary>Convert from text representation to an integer</fsummary> - <type> - <v>String = string()</v> - </type> <desc> <p>Returns an integer whose text representation is - <c>String</c>.</p> + <c><anno>String</anno></c>.</p> <pre> > <input>list_to_integer("123").</input> 123</pre> - <p>Failure: <c>badarg</c> if <c>String</c> contains a bad + <p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad representation of an integer.</p> </desc> </func> @@ -2045,13 +1883,10 @@ os_prompt% </pre> </desc> </func> <func> - <name>list_to_pid(String) -> pid()</name> + <name name="list_to_pid" arity="1"/> <fsummary>Convert from text representation to a pid</fsummary> - <type> - <v>String = string()</v> - </type> <desc> - <p>Returns a pid whose text representation is <c>String</c>.</p> + <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 @@ -2060,18 +1895,15 @@ os_prompt% </pre> <pre> > <input>list_to_pid("<0.4.1>").</input> <0.4.1></pre> - <p>Failure: <c>badarg</c> if <c>String</c> contains a bad + <p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad representation of a pid.</p> </desc> </func> <func> - <name>list_to_tuple(List) -> tuple()</name> + <name name="list_to_tuple" arity="1"/> <fsummary>Convert a list to a tuple</fsummary> - <type> - <v>List = [term()]</v> - </type> <desc> - <p>Returns a tuple which corresponds to <c>List</c>. <c>List</c> + <p>Returns a tuple which corresponds to <c><anno>List</anno></c>. <c><anno>List</anno></c> can contain any Erlang terms.</p> <pre> > <input>list_to_tuple([share, ['Ericsson_B', 163]]).</input> @@ -2079,38 +1911,30 @@ os_prompt% </pre> </desc> </func> <func> - <name>load_module(Module, Binary) -> {module, Module} | {error, Reason}</name> + <name name="load_module" arity="2"/> <fsummary>Load object code for a module</fsummary> - <type> - <v>Module = atom()</v> - <v>Binary = binary()</v> - <v>Reason = badfile | not_purged | badfile</v> - </type> - <desc> - <p>If <c>Binary</c> contains the object code for the module - <c>Module</c>, this BIF loads that object code. Also, if - the code for the module <c>Module</c> already exists, all + <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 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, Module}</c>, or <c>{error, Reason}</c> if loading - fails. <c>Reason</c> is one of the following:</p> + <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> <taglist> <tag><c>badfile</c></tag> <item> - <p>The object code in <c>Binary</c> has an incorrect format.</p> + <p>The object code in <c><anno>Binary</anno></c> has an + incorrect format <em>or</em> the object code contains code + for another module than <c><anno>Module</anno></c>.</p> </item> <tag><c>not_purged</c></tag> <item> - <p><c>Binary</c> contains a module which cannot be loaded + <p><c><anno>Binary</anno></c> contains a module which cannot be loaded because old code for this module already exists.</p> </item> - <tag><c>badfile</c></tag> - <item> - <p>The object code contains code for another module than - <c>Module</c></p> - </item> </taglist> <warning> <p>This BIF is intended for the code server (see @@ -2120,15 +1944,8 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:load_nif(Path, LoadInfo) -> ok | {error, {Reason, Text}}</name> + <name name="load_nif" arity="2"/> <fsummary>Load NIF library</fsummary> - <type> - <v>Path = string()</v> - <v>LoadInfo = term()</v> - <v>Reason = load_failed | bad_lib | load | reload | - upgrade | old_code</v> - <v>Text = string()</v> - </type> <desc> <note> <p>In releases older than OTP R14B, NIFs were an @@ -2139,21 +1956,21 @@ os_prompt% </pre> <c>{error,Reason,Text}</c>.</p> </note> <p>Loads and links a dynamic library containing native - implemented functions (NIFs) for a module. <c>Path</c> is a + 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>LoadInfo</c> can be any term. It will be passed on to + <p><c><anno>LoadInfo</anno></c> can be any term. It will be 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,{Reason,Text}}</c> - if loading fails. <c>Reason</c> is one of the atoms below, - while <c>Text</c> is a human readable string that may give + <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> <taglist> <tag><c>load_failed</c></tag> @@ -2179,11 +1996,8 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:loaded() -> [Module]</name> + <name name="loaded" arity="0"/> <fsummary>List of all loaded modules</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> <p>Returns a list of all loaded Erlang modules (current and/or old code), including preloaded modules.</p> @@ -2191,11 +2005,8 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:localtime() -> DateTime</name> + <name name="localtime" arity="0"/> <fsummary>Current local date and time</fsummary> - <type> - <v>DateTime = <seealso marker="calendar#type-datetime">calendar:datetime()</seealso></v> - </type> <desc> <p>Returns the current local date and time <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c>.</p> @@ -2212,32 +2023,27 @@ os_prompt% </pre> <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>Date1</anno>, <anno>Time1</anno>}</c> is returned.</p> + no conversion is done and <c><anno>Localtime</anno></c> is returned.</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>Date1</c> or <c>Time1</c> do - not denote a valid date or time.</p> + <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> does not denote + a valid date and time.</p> </desc> </func> <func> - <name>erlang:localtime_to_universaltime({Date1, Time1}, IsDst) -> {Date2, Time2}</name> + <name name="localtime_to_universaltime" arity="2"/> <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary> - <type> - <v>Date1 = Date2 = <seealso marker="calendar#type-date">calendar:date()</seealso></v> - <v>Time1 = Time2 = <seealso marker="calendar#type-time">calendar:time()</seealso></v> - <v>IsDst = true | false | undefined</v> - </type> <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>IsDst == true</c> the <c>{Date1, Time1}</c> is during - daylight saving time, if <c>IsDst == false</c> it is not, - and if <c>IsDst == undefined</c> the underlying OS may + <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 guess, which is the same as calling - <c>erlang:localtime_to_universaltime({Date1, Time1})</c>.</p> + <c>erlang:localtime_to_universaltime(<anno>Localtime</anno>)</c>.</p> <pre> > <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).</input> {{1996,11,6},{12,45,17}} @@ -2245,12 +2051,12 @@ 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>Date1</c> or <c>Time1</c> do - not denote a valid date or time.</p> + <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> does not denote + a valid date and time.</p> </desc> </func> <func> - <name>make_ref() -> reference()</name> + <name name="make_ref" arity="0"/> <fsummary>Return an almost unique reference</fsummary> <desc> <p>Returns an almost unique reference.</p> @@ -2262,33 +2068,23 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:make_tuple(Arity, InitialValue) -> tuple()</name> + <name name="make_tuple" arity="2"/> <fsummary>Create a new tuple of a given arity</fsummary> - <type> - <v>Arity = arity()</v> - <v>InitialValue = term()</v> - </type> <desc> - <p>Returns a new tuple of the given <c>Arity</c>, where all - elements are <c>InitialValue</c>.</p> + <p>Returns a new tuple of the given <c><anno>Arity</anno></c>, where all + elements are <c><anno>InitialValue</anno></c>.</p> <pre> > <input>erlang:make_tuple(4, []).</input> {[],[],[],[]}</pre> </desc> </func> <func> - <name>erlang:make_tuple(Arity, Default, InitList) -> tuple()</name> + <name name="make_tuple" arity="3"/> <fsummary>Create a new tuple with given arity and contents</fsummary> - <type> - <v>Arity = arity()</v> - <v>Default = term()</v> - <v>InitList = [{Position,term()}]</v> - <v>Position = integer()</v> - </type> - <desc> - <p><c>erlang:make_tuple</c> first creates a tuple of size <c>Arity</c> - where each element has the value <c>Default</c>. It then fills - in values from <c>InitList</c>. Each list element in <c>InitList</c> + <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 @@ -2307,15 +2103,11 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:md5(Data) -> Digest</name> + <name name="md5" arity="1"/> <fsummary>Compute an MD5 message digest</fsummary> - <type> - <v>Data = iodata()</v> - <v>Digest = binary()</v> - </type> <desc> - <p>Computes an <c>MD5</c> message digest from <c>Data</c>, where - the length of the digest is 128 bits (16 bytes). <c>Data</c> + <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> 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> @@ -2324,51 +2116,39 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:md5_final(Context) -> Digest</name> + <name name="md5_final" arity="1"/> <fsummary>Finish the update of an MD5 context and return the computed MD5 message digest</fsummary> - <type> - <v>Context = Digest = binary()</v> - </type> <desc> - <p>Finishes the update of an MD5 <c>Context</c> and returns + <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>erlang:md5_init() -> Context</name> + <name name="md5_init" arity="0"/> <fsummary>Create an MD5 context</fsummary> - <type> - <v>Context = binary()</v> - </type> <desc> <p>Creates an MD5 context, to be used in subsequent calls to <c>md5_update/2</c>.</p> </desc> </func> <func> - <name>erlang:md5_update(Context, Data) -> NewContext</name> + <name name="md5_update" arity="2"/> <fsummary>Update an MD5 context with data, and return a new context</fsummary> - <type> - <v>Data = iodata()</v> - <v>Context = NewContext = binary()</v> - </type> <desc> - <p>Updates an MD5 <c>Context</c> with <c>Data</c>, and returns - a <c>NewContext</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>erlang:memory() -> [{Type, Size}]</name> + <name name="memory" arity="0"/> + <type name="memory_type"/> <fsummary>Information about dynamically allocated memory</fsummary> - <type> - <v>Type, Size -- see below</v> - </type> <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>Type</c>is an atom describing memory type. The second - element <c>Size</c>is memory size in bytes. A description of + <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> <taglist> <tag><c>total</c></tag> @@ -2430,6 +2210,14 @@ os_prompt% </pre> <p>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> + </item> <tag><c>maximum</c></tag> <item> <p>The maximum total amount of memory allocated since @@ -2441,14 +2229,6 @@ os_prompt% </pre> <seealso marker="tools:instrument">instrument(3)</seealso> and/or <seealso marker="erts:erl">erl(1)</seealso>.</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> - </item> </taglist> <note> <p>The <c>system</c> value is not complete. Some allocated @@ -2512,16 +2292,15 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:memory(Type | [Type]) -> Size | [{Type, Size}]</name> + <name name="memory" arity="1" clause_i="1"/> + <name name="memory" arity="1" clause_i="2"/> + <type name="memory_type"/> <fsummary>Information about dynamically allocated memory</fsummary> - <type> - <v>Type, Size -- see below</v> - </type> <desc> <p>Returns the memory size in bytes allocated for memory of - type <c>Type</c>. The argument can also be given as a list - of <c>Type</c> atoms, in which case a corresponding list of - <c>{Type, Size}</c> tuples is returned.</p> + 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 @@ -2533,13 +2312,13 @@ os_prompt% </pre> <taglist> <tag><c>badarg</c></tag> <item> - If <c>Type</c> is not one of the memory types listed in the + If <c><anno>Type</anno></c> is not one of the memory types listed in the documentation of <seealso marker="#memory/0">erlang:memory/0</seealso>. </item> <tag><c>badarg</c></tag> <item> - If <c>maximum</c> is passed as <c>Type</c> and the emulator + 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> @@ -2561,13 +2340,10 @@ os_prompt% </pre> </desc> </func> <func> - <name>module_loaded(Module) -> boolean()</name> + <name name="module_loaded" arity="1"/> <fsummary>Check if a module is loaded</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> - <p>Returns <c>true</c> if the module <c>Module</c> is loaded, + <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 the module.</p> <warning> @@ -2578,22 +2354,15 @@ os_prompt% </pre> </desc> </func> <func> - <name>monitor(Type, Item) -> MonitorRef</name> + <name name="monitor" arity="2"/> <fsummary>Start monitoring</fsummary> - <type> - <v>Type = process</v> - <v>Item = pid() | {RegName, Node} | RegName</v> - <v> RegName = atom()</v> - <v> Node = node()</v> - <v>MonitorRef = reference()</v> - </type> - <desc> - <p>The calling process starts monitoring <c>Item</c> which is - an object of type <c>Type</c>.</p> + <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>Type</c> is <c>process</c>, but other types may be + allowed <c><anno>Type</anno></c> is <c>process</c>, but other types may be allowed in the future.</p> - <p><c>Item</c> can be:</p> + <p><c><anno>Item</anno></c> can be:</p> <taglist> <tag><c>pid()</c></tag> <item> @@ -2619,8 +2388,8 @@ os_prompt% </pre> unregistered.</p> </note> <p>A <c>'DOWN'</c> message will be sent to the monitoring - process if <c>Item</c> dies, if <c>Item</c> does not exist, - or if the connection is lost to the node which <c>Item</c> + 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> @@ -2631,11 +2400,11 @@ os_prompt% </pre> <item> <p>A reference to the monitored object:</p> <list type="bulleted"> - <item>the pid of the monitored process, if <c>Item</c> was + <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>Item</c> was specified as + <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>Item</c> was specified as + <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> @@ -2644,7 +2413,7 @@ os_prompt% </pre> <item> <p>Either the exit reason of the process, <c>noproc</c> (non-existing process), or <c>noconnection</c> (no - connection to <c>Node</c>).</p> + connection to <c><anno>Node</anno></c>).</p> </item> </taglist> <note> @@ -2662,7 +2431,7 @@ os_prompt% </pre> 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>Item</c> is not an error; it results in as many, completely + <c><anno>Item</anno></c> is not an error; it results in as many, completely independent, monitorings.</p> <note> <p>The format of the <c>'DOWN'</c> message changed in the 5.2 @@ -2680,25 +2449,21 @@ os_prompt% </pre> </desc> </func> <func> - <name>monitor_node(Node, Flag) -> true</name> + <name name="monitor_node" arity="2"/> <fsummary>Monitor the status of a node</fsummary> - <type> - <v>Node = node()</v> - <v>Flag = boolean()</v> - </type> <desc> - <p>Monitors the status of the node <c>Node</c>. If <c>Flag</c> - is <c>true</c>, monitoring is turned on; if <c>Flag</c> is + <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>Node</c> is not an error; it results in as many, + the same <c><anno>Node</anno></c> is not an error; it results in as many, completely independent, monitorings.</p> - <p>If <c>Node</c> fails or does not exist, the message + <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>Node</c> terminates, two <c>nodedown</c> messages are + and <c><anno>Node</anno></c> terminates, two <c>nodedown</c> messages are delivered to the process. If there is no connection to - <c>Node</c>, there will be an attempt to create one. If this + <c><anno>Node</anno></c>, there will be an attempt 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> @@ -2706,14 +2471,8 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:monitor_node(Node, Flag, Options) -> true</name> + <name name="monitor_node" arity="3"/> <fsummary>Monitor the status of a node</fsummary> - <type> - <v>Node = node()</v> - <v>Flag = boolean()</v> - <v>Options = [Option]</v> - <v>Option = allow_passive_connect</v> - </type> <desc> <p>Behaves as <c>monitor_node/2</c> except that it allows an extra option to be given, namely <c>allow_passive_connect</c>. @@ -2736,11 +2495,8 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:nif_error(Reason)</name> + <name name="nif_error" arity="1"/> <fsummary>Stop execution with a given reason</fsummary> - <type> - <v>Reason = term()</v> - </type> <desc> <p>Works exactly like <seealso marker="#error/1">erlang:error/1</seealso>, @@ -2751,12 +2507,8 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:nif_error(Reason, Args)</name> + <name name="nif_error" arity="2"/> <fsummary>Stop execution with a given reason</fsummary> - <type> - <v>Reason = term()</v> - <v>Args = [term()]</v> - </type> <desc> <p>Works exactly like <seealso marker="#error/2">erlang:error/2</seealso>, @@ -2767,11 +2519,8 @@ os_prompt% </pre> </desc> </func> <func> - <name>node() -> Node</name> + <name name="node" arity="0"/> <fsummary>Name of the local node</fsummary> - <type> - <v>Node = node()</v> - </type> <desc> <p>Returns the name of the local node. If the node is not alive, <c>nonode@nohost</c> is returned instead.</p> @@ -2779,14 +2528,10 @@ os_prompt% </pre> </desc> </func> <func> - <name>node(Arg) -> Node</name> + <name name="node" arity="1"/> <fsummary>At which node is a pid, port or reference located</fsummary> - <type> - <v>Arg = pid() | port() | reference()</v> - <v>Node = node()</v> - </type> <desc> - <p>Returns the node where <c>Arg</c> is located. <c>Arg</c> can + <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 alive, <c>nonode@nohost</c> is returned.</p> <p>Allowed in guard tests.</p> @@ -2801,17 +2546,13 @@ os_prompt% </pre> </desc> </func> <func> - <name>nodes(Arg | [Arg]) -> Nodes</name> + <name name="nodes" arity="1"/> <fsummary>All nodes of a certain type in the system</fsummary> - <type> - <v>Arg = visible | hidden | connected | this | known</v> - <v>Nodes = [node()]</v> - </type> <desc> <p>Returns a list of nodes according to argument given. The result returned when the argument is a list, is the list of nodes satisfying the disjunction(s) of the list elements.</p> - <p><c>Arg</c> can be any of the following:</p> + <p><c><anno>NodeType</anno></c> can be any of the following:</p> <taglist> <tag><c>visible</c></tag> <item> @@ -2840,15 +2581,12 @@ os_prompt% </pre> <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>Arg</c> the empty list [] is returned.</p> + any other <c><anno>Arg</anno></c> the empty list [] is returned.</p> </desc> </func> <func> - <name>now() -> timestamp()</name> - <type> - <v>timestamp() = {MegaSecs, Secs, MicroSecs}</v> - <v>MegaSecs = Secs = MicroSecs = integer() >= 0</v> - </type> + <name name="now" arity="0"/> + <type name="timestamp"/> <fsummary>Elapsed time since 00:00 GMT</fsummary> <desc> <p>Returns the tuple <c>{MegaSecs, Secs, MicroSecs}</c> which is @@ -2870,35 +2608,19 @@ os_prompt% </pre> </desc> </func> <func> - <name>open_port(PortName, PortSettings) -> port()</name> + <name name="open_port" arity="2"/> <fsummary>Open a port</fsummary> - <type> - <v>PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, FileName} | {fd, In, Out}</v> - <v> Command = string()</v> - <v> FileName = [ FileNameChar ] | binary()</v> - <v> FileNameChar = integer() (1..255 or any Unicode codepoint, see description)</v> - <v> In = Out = integer()</v> - <v>PortSettings = [Opt]</v> - <v> Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ ArgString ]} | {arg0, ArgString} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v> - <v> N = 1 | 2 | 4</v> - <v> L = integer()</v> - <v> Dir = string()</v> - <v> ArgString = [ FileNameChar ] | binary()</v> - <v> Env = [{Name, Val}]</v> - <v> Name = string()</v> - <v> Val = string() | false</v> - </type> <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. <c>PortName</c> is one of the following:</p> + process. <c><anno>PortName</anno></c> is one of the following:</p> <taglist> - <tag><c>{spawn, Command}</c></tag> + <tag><c>{spawn, <anno>Command</anno>}</c></tag> <item> - <p>Starts an external program. <c>Command</c> is the name - of the external program which will be run. <c>Command</c> + <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> runs outside the Erlang work space unless an Erlang - driver with the name <c>Command</c> is found. If found, + 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 runtime system.</p> @@ -2918,24 +2640,24 @@ os_prompt% </pre> 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, Command} instead if spaces in executable + {spawn_executable, <anno>Command</anno>} instead if spaces in executable file names is desired.</p> </item> - <tag><c>{spawn_driver, Command}</c></tag> + <tag><c>{spawn_driver, <anno>Command</anno>}</c></tag> <item> - <p>Works like <c>{spawn, Command}</c>, but demands the + <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 loaded driver. If no driver with that name is loaded, a <c>badarg</c> error is raised.</p> </item> - <tag><c>{spawn_executable, Command}</c></tag> + <tag><c>{spawn_executable, <anno>FileName</anno>}</c></tag> <item> - <p>Works like <c>{spawn, Command}</c>, but only runs - external executables. The <c>Command</c> in its whole + <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>PortSettings</c> can be used.</p> + <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 @@ -2966,7 +2688,7 @@ os_prompt% </pre> of the executable is limited to the ISO-latin-1 character set.</p></note> - <p>If the <c>Command</c> cannot be run, an error + <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 @@ -2974,23 +2696,23 @@ os_prompt% </pre> <c>eaccess</c> is raised when the given file is not executable.</p> </item> - <tag><c>{fd, In, Out}</c></tag> + <tag><c>{fd, <anno>In</anno>, <anno>Out</anno>}</c></tag> <item> <p>Allows an Erlang process to access any currently opened file descriptors used by Erlang. The file descriptor - <c>In</c> can be used for standard input, and the file - descriptor <c>Out</c> for standard output. It is only + <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> </item> </taglist> - <p><c>PortSettings</c> is a list of settings for the port. + <p><c><anno>PortSettings</anno></c> is a list of settings for the port. Valid settings are:</p> <taglist> - <tag><c>{packet, N}</c></tag> + <tag><c>{packet, <anno>N</anno>}</c></tag> <item> - <p>Messages are preceded by their length, sent in <c>N</c> + <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> </item> @@ -3000,7 +2722,7 @@ os_prompt% </pre> user-defined protocol must be used between the Erlang process and the external object.</p> </item> - <tag><c>{line, L}</c></tag> + <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 @@ -3008,7 +2730,7 @@ os_prompt% </pre> 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> - <p><c>L</c> specifies the maximum line length in bytes. + <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 but the last message. If end of file is encountered @@ -3016,39 +2738,40 @@ os_prompt% </pre> sequence, the last line will also be delivered with the <c>Flag</c> set to <c>noeol</c>. In all other cases, lines are delivered with <c>Flag</c> set to <c>eol</c>.</p> - <p>The <c>{packet, N}</c> and <c>{line, L}</c> settings are + <p>The <c>{packet, <anno>N</anno>}</c> and <c>{line, <anno>L</anno>}</c> settings are mutually exclusive.</p> </item> - <tag><c>{cd, Dir}</c></tag> + <tag><c>{cd, <anno>Dir</anno>}</c></tag> <item> - <p>This is only valid for <c>{spawn, Command}</c> and - <c>{spawn_executable, Command}</c>. - The external program starts using <c>Dir</c> as its - working directory. <c>Dir</c> must be a string. Not - available on VxWorks.</p> + <p>This is 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> </item> - <tag><c>{env, Env}</c></tag> + <tag><c>{env, <anno>Env</anno>}</c></tag> <item> - <p>This is only valid for <c>{spawn, Command}</c> and - <c>{spawn_executable, Command}</c>. + <p>This is 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>Env</c>.</p> - <p><c>Env</c> should be a list of tuples <c>{Name, Val}</c>, - where <c>Name</c> is the name of an environment variable, - and <c>Val</c> is the value it is to have in the spawned - port process. Both <c>Name</c> and <c>Val</c> must be - strings. The one exception is <c>Val</c> being the atom + 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 <c>false</c> (in analogy with <c>os:getenv/1</c>), which - removes the environment variable.</p> + removes the environment variable. + </p> <p>If Unicode filename encoding is in effect (see the <seealso marker="erts:erl#file_name_encoding">erl manual page</seealso>), the strings (both <c>Name</c> and <c>Value</c>) may contain characters with codepoints > 255.</p> </item> - <tag><c>{args, [ string() ]}</c></tag> + <tag><c>{args, [ string() | binary() ]}</c></tag> <item> - <p>This option is only valid for <c>{spawn_executable, Command}</c> + <p>This option is 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 @@ -3091,10 +2814,10 @@ os_prompt% </pre> option can be used.</p> </item> - <tag><c>{arg0, string()}</c></tag> + <tag><c>{arg0, string() | binary()}</c></tag> <item> - <p>This option is only valid for <c>{spawn_executable, Command}</c> + <p>This option is 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 @@ -3108,9 +2831,9 @@ os_prompt% </pre> <tag><c>exit_status</c></tag> <item> - <p>This is only valid for <c>{spawn, Command}</c> where - <c>Command</c> refers to an external program, and for - <c>{spawn_executable, Command}</c>.</p> + <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>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 @@ -3125,8 +2848,8 @@ os_prompt% </pre> </item> <tag><c>use_stdio</c></tag> <item> - <p>This is only valid for <c>{spawn, Command}</c> and - <c>{spawn_executable, Command}</c>. It + <p>This is 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 with Erlang.</p> @@ -3180,6 +2903,18 @@ os_prompt% </pre> 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> + <item> + <p>Set scheduler hint for port parallelism. If set to <c>true</c>, + the VM will schedule port tasks when it by this can improve the + parallelism in the system. If set to <c>false</c>, the VM will + try to perform port tasks immediately and by this improving the + 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> + </item> </taglist> <p>The default is <c>stream</c> for all types of port and <c>use_stdio</c> for spawned ports.</p> @@ -3223,7 +2958,7 @@ os_prompt% </pre> </item> <tag><c>enoent</c></tag> <item> - <p>The <c>Command</c> given in <c>{spawn_executable, Command}</c> does not point out an existing file.</p> + <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> </taglist> <p>During use of a port opened using <c>{spawn, Name}</c>, @@ -3232,63 +2967,55 @@ os_prompt% </pre> 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> - <p><marker id="ERL_MAX_PORTS"></marker> - The maximum number of ports that can be open at the same - time is 1024 by default, but can be configured by - the environment variable <c>ERL_MAX_PORTS</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> </desc> </func> <func> - <name>erlang:phash(Term, Range) -> Hash</name> + <name name="phash" arity="2"/> + <type_desc variable="Range">Range = 1..2^32, Hash = 1..Range</type_desc> <fsummary>Portable hash function</fsummary> - <type> - <v>Term = term()</v> - <v>Range = 1..2^32</v> - <v>Hash = 1..Range</v> - </type> <desc> <p>Portable hash function that will give 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>Term</c> within the range <c>1..Range</c>.</p> + 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> </desc> </func> <func> - <name>erlang:phash2(Term [, Range]) -> Hash</name> + <name name="phash2" arity="1"/> + <name name="phash2" arity="2"/> + <type_desc variable="Range">1..2^32</type_desc> + <type_desc variable="Hash">0..Range-1</type_desc> <fsummary>Portable hash function</fsummary> - <type> - <v>Term = term()</v> - <v>Range = 1..2^32</v> - <v>Hash = 0..Range-1</v> - </type> <desc> <p>Portable hash function that will give 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>Term</c> within the range <c>0..Range-1</c>. When called - without the <c>Range</c> argument, a value in the range + <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 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..Range-1</c> is different from - the range of <c>phash/2</c> (<c>1..Range</c>).</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> </desc> </func> <func> - <name>pid_to_list(Pid) -> string()</name> + <name name="pid_to_list" arity="1"/> <fsummary>Text representation of a pid</fsummary> - <type> - <v>Pid = pid()</v> - </type> <desc> <p>Returns a string which corresponds to the text - representation of <c>Pid</c>.</p> + 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 @@ -3297,88 +3024,81 @@ os_prompt% </pre> </desc> </func> <func> - <name>port_close(Port) -> true</name> + <name name="port_close" arity="1"/> <fsummary>Close an open port</fsummary> - <type> - <v>Port = port() | atom()</v> - </type> <desc> <p>Closes an open port. Roughly the same as - <c>Port ! {self(), close}</c> except for the error behaviour - (see below), and that the port does <em>not</em> reply with - <c>{Port, closed}</c>. Any process may close a port with - <c>port_close/1</c>, not only the port owner (the connected - process).</p> - <p>For comparison: <c>Port ! {self(), close}</c> fails with - <c>badarg</c> if <c>Port</c> cannot be sent to (i.e., - <c>Port</c> refers neither to a port nor to a process). If - <c>Port</c> is a closed port nothing happens. If <c>Port</c> + <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 + close a port with <c>port_close/1</c>, not only the port owner + (the connected process).</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> 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>Port ! {PortOwner, close}</c> just as if it itself was + <c><anno>Port</anno> ! {PortOwner, close}</c> just as if it itself was the port owner, but the reply always goes to the port owner.</p> - <p>In short: <c>port_close(Port)</c> has a cleaner and more - logical behaviour than <c>Port ! {self(), close}</c>.</p> - <p>Failure: <c>badarg</c> if <c>Port</c> is not an open port or + <p>As of OTP-R16 <c><anno>Port</anno> ! {PortOwner, close}</c> is truly + asynchronous. Note 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 + behavior.</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.</p> </desc> </func> <func> - <name>port_command(Port, Data) -> true</name> + <name name="port_command" arity="2"/> <fsummary>Send data to a port</fsummary> - <type> - <v>Port = port() | atom()</v> - <v>Data = iodata()</v> - </type> <desc> <p>Sends data to a port. Same as - <c>Port ! {self(), {command, Data}}</c> except for the error - behaviour (see below). Any process may send data to a port - with <c>port_command/2</c>, not only the port owner - (the connected process).</p> - <p>For comparison: <c>Port ! {self(), {command, Data}}</c> - fails with <c>badarg</c> if <c>Port</c> cannot be sent to - (i.e., <c>Port</c> refers neither to a port nor to a process). - If <c>Port</c> is a closed port the data message disappears - without a sound. If <c>Port</c> is open and the calling + <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 + 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 + 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>Data</c> is not a valid IO list.</p> + 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>Port ! {PortOwner, {command, Data}}</c> just as if it + <c><anno>Port</anno> ! {PortOwner, {command, <anno>Data</anno>}}</c> just as if it itself was the port owner.</p> - <p>In short: <c>port_command(Port, Data)</c> has a cleaner and - more logical behaviour than - <c>Port ! {self(), {command, Data}}</c>.</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 + 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 + behavior.</p> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> <item> - If <c>Port</c> is not an open port or the registered name + 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>Data</c> is not a valid io list. + If <c><anno>Data</anno></c> is not a valid io list. </item> </taglist> </desc> </func> <func> - <name>port_command(Port, Data, OptionList) -> boolean()</name> + <name name="port_command" arity="3"/> <fsummary>Send data to a port</fsummary> - <type> - <v>Port = port() | atom()</v> - <v>Data = iodata()</v> - <v>OptionList = [Option]</v> - <v>Option = force</v> - <v>Option = nosuspend</v> - </type> <desc> <p>Sends data to a port. <c>port_command(Port, Data, [])</c> equals <c>port_command(Port, Data)</c>.</p> @@ -3386,7 +3106,7 @@ os_prompt% </pre> 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>Option</c>s are valid:</p> + <p>Currently 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 @@ -3410,16 +3130,16 @@ os_prompt% </pre> <taglist> <tag><c>badarg</c></tag> <item> - If <c>Port</c> is not an open port or the registered name + 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>Data</c> is not a valid io list. + If <c><anno>Data</anno></c> is not a valid io list. </item> <tag><c>badarg</c></tag> <item> - If <c>OptionList</c> is not a valid option list. + If <c><anno>OptionList</anno></c> is not a valid option list. </item> <tag><c>notsup</c></tag> <item> @@ -3431,15 +3151,11 @@ os_prompt% </pre> </desc> </func> <func> - <name>port_connect(Port, Pid) -> true</name> + <name name="port_connect" arity="2"/> <fsummary>Set the owner of a port</fsummary> - <type> - <v>Port = port() | atom()</v> - <v>Pid = pid()</v> - </type> <desc> - <p>Sets the port owner (the connected port) to <c>Pid</c>. - Roughly the same as <c>Port ! {self(), {connect, Pid}}</c> + <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> except for the following:</p> <list type="bulleted"> <item> @@ -3450,6 +3166,9 @@ os_prompt% </pre> <c>{Port,connected}</c>.</p> </item> <item> + <p><c>port_connect/1</c> is synchronous, see below.</p> + </item> + <item> <p>The new port owner gets linked to the port.</p> </item> </list> @@ -3457,164 +3176,265 @@ os_prompt% </pre> <c>unlink(Port)</c> if this is not desired. Any process may set the port owner to be any process with <c>port_connect/2</c>.</p> - <p>For comparison: <c>Port ! {self(), {connect, Pid}}</c> fails - with <c>badarg</c> if <c>Port</c> cannot be sent to (i.e., - <c>Port</c> refers neither to a port nor to a process). If - <c>Port</c> is a closed port nothing happens. If <c>Port</c> + <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> 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>Port</c> is an open + the port, and that 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>Pid</c> is not an + 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>Port ! {PortOwner, {connect, Pid}}</c> just as if it + <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 the port owner.</p> - <p>In short: <c>port_connect(Port, Pid)</c> has a cleaner and - more logical behaviour than - <c>Port ! {self(),{connect,Pid}}</c>.</p> - <p>Failure: <c>badarg</c> if <c>Port</c> is not an open port + <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 + 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 + behavior.</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, or if <c>Pid</c> is not an existing local pid.</p> </desc> </func> <func> - <name>port_control(Port, Operation, Data) -> Res</name> + <name name="port_control" arity="3"/> <fsummary>Perform a synchronous control operation on a port</fsummary> - <type> - <v>Port = port() | atom()</v> - <v>Operation = integer()</v> - <v>Data = Res = iodata()</v> - </type> <desc> <p>Performs a synchronous control operation on a port. - The meaning of <c>Operation</c> and <c>Data</c> depends on + 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 support this control feature.</p> <p>Returns: a list of integers in the range 0 through 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>Port</c> is not an open port or - the registered name of an open port, if <c>Operation</c> + <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>Operation</c> or <c>Data</c>).</p> + <c><anno>Operation</anno></c> or <c><anno>Data</anno></c>).</p> </desc> </func> <func> - <name>erlang:port_call(Port, Operation, Data) -> term()</name> + <name name="port_call" arity="3"/> <fsummary>Synchronous call to a port with term data</fsummary> - <type> - <v>Port = port() | atom()</v> - <v>Operation = integer()</v> - <v>Data = term()</v> - </type> <desc> <p>Performs a synchronous call to a port. The meaning of - <c>Operation</c> and <c>Data</c> depends on the port, i.e., + <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 support this feature.</p> - <p><c>Port</c> is a port identifier, referring to a driver.</p> - <p><c>Operation</c> is an integer, which is passed on to + <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>Data</c> is any Erlang term. This data is converted to + <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>Failure: <c>badarg</c> if <c>Port</c> is not an open port or - the registered name of an open port, if <c>Operation</c> + <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>Operation</c> or <c>Data</c>).</p> + <c><anno>Operation</anno></c> or <c><anno>Data</anno></c>).</p> </desc> </func> <func> - <name>erlang:port_info(Port) -> [{Item, Info}] | undefined</name> + <name name="port_info" arity="1"/> <fsummary>Information about a port</fsummary> - <type> - <v>Port = port() | atom()</v> - <v>Item, Info -- see below</v> - </type> <desc> <p>Returns a list containing tuples with information about - the <c>Port</c>, or <c>undefined</c> if the port is not open. + 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.</p> - <taglist> - <tag><c>{registered_name, RegName}</c></tag> - <item> - <p><c>RegName</c> (an atom) is the registered name of - the port. If the port has no registered name, this tuple - is not present in the list.</p> - </item> - <tag><c>{id, Index}</c></tag> - <item> - <p><c>Index</c> (an integer) is the internal index of the - port. This index may be used to separate ports.</p> - </item> - <tag><c>{connected, Pid}</c></tag> - <item> - <p><c>Pid</c> is the process connected to the port.</p> - </item> - <tag><c>{links, Pids}</c></tag> - <item> - <p><c>Pids</c> is a list of pids to which processes the - port is linked.</p> - </item> - <tag><c>{name, String}</c></tag> - <item> - <p><c>String</c> is the command name set by - <c>open_port</c>.</p> - </item> - <tag><c>{input, Bytes}</c></tag> - <item> - <p><c>Bytes</c> is the total number of bytes read from - the port.</p> - </item> - <tag><c>{output, Bytes}</c></tag> - <item> - <p><c>Bytes</c> is the total number of bytes written to - the port.</p> - </item> - <tag><c>{os_pid, Integer | undefined}</c></tag> - <item> - <p><c>Integer</c> is the process identifier (or equivalent) of an OS process created with <c>open_port({spawn | spawn_executable, Command}, Options)</c>. If the port is not the result of spawning an OS process, the value is <c>undefined</c>.</p> - </item> - </taglist> - <p>Failure: <c>badarg</c> if <c>Port</c> is not a local port.</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 + <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>erlang:port_info(Port, Item) -> {Item, Info} | undefined | []</name> - <fsummary>Information about a port</fsummary> - <type> - <v>Port = port() | atom()</v> - <v>Item, Info -- see below</v> - </type> + <name name="port_info" arity="2" clause_i="1"/> + <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.</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> + <desc> + <p><c><anno>Index</anno></c> is the internal index of the port. This + index may 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.</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> + <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.</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> + <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.</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> + <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>If the port identified by <c><anno>Port</anno></c> is not open, + <c>undefined</c> is returned.</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> + <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 + 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.</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> + <desc> + <p><c><anno>Monitors</anno></c> represent processes that this port + is monitoring.</p> + <p>If the port identified by <c><anno>Port</anno></c> is not open, + <c>undefined</c> is returned.</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> <desc> - <p>Returns information about <c>Port</c> as specified - by <c>Item</c>, or <c>undefined</c> if the port is not open. - Also, if <c>Item == registered_name</c> and the port has no - registered name, [] is returned.</p> - <p>For valid values of <c>Item</c>, and corresponding - values of <c>Info</c>, see - <seealso marker="#port_info/1">erlang:port_info/1</seealso>.</p> - <p>Failure: <c>badarg</c> if <c>Port</c> is not a local port.</p> + <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.</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>erlang:port_to_list(Port) -> string()</name> + <name name="port_info" arity="2" clause_i="9"/> + <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 + <seealso marker="#open_port/2">open_port({spawn | spawn_executable, + 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.</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> + <desc> + <p><c><anno>Bytes</anno></c> is the total number of bytes written + to the port from Erlang processes using either + <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> + <p>If the port identified by <c><anno>Port</anno></c> is not open, + <c>undefined</c> is returned.</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> + <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> + </desc> + </func> + <func> + <name name="port_info" arity="2" clause_i="12"/> + <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 + implementation.</p> + <p>If the port identified by <c><anno>Port</anno></c> is not open, + <c>undefined</c> is returned.</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> + <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.</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> - <type> - <v>Port = port()</v> - </type> <desc> <p>Returns a string which corresponds to the text - representation of the port identifier <c>Port</c>.</p> + 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 @@ -3623,18 +3443,18 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:ports() -> [port()]</name> + <name name="ports" arity="0"/> <fsummary>All open ports</fsummary> <desc> - <p>Returns a list of all ports on the local node.</p> + <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> </desc> </func> <func> - <name>pre_loaded() -> [Module]</name> + <name name="pre_loaded" arity="0"/> <fsummary>List of all pre-loaded modules</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> <p>Returns a list of Erlang modules which are pre-loaded in the system. As all loading of code is done through the file @@ -3643,220 +3463,222 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:process_display(Pid, Type) -> void()</name> + <name name="process_display" arity="2"/> <fsummary>Write information about a local process on standard error</fsummary> - <type> - <v>Pid = pid()</v> - <v>Type = backtrace</v> - </type> <desc> - <p>Writes information about the local process <c>Pid</c> on + <p>Writes information about the local process <c><anno>Pid</anno></c> on standard error. The currently allowed value for the atom - <c>Type</c> is <c>backtrace</c>, which shows the contents of + <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>process_flag(Flag, Value) -> OldValue</name> - <fsummary>Set process flags for the calling process</fsummary> - <type> - <v>Flag, Value, OldValue -- see below</v> - </type> + <name name="process_flag" arity="2" clause_i="1"/> + <fsummary>Set process flag trap_exit for the calling process</fsummary> <desc> - <p>Sets certain flags for the process which calls this - function. Returns the old value of the flag.</p> - <taglist> - <tag><c>process_flag(trap_exit, Boolean)</c></tag> - <item> - <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 - 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> - <p>See also <seealso marker="#exit/2">exit/2</seealso>.</p> - </item> - <tag><c>process_flag(error_handler, Module)</c></tag> - <item> - <p>This is 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 - operation of the error handling module.</p> - </item> - <tag><c>process_flag(min_heap_size, MinHeapSize)</c></tag> - <item> - <p>This changes the minimum heap size for the calling - process.</p> - </item> - <tag><c>process_flag(min_bin_vheap_size, MinBinVHeapSize)</c></tag> - <item> - <p>This changes the minimum binary virtual heap size for the calling - process.</p> - </item> - <tag><marker id="process_flag_priority"><c>process_flag(priority, Level)</c></marker></tag> - <item> - <p>This sets the process priority. <c>Level</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> - <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> - 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> - <p>Scheduling is preemptive. Regardless of priority, a process - is preempted when it has consumed more than a certain amount - of reductions since the last time it was selected for - execution. - </p> - <p><em>NOTE</em>: You should 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> - <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 - <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> - <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> - </item> - - <tag><c>process_flag(save_calls, N)</c></tag> - <item> - <p><c>N</c> must be an integer in the interval 0..10000. - If <c>N</c> > 0, call saving is made active for the - process, which means that information about the <c>N</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, - 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> - </item> - <tag><c>process_flag(sensitive, Boolean)</c></tag> - <item> - <p>Set or clear the <c>sensitive</c> flag 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 - 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> - <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> - <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> - </item> - </taglist> + <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 + 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> + <p>Returns the old value of the flag.</p> + <p>See also <seealso marker="#exit/2">exit/2</seealso>.</p> </desc> </func> <func> - <name>process_flag(Pid, Flag, Value) -> OldValue</name> + <name name="process_flag" arity="2" clause_i="2"/> + <fsummary>Set process flag error_handler for the calling process</fsummary> + <desc> + <p>This is 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 + 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> + <desc> + <p>This 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> + <desc> + <p>This changes the minimum binary virtual 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="5"/> + <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> + <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> + 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> + <p>Scheduling is preemptive. Regardless of priority, a process + is preempted when it has consumed more than a certain amount + of reductions since the last time it was selected for + execution. + </p> + <p><em>NOTE</em>: You should 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> + <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 + <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> + <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> + <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> + <desc> + <p><c><anno>N</anno></c> must be an integer in the interval 0..10000. + If <c><anno>N</anno></c> > 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 + 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, + 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> + <desc> + <p>Set or clear the <c>sensitive</c> flag 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 + 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> + <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> + <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> + <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> - <type> - <v>Pid = pid()</v> - <v>Flag, Value, OldValue -- see below</v> - </type> <desc> - <p>Sets certain flags for the process <c>Pid</c>, in the same + <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 - <c>Flag</c> are only a subset of those allowed in + <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>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>process_info(Pid) -> InfoResult</name> + <name name="process_info" arity="1"/> + <type name="process_info_result_item"/> + <type name="priority_level"/> + <type name="stack_item"/> <fsummary>Information about a process</fsummary> - <type> - <v>Pid = pid()</v> - <v>Item = atom()</v> - <v>Info = term()</v> - <v>InfoTuple = {Item, Info}</v> - <v>InfoTupleList = [InfoTuple]</v> - <v>InfoResult = InfoTupleList | undefined</v> - </type> - <desc> - <p>Returns a list containing <c>InfoTuple</c>s with + <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>InfoTuple</c>s is not defined, nor - are all the <c>InfoTuple</c>s mandatory. The <c>InfoTuple</c>s + 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>InfoTuple</c>s with the following <c>Item</c>s + 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>, @@ -3864,12 +3686,12 @@ os_prompt% </pre> <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>Pid</c> has a registered name - also an <c>InfoTuple</c> with <c>Item == registered_name</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>InfoTuple</c>s.</p> + for information about specific <c><anno>InfoTuple</anno></c>s.</p> <warning> <p>This BIF is intended for <em>debugging only</em>, use <seealso marker="#process_info/2">process_info/2</seealso> @@ -3880,113 +3702,108 @@ os_prompt% </pre> </desc> </func> <func> - <name>process_info(Pid, ItemSpec) -> InfoResult</name> + <name name="process_info" arity="2" clause_i="1"/> + <name name="process_info" arity="2" clause_i="2"/> + <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> - <type> - <v>Pid = pid()</v> - <v>Item = atom()</v> - <v>Info = term()</v> - <v>ItemList = [Item]</v> - <v>ItemSpec = Item | ItemList</v> - <v>InfoTuple = {Item, Info}</v> - <v>InfoTupleList = [InfoTuple]</v> - <v>InfoResult = InfoTuple | InfoTupleList | undefined | []</v> - </type> - <desc> - <p>Returns information about the process identified by <c>Pid</c> - as specified by the <c>ItemSpec</c>, or <c>undefined</c> if the + <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 <c>ItemSpec</c> is a single - <c>Item</c>, the returned value is the corresponding - <c>InfoTuple</c> unless <c>ItemSpec == registered_name</c> + <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 <c>ItemSpec</c> is an <c>ItemList</c>, the result is an - <c>InfoTupleList</c>. The <c>InfoTuple</c>s in the - <c>InfoTupleList</c> will appear with the corresponding - <c>Item</c>s in the same order as the <c>Item</c>s appeared - in the <c>ItemList</c>. Valid <c>Item</c>s may appear multiple - times in the <c>ItemList</c>. + <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>ItemList</c> + <note><p>If <c>registered_name</c> is part of an <c><anno>ItemList</anno></c> and the process has no name registered a - <c>{registered_name, []}</c> <c>InfoTuple</c> <em>will</em> - appear in the resulting <c>InfoTupleList</c>. This - behavior is different than when - <c>ItemSpec == registered_name</c>, and than when + <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>InfoTuple</c>s with corresponding - <c>Item</c>s are valid:</p> + <p>Currently the following <c><anno>InfoTuple</anno></c>s with corresponding + <c><anno>Item</anno></c>s are valid:</p> <taglist> - <tag><c>{backtrace, Bin}</c></tag> + <tag><c>{backtrace, <anno>Bin</anno>}</c></tag> <item> - <p>The binary <c>Bin</c> contains the same information as + <p>The binary <c><anno>Bin</anno></c> contains the same information as the output from - <c>erlang:process_display(Pid, backtrace)</c>. Use + <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, BinInfo}</c></tag> + <tag><c>{binary, <anno>BinInfo</anno>}</c></tag> <item> - <p><c>BinInfo</c> is a list containing miscellaneous information + <p><c><anno>BinInfo</anno></c> is a list containing miscellaneous information about binaries currently being referred to by this process. - This <c>InfoTuple</c> may be changed or removed without prior + This <c><anno>InfoTuple</anno></c> may be changed or removed without prior notice.</p> </item> - <tag><c>{catchlevel, CatchLevel}</c></tag> + <tag><c>{catchlevel, <anno>CatchLevel</anno>}</c></tag> <item> - <p><c>CatchLevel</c> is the number of currently active - catches in this process. This <c>InfoTuple</c> may be + <p><c><anno>CatchLevel</anno></c> is the number of currently active + catches in this process. This <c><anno>InfoTuple</anno></c> may be changed or removed without prior notice.</p> </item> - <tag><c>{current_function, {Module, Function, Arity}}</c></tag> + <tag><c>{current_function, {<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 current function call of the process.</p> </item> - <tag><c>{current_location, {Module, Function, Arity, Location}}</c></tag> + <tag><c>{current_location, {<anno>Module</anno>, <anno>Function</anno>, <anno>Arity</anno>, <anno>Location</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 current function call of the process. - <c>Location</c> is a list of two-tuples that describes the + <c><anno>Location</anno></c> is a list of two-tuples that describes the location in the source code. </p> </item> - <tag><c>{current_stacktrace, Stack}</c></tag> + <tag><c>{current_stacktrace, <anno>Stack</anno>}</c></tag> <item> <p>Return 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> </item> - <tag><c>{dictionary, Dictionary}</c></tag> + <tag><c>{dictionary, <anno>Dictionary</anno>}</c></tag> <item> - <p><c>Dictionary</c> is the dictionary of the process.</p> + <p><c><anno>Dictionary</anno></c> is the dictionary of the process.</p> </item> - <tag><c>{error_handler, Module}</c></tag> + <tag><c>{error_handler, <anno>Module</anno>}</c></tag> <item> - <p><c>Module</c> is the error handler module used by + <p><c><anno>Module</anno></c> is the error handler module used by the process (for undefined function calls, for example).</p> </item> - <tag><c>{garbage_collection, GCInfo}</c></tag> + <tag><c>{garbage_collection, <anno>GCInfo</anno>}</c></tag> <item> - <p><c>GCInfo</c> is a list which contains miscellaneous + <p><c><anno>GCInfo</anno></c> is a list which contains miscellaneous information about garbage collection for this process. - The content of <c>GCInfo</c> may be changed without + The content of <c><anno>GCInfo</anno></c> may be changed without prior notice.</p> </item> - <tag><c>{group_leader, GroupLeader}</c></tag> + <tag><c>{group_leader, <anno>GroupLeader</anno>}</c></tag> <item> - <p><c>GroupLeader</c> is group leader for the IO of + <p><c><anno>GroupLeader</anno></c> is group leader for the IO of the process.</p> </item> - <tag><c>{heap_size, Size}</c></tag> + <tag><c>{heap_size, <anno>Size</anno>}</c></tag> <item> - <p><c>Size</c> is the size in words of youngest heap generation + <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. @@ -3998,10 +3815,11 @@ os_prompt% </pre> the initial function call with which the process was spawned.</p> </item> - <tag><c>{links, PidsAndPorts}</c></tag> + <tag><c>{links, <anno>PidsAndPorts</anno>}</c></tag> <item> - <p><c>PidsAndPorts</c> is a list of pids and port identifiers, with - processes or ports to which the process has a link.</p> + <p><c><anno>PidsAndPorts</anno></c> is a list of pids and + port identifiers, with processes or ports to which the process + has a link.</p> </item> <tag><c>{last_calls, false|Calls}</c></tag> <item> @@ -4011,131 +3829,131 @@ os_prompt% </pre> If call saving is active, a list is returned, in which the last element is the most recent called.</p> </item> - <tag><c>{memory, Size}</c></tag> + <tag><c>{memory, <anno>Size</anno>}</c></tag> <item> - <p><c>Size</c> is the size in bytes of the process. This + <p><c><anno>Size</anno></c> is the size in bytes of the process. This includes call stack, heap and internal structures.</p> </item> - <tag><c>{message_queue_len, MessageQueueLen}</c></tag> + <tag><c>{message_queue_len, <anno>MessageQueueLen</anno>}</c></tag> <item> - <p><c>MessageQueueLen</c> is the number of messages + <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>MessageQueue</c> returned as + the length of the list <c><anno>MessageQueue</anno></c> returned as the info item <c>messages</c> (see below).</p> </item> - <tag><c>{messages, MessageQueue}</c></tag> + <tag><c>{messages, <anno>MessageQueue</anno>}</c></tag> <item> - <p><c>MessageQueue</c> is a list of the messages to + <p><c><anno>MessageQueue</anno></c> is a list of the messages to the process, which have not yet been processed.</p> </item> - <tag><c>{min_heap_size, MinHeapSize}</c></tag> + <tag><c>{min_heap_size, <anno>MinHeapSize</anno>}</c></tag> <item> - <p><c>MinHeapSize</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, MinBinVHeapSize}</c></tag> + <tag><c>{min_bin_vheap_size, <anno>MinBinVHeapSize</anno>}</c></tag> <item> - <p><c>MinBinVHeapSize</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, Pids}</c></tag> + <tag><c>{monitored_by, <anno>Pids</anno>}</c></tag> <item> <p>A list of pids that are monitoring the process (with <c>monitor/2</c>).</p> </item> - <tag><c>{monitors, Monitors}</c></tag> + <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, Pid}</c>, and for a remote process + is <c>{process, <anno>Pid</anno>}</c>, and for a remote process monitor by name, the list item is - <c>{process, {RegName, Node}}</c>.</p> + <c>{process, {<anno>RegName</anno>, <anno>Node</anno>}}</c>.</p> </item> <tag><c>{priority, Level}</c></tag> <item> - <p><c>Level</c> is the current priority level for + <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> </item> - <tag><c>{reductions, Number}</c></tag> + <tag><c>{reductions, <anno>Number</anno>}</c></tag> <item> - <p><c>Number</c> is the number of reductions executed by + <p><c><anno>Number</anno></c> is the number of reductions executed by the process.</p> </item> - <tag><c>{registered_name, Atom}</c></tag> + <tag><c>{registered_name, <anno>Atom</anno>}</c></tag> <item> - <p><c>Atom</c> is the registered name of the process. If + <p><c><anno>Atom</anno></c> is the registered name of the process. If the process has no registered name, this tuple is not present in the list.</p> </item> - <tag><c>{sequential_trace_token, [] | SequentialTraceToken}</c></tag> + <tag><c>{sequential_trace_token, [] | <anno>SequentialTraceToken</anno>}</c></tag> <item> - <p><c>SequentialTraceToken</c> the sequential trace token for - the process. This <c>InfoTuple</c> may be changed or removed + <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> </item> - <tag><c>{stack_size, Size}</c></tag> + <tag><c>{stack_size, <anno>Size</anno>}</c></tag> <item> - <p><c>Size</c> is the stack size of the process in words.</p> + <p><c><anno>Size</anno></c> is the stack size of the process in words.</p> </item> - <tag><c>{status, Status}</c></tag> + <tag><c>{status, <anno>Status</anno>}</c></tag> <item> - <p><c>Status</c> is the status of the process. <c>Status</c> + <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> </item> - <tag><c>{suspending, SuspendeeList}</c></tag> + <tag><c>{suspending, <anno>SuspendeeList</anno>}</c></tag> <item> - <p><c>SuspendeeList</c> is a list of <c>{Suspendee, - ActiveSuspendCount, OutstandingSuspendCount}</c> tuples. - <c>Suspendee</c> is the pid of a process that have been or is to - be suspended by the process identified by <c>Pid</c> via the + <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>ActiveSuspendCount</c> is the number of times the - <c>Suspendee</c> has been suspended by <c>Pid</c>. - <c>OutstandingSuspendCount</c> is the number of not yet - completed suspend requests sent by <c>Pid</c>. That is, - if <c>ActiveSuspendCount /= 0</c>, <c>Suspendee</c> is + 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>. + <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>OutstandingSuspendCount /= 0</c> the <c>asynchronous</c> + <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>Pid</c>. - Note that the <c>ActiveSuspendCount</c> and - <c>OutstandingSuspendCount</c> are not the total suspend count - on <c>Suspendee</c>, only the parts contributed by <c>Pid</c>. + 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> </item> - <tag><c>{total_heap_size, Size}</c></tag> + <tag><c>{total_heap_size, <anno>Size</anno>}</c></tag> <item> - <p><c>Size</c> is the total size in words of all heap + <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> </item> - <tag><c>{trace, InternalTraceFlags}</c></tag> + <tag><c>{trace, <anno>InternalTraceFlags</anno>}</c></tag> <item> - <p><c>InternalTraceFlags</c> is an integer representing - internal trace flag for this process. This <c>InfoTuple</c> + <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> </item> - <tag><c>{trap_exit, Boolean}</c></tag> + <tag><c>{trap_exit, <anno>Boolean</anno>}</c></tag> <item> - <p><c>Boolean</c> is <c>true</c> if the process is trapping + <p><c><anno>Boolean</anno></c> is <c>true</c> if the process is trapping exits, otherwise it is <c>false</c>.</p> </item> </taglist> <p>Note however, that not all implementations support every one - of the above <c>Items</c>.</p> - <p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process, - or if <c>Item</c> is not a valid <c>Item</c>.</p> + 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> </desc> </func> <func> - <name>processes() -> [pid()]</name> + <name name="processes" arity="0"/> <fsummary>All processes</fsummary> <desc> <p>Returns a list of process identifiers corresponding to @@ -4152,13 +3970,10 @@ os_prompt% </pre> </desc> </func> <func> - <name>purge_module(Module) -> void()</name> + <name name="purge_module" arity="1"/> <fsummary>Remove old code for a module</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> - <p>Removes old code for <c>Module</c>. Before this BIF is used, + <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> <warning> @@ -4167,20 +3982,17 @@ os_prompt% </pre> used elsewhere.</p> </warning> <p>Failure: <c>badarg</c> if there is no old code for - <c>Module</c>.</p> + <c><anno>Module</anno></c>.</p> </desc> </func> <func> - <name>put(Key, Val) -> OldVal | undefined</name> + <name name="put" arity="2"/> <fsummary>Add a new value to the process dictionary</fsummary> - <type> - <v>Key = Val = OldVal = term()</v> - </type> - <desc> - <p>Adds a new <c>Key</c> to the process dictionary, associated - with the value <c>Val</c>, and returns <c>undefined</c>. If - <c>Key</c> already exists, the old value is deleted and - replaced by <c>Val</c> and the function returns the old value.</p> + <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 @@ -4194,17 +4006,9 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:raise(Class, Reason, Stacktrace)</name> + <name name="raise" arity="3"/> + <type name="raise_stacktrace"/> <fsummary>Stop execution with an exception of given class, reason and call stack backtrace</fsummary> - <type> - <v>Class = error | exit | throw</v> - <v>Reason = term()</v> - <v>Stacktrace = [{Module, Function, Arity | Args} | {Fun, Args}]</v> - <v> Module = Function = atom()</v> - <v> Arity = arity()</v> - <v> Args = [term()]</v> - <v> Fun = [fun()]</v> - </type> <desc> <p>Stops the execution of the calling process with an exception of given class, reason and call stack backtrace @@ -4215,11 +4019,11 @@ os_prompt% </pre> be avoided in applications, unless you know very well what you are doing.</p> </warning> - <p><c>Class</c> is one of <c>error</c>, <c>exit</c> or + <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(Class, Reason, Stacktrace)</c> is - equivalent to <c>erlang:Class(Reason)</c>. - <c>Reason</c> is any term and <c>Stacktrace</c> is a list as + <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> @@ -4236,24 +4040,21 @@ os_prompt% </pre> 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(Class, Reason, Stacktrace))</c> + <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>erlang:read_timer(TimerRef) -> integer() >= 0 | false</name> + <name name="read_timer" arity="1"/> <fsummary>Number of milliseconds remaining for a timer</fsummary> - <type> - <v>TimerRef = reference()</v> - </type> <desc> - <p><c>TimerRef</c> is a timer reference returned by + <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>TimerRef</c> was never a + <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> <p>See also @@ -4264,14 +4065,11 @@ os_prompt% </pre> </desc> </func> <func> - <name>erlang:ref_to_list(Ref) -> string()</name> + <name name="ref_to_list" arity="1"/> <fsummary>Text representation of a reference</fsummary> - <type> - <v>Ref = reference()</v> - </type> <desc> <p>Returns a string which corresponds to the text - representation of <c>Ref</c>.</p> + 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 @@ -4280,33 +4078,25 @@ os_prompt% </pre> </desc> </func> <func> - <name>register(RegName, Pid | Port) -> true</name> + <name name="register" arity="2"/> <fsummary>Register a name for a pid (or port)</fsummary> - <type> - <v>RegName = atom()</v> - <v>Pid = pid()</v> - <v>Port = port()</v> - </type> - <desc> - <p>Associates the name <c>RegName</c> with a pid or a port - identifier. <c>RegName</c>, which must be an atom, can be used + <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 - (<c>RegName ! Message</c>).</p> + (<c><anno>RegName</anno> ! Message</c>).</p> <pre> > <input>register(db, Pid).</input> true</pre> - <p>Failure: <c>badarg</c> if <c>Pid</c> is not an existing, - local process or port, if <c>RegName</c> is already in use, + <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>RegName</c> is the atom <c>undefined</c>.</p> + name), or if <c><anno>RegName</anno></c> is the atom <c>undefined</c>.</p> </desc> </func> <func> - <name>registered() -> [RegName]</name> + <name name="registered" arity="0"/> <fsummary>All registered names</fsummary> - <type> - <v>RegName = atom()</v> - </type> <desc> <p>Returns a list of names which have been registered using <seealso marker="#register/2">register/2</seealso>.</p> @@ -4316,22 +4106,19 @@ true</pre> </desc> </func> <func> - <name>erlang:resume_process(Suspendee) -> true</name> + <name name="resume_process" arity="1"/> <fsummary>Resume a suspended process</fsummary> - <type> - <v>Suspendee = pid()</v> - </type> <desc> <p>Decreases the suspend count on the process identified by - <c>Suspendee</c>. <c>Suspendee</c> should previously have been + <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>, or <seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso> - by the process calling <c>erlang:resume_process(Suspendee)</c>. When - the suspend count on <c>Suspendee</c> reach zero, <c>Suspendee</c> + 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>Suspendee</c> was in before it was + from suspended into the state <c><anno>Suspendee</anno></c> was in before it was suspended. </p> <warning> @@ -4341,29 +4128,26 @@ true</pre> <taglist> <tag><c>badarg</c></tag> <item> - If <c>Suspendee</c> isn't a process identifier. + If <c><anno>Suspendee</anno></c> isn't a process identifier. </item> <tag><c>badarg</c></tag> <item> If the process calling <c>erlang:resume_process/1</c> had not previously increased the suspend count on the process - identified by <c>Suspendee</c>. + identified by <c><anno>Suspendee</anno></c>. </item> <tag><c>badarg</c></tag> <item> - If the process identified by <c>Suspendee</c> is not alive. + If the process identified by <c><anno>Suspendee</anno></c> is not alive. </item> </taglist> </desc> </func> <func> - <name>round(Number) -> integer()</name> + <name name="round" arity="1"/> <fsummary>Return an integer by rounding a number</fsummary> - <type> - <v>Number = number()</v> - </type> <desc> - <p>Returns an integer by rounding <c>Number</c>.</p> + <p>Returns an integer by rounding <c><anno>Number</anno></c>.</p> <pre> > <input>round(5.5).</input> 6</pre> @@ -4371,7 +4155,7 @@ true</pre> </desc> </func> <func> - <name>self() -> pid()</name> + <name name="self" arity="0"/> <fsummary>Pid of the calling process</fsummary> <desc> <p>Returns the pid (process identifier) of the calling process.</p> @@ -4382,33 +4166,21 @@ true</pre> </desc> </func> <func> - <name>erlang:send(Dest, Msg) -> Msg</name> + <name name="send" arity="2"/> <fsummary>Send a message</fsummary> - <type> - <v>Dest = pid() | port() | RegName | {RegName, Node}</v> - <v>Msg = term()</v> - <v> RegName = atom()</v> - <v> Node = node()</v> - </type> - <desc> - <p>Sends a message and returns <c>Msg</c>. This is the same as - <c>Dest ! Msg</c>.</p> - <p><c>Dest</c> may be a remote or local pid, a (local) port, a - locally registered name, or a tuple <c>{RegName, Node}</c> + <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> for a registered name at another node.</p> </desc> </func> <func> - <name>erlang:send(Dest, Msg, [Option]) -> Res</name> + <name name="send" arity="3"/> + <type name="dst"/> <fsummary>Send a message conditionally</fsummary> - <type> - <v>Dest = pid() | port() | RegName | {RegName, Node}</v> - <v> RegName = atom()</v> - <v> Node = node()</v> - <v>Msg = term()</v> - <v>Option = nosuspend | noconnect</v> - <v>Res = ok | nosuspend | noconnect</v> - </type> <desc> <p>Sends a message and returns <c>ok</c>, or does not send the message but returns something else (see below). Otherwise @@ -4438,28 +4210,24 @@ true</pre> </desc> </func> <func> - <name>erlang:send_after(Time, Dest, Msg) -> TimerRef</name> + <name name="send_after" arity="3"/> + <type_desc variable="Time">0 <= Time <= 4294967295</type_desc> <fsummary>Start a timer</fsummary> - <type> - <v>Time = integer() >= 0</v> - <v> 0 <= Time <= 4294967295</v> - <v>Dest = pid() | RegName </v> - <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> - <v>Msg = term()</v> - <v>TimerRef = reference()</v> - </type> <desc> <p>Starts a timer which will send the message <c>Msg</c> - to <c>Dest</c> after <c>Time</c> milliseconds.</p> - <p>If <c>Dest</c> is an atom, it is supposed to be the name of + 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>Dest</c> is a pid, the timer will be automatically - canceled if the process referred to by the pid is not alive, + + <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>Dest</c> is an atom.</p> + 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>, @@ -4559,32 +4327,25 @@ true</pre> </desc> </func> <func> - <name>setelement(Index, Tuple1, Value) -> Tuple2</name> + <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> - <type> - <v>Index = 1..tuple_size(Tuple1)</v> - <v>Tuple1 = Tuple2 = tuple()</v> - <v>Value = term()</v> - </type> - <desc> - <p>Returns a tuple which is a copy of the argument <c>Tuple1</c> - with the element given by the integer argument <c>Index</c> + <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> (the first element is the element with index 1) replaced by - the argument <c>Value</c>.</p> + the argument <c><anno>Value</anno></c>.</p> <pre> > <input>setelement(2, {10, green, bottles}, red).</input> {10,red,bottles}</pre> </desc> </func> <func> - <name>size(Item) -> integer() >= 0</name> + <name name="size" arity="1"/> <fsummary>Size of a tuple or binary</fsummary> - <type> - <v>Item = tuple() | binary()</v> - </type> <desc> <p>Returns an integer which is the size of the argument - <c>Item</c>, which must be either a tuple or a binary.</p> + <c><anno>Item</anno></c>, which must be either a tuple or a binary.</p> <pre> > <input>size({morni, mulle, bwange}).</input> 3</pre> @@ -4612,20 +4373,16 @@ true</pre> </desc> </func> <func> - <name>spawn(Module, Function, Args) -> pid()</name> + <name name="spawn" arity="3"/> <fsummary>Create a new process with a function as entry point</fsummary> - <type> - <v>Module = Function = atom()</v> - <v>Args = [term()]</v> - </type> <desc> <p>Returns the pid of a new process started by the application - of <c>Module:Function</c> to <c>Args</c>. The new process + 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(Module, Function, Args)</c> is evaluated by the new process if - <c>Module:Function/Arity</c> does not exist (where - <c>Arity</c> is the length of <c>Args</c>). The error handler + <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 @@ -4672,15 +4429,11 @@ true</pre> </desc> </func> <func> - <name>spawn_link(Module, Function, Args) -> pid()</name> + <name name="spawn_link" arity="3"/> <fsummary>Create and link to a new process with a function as entry point</fsummary> - <type> - <v>Module = Function = atom()</v> - <v>Args = [term()]</v> - </type> <desc> <p>Returns the pid of a new process started by the application - of <c>Module:Function</c> to <c>Args</c>. A link is created + 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> @@ -4859,15 +4612,12 @@ true</pre> </desc> </func> <func> - <name>split_binary(Bin, Pos) -> {Bin1, Bin2}</name> + <name name="split_binary" arity="2"/> + <type_desc variable="Pos">0..byte_size(Bin)</type_desc> <fsummary>Split a binary into two</fsummary> - <type> - <v>Bin = Bin1 = Bin2 = binary()</v> - <v>Pos = 0..byte_size(Bin)</v> - </type> <desc> <p>Returns a tuple containing the binaries which are the result - of splitting <c>Bin</c> into two parts at position <c>Pos</c>. + 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> <pre> @@ -4884,30 +4634,24 @@ true</pre> </desc> </func> <func> - <name>erlang:start_timer(Time, Dest, Msg) -> TimerRef</name> + <name name="start_timer" arity="3"/> + <type_desc variable="Time">0 <= Time <= 4294967295</type_desc> <fsummary>Start a timer</fsummary> - <type> - <v>Time = integer() >= 0</v> - <v> 0 <= Time <= 4294967295</v> - <v>Dest = LocalPid | RegName </v> - <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> - <v> RegName = atom()</v> - <v>Msg = term()</v> - <v>TimerRef = reference()</v> - </type> <desc> <p>Starts a timer which will send the message - <c>{timeout, TimerRef, Msg}</c> to <c>Dest</c> - after <c>Time</c> milliseconds.</p> - <p>If <c>Dest</c> is an atom, it is supposed to be the name of + <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>Dest</c> is a pid, the timer will be automatically - canceled if the process referred to by the pid is not alive, + <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>Dest</c> is an atom.</p> + 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>, @@ -4918,54 +4662,52 @@ true</pre> </desc> </func> <func> - <name>statistics(Type) -> Res</name> - <fsummary>Information about the system</fsummary> - <type> - <v>Type, Res -- see below</v> - </type> + <name name="statistics" arity="1" clause_i="1"/> + <fsummary>Information about context switches</fsummary> <desc> - <p>All times are in milliseconds unless otherwise specified.</p> - <p>Returns information about the system as specified by - <c>Type</c>:</p> - <taglist> - <tag><c>context_switches</c></tag> - <item> - <p>Returns <c>{ContextSwitches, 0}</c>, where - <c>ContextSwitches</c> is the total number of context - switches since the system started.</p> - </item> - <tag><marker id="statistics_exact_reductions"><c>exact_reductions</c></marker></tag> - <item> - <p>Returns - <c>{Total_Exact_Reductions, Exact_Reductions_Since_Last_Call}</c>.</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> - </item> - <tag><c>garbage_collection</c></tag> - <item> - <p>Returns <c>{Number_of_GCs, Words_Reclaimed, 0}</c>. This - information may not be valid for all implementations.</p> - <pre> + <p><c><anno>ContextSwitches</anno></c> is the total number of context + switches since the system started.</p> + </desc> + </func> + <func> + <name name="statistics" arity="1" clause_i="2"/> + <fsummary>Information about exact reductions</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> + </desc> + </func> + <func> + <name name="statistics" arity="1" clause_i="3"/> + <fsummary>Information about garbage collection</fsummary> + <desc> + <p>This information may not be valid for all implementations.</p> + <pre> > <input>statistics(garbage_collection).</input> {85,23961,0} </pre> - </item> - <tag><c>io</c></tag> - <item> - <p>Returns <c>{{input, Input}, {output, Output}}</c>, - where <c>Input</c> is the total number of bytes received - through ports, and <c>Output</c> is the total number of - bytes output to ports.</p> - </item> - <tag><marker id="statistics_reductions"><c>reductions</c></marker></tag> - <item> - <p>Returns - <c>{Total_Reductions, Reductions_Since_Last_Call}</c>.</p> + </desc> + </func> + <func> + <name name="statistics" arity="1" clause_i="4"/> + <fsummary>Information about io</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> + </desc> + </func> + <func> + <name name="statistics" arity="1" clause_i="5"/> + <fsummary>Information about reductions</fsummary> + <desc> + <marker id="statistics_reductions"></marker> <note> - <p>From erts version 5.5 (OTP release R11B) + <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 @@ -4975,53 +4717,65 @@ true</pre> > <input>statistics(reductions).</input> {2046,11} </pre> - </item> - <tag><c>run_queue</c></tag> - <item> - <p>Returns the length of the run queue, that is, the number - of processes that are ready to run.</p> - </item> - <tag><c>runtime</c></tag> - <item> - <p>Returns <c>{Total_Run_Time, Time_Since_Last_Call}</c>. - 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.</p> + </desc> + </func> + <func> + <name name="statistics" arity="1" clause_i="6"/> + <fsummary>Information about the run-queue</fsummary> + <desc> + <p>Returns the length of the run queue, that is, the number + of processes that are ready to run.</p> + </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.</p> <pre> > <input>statistics(runtime).</input> {1690,1620} </pre> - </item> - <tag><marker id="statistics_scheduler_wall_time"><c>scheduler_wall_time</c></marker></tag> - <item> - <p>Returns a list of tuples with - <c>{SchedulerId, ActiveTime, TotalTime}</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> + </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> + <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> - <p> - Returns <c>undefined</c> if the system flag <seealso marker="#system_flag_scheduler_wall_time"> - scheduler_wall_time</seealso> is turned off. - </p> + <p> + Returns <c>undefined</c> if the 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 may appear in different order - between calls. - </p> - <p>Using <c>scheduler_wall_time</c> to calculate scheduler utilization.</p> + <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> <pre> > <input>erlang:system_flag(scheduler_wall_time, true).</input> false @@ -5049,34 +4803,26 @@ ok {Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), A/T.</input> 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> </note> - </item> - - <tag><c>wall_clock</c></tag> - <item> - <p>Returns - <c>{Total_Wallclock_Time, Wallclock_Time_Since_Last_Call}</c>. - <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> - </item> - </taglist> </desc> </func> <func> - <name>erlang:suspend_process(Suspendee, OptList) -> boolean()</name> + <name name="statistics" arity="1" clause_i="9"/> + <fsummary>Information about wall-clock</fsummary> + <desc> + <p><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> - <type> - <v>Suspendee = pid()</v> - <v>OptList = [Opt]</v> - <v>Opt = atom()</v> - </type> <desc> <p>Increases the suspend count on the process identified by - <c>Suspendee</c> and puts it in the suspended state if it isn't + <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> @@ -5084,49 +4830,49 @@ ok <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>Suspendee</c> is - decreased when - <seealso marker="#resume_process/1">erlang:resume_process(Suspendee)</seealso> + count reach 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(Suspendee)</c>. All increased suspend + <c>erlang:suspend_process(<anno>Suspendee</anno>)</c>. All increased suspend counts on other processes acquired by a process will automatically be decreased when the process terminates.</p> - <p>Currently the following options (<c>Opt</c>s) are available:</p> + <p>Currently the following options (<c><anno>Opt</anno></c>s) are available:</p> <taglist> <tag><c>asynchronous</c></tag> <item> A suspend request is sent to the process identified by - <c>Suspendee</c>. <c>Suspendee</c> will eventually suspend + <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>Suspendee</c> has suspended yet - or not. Note that the point in time when the <c>Suspendee</c> + 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>Suspendee</c> will <em>eventually</em> suspend (unless it + <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>Suspendee</c> has actually suspended. + be blocked until the <c><anno>Suspendee</anno></c> has actually suspended. </item> <tag><c>unless_suspending</c></tag> <item> - The process identified by <c>Suspendee</c> will be suspended + The process identified by <c><anno>Suspendee</anno></c> will be suspended unless the calling process already is suspending the - <c>Suspendee</c>. If <c>unless_suspending</c> is combined + <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>Suspendee</c> or if a suspend request already has been sent + <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>Suspendee</c>, or if combined with the <c>asynchronous</c> + 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>Suspendee</c> + <c>false</c> is returned and the suspend count on <c><anno>Suspendee</anno></c> will remain unchanged. </item> </taglist> <p>If the suspend count on the process identified by - <c>Suspendee</c> was increased, <c>true</c> is returned; otherwise, + <c><anno>Suspendee</anno></c> was increased, <c>true</c> is returned; otherwise, <c>false</c> is returned.</p> <warning> @@ -5136,28 +4882,28 @@ ok <taglist> <tag><c>badarg</c></tag> <item> - If <c>Suspendee</c> isn't a process identifier. + If <c><anno>Suspendee</anno></c> isn't a process identifier. </item> <tag><c>badarg</c></tag> <item> - If the process identified by <c>Suspendee</c> is same the process as + If the process identified by <c><anno>Suspendee</anno></c> is same the process as the process calling <c>erlang:suspend_process/2</c>. </item> <tag><c>badarg</c></tag> <item> - If the process identified by <c>Suspendee</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>Suspendee</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>OptList</c> isn't a proper list of valid <c>Opt</c>s. + If <c><anno>OptList</anno></c> isn't 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>Suspendee</c> has been suspended more + 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 @@ -5180,292 +4926,322 @@ ok </desc> </func> <func> - <name>erlang:system_flag(Flag, Value) -> OldValue</name> - <fsummary>Set system flags</fsummary> - <type> - <v>Flag, Value, OldValue -- see below</v> - </type> + <name name="system_flag" arity="2" clause_i="1"/> + <fsummary>Set system flag backtrace_depth</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"/> + <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>The - <seealso marker="#system_flag_cpu_topology">cpu_topology</seealso>, - and - <seealso marker="#system_flag_scheduler_bind_type">scheduler_bind_type</seealso> - <c>Flag</c>s are <em>deprecated</em> and have been scheduled for - removal in erts-5.10/OTP-R16.</p> + <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> </warning> - <p>Sets various system properties of the Erlang node. Returns - the old value of the flag.</p> + <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 + detected. The returned value equals the value returned + from <c>erlang:system_info(cpu_topology)</c> before the + 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> + </desc> + </func> + <func> + <name name="system_flag" arity="2" clause_i="3"/> + <fsummary>Set system flag fullsweep_after</fsummary> + <desc> + <p><c><anno>Number</anno></c> is a non-negative integer which indicates + how many times generational garbage collections can be + done without forcing a fullsweep collection. The value + applies to new processes; 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.</p> + <p>An alternative way to set this value is through the + (operating system) environment variable + <c>ERL_FULLSWEEP_AFTER</c>.</p> + </desc> + </func> + <func> + <name name="system_flag" arity="2" clause_i="4"/> + <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 + <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or + <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="5"/> + <fsummary>Set system flag min_bin_vheap_size</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 + <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 + <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or + <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 multi_scheduling</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 + 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 + 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>, + <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="7"/> + <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> + </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, + Solaris, FreeBSD, and Windows systems, but more systems will be + supported in the future. + </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. + 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> <taglist> - <tag><c>erlang:system_flag(backtrace_depth, Depth)</c></tag> - <item> - <p>Sets the maximum depth of call stack back-traces in the - exit reason element of <c>'EXIT'</c> tuples.</p> - </item> - <tag><marker id="system_flag_cpu_topology"><c>erlang:system_flag(cpu_topology, CpuTopology)</c></marker></tag> - <item> - <p><em>NOTE:</em> 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> - <p>Sets the user defined <c>CpuTopology</c>. The user defined - CPU topology will override any automatically detected - CPU topology. By passing <c>undefined</c> as <c>CpuTopology</c> - the system will revert back 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> - <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>CpuTopology</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> - </item> - <tag><c>erlang:system_flag(fullsweep_after, Number)</c></tag> - <item> - <p><c>Number</c> is a non-negative integer which indicates - how many times generational garbage collections can be - done without forcing a fullsweep collection. The value - applies to new processes; processes already running are - not affected.</p> - <p>In low-memory systems (especially without virtual - memory), setting the value to 0 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> - </item> - <tag><c>erlang:system_flag(min_heap_size, MinHeapSize)</c></tag> - <item> - <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 - <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or - <seealso marker="#process_flag/2">process_flag/2</seealso>. </p> - </item> - <tag><c>erlang:system_flag(min_bin_vheap_size, MinBinVHeapSize)</c></tag> - <item> - <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 - <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 - <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or - <seealso marker="#process_flag/2">process_flag/2</seealso>. </p> - </item> - <tag><marker id="system_flag_multi_scheduling"><c>erlang:system_flag(multi_scheduling, BlockState)</c></marker></tag> - <item> - <p><c>BlockState = block | unblock</c></p> - <p>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>BlockState =:= block</c>, multi-scheduling will - be blocked. If <c>BlockState =:= 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 - 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 - 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, BlockState)</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>, - <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_flag_scheduler_bind_type"><c>erlang:system_flag(scheduler_bind_type, How)</c></marker></tag> - <item> - <p><em>NOTE:</em> 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> - <p>Controls if and how schedulers are bound to logical - processors.</p> - <p>When <c>erlang:system_flag(scheduler_bind_type, How)</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, - Solaris, FreeBSD, and Windows systems, but more systems will be - supported in the future. - </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. - 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>How</c> - argument determines how schedulers are bound. <c>How</c> can - currently be one of:</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>. - </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>. - </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>. - </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>. - </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>. - </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>. - </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>. - </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>. - </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>. - </p></item> - </taglist> - <p>The value returned equals <c>How</c> before the - <c>scheduler_bind_type</c> flag was changed.</p> - <p>Failure:</p> - <taglist> - <tag><c>notsup</c></tag> - <item> - <p>If binding of schedulers is not supported.</p> - </item> - <tag><c>badarg</c></tag> - <item> - <p>If <c>How</c> isn't one of the documented alternatives.</p> - </item> - <tag><c>badarg</c></tag> - <item> - <p>If no CPU topology information is available.</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> - <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> - </item> - <tag><marker id="system_flag_scheduler_wall_time"><c>erlang:system_flag(scheduler_wall_time, Boolean)</c></marker></tag> + <tag><c>unbound</c></tag> + <item><p>Same as the <c>erl</c> command line argument + <seealso marker="erts:erl#+sbt">+sbt u</seealso>. + </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>. + </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>. + </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>. + </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>. + </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>. + </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>. + </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>. + </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>. + </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> + <taglist> + <tag><c>notsup</c></tag> <item> - <p>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> + <p>If binding of schedulers is not supported.</p> </item> - - <tag><marker id="system_flag_schedulers_online"><c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></marker></tag> + <tag><c>badarg</c></tag> <item> - <p>Sets the amount of schedulers online. Valid range is - <![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]>. - </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> + <p>If <c>How</c> isn't one of the documented alternatives.</p> </item> - - <tag><c>erlang:system_flag(trace_control_word, TCW)</c></tag> + <tag><c>badarg</c></tag> <item> - <p>Sets the value of the node's trace control word to - <c>TCW</c>. <c>TCW</c> should be an unsigned integer. For - more information see documentation of the - <seealso marker="erts:match_spec#set_tcw">set_tcw</seealso> - function in the match specification documentation in the - ERTS User's Guide.</p> + <p>If no CPU topology information is available.</p> </item> </taglist> - <note> - <p>The <c>schedulers</c> option has been removed as - of erts version 5.5.3. The number of scheduler - threads is determined at emulator boot time, and - cannot be changed after that.</p> - </note> + <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> + <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> </desc> </func> <func> - <name>erlang:system_info(Type) -> Res</name> - <fsummary>Information about the system</fsummary> - <type> - <v>Type, Res -- see below</v> - </type> + <name name="system_flag" arity="2" clause_i="8"/> + <fsummary>Set system flag scheduler_wall_time</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> + </desc> + </func> + <func> + <name name="system_flag" arity="2" clause_i="9"/> + <fsummary>Set system flag schedulers_online</fsummary> <desc> - <p>Returns various information about the current system - (emulator) as specified by <c>Type</c>:</p> + <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> + <p>Returns the old value of the flag.</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> + </desc> + </func> + <func> + <name name="system_flag" arity="2" clause_i="10"/> + <fsummary>Set system flag trace_control_word</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 + <seealso marker="erts:match_spec#set_tcw">set_tcw</seealso> + function in the match specification documentation in the + ERTS User's Guide.</p> + <p>Returns the old value of the flag.</p> + </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"/> + <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 + current system (emulator) as specified by + <c><anno>Item</anno></c>:</p> <taglist> <tag><marker id="system_info_allocated_areas"><c>allocated_areas</c></marker></tag> <item> @@ -5490,37 +5266,27 @@ ok </item> <tag><marker id="system_info_allocator"><c>allocator</c></marker></tag> <item> - <p>Returns <c>{Allocator, Version, Features, Settings}.</c></p> - <p>Types:</p> - <list type="bulleted"> - <item><c>Allocator = undefined | glibc</c></item> - <item><c>Version = [integer()]</c></item> - <item><c>Features = [atom()]</c></item> - <item><c>Settings = [{Subsystem, [{Parameter, Value}]}]</c></item> - <item><c>Subsystem = atom()</c></item> - <item><c>Parameter = atom()</c></item> - <item><c>Value = term()</c></item> - </list> + <p>Returns <c>{<anno>Allocator</anno>, <anno>Version</anno>, <anno>Features</anno>, <anno>Settings</anno>}.</c></p> <p>Explanation:</p> <list type="bulleted"> <item> - <p><c>Allocator</c> corresponds to the <c>malloc()</c> - implementation used. If <c>Allocator</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> </item> <item> - <p><c>Version</c> is a list of integers (but not a + <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>Features</c> is a list of atoms representing + <p><c><anno>Features</anno></c> is a list of atoms representing allocation features used.</p> </item> <item> - <p><c>Settings</c> is a list of subsystems, their + <p><c><anno>Settings</anno></c> is a list of subsystems, their configurable parameters, and used values. Settings may differ between different combinations of platforms, allocators, and allocation features. @@ -5540,15 +5306,15 @@ ok erts_alloc(3)</seealso> documentation. </p> </item> - <tag><marker id="system_info_allocator_tuple"><c>{allocator, Alloc}</c></marker></tag> + <tag><marker id="system_info_allocator_tuple"><c>{allocator, <anno>Alloc</anno>}</c></marker></tag> <item> <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 where <c>InstanceInfo</c> contains information about a specific instance of the allocator. - If <c>Alloc</c> is not a recognized allocator, - <c>undefined</c> is returned. If <c>Alloc</c> is disabled, + 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 @@ -5577,54 +5343,51 @@ ok values. The first value is memory pool size and the second value used memory size.</p> </item> - <tag><marker id="system_info_allocator_sizes"><c>{allocator_sizes, Alloc}</c></marker></tag> + <tag><marker id="system_info_allocator_sizes"><c>{allocator_sizes, <anno>Alloc</anno>}</c></marker></tag> <item> <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, Alloc})</seealso>. + <seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, <anno>Alloc</anno>})</seealso>. </p> </item> - <tag><c>build_type</c></tag> - <item> - <p>Returns an atom describing the build type of the runtime - system. This is normally the atom <c>opt</c> for optimized. - 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> - </item> - <tag><c>c_compiler_used</c></tag> - <item> - <p>Returns a two-tuple describing the C compiler used when - 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> - </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 - 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 - 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> - </item> - <tag><marker id="system_info_cpu_topology"><c>cpu_topology</c></marker></tag> + </taglist> + </desc> + </func> + <func> + <name name="system_info" arity="1" clause_i="10"/> + <name name="system_info" arity="1" clause_i="11"/> + <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. + </type_desc> + <type_desc name="level_entry"> + <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. + </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. + </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> + <taglist> + <tag><c>cpu_topology</c></tag> <item> - <p>Returns the <c>CpuTopology</c> which currently is used by the + <p>Returns the <c><anno>CpuTopology</anno></c> which currently is 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 @@ -5632,31 +5395,11 @@ ok <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>Types:</p> - <list type="bulleted"> - <item><c>CpuTopology = LevelEntryList | undefined</c></item> - <item><c>LevelEntryList = [LevelEntry]</c> (all - <c>LevelEntry</c>s of a <c>LevelEntryList</c> - must contain the same <c>LevelTag</c>, except - on the top level where both <c>node</c> and - <c>processor</c> <c>LevelTag</c>s may co-exist)</item> - <item><c>LevelEntry = {LevelTag, SubLevel} - | {LevelTag, InfoList, SubLevel}</c> - (<c>{LevelTag, SubLevel} - == {LevelTag, [], SubLevel}</c>)</item> - <item><c>LevelTag = node|processor|core|thread</c> - (more <c>LevelTag</c>s may be introduced in - the future)</item> - <item><c>SubLevel = [LevelEntry] | LogicalCpuId</c></item> - <item><c>LogicalCpuId = {logical, integer()}</c></item> - <item><c>InfoList = []</c> (the <c>InfoList</c> - may be extended in the future)</item> - </list> <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>CpuTopology</c> term can be omitted if - only one entry exists and the <c>InfoList</c> is empty. + <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>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> @@ -5668,15 +5411,15 @@ ok 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>CpuTopology</c> type yet, but will be in the + 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>CpuTopology</c> type to change. + <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>CpuTopology</c>. For more + <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 @@ -5686,7 +5429,7 @@ ok </item> <tag><marker id="system_info_cpu_topology_detected"><c>{cpu_topology, detected}</c></marker></tag> <item> - <p>Returns the automatically detected <c>CpuTopology</c>. The + <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. @@ -5698,13 +5441,112 @@ ok </item> <tag><c>{cpu_topology, used}</c></tag> <item> - <p>Returns the <c>CpuTopology</c> which is used by the + <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> </item> + </taglist> + </desc> + </func> + <func> + <name name="system_info" arity="1" clause_i="6"/> + <name name="system_info" arity="1" clause_i="7"/> + <name name="system_info" arity="1" clause_i="8"/> + <name name="system_info" arity="1" clause_i="9"/> + <name name="system_info" arity="1" clause_i="12"/> + <name name="system_info" arity="1" clause_i="13"/> + <name name="system_info" arity="1" clause_i="14"/> + <name name="system_info" arity="1" clause_i="15"/> + <name name="system_info" arity="1" clause_i="16"/> + <name name="system_info" arity="1" clause_i="17"/> + <name name="system_info" arity="1" clause_i="18"/> + <name name="system_info" arity="1" clause_i="19"/> + <name name="system_info" arity="1" clause_i="20"/> + <name name="system_info" arity="1" clause_i="21"/> + <name name="system_info" arity="1" clause_i="22"/> + <name name="system_info" arity="1" clause_i="23"/> + <name name="system_info" arity="1" clause_i="24"/> + <name name="system_info" arity="1" clause_i="25"/> + <name name="system_info" arity="1" clause_i="26"/> + <name name="system_info" arity="1" clause_i="27"/> + <name name="system_info" arity="1" clause_i="28"/> + <name name="system_info" arity="1" clause_i="29"/> + <name name="system_info" arity="1" clause_i="30"/> + <name name="system_info" arity="1" clause_i="31"/> + <name name="system_info" arity="1" clause_i="32"/> + <name name="system_info" arity="1" clause_i="33"/> + <name name="system_info" arity="1" clause_i="34"/> + <name name="system_info" arity="1" clause_i="35"/> + <name name="system_info" arity="1" clause_i="36"/> + <name name="system_info" arity="1" clause_i="37"/> + <name name="system_info" arity="1" clause_i="38"/> + <name name="system_info" arity="1" clause_i="39"/> + <name name="system_info" arity="1" clause_i="40"/> + <name name="system_info" arity="1" clause_i="41"/> + <name name="system_info" arity="1" clause_i="42"/> + <name name="system_info" arity="1" clause_i="43"/> + <name name="system_info" arity="1" clause_i="44"/> + <name name="system_info" arity="1" clause_i="45"/> + <name name="system_info" arity="1" clause_i="46"/> + <name name="system_info" arity="1" clause_i="47"/> + <name name="system_info" arity="1" clause_i="48"/> + <name name="system_info" arity="1" clause_i="49"/> + <name name="system_info" arity="1" clause_i="50"/> + <name name="system_info" arity="1" clause_i="51"/> + <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> + <taglist> + <tag><c>allocated_areas</c>, <c>allocator</c>, + <c>alloc_util_allocators</c>, <c>allocator_sizes</c></tag> + <item> + <p>See <seealso marker="#system_info_allocator_tags">above</seealso>.</p> + </item> + <tag><c>build_type</c></tag> + <item> + <p>Returns an atom describing the build type of the runtime + system. This is normally the atom <c>opt</c> for optimized. + 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> + </item> + <tag><c>c_compiler_used</c></tag> + <item> + <p>Returns a two-tuple describing the C compiler used when + 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> + </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 + 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 + 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> + </item> + <tag><c>cpu_topology</c></tag> + <item> + <p>See <seealso marker="#system_info_cpu_topology_tags">above</seealso>.</p> + </item> <tag><c>creation</c></tag> <item> <p>Returns the creation of the local node as an integer. @@ -5734,10 +5576,10 @@ ok <item> <p>Returns a list of tuples <c>{Node, ControllingEntity}</c>, one entry for each - connected remote node. The <c>Node</c> is the name of the - node and the <c>ControllingEntity</c> is the port or pid + 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>ControllingEntity</c> for nodes + 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> </item> @@ -5785,7 +5627,7 @@ ok </item> <tag><c>fullsweep_after</c></tag> <item> - <p>Returns <c>{fullsweep_after, integer()}</c> which is the + <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> @@ -5878,12 +5720,12 @@ ok </item> <tag><c>min_heap_size</c></tag> <item> - <p>Returns <c>{min_heap_size, MinHeapSize}</c> where <c>MinHeapSize</c> is the current system wide + <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, MinBinVHeapSize}</c> where <c>MinBinVHeapSize</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> @@ -5927,10 +5769,10 @@ ok </item> <tag><marker id="system_info_multi_scheduling_blockers"><c>multi_scheduling_blockers</c></marker></tag> <item> - <p>Returns a list of <c>PID</c>s when multi-scheduling - is blocked; otherwise, the empty list. The <c>PID</c>s - in the list is <c>PID</c>s of the processes currently - blocking multi-scheduling. A <c>PID</c> will only be + <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 process has blocked multiple times.</p> <p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>, @@ -5941,19 +5783,40 @@ ok <item> <p>Returns a string containing the OTP release number.</p> </item> - <tag><c>process_count</c></tag> + <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> + <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> + </item> + <tag><marker id="system_info_port_limit"><c>port_limit</c></marker></tag> + <item> + <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> + </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.</p> + <c>length(processes())</c> returns, but more efficient.</p> </item> - <tag><c>process_limit</c></tag> + <tag><marker id="system_info_process_limit"><c>process_limit</c></marker></tag> <item> - <p>Returns the maximum number of concurrently existing + <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 command line - flag <c>+P</c>, see - <seealso marker="erts:erl#max_processes">erl(1)</seealso>.</p> + 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> </item> <tag><c>procs</c></tag> <item> @@ -6005,7 +5868,7 @@ ok <item> <p>Returns the scheduler id (<c>SchedulerId</c>) of the scheduler thread that the calling process is executing - on. <c>SchedulerId</c> is a positive integer; where + 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> @@ -6037,7 +5900,8 @@ ok <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> + </p> <name name="system_info" arity="1" clause_i="49"/> + </item> <tag><c>smp_support</c></tag> <item> @@ -6131,53 +5995,39 @@ ok </func> <func> - <name>erlang:system_monitor() -> MonSettings</name> + <name name="system_monitor" arity="0"/> + <type name="system_monitor_option"/> <fsummary>Current system performance monitoring settings</fsummary> - <type> - <v>MonSettings -> {MonitorPid, Options} | undefined</v> - <v> MonitorPid = pid()</v> - <v> Options = [Option]</v> - <v> Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v> - <v> Time = Size = integer()</v> - </type> <desc> <p>Returns the current system monitoring settings set by <seealso marker="#system_monitor/2">erlang:system_monitor/2</seealso> - as <c>{MonitorPid, Options}</c>, or <c>undefined</c> if there + 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 from the one that was set.</p> </desc> </func> <func> - <name>erlang:system_monitor(undefined | {MonitorPid, Options}) -> MonSettings</name> + <name name="system_monitor" arity="1"/> + <type name="system_monitor_option"/> <fsummary>Set or clear system performance monitoring options</fsummary> - <type> - <v>MonitorPid, Options, MonSettings -- see below</v> - </type> <desc> <p>When called with the argument <c>undefined</c>, all system performance monitoring settings are cleared.</p> - <p>Calling the function with <c>{MonitorPid, Options}</c> as + <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(MonitorPid, Options)</seealso>.</p> + <seealso marker="#system_monitor/2">erlang:system_monitor(<anno>MonitorPid</anno>, <anno>Options</anno>)</seealso>.</p> <p>Returns the previous system monitor settings just like <seealso marker="#system_monitor/0">erlang:system_monitor/0</seealso>.</p> </desc> </func> <func> - <name>erlang:system_monitor(MonitorPid, [Option]) -> MonSettings</name> + <name name="system_monitor" arity="2"/> + <type name="system_monitor_option"/> <fsummary>Set system performance monitoring options</fsummary> - <type> - <v>MonitorPid = pid()</v> - <v>Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v> - <v> Time = Size = integer()</v> - <v>MonSettings = {OldMonitorPid, [Option]}</v> - <v> OldMonitorPid = pid()</v> - </type> - <desc> - <p>Sets system performance monitoring options. <c>MonitorPid</c> + <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> <taglist> @@ -6186,7 +6036,7 @@ ok <p>If a garbage collection in the system takes at least <c>Time</c> wallclock milliseconds, a message <c>{monitor, GcPid, long_gc, Info}</c> is sent to - <c>MonitorPid</c>. <c>GcPid</c> is the pid that was + <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 @@ -6209,7 +6059,7 @@ ok <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>MonitorPid</c>. <c>GcPid</c> and <c>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 @@ -6225,7 +6075,7 @@ ok <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>MonitorPid</c>. <c>SusPid</c> is the pid that got + <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> @@ -6234,7 +6084,7 @@ 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>MonitorPid</c>. <c>SusPid</c> is the pid that got + <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> @@ -6249,48 +6099,48 @@ ok <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>MonitorPid</c> does not exist.</p> + <p>Failure: <c>badarg</c> if <c><anno>MonitorPid</anno></c> does not exist or is not a local process.</p> </desc> </func> <func> - <name>erlang:system_profile() -> ProfilerSettings</name> + <name name="system_profile" arity="0"/> + <type name="system_profile_option"/> <fsummary>Current system profiling settings</fsummary> - <type> - <v>ProfilerSettings -> {ProfilerPid, Options} | undefined</v> - <v> ProfilerPid = pid() | port()</v> - <v> Options = [Option]</v> - <v> Option = runnable_procs | runnable_ports | scheduler | exclusive</v> - </type> <desc> <p>Returns the current system profiling settings set by <seealso marker="#system_profile/2">erlang:system_profile/2</seealso> - as <c>{ProfilerPid, Options}</c>, or <c>undefined</c> if there + 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 from the one that was set.</p> </desc> </func> <func> - <name>erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings</name> + <name name="system_profile" arity="2"/> + <type name="system_profile_option"/> <fsummary>Current system profiling settings</fsummary> - <type> - <v>ProfilerSettings -> {ProfilerPid, Options} | undefined</v> - <v> ProfilerPid = pid() | port()</v> - <v> Options = [Option]</v> - <v> Option = runnable_procs | runnable_ports | scheduler | exclusive</v> - </type> - <desc> - <p>Sets system profiler options. <c>ProfilerPid</c> + <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. 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 + 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> + </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>ProfilerPid</c>. Running processes that is reinserted into the + <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> @@ -6299,24 +6149,14 @@ ok <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>ProfilerPid</c>. + <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>ProfilerPid</c>. - </p> - </item> - <tag><c>exclusive</c></tag> - <item> - <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. + to <c><anno>ProfilerPid</anno></c>. </p> </item> </taglist> @@ -6327,14 +6167,11 @@ ok </func> <func> - <name>term_to_binary(Term) -> ext_binary()</name> + <name name="term_to_binary" arity="1"/> <fsummary>Encode a term to an Erlang external term format binary</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> <p>Returns a binary data object which is the result of encoding - <c>Term</c> according to the Erlang external term format.</p> + <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 writing a term to a file in an efficient way, or sending an Erlang term to some type of communications channel not @@ -6344,20 +6181,16 @@ ok </desc> </func> <func> - <name>term_to_binary(Term, [Option]) -> ext_binary()</name> + <name name="term_to_binary" arity="2"/> <fsummary>Encode a term to en Erlang external term format binary</fsummary> - <type> - <v>Term = term()</v> - <v>Option = compressed | {compressed,Level} | {minor_version,Version}</v> - </type> <desc> <p>Returns a binary data object which is the result of encoding - <c>Term</c> according to the Erlang external term format.</p> + <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,Level}</c>, where <c>Level</c> is an + 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 @@ -6366,16 +6199,16 @@ ok 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,Version}</c> can be use to control + <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>Version</c> + 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> forces any floats in the term to be encoded + <p><c>{minor_version, 1}</c> 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 the new representation.</p> - <p><c>{minor_version,0}</c> is currently the default, meaning that floats + <p><c>{minor_version, 0}</c> is currently the default, 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 binary.</p> @@ -6384,14 +6217,11 @@ ok </desc> </func> <func> - <name>throw(Any)</name> + <name name="throw" arity="1"/> <fsummary>Throw an exception</fsummary> - <type> - <v>Any = term()</v> - </type> <desc> <p>A non-local return from a function. If evaluated within a - <c>catch</c>, <c>catch</c> will return the value <c>Any</c>.</p> + <c>catch</c>, <c>catch</c> will return the value <c><anno>Any</anno></c>.</p> <pre> > <input>catch throw({hello, there}).</input> {hello,there}</pre> @@ -6399,11 +6229,8 @@ ok </desc> </func> <func> - <name>time() -> {Hour, Minute, Second}</name> + <name name="time" arity="0"/> <fsummary>Current time</fsummary> - <type> - <v>Hour = Minute = Second = integer() >= 0</v> - </type> <desc> <p>Returns the current time as <c>{Hour, Minute, Second}</c>.</p> <p>The time zone and daylight saving time correction depend on @@ -6414,35 +6241,27 @@ ok </desc> </func> <func> - <name>tl(List1) -> List2</name> + <name name="tl" arity="1"/> <fsummary>Tail of a list</fsummary> - <type> - <v>List1 = List2 = [term()]</v> - </type> <desc> - <p>Returns the tail of <c>List1</c>, that is, the list minus + <p>Returns the tail of <c><anno>List</anno></c>, that is, the list minus the first element.</p> <pre> > <input>tl([geesties, guilies, beasties]).</input> [guilies, beasties]</pre> <p>Allowed in guard tests.</p> - <p>Failure: <c>badarg</c> if <c>List</c> is the empty list [].</p> + <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty list [].</p> </desc> </func> <func> - <name>erlang:trace(PidSpec, How, FlagList) -> integer() >= 0</name> + <name name="trace" arity="3"/> + <type name="trace_flag"/> <fsummary>Set trace flags for a process or processes</fsummary> - <type> - <v>PidSpec = pid() | existing | new | all</v> - <v>How = boolean()</v> - <v>FlagList = [Flag]</v> - <v> Flag -- see below</v> - </type> - <desc> - <p>Turns on (if <c>How == true</c>) or off (if - <c>How == false</c>) the trace flags in <c>FlagList</c> for - the process or processes represented by <c>PidSpec</c>.</p> - <p><c>PidSpec</c> is either a pid for a local process, or one of + <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> <taglist> <tag><c>existing</c></tag> @@ -6459,7 +6278,7 @@ ok will be created in the future.</p> </item> </taglist> - <p><c>FlagList</c> can contain any number of the following + <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> <taglist> @@ -6774,11 +6593,11 @@ ok <p>Only one process can trace a particular process. For this reason, attempts to trace an already traced process will fail.</p> <p>Returns: A number indicating the number of processes that - matched <c>PidSpec</c>. If <c>PidSpec</c> is a pid, - the return value will be <c>1</c>. If <c>PidSpec</c> is + 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 the number of processes running, excluding tracer processes. - If <c>PidSpec</c> is <c>new</c>, the return value will be + If <c><anno>PidSpec</anno></c> is <c>new</c>, the return value will be <c>0</c>.</p> <p>Failure: If specified arguments are not supported. For example <c>cpu_timestamp</c> is not supported on all @@ -6786,64 +6605,58 @@ ok </desc> </func> <func> - <name>erlang:trace_delivered(Tracee) -> Ref</name> + <name name="trace_delivered" arity="1"/> <fsummary>Notification when trace has been delivered</fsummary> - <type> - <v>Tracee = pid() | all</v> - <v>Ref = reference()</v> - </type> <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>Tracee</c> has passed some specific point in its execution, + <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(Tracee)</c>. A - <c>{trace_delivered, Tracee, Ref}</c> message is sent to - the caller of <c>erlang:trace_delivered(Tracee)</c> when it + you can 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>Tracee</c> had reached + the tracer up to the point that the <c><anno>Tracee</anno></c> had reached at the time of the call to - <c>erlang:trace_delivered(Tracee)</c>.</p> + <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>Tracee</c> isn't, and + 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 <c>trace_delivered</c> message arrives.</p> - <p>Note that <c>Tracee</c> has to refer to a process currently, + <p>Note that <c><anno>Tracee</anno></c> has to refer to a process currently, or previously existing on the same node as the caller of - <c>erlang:trace_delivered(Tracee)</c> resides on. - The special <c>Tracee</c> atom <c>all</c> denotes all processes + <c>erlang:trace_delivered(<anno>Tracee</anno>)</c> resides on. + 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 tracee, port <c>B</c> is + <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, Ref}</c> message before closing + for the <c>{trace_delivered, A, <anno>Ref</anno>}</c> message before closing <c>B</c>.</p> - <p>Failure: <c>badarg</c> if <c>Tracee</c> does not refer to a + <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(Tracee)</c> resides on.</p> + <c>erlang:trace_delivered(<anno>Tracee</anno>)</c> resides on.</p> </desc> </func> <func> - <name>erlang:trace_info(PidOrFunc, Item) -> Res</name> + <name name="trace_info" arity="2"/> + <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> - <type> - <v>PidOrFunc = pid() | new | {Module, Function, Arity} | on_load</v> - <v> Module = Function = atom()</v> - <v> Arity = arity()</v> - <v>Item, Res -- see below</v> - </type> <desc> <p>Returns trace information about a process or function.</p> - <p>To get information about a process, <c>PidOrFunc</c> should + <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>Item</c> must have one of the following + be returned. <c><anno>Item</anno></c> must have one of the following values:</p> <taglist> <tag><c>flags</c></tag> @@ -6923,22 +6736,24 @@ ok <tag><c>all</c></tag> <item> - <p>Return a list containing the <c>{Item, Value}</c> tuples + <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 is active for this function.</p> </item> </taglist> - <p>The actual return value will be <c>{Item, Value}</c>, where + <p>The actual return value will be <c>{<anno>Item</anno>, Value}</c>, where <c>Value</c> is the requested information as described above. 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>PidOrFunc</c> is the <c>on_load</c>, the information + <p>If <c><anno>PidOrFunc</anno></c> is the <c>on_load</c>, the information returned refers to the default value for code that will be loaded.</p> </desc> </func> <func> - <name>erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0</name> + <name name="trace_pattern" arity="2" clause_i="1"/> + <type name="trace_pattern_mfa"/> + <type name="trace_match_spec"/> <fsummary>Set trace patterns for global call tracing</fsummary> <desc> <p>The same as @@ -6947,11 +6762,11 @@ ok </desc> </func> <func> - <name>erlang:trace_pattern(MFA, MatchSpec, FlagList) -> integer() >= 0</name> + <name name="trace_pattern" arity="3"/> + <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> - <type> - <v>MFA, MatchSpec, FlagList -- see below</v> - </type> <desc> <p>This BIF is used to enable or disable call tracing for exported functions. It must be combined with @@ -6976,7 +6791,7 @@ ok 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>MFA</c> argument should be a tuple like + <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). @@ -6999,11 +6814,11 @@ ok </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>FlagList</c>.</p> - <p>If the <c>MFA</c> argument is the atom <c>on_load</c>, + 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 modules that are newly loaded.</p> - <p>The <c>MatchSpec</c> argument can take any of the following + <p>The <c><anno>MatchSpec</anno></c> argument can take any of the following forms:</p> <taglist> <tag><c>false</c></tag> @@ -7015,7 +6830,7 @@ ok <item> <p>Enable tracing for the matching function(s).</p> </item> - <tag><c>MatchSpecList</c></tag> + <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 @@ -7023,18 +6838,18 @@ ok </item> <tag><c>restart</c></tag> <item> - <p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>: + <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 - for other <c>FlagList</c> options.</p> + for other <c><anno>FlagList</anno></c> options.</p> </item> <tag><c>pause</c></tag> <item> - <p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>: pause + <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> </item> </taglist> - <p>The <c>FlagList</c> parameter is a list of options. + <p>The <c><anno>FlagList</anno></c> parameter is a list of options. The following options are allowed:</p> <taglist> <tag><c>global</c></tag> @@ -7053,13 +6868,13 @@ ok the process, a <c>return_to</c> message will also be sent when this function returns to its caller.</p> </item> - <tag><c>meta | {meta, Pid}</c></tag> + <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 - or port <c>Pid</c> whenever any of the specified + or port <c><anno>Pid</anno></c> whenever any of the specified functions are called, regardless of how they are called. - If no <c>Pid</c> is specified, <c>self()</c> is used as a + 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>, @@ -7071,32 +6886,32 @@ ok </item> <tag><c>call_count</c></tag> <item> - <p>Starts (<c>MatchSpec == true</c>) or stops - (<c>MatchSpec == false</c>) call count tracing for all + <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 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>MatchSpec == pause</c>. Paused and running + paused with <c><anno>MatchSpec</anno> == pause</c>. Paused and running counters can be restarted from zero with - <c>MatchSpec == restart</c>.</p> + <c><anno>MatchSpec</anno> == restart</c>.</p> <p>The counter value can be read with <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p> </item> <tag><c>call_time</c></tag> <item> - <p>Starts (<c>MatchSpec == true</c>) or stops - (<c>MatchSpec == false</c>) call time tracing for all + <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. 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>MatchSpec == pause</c>. Paused and running + paused with <c><anno>MatchSpec</anno> == pause</c>. Paused and running counters can be restarted from zero with - <c>MatchSpec == restart</c>.</p> + <c><anno>MatchSpec</anno> == restart</c>.</p> <p>The counter value can be read with <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p> </item> @@ -7122,18 +6937,15 @@ ok <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>MFA</c> argument. This will be zero if none matched at + the <c><anno>MFA</anno></c> argument. This will be zero if none matched at all.</p> </desc> </func> <func> - <name>trunc(Number) -> integer()</name> + <name name="trunc" arity="1"/> <fsummary>Return an integer by the truncating a number</fsummary> - <type> - <v>Number = number()</v> - </type> <desc> - <p>Returns an integer by the truncating <c>Number</c>.</p> + <p>Returns an integer by the truncating <c><anno>Number</anno></c>.</p> <pre> > <input>trunc(5.5).</input> 5</pre> @@ -7141,13 +6953,10 @@ ok </desc> </func> <func> - <name>tuple_size(Tuple) -> integer() >= 0</name> + <name name="tuple_size" arity="1"/> <fsummary>Return the size of a tuple</fsummary> - <type> - <v>Tuple = tuple()</v> - </type> <desc> - <p>Returns an integer which is the number of elements in <c>Tuple</c>.</p> + <p>Returns an integer which is the number of elements in <c><anno>Tuple</anno></c>.</p> <pre> > <input>tuple_size({morni, mulle, bwange}).</input> 3</pre> @@ -7155,25 +6964,19 @@ ok </desc> </func> <func> - <name>tuple_to_list(Tuple) -> [term()]</name> + <name name="tuple_to_list" arity="1"/> <fsummary>Convert a tuple to a list</fsummary> - <type> - <v>Tuple = tuple()</v> - </type> <desc> - <p>Returns a list which corresponds to <c>Tuple</c>. - <c>Tuple</c> may contain any Erlang terms.</p> + <p>Returns a list which corresponds to <c><anno>Tuple</anno></c>. + <c><anno>Tuple</anno></c> may contain any Erlang terms.</p> <pre> > <input>tuple_to_list({share, {'Ericsson_B', 163}}).</input> [share,{'Ericsson_B',163}]</pre> </desc> </func> <func> - <name>erlang:universaltime() -> DateTime</name> + <name name="universaltime" arity="0"/> <fsummary>Current date and time according to Universal Time Coordinated (UTC)</fsummary> - <type> - <v>DateTime = <seealso marker="calendar#type-datetime">calendar:datetime()</seealso></v> - </type> <desc> <p>Returns the current date and time according to Universal Time Coordinated (UTC), also called GMT, in the form @@ -7187,46 +6990,39 @@ ok </desc> </func> <func> - <name>erlang:universaltime_to_localtime({Date1, Time1}) -> {Date2, Time2}</name> + <name name="universaltime_to_localtime" arity="1"/> <fsummary>Convert from Universal Time Coordinated (UTC) to local date and time</fsummary> - <type> - <v>Date1 = Date2 = <seealso marker="calendar#type-date">calendar:date()</seealso></v> - <v>Time1 = Time2 = <seealso marker="calendar#type-time">calendar:time()</seealso></v> - </type> <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 - <c>{Date1, Time1}</c> is returned.</p> + <c><anno>Universaltime</anno></c> is returned.</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>Date1</c> or <c>Time1</c> do - not denote a valid date or time.</p> + <p>Failure: <c>badarg</c> if <c>Universaltime</c> does not denote + a valid date and time.</p> </desc> </func> <func> - <name>unlink(Id) -> true</name> + <name name="unlink" arity="1"/> <fsummary>Remove a link, if there is one, to another process or port</fsummary> - <type> - <v>Id = pid() | port()</v> - </type> <desc> <p>Removes the link, if there is one, between the calling - process and the process or port referred to by <c>Id</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>Id</c>, or if <c>Id</c> does not exist.</p> - <p>Once <c>unlink(Id)</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>Id</c> has no effect on the caller in the future (unless + <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', Id, _}</c> message due to the link might have + <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', Id, _}</c> message can be the - result of the link, but can also be the result of <c>Id</c> + 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(Id)</c>, as follow:</p> + after the call to <c>unlink(<anno>Id</anno>)</c>, as follow:</p> <code type="none"> unlink(Id), @@ -7249,13 +7045,10 @@ ok </desc> </func> <func> - <name>unregister(RegName) -> true</name> + <name name="unregister" arity="1"/> <fsummary>Remove the registered name for a process (or port)</fsummary> - <type> - <v>RegName = atom()</v> - </type> <desc> - <p>Removes the registered name <c>RegName</c>, associated with a + <p>Removes the registered name <c><anno>RegName</anno></c>, associated with a pid or a port identifier.</p> <pre> > <input>unregister(db).</input> @@ -7266,7 +7059,7 @@ true</pre> </desc> </func> <func> - <name>whereis(RegName) -> pid() | port() | undefined</name> + <name name="whereis" arity="1"/> <fsummary>Get the pid (or port) with a given registered name</fsummary> <desc> <p>Returns the pid or port identifier with the registered name diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml index ec5e7d9b74..c73cdfd290 100644 --- a/erts/doc/src/erts_alloc.xml +++ b/erts/doc/src/erts_alloc.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2002</year><year>2011</year> + <year>2002</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -276,7 +276,7 @@ <item> Max cached segments. The maximum number of memory segments stored in the memory segment cache. Valid range is - 0-30. Default value is 5.</item> + 0-30. Default value is 10.</item> </taglist> <p>The following flags are available for configuration of <c>sys_alloc</c>:</p> @@ -341,7 +341,8 @@ Largest (<c>mseg_alloc</c>) multiblock carrier size (in kilobytes). See <seealso marker="#mseg_mbc_sizes">the description on how sizes for mseg_alloc multiblock carriers are decided</seealso> - in "the <c>alloc_util</c> framework" section.</item> + in "the <c>alloc_util</c> framework" section. On 32-bit Unix style OS + this limit can not be set higher than 128 megabyte.</item> <tag><marker id="M_mbcgs"><c><![CDATA[+M<S>mbcgs <ratio>]]></c></marker></tag> <item> (<c>mseg_alloc</c>) multiblock carrier growth stages. See @@ -413,7 +414,8 @@ Singleblock carrier threshold. Blocks larger than this threshold will be placed in singleblock carriers. Blocks smaller than this threshold will be placed in multiblock - carriers.</item> + carriers. On 32-bit Unix style OS this threshold can not be set higher + than 8 megabytes.</item> <tag><marker id="M_sbmbcs"><c><![CDATA[+M<S>sbmbcs <size>]]></c></marker></tag> <item> Small block multiblock carrier size (in bytes). Memory blocks smaller diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index e996d3e8e3..c9c46afa4b 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2012</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,6 +30,909 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<section><title>Erts 5.10.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The BIF <seealso + marker="erlang#is_process_alive/1"><c>is_process_alive/1</c></seealso> + could prematurely return <c>false</c> while the process + being inspected was terminating. This bug was introduced + in ERTS-5.10.</p> + <p> + Own Id: OTP-10926</p> + </item> + <item> + <p>Fix a problem in <c>erlang:delete_element/2</c> where + the call could corrupt one word of stack if the heap and + stack met during call.</p> + <p> + Own Id: OTP-10932</p> + </item> + <item> + <p> + The <seealso + marker="erl#+sws"><c>+sws<value></c></seealso> and + <seealso + marker="erl#+swt"><c>+swt<value></c></seealso> + system flags failed if no white space were passed between + the parameter and value parts of the flags. Upon failure, + the runtime system refused to start.</p> + <p> + Own Id: OTP-11000</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Scheduler threads will now by default be less eager + requesting wakeup due to certain cleanup operations. This + can also be controlled using the <seealso + marker="erl#+swct"><c>+swct</c></seealso> command line + argument of <seealso + marker="erl"><c>erl(1)</c></seealso>.</p> + <p> + Own Id: OTP-10994</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Threads created internally in the runtime system by + vanilla, fd, and spawn drivers on Windows systems could + make thread unsafe calls to <c>driver_select()</c>.</p> + <p> + Own Id: OTP-10802</p> + </item> + <item> + <p> + Threads created internally in the runtime system by the + vanilla, fd, and spawn drivers on Windows systems could + make unsafe memory accesses to driver data after port had + terminated.</p> + <p> + Own Id: OTP-10803</p> + </item> + <item> + <p> + The runtime system could crash when flushing data to + standard out or standard error on Windows.</p> + <p> + Own Id: OTP-10807</p> + </item> + <item> + <p>Bugs due to the port optimizations introduced in + erts-5.10/OTP-R16A have been fixed:</p> <list> + <item>Memory leak when terminating ports</item> + <item>Memory leak when reaching the system limit of + maximum amount of concurrently existing ports</item> + <item>Crashs due to missing, or late test of bad port + handle</item> <item>The newly introduced driver API + function <c>erl_drv_busy_msgq_limits()</c> could not be + used by dynamically linked in drivers on Windows</item> + </list> + <p> + Own Id: OTP-10809 Aux Id: OTP-10336 </p> + </item> + <item> + <p> + Fix <c>{packet,httph}</c> header capitalization for + unrecognized header fields longer than 20 charachters + such as <c>Sec-Websocket-Version</c>. The limit is simply + raised from 20 to 50 characters with the hope that valid + headers longer than 50 are not used.</p> + <p> + Own Id: OTP-10824</p> + </item> + <item> + <p> + Fix rounding issues in float_to_list/1,2. Thanks to Serge + Aleynikov</p> + <p> + Own Id: OTP-10837</p> + </item> + <item> + <p> + Fix memory leak in file driver introduced in R16A.</p> + <p> + Own Id: OTP-10841</p> + </item> + <item> + <p>A bug in an ERTS internal queue implementation could + cause the loss of a wake up signal to a consumer thread. + This has now been fixed.</p> + <p>The effect of this bug, when triggered, was often only + a small or even no delay of certain operations. This + since, threads often are woken due to other unrelated + reasons. However, if the consumer thread was not woken + due to other reasons when the bug was triggered, these + operations could be left hanging, potentially for ever. + Such effects seems to have been very rare, but we have on + at least one occasion gotten a report about such an + issue.</p> + <p>Operations potentially effected by this bug:</p> + <taglist> <tag>Inspection of memory allocation + status</tag> <item>The Erlang process calling + <c>erlang:memory/[0,1]</c>, or + <c>erlang:system_info({allocator|allocator_sizes, _})</c> + could potentially hang waiting for responses from + involved threads.</item> <tag>Async thread pool + jobs</tag> <item>An async thread pool job request and/or + reply could potentially be left hanging. In OTP this only + effected file operations, but user implemented drivers + using the async thread pool were also effected. In the + file operation case, this would typically translate into + an Erlang process potentially hanging on the file + operation.</item> <tag>Shutting down the runtime + system</tag> <item>Due to the issue with the async thread + pool mentioned above, flushing of I/O while terminating + the runtime system could also potentially hang.</item> + <tag>ETS memory deallocation</tag> <item>Scheduled jobs + handling deallocation of the main structure of an ETS + table could potentially hang. This more or less only + translates into minor memory leaks.</item> <tag>Shutting + down distribution</tag> <item>The distribution shutdown + phase used when manually shutting down the distribution, + i.e., when calling <c>net_kernel:stop()</c>, could + potentially hang.</item> </taglist> + <p> + Own Id: OTP-10854</p> + </item> + <item> + <p> + OS X Snow Leopard now only uses write, as writev does not + work properly on very large files.</p> + <p> + Own Id: OTP-10858</p> + </item> + <item> + <p> + Fixed a bug where line oriented file I/O using read_ahead + was very slow for files with very large difference in + line length.</p> + <p> + Own Id: OTP-10859</p> + </item> + <item> + <p> + In erts-5.10 (R16A) faulty hashvalues were produced for + non-ASCII atoms (characters in byte-range 128..255). This + has now been fixed and hashvalues conforms to previous + OTP releases.</p> + <p> + Own Id: OTP-10860</p> + </item> + <item> + <p> + Fixes of memory accesses that might be thread unsafe when + the runtime system has been linked against third-party + libraries for atomic memory operations during the build. + Most builds are uneffected by this bug. If triggered, the + runtime system will most likely crash more or less + immediately.</p> + <p> + Own Id: OTP-10875 Aux Id: OTP-10854 </p> + </item> + <item> + <p> + Fixed a bug where it was longer possible to give the +sws + proposal flag to non-smp emulators.</p> + <p> + Own Id: OTP-10881 Aux Id: seq12258 </p> + </item> + <item> + <p> + Faulty type to bytes read for ReadFile on Windows. This + could cause windows systems to misbehave. The correct + type is now used.</p> + <p> + Own Id: OTP-10890</p> + </item> + <item> + <p> + Change default max ports for Windows to 8192. Having a + too large value caused Windows to not be able to recover + properly. If you want to use another value, pass <c>+Q + Value</c> to erl or werl.</p> + <p> + Own Id: OTP-10892</p> + </item> + <item> + <p> + Fix rare crash on halfword vm during code loading.</p> + <p> + Own Id: OTP-10896</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Tuple funs (deprecated in R15B) are no longer supported.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10170</p> + </item> + <item> + <p> + Added four new bifs, <c>erlang:binary_to_integer/1,2</c>, + <c>erlang:integer_to_binary/1</c>, + <c>erlang:binary_to_float/1</c> and + <c>erlang:float_to_binary/1,2</c>. These bifs work + similarly to how their list counterparts work, except + they operate on binaries. In most cases converting from + and to binaries is faster than converting from and to + lists. </p> + <p> + These bifs are auto-imported into erlang source files and + can therefore be used without the <c>erlang</c> prefix.</p> + <p> + Own Id: OTP-10300 Aux Id: kunagi-74 [74] </p> + </item> + <item> + <p> + The experimental support for packages has been removed.</p> + <p> + Own Id: OTP-10348 Aux Id: kunagi-316 [227] </p> + </item> + <item> + <p>The driver API function <seealso + marker="erl_driver#erl_drv_consume_timeslice"><c>erl_drv_consume_timeslice()</c></seealso>, + and the NIF API function <seealso + marker="erl_nif#enif_consume_timeslice"><c>enif_consume_timeslice()</c></seealso> + have been introduced.</p> + <p>These functions are provided in order to better + support co-operative scheduling, improve system + responsiveness, and to make it easier to prevent + misbehaviors of the VM due to a process or port + monopolizing a scheduler thread. They can be used when + dividing lengthy work into a number of repeated calls + without the need to use threads.</p> + <p> + Own Id: OTP-10810</p> + </item> + <item> + <p> + The list_to_integer/2 bif has been optimized when used + with bases other than 10.</p> + <p> + Own Id: OTP-10834 Aux Id: kunagi-74 [74] </p> + </item> + <item> + <p> + The git commit sha of the HEAD commit is now added to the + Erlang shell when compiling a non-released Erlang + version.</p> + <p> + Own Id: OTP-10838</p> + </item> + <item> + <p>Change caching policy for memory segment allocator. + For instance, prefer sbc segments over mbc segments, + caching policy is time-arrow aware, evicting older cached + segments to store newer segments. </p> <p>The default + number of cachable segment has been increased from five + to ten segments. This can be modified, same as before, + with the command line option <c>+MMmcs 5</c></p> + <p>Impact: Increased speed for processing on larger + objects, e.g. binaries. Slight increase of mapped and + resident memory. Tune your system with memory options to + <c>erl</c> for best performance.</p> + <p> + Own Id: OTP-10840</p> + </item> + <item> + <p> + Updated config.sub and config.guess to latest version + from gnu.org</p> + <p> + Own Id: OTP-10848</p> + </item> + <item> + <p> + Add an xcomp file for Blue Gene/Q. Thanks to Kostis + Sagonas.</p> + <p> + Own Id: OTP-10849</p> + </item> + <item> + <p> + Cleanup of documentation of the type language. Thanks to + Kostis Sagonas.</p> + <p> + Own Id: OTP-10850</p> + </item> + <item> + <p> + Change the return value of hipe_bifs:remove_refs_from/1. + Thanks to Kostis Sagonas.</p> + <p> + Own Id: OTP-10851</p> + </item> + <item> + <p> + As of ERTS-5.10/OTP-R16A node names passed in the EPMD + protocol are required to be encoded in UTF-8. Since EPMD + previously accepted latin1 encoded node names this is an + incompatibility. However, since Erlang nodes always have + required characters in node names to be 7-bit ASCII + characters (and still do require this), this + incompatibility should not effect anyone using EPMD as an + Erlang Port Mapper Daemon.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10872 Aux Id: OTP-10753 </p> + </item> + <item> + <p> + The +pc flag to erl can be used to set the range of + characters considered printable. This affects how the + shell and io:format("~tp",...) functionality does + heuristic string detection. More can be read in STDLIB + users guide.</p> + <p> + Own Id: OTP-10884</p> + </item> + <item> + <p> + Fix a number of type cast errors related to formatted + printing on Win64 that can potentially cause problem when + the Erlang VM exceeds 4 GB of ram. (Thanks to Blaine + Whittle for the original patch)</p> + <p> + Own Id: OTP-10887</p> + </item> + <item> + <p> + The effect of the deprecated environment variable + ERL_MAX_PORTS had been removed premeturely. It has now + been readded. Note that this is still scheduled to be + released in R17B.</p> + <p> + Own Id: OTP-10895</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Set new peeled off SCTP socket to nonblocking socket + (Thanks to Jonas Falkevik)</p> + <p> + Own Id: OTP-10491</p> + </item> + <item> + <p> + Fix various typos (thanks to Tuncer Ayaz)</p> + <p> + Own Id: OTP-10611</p> + </item> + <item> + <p> + Fix fd leak when using async thread pool</p> + <p> When using the async thread pool, if an erlang + process asks to open a file and it gets shutdown/killed + while the file:open/2 call hasn't returned, it's possible + to leak a file descriptor against the target file. This + has now been fixed. (Thanks to Filipe David Manana)</p> + <p> + Own Id: OTP-10677</p> + </item> + <item> + <p> + Use sys/types.h instead of string.h to pull ssize_t + definition to erl_driver.h. This fixes build issue on + NetBSD. (Thanks to Yamamoto Takashi).</p> + <p> + Own Id: OTP-10699</p> + </item> + <item> + <p> + Arguments given with the -run or -s flags to erl are now + translated according to the file name encoding mode of + the runtime system.</p> + <p> + Own Id: OTP-10702</p> + </item> + <item> + <p> + The octet counters in the gen_tcp/inet interface could + behave in unexpected ways on 64bit platforms. The + behaviour is now as expected.</p> + <p> + Own Id: OTP-10746</p> + </item> + <item> + <p> + Certain linux kernels, most notably in redhat and CentOS + distribution, had a bug in writev which generated an + infinite loop in the tcp code of the VM. The bug is now + worked around.</p> + <p> + Own Id: OTP-10747</p> + </item> + <item> + <p> + A process that got killed (got an exit signal) while + operating on a compresseed file, could cause a + segmentation fault in the VM. This is now corrected. + Thanks to Filipe David Manana for identifying the problem + and submitting a solution.</p> + <p> + Own Id: OTP-10748</p> + </item> + <item> + <p> + Windows previously used three digit exponent in + formatting which caused difference between platforms, as + can be seen by float_to_list/1. This has now been fixed.</p> + <p> + Own Id: OTP-10751</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A boolean socket option 'ipv6_v6only' for IPv6 sockets + has been added. The default value of the option is OS + dependent, so applications aiming to be portable should + consider using <c>{ipv6_v6only,true}</c> when creating an + <c>inet6</c> listening/destination socket, and if + neccesary also create an <c>inet</c> socket on the same + port for IPv4 traffic. See the documentation.</p> + <p> + Own Id: OTP-8928 Aux Id: kunagi-193 [104] </p> + </item> + <item> + <p>It is now allowed to define stubs for BIFs, to allow + type specs to be written for BIFs. For example, if there + is BIF called <c>lists:member/2</c>, a dummy definition + of <c>lists:member/2</c> is now allowed.</p> + <p> + Own Id: OTP-9861</p> + </item> + <item> + <p>Process optimizations. The most notable:</p> <list> + <item>New internal process table implementation allowing + for both parallel reads as well as writes. Especially + read operations have become really cheap. This reduce + contention in various situations. For example when, + spawning processes, terminating processes, sending + messages, etc.</item> <item>Optimizations of run queue + management reducing contention.</item> + <item>Optimizations of process internal state changes reducing + contention.</item> </list> <p>These changes imply changes + of the characteristics the system. Most notable: changed + timing in the system.</p> + <p> + Own Id: OTP-9892 Aux Id: OTP-10167 </p> + </item> + <item> + <p> + Non-blocking code loading. Earlier when an Erlang module + was loaded, all other execution in the VM were halted + while the load operation was carried out in single + threaded mode. Now modules are loaded without blocking + the VM. Processes may continue executing undisturbed in + parallel during the entire load operation. The load + operation is completed by making the loaded code visible + to all processes in a consistent way with one single + atomic instruction. Non-blocking code loading will + improve realtime characteristics when modules are + loaded/upgraded on a running SMP system.</p> + <p> + Own Id: OTP-9974</p> + </item> + <item> + <p>In the SMP emulator, turning on and off tracing will + no longer take down the system to single-scheduling. </p> + <p> + Own Id: OTP-10122</p> + </item> + <item> + <p>Remove VxWorks support</p> + <p> + Own Id: OTP-10146</p> + </item> + <item> + <p> + Added a general framework for executing benchmarks of + Erlang/OTP. Benchmarks for the Erlang VM and mnesia have + been incorporated in the framework. </p> + <p> + For details about how to add more benchmarks see + $ERL_TOP/HOWTO/BENCHMARKS.md in the source distribution.</p> + <p> + Own Id: OTP-10156</p> + </item> + <item> + <p> + Optimized deletion of ETS-tables which significantly + improves performance when large amounts of temporary + tables are used.</p> + <p> + This change imply changes of the characteristics the + system. Most notable: changed timing in the system.</p> + <p> + Own Id: OTP-10167 Aux Id: OTP-9892 </p> + </item> + <item> + <p> + Tuple funs (deprecated in R15B) are no longer supported.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10170</p> + </item> + <item> + <p> + New internal header scheme for allocators</p> + <p> + Impact: Reduces size on object allocated in multiblock + carriers by one word</p> + <p> + Own Id: OTP-10273 Aux Id: kunagi-20 [20] </p> + </item> + <item> + <p>Major port improvements. The most notable:</p> <list> + <item>New internal port table implementation allowing for + both parallel reads as well as writes. Especially read + operations have become really cheap.This reduce + contention in various situations. For example when, + creating ports, terminating ports, etc. </item> + <item>Dynamic allocation of port structures. This allow + for a much larger maximum amount of ports allowed as a + default. The previous default of 1024 has been raised to + 65536. Maximum amount of ports can be set using the + <seealso marker="erts:erl#+Q">+Q</seealso> command line + flag of <seealso marker="erts:erl">erl(1)</seealso>. The + previously used environment variable <c>ERL_MAX_PORTS</c> + has been deprecated and scheduled for removal in + OTP-R17.</item> <item>Major rewrite of scheduling of port + tasks. Major benefits of the rewrite are reduced + contention on run queue locks, and reduced amount of + memory allocation operations needed. The rewrite was also + necessary in order to make it possible to schedule + signals from processes to ports.</item> <item>Improved + internal thread progress functionality for easy + management of unmanaged threads. This improvement was + necessary for the rewrite of the port task + scheduling.</item> <item>Rewrite of all process to port + signal implementations in order to make it possible to + schedule those operations. All port operations can now be + scheduled which allows for reduced lock contention on the + port lock as well as truly asynchronous communication + with ports.</item> <item>Optimized lookup of port handles + from drivers.</item> <item>Optimized driver lookup when + creating ports.</item> <item>Preemptable <seealso + marker="erts:erlang#ports-0">erlang:ports/0</seealso> + BIF.</item> <item>Improving responsiveness by bumping + reductions for a process calling a driver callback + directly.</item> </list> + <p>These changes imply changes of the characteristics of + the system. The most notable:</p> <taglist> <tag>Order of + signal delivery</tag> <item>The previous implementation + of the VM has delivered signals from processes to ports + in a synchronous stricter fashion than required by the + language. As of ERTS version 5.10, signals are truly + asynchronously delivered. The order of signal delivery + still adheres to the requirements of the language, but + only to the requirements. That is, some signal sequences + that previously always were delivered in one specific + order may now from time to time be delivered in different + orders. This may cause Erlang programs that have made + <em>false assumptions</em> about signal delivery order to + fail even though they previously succeeded. For more + information about signal ordering guarantees, see the + chapter on <seealso + marker="erts:communication">communication</seealso> in + the ERTS user's guide. The <seealso + marker="erts:erl#+n">+n</seealso> command line flag of + <seealso marker="erts:erl">erl(1)</seealso> can be + helpful when trying to find signaling order bugs in + Erlang code that have been exposed by these + changes.</item> <tag>Latency of signals sent from + processes to ports</tag> <item>Signals from processes to + ports where previously always delivered immediately. This + kept latency for such communication to a minimum, but it + could cause lock contention which was very expensive for + the system as a whole. In order to keep this latency low + also in the future, most signals from processes to ports + are by default still delivered immediately as long as no + conflicts occur. Such conflicts include not being able to + acquire the port lock, but also include other conflicts. + When a conflict occur, the signal will be scheduled for + delivery at a later time. A scheduled signal delivery may + cause a higher latency for this specific communication, + but improves the overall performance of the system since + it reduce lock contention between schedulers. The default + behavior of only scheduling delivery of these signals on + conflict can be changed by passing the <seealso + marker="erts:erl#+spp">+spp</seealso> command line flag + to <seealso marker="erts:erl">erl(1)</seealso>. The + behavior can also be changed on port basis using the + <seealso + marker="erts:erlang#open_port_parallelism">parallelism</seealso> + option of the <seealso + marker="erts:erlang#open_port-2">open_port/2</seealso> + BIF.</item> <tag>Execution time of the + <c>erlang:ports/0</c> BIF</tag> <item>Since <seealso + marker="erts:erlang#ports-0">erlang:ports/0</seealso> now + can be preempted, the responsiveness of the system as a + whole has been improved. A call to <c>erlang:ports/0</c> + may, however, take a much longer time to complete than + before. How much longer time heavily depends on the + system load.</item> <tag>Reduction cost of calling driver + callbacks</tag> <item>Calling a driver callback is quite + costly. This was previously not reflected in reduction + cost at all. Since the reduction cost now has increased, + a process performing lots of direct driver calls will be + scheduled out more frequently than before.</item> + </taglist> + <p><em>Potential incompatibilities</em>:</p> <list> + <item><c>driver_send_term()</c> has been deprecated and + has been scheduled for removal in OTP-R17. Replace usage + of <c>driver_send_term()</c> with usage of <seealso + marker="erts:erl_driver#erl_drv_send_term">erl_drv_send_term()</seealso>.</item> + <item><c>driver_output_term()</c> has been deprecated and + has been scheduled for removal in OTP-R17. Replace usage + of <c>driver_output_term()</c> with usage of <seealso + marker="erts:erl_driver#erl_drv_output_term">erl_drv_output_term()</seealso>.</item> + <item>The new function <seealso + marker="erts:erl_driver#erl_drv_busy_msgq_limits">erl_drv_busy_msgq_limits()</seealso> + has been added in order to able to control management of + port queues.</item> </list> + <p>The <seealso + marker="erts:erl_driver#version_management">driver API + version</seealso> has been bumped to 2.1 from 2.0 due to + the above changes in the driver API.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10336 Aux Id: OTP-9892 </p> + </item> + <item> + <p> + The experimental support for packages has been removed.</p> + <p> + Own Id: OTP-10348 Aux Id: kunagi-316 [227] </p> + </item> + <item> + <p> + Wrong parameters when setting seq_trace-tokens from + within a trace-pattern could crash the VM. This is now + corrected.</p> + <p> + Own Id: OTP-10522</p> + </item> + <item> + <p> + Erlang specification 4.7.3 defines max tuple size to + 65535 elements It is now enforced to no more than + 16777215 elements (arity 24 bits)</p> + <p> + Previous edge cases (28 bits) were not validated and + could cause undefined behaviour.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10633</p> + </item> + <item> + <p> + Add insert_element/3 and delete_element/2</p> + <p> + Own Id: OTP-10643</p> + </item> + <item> + <p> + The previous default of a maximum of 32768 simultaneous + processes has been raised to 262144. This value can be + changed using the the <seealso + marker="erl#+P">+P</seealso> command line flag of + <seealso marker="erl">erl(1)</seealso>. Note that the + value passed now is considered as a hint, and that actual + value chosen in most cases will be a power of two.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10647 Aux Id: OTP-9892, OTP-10336 </p> + </item> + <item> + <p> + The previously (in R15) proposed scheduler wakeup + strategy is now used by default. This strategy is not as + quick to forget about previous overload as the previous + strategy.</p> + <p> + This change imply changes of the characteristics the + system. Most notable: When a small overload comes and + then disappears repeatedly, the system will for a bit + longer time be willing to wake up schedulers than before. + Timing in the system will due to this also change.</p> + <p> + The previous strategy can still be enabled by passing the + <seealso marker="erl#+sws">+sws legacy</seealso> command + line flag to <c>erl</c>.</p> + <p> + Own Id: OTP-10661 Aux Id: OTP-10033 </p> + </item> + <item> + <p> + The <seealso marker="erl#+stbt">+stbt</seealso> command line + argument of <c>erl</c> was added. This argument can be + used for trying to set scheduler bind type. Upon failure + unbound schedulers will be used.</p> + <p> + Own Id: OTP-10668</p> + </item> + <item> + <p> + Support ANSI in console</p> + <p> + Unix platforms will no longer filter control sequences to + the ttsl driver thus enabling ANSI and colors in console. + (Thanks to Pedram Nimreezi)</p> + <p> + Own Id: OTP-10678</p> + </item> + <item> + <p>Add file:allocate/3 operation</p> + <p>This operation allows pre-allocation of space for + files. It succeeds only on systems that support such + operation. (Thanks to Filipe David Manana)</p> + <p> + Own Id: OTP-10680</p> + </item> + <item> + <p>Treat <c>-Wreturn-type</c> warnings as error when + using GCC (Thanks to Tuncer Ayaz)</p> + <p> + Own Id: OTP-10683</p> + </item> + <item> + <p> + Implement ./otp_build configure --enable-silent-rules</p> + <p> + With silent rules, the output of make is less verbose and + compilation warnings are easier to spot. Silent rules are + disabled by default and can be disabled or enabled at + will by make V=0 and make V=1. (Thanks to Anthony Ramine)</p> + <p> + Own Id: OTP-10726</p> + </item> + <item> + <p> + Use share flags for all file operations on Windows. + Thanks to Filipe David Borba Manana.</p> + <p> + Own Id: OTP-10727</p> + </item> + <item> + <p> + Make/fakefop adjustments. Thanks to Tuncer Ayaz and + Sebastian Rasmussen.</p> + <p> + Own Id: OTP-10733</p> + </item> + <item> + <p> + The runtime system will now by default use 10 async + threads if thread support has been enabled when building + the runtime system.</p> + <p> + This will prevent long blocking file-operations from + blocking scheduler threads for long periods of time, + which can be harmful. Apart from file-operations, it also + effects other operations scheduled on the async thread + pool by user implemented drivers.</p> + <p> + The amount of async threads can be controlled by using + the <seealso + marker="erl#async_thread_pool_size"><c>+A</c></seealso> + command line argument of <c>erl(1)</c>. When running some + offline tools you <em>might</em> want to disable async + threads, but you are advised <em>not</em> to in the + general case. Instead, you might want to increase the + amount of async threads used.</p> + <p> + This change imply changes of the characteristics the + system compared to the previous default. The + responsiveness of the system as a whole will be improved. + Operations scheduled on the async thread pool will get an + increased latency. The throughput of these operations may + increase, or decrease depending on the type of the + operations and how they get scheduled. In the case of + file operations, the throughput very much depends on how + the Erlang application access files. Multiple concurrent + accesses to different files have the potential of an + increased throughput.</p> + <p> + Own Id: OTP-10736</p> + </item> + <item> + <p> + The default reader group limit has been increased to 64 + from 8. This limit can be set using the <c>+rg</c> + command line argument of <c>erl(1)</c>.</p> + <p> + This change of default value will reduce lock contention + on ETS tables using the <c>read_concurrency</c> option at + the expense of memory consumption when the amount of + schedulers and logical processors are beween 8 and 64. + For more information, see documentation of the <c>+rg</c> + command line argument of <c>erl(1)</c>.</p> + <p> + Own Id: OTP-10737</p> + </item> + <item> + <p> + New BIF float_to_list/2 which solves a problem of + float_to_list/1 that doesn't allow specifying the number + of digits after the decimal point when formatting floats + (Thanks to Serge Aleynikov).</p> + <p> + Own Id: OTP-10752</p> + </item> + <item> + <p> + Limited support for unicode atoms in the external format + and in the internal representation of the vm. This is a + preparative feature in order to support communication + with future releases of Erlang/OTP that may create + unicode atoms.</p> + <p> + Own Id: OTP-10753</p> + </item> + <item> + <p> + Increased potential concurrency in ETS for + <c>write_concurrency</c> option. The number of internal + table locks has increased from 16 to 64. This makes it + four times less likely that two concurrent processes + writing to the same table would collide and thereby + serialized. The cost is an increased constant memory + footprint for tables using write_concurrency. The memory + consumption per inserted record is not affected. The + increased footprint can be particularly large if + <c>write_concurrency</c> is combined with + <c>read_concurrency</c>.</p> + <p> + Own Id: OTP-10787</p> + </item> + </list> + </section> + +</section> + <section><title>Erts 5.9.3.1</title> <section><title>Known Bugs and Problems</title> diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml index e27b722721..fa50329cad 100644 --- a/erts/doc/src/part.xml +++ b/erts/doc/src/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,7 @@ <description> <p>The Erlang Runtime System Application <em>ERTS</em>.</p> </description> + <xi:include href="communication.xml"/> <xi:include href="match_spec.xml"/> <xi:include href="crash_dump.xml"/> <xi:include href="alt_dist.xml"/> diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml index 2042cf28bd..e55923c344 100644 --- a/erts/doc/src/ref_man.xml +++ b/erts/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -49,7 +49,6 @@ <xi:include href="escript.xml"/> <xi:include href="erlsrv.xml"/> <xi:include href="start_erl.xml"/> - <xi:include href="erl_set_memory_block.xml"/> <xi:include href="run_erl.xml"/> <xi:include href="start.xml"/> <xi:include href="erl_driver.xml"/> |