diff options
Diffstat (limited to 'erts/doc/src')
| -rw-r--r-- | erts/doc/src/absform.xml | 17 | ||||
| -rw-r--r-- | erts/doc/src/crash_dump.xml | 4 | ||||
| -rw-r--r-- | erts/doc/src/erl_cmd.xml | 24 | ||||
| -rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 382 | ||||
| -rw-r--r-- | erts/doc/src/erl_driver.xml | 8 | ||||
| -rw-r--r-- | erts/doc/src/erl_ext_dist.xml | 69 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 357 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 657 | ||||
| -rw-r--r-- | erts/doc/src/erlsrv_cmd.xml | 5 | ||||
| -rw-r--r-- | erts/doc/src/erts_alloc.xml | 26 | ||||
| -rw-r--r-- | erts/doc/src/match_spec.xml | 61 | ||||
| -rw-r--r-- | erts/doc/src/time_correction.xml | 62 | ||||
| -rw-r--r-- | erts/doc/src/tty.xml | 20 |
13 files changed, 1186 insertions, 506 deletions
diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index afdb2e7b70..d5c27bb200 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2001</year><year>2021</year> + <year>2001</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -412,6 +412,13 @@ For Rep(Q), see below.</p> </item> <item> + <p>If E is a map comprehension <c>#{E_0 || Q_1, ..., Q_k}</c>, + where <c>E_0</c> is an association <c>K => V</c> + and each <c>Q_i</c> is a qualifier, then Rep(E) = + <c>{mc,ANNO,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}</c>. + For Rep(E_0) and Rep(Q), see below.</p> + </item> + <item> <p>If E is a map creation <c>#{A_1, ..., A_k}</c>, where each <c>A_i</c> is an association <c>E_i_1 => E_i_2</c>, then Rep(E) = <c>{map,ANNO,[Rep(A_1), ..., Rep(A_k)]}</c>. @@ -564,7 +571,7 @@ Rep(Q) = <c>Rep(E)</c>.</p> </item> <item> - <p>If Q is a generator <c>P <- E</c>, where <c>P</c> is + <p>If Q is a list generator <c>P <- E</c>, where <c>P</c> is a pattern and <c>E</c> is an expression, then Rep(Q) = <c>{generate,ANNO,Rep(P),Rep(E)}</c>.</p> </item> @@ -573,6 +580,12 @@ a pattern and <c>E</c> is an expression, then Rep(Q) = <c>{b_generate,ANNO,Rep(P),Rep(E)}</c>.</p> </item> + <item> + <p>If Q is a map generator <c>P <- E</c>, where <c>P</c> is + an association pattern <c>P_1 := P_2</c> and <c>E</c> is an expression, then Rep(Q) = + <c>{m_generate,ANNO,Rep(P),Rep(E)}</c>. + For Rep(P), see below.</p> + </item> </list> </section> diff --git a/erts/doc/src/crash_dump.xml b/erts/doc/src/crash_dump.xml index 4524401473..bc3e085099 100644 --- a/erts/doc/src/crash_dump.xml +++ b/erts/doc/src/crash_dump.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1999</year><year>2022</year> + <year>1999</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -534,7 +534,7 @@ Slogan: <reason></pre> <tag><em>Type</em></tag> <item> <p>The table type, that is, <c>set</c>, <c>bag</c>, - <c>dublicate_bag</c>, or <c>ordered_set</c>.</p> + <c>duplicate_bag</c>, or <c>ordered_set</c>.</p> </item> <tag><em>Compressed</em></tag> <item> diff --git a/erts/doc/src/erl_cmd.xml b/erts/doc/src/erl_cmd.xml index ebfed75bf4..f6a36ecffd 100644 --- a/erts/doc/src/erl_cmd.xml +++ b/erts/doc/src/erl_cmd.xml @@ -540,12 +540,12 @@ $ <input>erl \ to implement an Alternative Carrier for the Erlang Distribution</seeguide>.</p> </item> - <tag><c><![CDATA[-noinput]]></c></tag> + <tag><marker id="noinput"/><c><![CDATA[-noinput]]></c></tag> <item> <p>Ensures that the Erlang runtime system never tries to read any input. Implies <c><![CDATA[-noshell]]></c>.</p> </item> - <tag><c><![CDATA[-noshell]]></c></tag> + <tag><marker id="noshell"/><c><![CDATA[-noshell]]></c></tag> <item> <p>Starts an Erlang runtime system with no shell. This flag makes it possible to have the Erlang runtime system as a @@ -949,6 +949,14 @@ $ <input>erl \ <seeerl marker="erlang#process_flag_max_heap_size"> <c>process_flag(max_heap_size, MaxHeapSize)</c></seeerl>.</p> </item> + <tag><marker id="+hmaxib"/><c><![CDATA[+hmaxib true|false]]></c></tag> + <item> + <p>Sets whether to include the size of shared off-heap binaries + in the sum compared against the maximum heap size. Defaults to + <c>false</c>. For more information, see + <seeerl marker="erlang#process_flag_max_heap_size"> + <c>process_flag(max_heap_size, MaxHeapSize)</c></seeerl>.</p> + </item> <tag><marker id="+hmaxk"/><c><![CDATA[+hmaxk true|false]]></c></tag> <item> <p>Sets whether to kill processes reaching the maximum heap size or not. @@ -1048,6 +1056,18 @@ $ <input>erl \ section in the BeamAsm internal documentation. </p> </item> + <tag><marker id="+JMsingle"/><c>+JMsingle true|false</c></tag> + <item> + <p>Enables or disables the use of single-mapped RWX memory for JIT + code. The default is to map JIT:ed machine code into two + regions sharing the same physical pages, where one region is + executable but not writable, and the other writable but not + executable. As some tools, such as QEMU user mode emulation, + cannot deal with the dual mapping, this flags allows it to be + disabled. This flag is automatically enabled by the + <seecom marker="#+JPperf"><c>+JPperf</c></seecom> flag. + </p> + </item> <tag><c><![CDATA[+L]]></c></tag> <item> <p>Prevents loading information about source filenames and line diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index 400d3d896d..389e967f5f 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -1097,11 +1097,8 @@ DiB == gen_digest(ChA, ICA)? </item> <tag><marker id="DFLAG_UNLINK_ID"/><c>-define(DFLAG_UNLINK_ID, 16#2000000).</c></tag> <item> - <p>Use the <seeguide marker="#new_link_protocol">new link protocol</seeguide>.</p> - <note><p>This flag will become mandatory in OTP 26.</p></note> - <p>Unless both nodes have set the <c>DFLAG_UNLINK_ID</c> flag, the - <seeguide marker="#old_link_protocol">old link protocol</seeguide> - will be used as a fallback.</p> + <p>Use the <seeguide marker="#link_protocol">new link protocol</seeguide>.</p> + <note><p>This flag is mandatory as of OTP 26.</p></note> </item> <tag><c>-define(DFLAG_MANDATORY_25_DIGEST, (1 bsl 36)).</c></tag> <item> @@ -1133,8 +1130,7 @@ DiB == gen_digest(ChA, ICA)? <seeguide marker="erl_ext_dist#V4_PORT_EXT"><c>V4_PORT_EXT</c></seeguide>, and in the reference case up to 5 32-bit ID words are now accepted in <seeguide marker="erl_ext_dist#NEWER_REFERENCE_EXT"><c>NEWER_REFERENCE_EXT</c></seeguide>. - Introduced in OTP 24.</p> - <note><p>This flag will become mandatory in OTP 26.</p></note> + This flag was introduced in OTP 24 and became mandatory in OTP 26.</p> </item> <tag><marker id="DFLAG_ALIAS"/><c>-define(DFLAG_ALIAS, (1 bsl 35)).</c></tag> <item> @@ -1273,17 +1269,12 @@ DiB == gen_digest(ChA, ICA)? <p><c>{3, FromPid, ToPid, Reason}</c></p> <p>This signal is sent when a link has been broken</p> </item> - <tag><marker id="UNLINK"/><c>UNLINK</c> (deprecated)</tag> + <tag><marker id="UNLINK"/><c>UNLINK</c> (obsolete)</tag> <item> <p><c>{4, FromPid, ToPid}</c></p> - <p>This signal is sent by <c>FromPid</c> in order to remove - a link between <c>FromPid</c> and <c>ToPid</c>, when using the - <seeguide marker="#old_link_protocol">old link - protocol</seeguide>.</p> - <warning><p>This signal has been deprecated and will not - be supported in OTP 26. For more information see the - documentation of the - <seeguide marker="#new_link_protocol">new link protocol</seeguide>. + <warning><p>This signal is obsolete and not supported as of + OTP 26. For more information see the documentation of the + <seeguide marker="#link_protocol">link protocol</seeguide>. </p></warning> </item> <tag><c>NODE_LINK</c></tag> @@ -1573,11 +1564,9 @@ DiB == gen_digest(ChA, ICA)? among all not yet acknowledged <c>UNLINK_ID</c> signals from <c>FromPid</c> to <c>ToPid</c>.</p> <p> - This signal is only passed when the - <seeguide marker="#new_link_protocol">new link protocol</seeguide> - has been negotiated using the - <seeguide marker="erl_dist_protocol#DFLAG_UNLINK_ID"><c>DFLAG_UNLINK_ID</c></seeguide> - <seeguide marker="erl_dist_protocol#dflags">distribution flag</seeguide>. + This signal is part of the + <seeguide marker="#link_protocol">new link protocol</seeguide> + which became mandatory as of OTP 26. </p> </item> <tag><marker id="UNLINK_ID_ACK"/><c>UNLINK_ID_ACK</c></tag> @@ -1592,11 +1581,9 @@ DiB == gen_digest(ChA, ICA)? <c>ToPid</c> identifies the sender of the <c>UNLINK_ID</c> signal.</p> <p> - This signal is only passed when the - <seeguide marker="#new_link_protocol">new link protocol</seeguide> - has been negotiated using the - <seeguide marker="erl_dist_protocol#DFLAG_UNLINK_ID"><c>DFLAG_UNLINK_ID</c></seeguide> - <seeguide marker="erl_dist_protocol#dflags">distribution flag</seeguide>. + This signal is part of the + <seeguide marker="#link_protocol">new link protocol</seeguide> + which became mandatory as of OTP 26. </p> </item> </taglist> @@ -1627,200 +1614,173 @@ DiB == gen_digest(ChA, ICA)? </section> <section> <marker id="link_protocol"/> + <!-- The following markers kept in order not to break links + from the outside world... --> + <marker id="new_link_protocol"/> + <marker id="old_link_protocol"/> <title>Link Protocol</title> - <section> - <marker id="new_link_protocol"/> - <title>New Link Protocol</title> - - <p> - The new link protocol will be used when both nodes flag that - they understand it using the - <seeguide marker="#DFLAG_UNLINK_ID"><c>DFLAG_UNLINK_ID</c></seeguide> - <seeguide marker="#dflags">distribution flag</seeguide>. If - one of the nodes does not understand the new link protocol, the - <seeguide marker="#old_link_protocol">old link protocol</seeguide> - will be used as a fallback. - </p> - - <p> - The new link protocol introduces two new signals, - <seeguide marker="#UNLINK_ID"><c>UNLINK_ID</c></seeguide> and - <seeguide marker="#UNLINK_ID"><c>UNLINK_ID_ACK</c></seeguide>, - which replace the old - <seeguide marker="#UNLINK"><c>UNLINK</c></seeguide> - signal. The old <seeguide marker="#LINK"><c>LINK</c></seeguide> - signal is still sent in order to set up a link, but handled - differently upon reception. - </p> - - <p> - In order to set up a link, a <c>LINK</c> signal is sent, from - the process initiating the operation, to the process that it - wants to link to. In order to remove a link, an - <c>UNLINK_ID</c> signal is sent, from the process initiating - the operation, to the linked process. The receiver of an - <c>UNLINK_ID</c> signal responds with an <c>UNLINK_ID_ACK</c> - signal. Upon reception of an <c>UNLINK_ID</c> signal, the - corresponding <c>UNLINK_ID_ACK</c> signal <em>must</em> be - sent before any other signals are sent to the sender of the - <c>UNLINK_ID</c> signal. Together with - <seeguide marker="system/reference_manual:processes#signal-delivery">the - signal ordering guarantee</seeguide> of Erlang this makes it - possible for the sender of the <c>UNLINK_ID</c> signal to know - the order of other signals which is essential for the protocol. - The <c>UNLINK_ID_ACK</c> signal should contain the same - <c>Id</c> as the <c>Id</c> contained in the <c>UNLINK_ID</c> - signal being acknowledged. - </p> + <p> + The new link protocol introduced in OTP 23.3 became mandatory + as of OTP 26. As of OTP 26, OTP nodes will therefor refuse to + connect to nodes that do not indicate that they support the + new link protocol using the + <seeguide marker="#DFLAG_UNLINK_ID"><c>DFLAG_UNLINK_ID</c></seeguide> + <seeguide marker="#dflags">distribution flag</seeguide>. + </p> - <p> - Processes also need to maintain process local information about - links. The state of this process local information is changed - when the signals above are sent and received. This process - local information also determines if a signal should be sent - when a process calls - <seemfa marker="erlang#link/1"><c>link/1</c></seemfa> or - <seemfa marker="erlang#unlink/1"><c>unlink/1</c></seemfa>. - A <c>LINK</c> signal is only sent if there does not currently - exist an active link between the processes according to the - process local information and an <c>UNLINK_ID</c> signal is - only sent if there currently exists an active link between the - processes according to the process local information. - </p> + <p> + The new link protocol introduced two new signals, + <seeguide marker="#UNLINK_ID"><c>UNLINK_ID</c></seeguide> and + <seeguide marker="#UNLINK_ID"><c>UNLINK_ID_ACK</c></seeguide>, + which replaced the old + <seeguide marker="#UNLINK"><c>UNLINK</c></seeguide> + signal. The old <seeguide marker="#LINK"><c>LINK</c></seeguide> + signal is still sent in order to set up a link, but handled + differently upon reception. + </p> - <p> - The process local information about a link contains: - </p> - <taglist> - <tag>Pid</tag> - <item> - Process identifier of the linked process. - </item> - <tag>Active Flag</tag> - <item> - If set, the link is active and the process will react on - <seeguide marker="system/reference_manual:processes#receiving_exit_signals">incoming - exit signals</seeguide> issued due to the link. If not set, - the link is inactive and incoming exit signals, issued due - to the link, will be ignored. That is, the processes are - considered as <em>not</em> linked. - </item> - <tag>Unlink Id</tag> - <item> - Identifier of an outstanding unlink operation. That is, - an unlink operation that has not yet been acknowledged. - This information is only used when the active flag is not - set. - </item> - </taglist> + <p> + In order to set up a link, a <c>LINK</c> signal is sent, from + the process initiating the operation, to the process that it + wants to link to. In order to remove a link, an + <c>UNLINK_ID</c> signal is sent, from the process initiating + the operation, to the linked process. The receiver of an + <c>UNLINK_ID</c> signal responds with an <c>UNLINK_ID_ACK</c> + signal. Upon reception of an <c>UNLINK_ID</c> signal, the + corresponding <c>UNLINK_ID_ACK</c> signal <em>must</em> be + sent before any other signals are sent to the sender of the + <c>UNLINK_ID</c> signal. Together with + <seeguide marker="system/reference_manual:processes#signal-delivery">the + signal ordering guarantee</seeguide> of Erlang this makes it + possible for the sender of the <c>UNLINK_ID</c> signal to know + the order of other signals which is essential for the protocol. + The <c>UNLINK_ID_ACK</c> signal should contain the same + <c>Id</c> as the <c>Id</c> contained in the <c>UNLINK_ID</c> + signal being acknowledged. + </p> - <p> - A process is only considered linked to another process - if it has process local information about the link - containing the process identifier of the other process and - with the active flag set. - </p> + <p> + Processes also need to maintain process local information about + links. The state of this process local information is changed + when the signals above are sent and received. This process + local information also determines if a signal should be sent + when a process calls + <seemfa marker="erlang#link/1"><c>link/1</c></seemfa> or + <seemfa marker="erlang#unlink/1"><c>unlink/1</c></seemfa>. + A <c>LINK</c> signal is only sent if there does not currently + exist an active link between the processes according to the + process local information and an <c>UNLINK_ID</c> signal is + only sent if there currently exists an active link between the + processes according to the process local information. + </p> - <p> - The process local information about a link is updated as - follows: - </p> - <taglist> - <tag>A <c>LINK</c> signal is sent</tag> - <item> - Link information is created if not already existing. The - active flag is set, and unlink id is cleared. That is, - if we had an outstanding unlink operation we will ignore - the result of that operation and enable the link. - </item> - <tag>A <c>LINK</c> signal is received</tag> - <item> - If no link information already exists, it is created, the - active flag is set and unlink id is cleared. If the link - information already exists, the signal is silently ignored, - regardless of whether the active flag is set or not. - That is, if we have an outstanding unlink operation we will - <em>not</em> activate the link. In this scenario, the sender - of the <c>LINK</c> signal has not yet sent an - <c>UNLINK_ID_ACK</c> signal corresponding to our - <c>UNLINK_ID</c> signal which means that it will receive - our <c>UNLINK_ID</c> signal after it sent its - <c>LINK</c> signal. This in turn means that both processes - in the end will agree that there is no link between them. - </item> - <tag>An <c>UNLINK_ID</c> signal is sent</tag> - <item> - Link information already exists and the active flag is set - (otherwise the signal would not be sent). The active flag - is unset, and the unlink id of the signal is saved in the - link information. - </item> - <tag>An <c>UNLINK_ID</c> signal is received</tag> - <item> - If the active flag is set, information about the link - is removed. If the active flag is not set (that is, we have - an outstanding unlink operation), the information about the - link is left unchanged. - </item> - <tag>An <c>UNLINK_ID_ACK</c> signal is sent</tag> - <item> - This is done when an <c>UNLINK_ID</c> signal is received and - causes no further changes of the link information. - </item> - <tag>An <c>UNLINK_ID_ACK</c> signal is received</tag> - <item> - If information about the link exists, the active flag is not - set, and the unlink id in the link information equals the - <c>Id</c> in the signal, the link information is removed; - otherwise, the signal is ignored. - </item> - </taglist> + <p> + The process local information about a link contains: + </p> + <taglist> + <tag>Pid</tag> + <item> + Process identifier of the linked process. + </item> + <tag>Active Flag</tag> + <item> + If set, the link is active and the process will react on + <seeguide marker="system/reference_manual:processes#receiving_exit_signals">incoming + exit signals</seeguide> issued due to the link. If not set, + the link is inactive and incoming exit signals, issued due + to the link, will be ignored. That is, the processes are + considered as <em>not</em> linked. + </item> + <tag>Unlink Id</tag> + <item> + Identifier of an outstanding unlink operation. That is, + an unlink operation that has not yet been acknowledged. + This information is only used when the active flag is not + set. + </item> + </taglist> - <p> - When a process receives an exit signal due to a link, the - process will first react to the exit signal if the link - is active and then remove the process local information about - the link. - </p> - <p> - In case the connection is lost between two nodes, exit signals - with exit reason <c>noconnection</c> are sent to all processes - with links over the connection. This will cause all process - local information about links over the connection to be - removed. - </p> - <p> - Exactly the same link protocol is also used internally on an - Erlang node. The signals however have different formats since - they do not have to be sent over the wire. - </p> - </section> + <p> + A process is only considered linked to another process + if it has process local information about the link + containing the process identifier of the other process and + with the active flag set. + </p> - <section> - <marker id="old_link_protocol"/> - <title>Old Link Protocol</title> + <p> + The process local information about a link is updated as + follows: + </p> + <taglist> + <tag>A <c>LINK</c> signal is sent</tag> + <item> + Link information is created if not already existing. The + active flag is set, and unlink id is cleared. That is, + if we had an outstanding unlink operation we will ignore + the result of that operation and enable the link. + </item> + <tag>A <c>LINK</c> signal is received</tag> + <item> + If no link information already exists, it is created, the + active flag is set and unlink id is cleared. If the link + information already exists, the signal is silently ignored, + regardless of whether the active flag is set or not. + That is, if we have an outstanding unlink operation we will + <em>not</em> activate the link. In this scenario, the sender + of the <c>LINK</c> signal has not yet sent an + <c>UNLINK_ID_ACK</c> signal corresponding to our + <c>UNLINK_ID</c> signal which means that it will receive + our <c>UNLINK_ID</c> signal after it sent its + <c>LINK</c> signal. This in turn means that both processes + in the end will agree that there is no link between them. + </item> + <tag>An <c>UNLINK_ID</c> signal is sent</tag> + <item> + Link information already exists and the active flag is set + (otherwise the signal would not be sent). The active flag + is unset, and the unlink id of the signal is saved in the + link information. + </item> + <tag>An <c>UNLINK_ID</c> signal is received</tag> + <item> + If the active flag is set, information about the link + is removed. If the active flag is not set (that is, we have + an outstanding unlink operation), the information about the + link is left unchanged. + </item> + <tag>An <c>UNLINK_ID_ACK</c> signal is sent</tag> + <item> + This is done when an <c>UNLINK_ID</c> signal is received and + causes no further changes of the link information. + </item> + <tag>An <c>UNLINK_ID_ACK</c> signal is received</tag> + <item> + If information about the link exists, the active flag is not + set, and the unlink id in the link information equals the + <c>Id</c> in the signal, the link information is removed; + otherwise, the signal is ignored. + </item> + </taglist> - <p> - The old link protocol utilize two signals - <seeguide marker="#LINK"><c>LINK</c></seeguide>, and - <seeguide marker="#UNLINK"><c>UNLINK</c></seeguide>. The - <c>LINK</c> signal informs the other process that a link - should be set up, and the <c>UNLINK</c> signal informs the - other process that a link should be removed. This protocol - is however a bit too naive. If both processes operate on the - link simultaneously, the link may end up in an inconsistent - state where one process thinks it is linked while the other - thinks it is not linked. - </p> - <p> - This protocol is deprecated and support for it will be removed - in OTP 26. Until then, it will be used as fallback when - communicating with old nodes that do not understand the - <seeguide marker="#new_link_protocol">new link - protocol</seeguide>. - </p> - </section> + <p> + When a process receives an exit signal due to a link, the + process will first react to the exit signal if the link + is active and then remove the process local information about + the link. + </p> + <p> + In case the connection is lost between two nodes, exit signals + with exit reason <c>noconnection</c> are sent to all processes + with links over the connection. This will cause all process + local information about links over the connection to be + removed. + </p> + <p> + Exactly the same link protocol is also used internally on an + Erlang node. The signals however have different formats since + they do not have to be sent over the wire. + </p> </section> </section> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 2547b6e952..5e0e0349f3 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>2021</year> + <year>2001</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -2567,12 +2567,14 @@ ErlDrvTermData spec[] = { ERL_DRV_STRING_CONS, (ErlDrvTermData)"abc", 3, }; 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 + <p> + <marker id="ERL_DRV_EXT2TERM"/> + The <c>ERL_DRV_EXT2TERM</c> term type is used for passing a term encoded with the <seeguide marker="erl_ext_dist">external format</seeguide>, that is, a term that has been encoded by <seemfa marker="erlang#term_to_binary/2"> - <c>erlang:term_to_binary</c></seemfa>, + <c>erlang:term_to_binary()</c></seemfa>, <seecref marker="erl_interface:ei"><c>erl_interface:ei(3)</c></seecref>, and so on. For example, if <c>binp</c> is a pointer to an <c>ErlDrvBinary</c> diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index b4b245187d..712c30afc0 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>2021</year> + <year>2023</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -655,6 +655,7 @@ encoded using <c>NEW_PORT_EXT</c>, even external ports received as <seeguide marker="#PORT_EXT"><c>PORT_EXT</c></seeguide> from older nodes. </p> + </section> <section> @@ -683,8 +684,10 @@ works just like in <seeguide marker="#NEW_PID_EXT"><c>NEW_PID_EXT</c></seeguide>. Port operations are not allowed across node boundaries. </p> - <p><c>V4_PORT_EXT</c> was introduced in OTP 24, but only to be decoded - and echoed back. Not encoded for local ports. + <p>In OTP 26 distribution flag + <seeguide marker="erl_dist_protocol#DFLAG_V4_NC"><c>DFLAG_V4_NC</c></seeguide> + as well as <c>V4_PORT_EXT</c> became mandatory accepting full + 64-bit ports to be decoded and echoed back. </p> </section> @@ -742,14 +745,10 @@ <seeguide marker="#utf8_atoms">encoded as an atom</seeguide>.</p> </item> <tag><c>ID</c></tag> - <item><p>A 32-bit big endian unsigned integer. If distribution flag - <seeguide marker="erl_dist_protocol#DFLAG_V4_NC"><c>DFLAG_V4_NC</c></seeguide> - is not set, only 15 bits may be used and the rest must be 0.</p> + <item><p>A 32-bit big endian unsigned integer.</p> </item> <tag><c>Serial</c></tag> - <item><p>A 32-bit big endian unsigned integer. If distribution flag - <seeguide marker="erl_dist_protocol#DFLAG_V4_NC"><c>DFLAG_V4_NC</c></seeguide> - is not set, only 13 bits may be used and the rest must be 0.</p> + <item><p>A 32-bit big endian unsigned integer.</p> </item> <tag><c>Creation</c></tag> <item><p>A 32-bit big endian unsigned integer. All identifiers @@ -768,9 +767,10 @@ even external pids received as <seeguide marker="#PID_EXT"><c>PID_EXT</c></seeguide> from older nodes. </p> - <p>In OTP 24 distribution flag + <p>In OTP 26 distribution flag <seeguide marker="erl_dist_protocol#DFLAG_V4_NC"><c>DFLAG_V4_NC</c></seeguide> - was introduced, accepting full 64-bit pids to be decoded and echoed back. + became mandatory accepting full 64-bit pids to be decoded + and echoed back. </p> </section> @@ -1080,9 +1080,7 @@ <seeguide marker="#utf8_atoms">encoded as an atom</seeguide>.</p> </item> <tag><c>Len</c></tag> - <item><p>A 16-bit big endian unsigned integer not larger than 5 when the - <seeguide marker="erl_dist_protocol#DFLAG_V4_NC"><c>DFLAG_V4_NC</c></seeguide> - has been set; otherwise not larger than 3.</p> + <item><p>A 16-bit big endian unsigned integer not larger than 5.</p> </item> <tag><c>ID</c></tag> <item><p>A sequence of <c>Len</c> big-endian unsigned integers @@ -1104,6 +1102,9 @@ <seeguide marker="#NEW_REFERENCE_EXT"><c>NEW_REFERENCE_EXT</c></seeguide> from older nodes. </p> + <p>In OTP 26 distribution flag + <seeguide marker="erl_dist_protocol#DFLAG_V4_NC"><c>DFLAG_V4_NC</c></seeguide> + became mandatory. References now can contain up to 5 <c>ID</c> words.</p> </section> <section> @@ -1420,6 +1421,46 @@ </note> </section> + <section> + <marker id="LOCAL_EXT"/> + <title>LOCAL_EXT</title> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">...</cell> + </row> + <row> + <cell align="center"><c>121</c></cell> + <cell align="center">...</cell> + </row> + <tcaption>LOCAL_EXT</tcaption></table> + <p> + Marks that this is encoded on an alternative local external term + format intended to only be decoded by a specific local decoder. + The bytes following from here on may contain any unspecified type + of encoding of terms. It is the responsibility of the user to only + attempt to decode terms on the local external term format which has + been produced by a matching encoder. + </p> + <p> + This tag is used by the Erlang runtime system upon encoding the local + external term format when the + <seeerl marker="erts:erlang#term_to_binary_local"><c>local</c></seeerl> + option is passed to + <seemfa marker="erts:erlang#term_to_binary/2"><c>term_to_binary/2</c></seemfa>, + but can be used by other encoders as well providing similar + functionality. The Erlang runtime system adds a hash immediately + following the <c>LOCAL_EXT</c> tag which is verified on decoding in + order to verify that encoder and decoder match which might be a good + practice. This will very likely catch mistakes made by users, but + is not guaranteed to, and is not intended to, prevent decoding of an + intentionally forged encoding on the local external term format. + </p> + <p> + <c>LOCAL_EXT</c> was introduced in OTP @OTP-18477@. + </p> + </section> + </chapter> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 4208aa269a..40ada94031 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>2022</year> + <year>2001</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -171,11 +171,37 @@ $> erl to query terms, like <c>enif_is_atom</c>, <c>enif_is_identical</c>, and <c>enif_compare</c>.</p> <p>All terms of type <c>ERL_NIF_TERM</c> belong to an environment of - type <seecref marker="#ErlNifEnv"><c>ErlNifEnv</c></seecref>. The - lifetime of a term is controlled by the lifetime of its environment - object. All API functions that read or write terms has the - environment that the term belongs to as the first function - argument.</p> + type <seecref marker="#ErlNifEnv"><c>ErlNifEnv</c></seecref>, + except atoms created during loading (by callbacks + <seecref marker="#load"><c>load</c></seecref> or + <seecref marker="#upgrade"><c>upgrade</c></seecref>). The lifetime of + a term is controlled by the lifetime of its environment object. All + API functions that read or write terms have the environment that the + term belongs to as the first function argument. However, the atoms + created during loading can be referred as a term in any <c>ErlNifEnv</c>. + That is, the best practice it to create all your atoms during + loading and store them in static/global variables, for example:</p> + <code type="none"><![CDATA[ +#include <erl_nif.h> + +ERL_NIF_TERM world_atom; + +static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info) +{ + world_atom = enif_make_atom(env, "world"); + return 0; +} + +static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) +{ + ERL_NIF_TERM hello_string = enif_make_string(env, "Hello", ERL_NIF_LATIN1); + return enif_make_tuple2(env, hello_string, world_atom); +} + +static ErlNifFunc nif_funcs[] = { { "hello", 0, hello } }; + +ERL_NIF_INIT(niftest, nif_funcs, load, NULL, NULL, NULL) +]]></code> </item> <tag>Binaries</tag> <item> @@ -785,6 +811,41 @@ typedef struct { To compare two monitors, <seecref marker="#enif_compare_monitors"> <c>enif_compare_monitors</c></seecref> must be used.</p> </item> + <tag><marker id="ErlNifOnHaltCallback"/><c>ErlNifOnHaltCallback</c></tag> + <item> + <code type="none"> +typedef void ErlNifOnHaltCallback(void *priv_data);</code> + <p> + The function prototype of an <i>on halt</i> callback function. + </p> + <p> + An <i>on halt</i> callback can be installed using + <seecref marker="#on_halt"><c>enif_set_option()</c></seecref>. Such + an installed callback will be called when the runtime system is + halting. + </p> + </item> + <tag><marker id="ErlNifOption"/><c>ErlNifOption</c></tag> + <item> + <p> + An enumeration of the options that can be set using + <seecref marker="#enif_set_option"><c>enif_set_option()</c></seecref>. + </p> + <p>Currently valid options:</p> + <taglist> + <tag><seecref marker="#delay_halt"><c>ERL_NIF_OPT_DELAY_HALT</c></seecref></tag> + <item><p> + Enable delay of runtime system halt with flushing enabled until + all calls to NIFs in the NIF library have returned. + </p></item> + <tag><seecref marker="#on_halt"><c>ERL_NIF_OPT_ON_HALT</c></seecref></tag> + <item><p> + Install a callback that will be called when the runtime system + halts with flushing enabled. + </p></item> + </taglist> + </item> + <tag><marker id="ErlNifPid"/><c>ErlNifPid</c></tag> <item> <p>A process identifier (pid). In contrast to pid terms (instances of @@ -869,11 +930,12 @@ typedef void ErlNifResourceDynCall(ErlNifEnv* caller_env, void* obj, void* call_ <item> <code type="none"> typedef enum { - ERL_NIF_LATIN1 + ERL_NIF_LATIN1, + ERL_NIF_UTF8, }ErlNifCharEncoding;</code> <p>The character encoding used in strings and atoms. The only - supported encoding is <c>ERL_NIF_LATIN1</c> for - ISO Latin-1 (8-bit ASCII).</p> + supported encodings are <c>ERL_NIF_LATIN1</c> for + ISO Latin-1 (8-bit ASCII) and <c>ERL_NIF_UTF8</c> for UTF-8.</p> </item> <tag><marker id="ErlNifSysInfo"/><c>ErlNifSysInfo</c></tag> <item> @@ -1395,32 +1457,32 @@ enif_free_iovec(iovec);]]></code> </func> <func> - <name since="OTP R13B04"><ret>int</ret><nametext>enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM - term, char* buf, unsigned size, ErlNifCharEncoding encode)</nametext> + <name since="OTP R13B04"><ret>int</ret><nametext>enif_get_atom(ErlNifEnv *env, ERL_NIF_TERM + term, char *buf, unsigned size, ErlNifCharEncoding encoding)</nametext> </name> <fsummary>Get the text representation of an atom term.</fsummary> <desc> <p>Writes a <c>NULL</c>-terminated string in the buffer pointed to by - <c>buf</c> of size <c>size</c>, consisting of the string - representation of the atom <c>term</c> with encoding - <seecref marker="#ErlNifCharEncoding">encode</seecref>.</p> + <c>buf</c> of size <c>size</c> bytes, consisting of the string + representation of the atom <c>term</c> with + <seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p> <p>Returns the number of bytes written (including terminating <c>NULL</c> character) or <c>0</c> if <c>term</c> is not an atom with - maximum length of <c>size-1</c>.</p> + maximum length of <c>size-1</c> bytes in <c>encoding</c>.</p> </desc> </func> <func> - <name since="OTP R14B"><ret>int</ret><nametext>enif_get_atom_length(ErlNifEnv* env, - ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)</nametext> + <name since="OTP R14B"><ret>int</ret><nametext>enif_get_atom_length(ErlNifEnv *env, + ERL_NIF_TERM term, unsigned *len, ErlNifCharEncoding encoding)</nametext> </name> <fsummary>Get the length of atom <c>term</c>.</fsummary> <desc> <p>Sets <c>*len</c> to the length (number of bytes excluding terminating <c>NULL</c> character) of the atom <c>term</c> with - encoding <c>encode</c>.</p> + <seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p> <p>Returns <c>true</c> on success, or <c>false</c> if <c>term</c> is not - an atom.</p> + an atom or if the atom cannot be encoded using <c>encoding</c>.</p> </desc> </func> @@ -1562,13 +1624,13 @@ enif_free_iovec(iovec);]]></code> <func> <name since="OTP R13B04"><ret>int</ret><nametext>enif_get_string(ErlNifEnv* env, ERL_NIF_TERM list, char* buf, unsigned size, - ErlNifCharEncoding encode)</nametext></name> + ErlNifCharEncoding encoding)</nametext></name> <fsummary>Get a C-string from a list.</fsummary> <desc> <p>Writes a <c>NULL</c>-terminated string in the buffer pointed to by <c>buf</c> with size <c>size</c>, consisting of the characters - in the string <c>list</c>. The characters are written using encoding - <seecref marker="#ErlNifCharEncoding">encode</seecref>.</p> + in the string <c>list</c>. The characters are written using + <seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p> <p>Returns one of the following:</p> <list type="bulleted"> <item>The number of bytes written (including terminating <c>NULL</c> @@ -1576,13 +1638,28 @@ enif_free_iovec(iovec);]]></code> <item><c>-size</c> if the string was truncated because of buffer space</item> <item><c>0</c> if <c>list</c> is not a string that can be encoded - with <c>encode</c> or if <c>size</c> was < <c>1</c>.</item> + with <c>encoding</c> or if <c>size</c> was < <c>1</c>.</item> </list> <p>The written string is always <c>NULL</c>-terminated, unless buffer <c>size</c> is < <c>1</c>.</p> </desc> </func> + + <func> + <name since="OTP @OTP-18334@"><ret>int</ret><nametext>enif_get_string_length(ErlNifEnv *env, + ERL_NIF_TERM list, unsigned *len, ErlNifCharEncoding encoding)</nametext> + </name> + <fsummary>Get the length of a C-string <c>list</c>.</fsummary> + <desc> + <p>Sets <c>*len</c> to the length (number of bytes excluding + terminating <c>NULL</c> character) of the string <c>list</c> with + <seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p> + <p>Returns <c>true</c> on success, or <c>false</c> if <c>list</c> is not + a string that can be encoded with <c>encoding</c>.</p> + </desc> + </func> + <func> <name since="OTP R13B04"><ret>int</ret><nametext>enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM term, int* arity, const ERL_NIF_TERM** array)</nametext></name> @@ -2029,7 +2106,7 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); <func> <name since=""><ret>ERL_NIF_TERM</ret> - <nametext>enif_make_atom(ErlNifEnv* env, const char* name)</nametext> + <nametext>enif_make_atom(ErlNifEnv *env, const char *name)</nametext> </name> <fsummary>Create an atom term.</fsummary> <desc> @@ -2042,16 +2119,16 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> - <name since="OTP R14B"><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom_len(ErlNifEnv* env, - const char* name, size_t len)</nametext></name> + <name since="OTP R14B"><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom_len(ErlNifEnv *env, + const char *name, size_t len)</nametext></name> <fsummary>Create an atom term.</fsummary> <desc> <p>Create an atom term from the string <c>name</c> with length - <c>len</c>. <c>NULL</c> characters are treated as any other - characters. If <c>len</c> exceeds the maximum length - allowed for an atom (255 characters), <c>enif_make_atom</c> invokes - <seecref marker="#enif_make_badarg"> - <c>enif_make_badarg</c></seecref>.</p> + <c>len</c> and ISO Latin-1 encoding. <c>NULL</c> characters are + treated as any other characters. If <c>len</c> exceeds the maximum + length allowed for an atom (255 characters), <c>enif_make_atom</c> + invokes <seecref marker="#enif_make_badarg"><c>enif_make_badarg</c> + </seecref>.</p> </desc> </func> @@ -2120,35 +2197,37 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> - <name since="OTP R13B04"><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, - const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding - encode)</nametext></name> + <name since="OTP R13B04"><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv *env, + const char *name, ERL_NIF_TERM *atom, ErlNifCharEncoding + encoding)</nametext></name> <fsummary>Create an existing atom term.</fsummary> <desc> <p>Tries to create the term of an already existing atom from - the <c>NULL</c>-terminated C-string <c>name</c> with encoding - <seecref marker="#ErlNifCharEncoding">encode</seecref>.</p> + the <c>NULL</c>-terminated C-string <c>name</c> with + <seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p> <p>If the atom already exists, this function stores the term in - <c>*atom</c> and returns <c>true</c>, otherwise <c>false</c>. - Also returns <c>false</c> if the length of <c>name</c> exceeds the - maximum length allowed for an atom (255 characters).</p> + <c>*atom</c> and returns <c>true</c>, otherwise returns <c>false</c>. + It also returns <c>false</c> if the string <c>name</c> exceeds the + maximum length allowed for an atom (255 characters) or if <c>name</c> + is not correctly encoded.</p> </desc> </func> <func> - <name since="OTP R14B"><ret>int</ret><nametext>enif_make_existing_atom_len(ErlNifEnv* env, - const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding + <name since="OTP R14B"><ret>int</ret><nametext>enif_make_existing_atom_len(ErlNifEnv *env, + const char *name, size_t len, ERL_NIF_TERM *atom, ErlNifCharEncoding encoding)</nametext></name> <fsummary>Create an existing atom term.</fsummary> <desc> <p>Tries to create the term of an already existing atom from the - string <c>name</c> with length <c>len</c> and encoding - <seecref marker="#ErlNifCharEncoding">encode</seecref>. <c>NULL</c> + string <c>name</c> with length <c>len</c> bytes and + <seecref marker="#ErlNifCharEncoding">encoding</seecref>. <c>NULL</c> characters are treated as any other characters.</p> <p>If the atom already exists, this function stores the term in - <c>*atom</c> and returns <c>true</c>, otherwise <c>false</c>. - Also returns <c>false</c> if <c>len</c> exceeds the maximum length - allowed for an atom (255 characters).</p> + <c>*atom</c> and returns <c>true</c>, otherwise returns <c>false</c>. + It also returns <c>false</c> if the string <c>name</c> exceeds the + maximum length allowed for an atom (255 characters) or if <c>name</c> + is not correctly encoded.</p> </desc> </func> @@ -2316,6 +2395,40 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> + <name since="OTP @OTP-18334@"><ret>int</ret><nametext>enif_make_new_atom(ErlNifEnv *env, + const char *name, ERL_NIF_TERM *atom, ErlNifCharEncoding + encoding)</nametext></name> + <fsummary>Create a new or existing atom term.</fsummary> + <desc> + <p>Creates an atom term from the <c>NULL</c>-terminated C-string + <c>name</c> with + <seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p> + <p>If successful, <c>true</c> is returned and the atom term is stored in + <c>*atom</c>.</p> + <p>Otherwise, <c>false</c> is returned if the length of <c>name</c> + exceeds the maximum length allowed for an atom (255 characters) + or if <c>name</c> is not correctly encoded.</p> + </desc> + </func> + + <func> + <name since="OTP @OTP-18334@"><ret>int</ret><nametext>enif_make_new_atom_len(ErlNifEnv *env, + const char *name, size_t len, ERL_NIF_TERM *atom, ErlNifCharEncoding + encoding)</nametext></name> + <fsummary>Create a new or existing atom term.</fsummary> + <desc> + <p>Create an atom term from string <c>name</c> with + length <c>len</c> bytes and + <seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p> + <p>If successful, <c>true</c> is returned and atom term is stored in + <c>*atom</c>.</p> + <p>Otherwise, <c>false</c> is returned if the string exceeds the maximum + length allowed for an atom (255 characters) or if the string is not + correctly encoded.</p> + </desc> + </func> + + <func> <name since="OTP R14B"><ret>unsigned char *</ret><nametext>enif_make_new_binary(ErlNifEnv* env, size_t size, ERL_NIF_TERM* termp)</nametext></name> <fsummary>Allocate and create a new binary term.</fsummary> @@ -2452,24 +2565,24 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> - <name since=""><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, - const char* string, ErlNifCharEncoding encoding)</nametext></name> + <name since=""><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv *env, + const char *string, ErlNifCharEncoding encoding)</nametext></name> <fsummary>Create a string.</fsummary> <desc> <p>Creates a list containing the characters of the - <c>NULL</c>-terminated string <c>string</c> with encoding + <c>NULL</c>-terminated string <c>string</c> with <seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p> </desc> </func> <func> - <name since="OTP R14B"><ret>ERL_NIF_TERM</ret><nametext>enif_make_string_len(ErlNifEnv* - env, const char* string, size_t len, ErlNifCharEncoding + <name since="OTP R14B"><ret>ERL_NIF_TERM</ret><nametext>enif_make_string_len(ErlNifEnv + *env, const char *string, size_t len, ErlNifCharEncoding encoding)</nametext></name> <fsummary>Create a string.</fsummary> <desc> <p>Creates a list containing the characters of the string <c>string</c> - with length <c>len</c> and encoding + with length <c>len</c> and <seecref marker="#ErlNifCharEncoding">encoding</seecref>. <c>NULL</c> characters are treated as any other characters.</p> </desc> @@ -3413,6 +3526,146 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { </func> <func> + <name since="OTP @OTP-17771@"> + <ret>int</ret><nametext>enif_set_option(ErlNifEnv *env, ErlNifOption opt, ...)</nametext> + </name> + <fsummary> + Set an option. + </fsummary> + <desc> + <marker id="enif_set_option"/> + <p> + Set an option. On success, zero will be returned. On failure, a non + zero value will be returned. Currently the following options can be set: + </p> + <taglist> + <tag><marker id="delay_halt"/> + <c>int enif_set_option(ErlNifEnv *env, + </c><seecref marker="#ErlNifOption"><c>ERL_NIF_OPT_DELAY_HALT</c></seecref><c>)</c> + </tag> + <item> + <p> + Enable delay of runtime system halt with flushing enabled until + all calls to NIFs in the NIF library have returned. If the + <i>delay halt</i> feature has not been enabled, a halt with + flushing enabled may complete even though processes are still + executing inside NIFs in the NIF library. Note that by + <i>returning</i> we here mean the first point where the NIF + returns control back to the runtime system, and <em>not</em> the + point where a call to a NIF return a value back to the Erlang + code that called the NIF. That is, if you schedule execution of + a NIF, using <seecref marker="#enif_schedule_nif"> + <c>enif_schedule_nif()</c></seecref>, from within a NIF while + the system is halting, the scheduled NIF call will <em>not</em> + be executed even though <i>delay halt</i> has been enabled for + the NIF library. + </p> + <p> + The runtime system halts when one of the + <seemfa marker="erlang#halt/0"><c>erlang:halt()</c></seemfa> + BIFs are called. By default flushing is enabled, but can be + disabled using the + <seemfa marker="erlang#halt/2"><c>erlang:halt/2</c></seemfa> BIF. + When flushing has been disabled, the <i>delay halt</i> setting + will have no effect. That is, the runtime system will halt without + waiting for NIFs to return even if the <i>delay halt</i> setting + has been enabled. See the + <seeerl marker="erlang#halt_flush"><c>{flush, boolean()}</c></seeerl> + option of <c>erlang:halt/2</c> for more information. + </p> + <p> + The <c>ERL_NIF_OPT_DELAY_HALT</c> option can only be set during + loading of a NIF library in a call to <c>enif_set_option()</c> + inside a NIF library + <seecref marker="#load"><c>load()</c></seecref> or + <seecref marker="#upgrade"><c>upgrade()</c></seecref> call, + and will fail if set somewhere else. The <c>env</c> + argument <i>must</i> be the callback environment passed to the + <c>load()</c> or the <c>upgrade()</c> call. This option can also + only be set once. That is, the <i>delay halt</i> setting cannot + be changed once it has been enabled. The <i>delay halt</i> + setting is tied to the module instance with which the NIF library + instance has been loaded. That is, in case both a new and old + version of a module using the NIF library are loaded, they can + have the same or different <i>delay halt</i> settings. + </p> + <p> + The <i>delay halt</i> feature can be used in combination with an + <seecref marker="#on_halt"><i>on halt</i></seecref> callback. + The <i>on halt</i> callback is in this case typically used to + notify processes blocked in NIFs in the library that it is time + to return in order to let the runtime system complete the + halting. Such NIFs should be dirty NIFs, since ordinary NIFs + should never block for a long time. + </p> + </item> + <tag><marker id="on_halt"/> + <c>int enif_set_option(ErlNifEnv *env, + </c><seecref marker="#ErlNifOption"><c>ERL_NIF_OPT_ON_HALT</c></seecref><c>, + </c><seecref marker="#ErlNifOnHaltCallback"><c>ErlNifOnHaltCallback</c></seecref><c> + *on_halt)</c> + </tag> + <item> + <p> + Install a callback that will be called when the runtime system + halts with flushing enabled. + </p> + <p> + The runtime system halts when one of the + <seemfa marker="erlang#halt/0"><c>erlang:halt()</c></seemfa> BIFs + are called. By default flushing is enabled, but can be disabled + using the + <seemfa marker="erlang#halt/2"><c>erlang:halt/2</c></seemfa> BIF. + When flushing has been disabled, the runtime system will halt + without calling any <i>on halt</i> callbacks even if such are + installed. See the + <seeerl marker="erlang#halt_flush"><c>{flush, boolean()}</c></seeerl> + option of <c>erlang:halt/2</c> for more information. + </p> + <p> + The <c>ERL_NIF_OPT_ON_HALT</c> option can only be set during + loading of a NIF library in a call to <c>enif_set_option()</c> + inside a NIF library + <seecref marker="#load"><c>load()</c></seecref> or + <seecref marker="#upgrade"><c>upgrade()</c></seecref> call, + and will fail if called somewhere else. The <c>env</c> + argument <i>must</i> be the callback environment passed to the + <c>load()</c> or the <c>upgrade()</c> call. The <c>on_halt</c> + argument should be a function pointer to the callback to install. + The <i>on halt</i> callback will be tied to the module instance + with which the NIF library instance has been loaded. That is, in + case both a new and old version of a module using the NIF library + are loaded, they can both have different, none, or the same + <i>on halt</i> callbacks installed. When unloading the NIF + library during a + <seemfa marker="kernel:code#purge/1">code purge</seemfa>, an + installed <i>on halt</i> callback will be uninstalled. + The <c>ERL_NIF_OPT_ON_HALT</c> option can also only be set + once. That is, the <i>on halt</i> callback cannot be changed + or removed once it has been installed by any other means than + purging the module instance that loaded the NIF library. + </p> + <p> + When the installed <i>on halt</i> callback is called, it will be + passed a pointer to <c>priv_data</c> as argument. The + <c>priv_data</c> pointer can be set when loading the NIF library. + </p> + <p> + The <i>on halt</i> callback can be used in combination with + <seecref marker="#delay_halt"><i>delay of halt</i></seecref> until + all calls into the library have returned. The <i>on halt</i> + callback is in this case typically used to notify processes + blocked in NIFs in the library that it is time to return in order + to let the runtime system complete the halting. Such NIFs should + be dirty NIFs, since ordinary NIFs should never block for a long + time. + </p> + </item> + </taglist> + </desc> + </func> + + <func> <name since="OTP 22.0"><ret>void</ret> <nametext>enif_set_pid_undefined(ErlNifPid* pid)</nametext></name> <fsummary>Set pid as undefined.</fsummary> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index b6e34a9332..d7fa7b8149 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2022</year> + <year>1996</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -790,12 +790,12 @@ client(ServerPid, Request) -> <c>utf8</c> or <c>unicode</c>, the characters are encoded using UTF-8 where characters may require multiple bytes.</p> - <note> + <change> <p>As from Erlang/OTP 20, atoms can contain any Unicode character and <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> may fail if the text representation for <c><anno>Atom</anno></c> contains a Unicode character > 255.</p> - </note> + </change> <p>Example:</p> <pre> > <input>atom_to_binary('Erlang', latin1).</input> @@ -874,11 +874,11 @@ client(ServerPid, Request) -> <c><anno>Binary</anno></c>. If <c><anno>Encoding</anno></c> is <c>utf8</c> or <c>unicode</c>, the binary must contain valid UTF-8 sequences.</p> - <note> + <change> <p>As from Erlang/OTP 20, <c>binary_to_atom(<anno>Binary</anno>, utf8)</c> is capable of decoding any Unicode character. Earlier versions would fail if the binary contained Unicode characters > 255.</p> - </note> + </change> <note> <p>The number of characters that are permitted in an atom name is limited. The default limits can be found in the @@ -1392,7 +1392,7 @@ hello by passing option <c>{allow_gc, false}</c>.</p> </item> </taglist> - <note> + <change> <p> Up until ERTS version 8.*, the check process code operation checks for all types of references to the old code. That is, @@ -1414,7 +1414,7 @@ hello and will automatically be enabled if dirty scheduler support is enabled. </p> - </note> + </change> <p>See also <seeerl marker="kernel:code"> <c>code(3)</c></seeerl>.</p> <p>Failures:</p> @@ -1589,6 +1589,10 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> headers and the beginning of any following message body.</p> <p>The variants <c>http_bin</c> and <c>httph_bin</c> return strings (<c>HttpString</c>) as binaries instead of lists.</p> + <p>Since OTP 26.0, <c><anno>Host</anno></c> may be an IPv6 + address enclosed in <c>[]</c>, as defined in + <url href="https://www.ietf.org/rfc/rfc2732.txt">RFC2732 + </url>.</p> </item> </taglist> <p>Options:</p> @@ -1677,7 +1681,13 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> <c>demonitor(<anno>MonitorRef</anno>, [flush])</c></seemfa> can be used instead of <c>demonitor(<anno>MonitorRef</anno>)</c> if this cleanup is wanted.</p> - <note> + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> + <change> <p>Before Erlang/OTP R11B (ERTS 5.5) <c>demonitor/1</c> behaved completely asynchronously, that is, the monitor was active until the "demonitor signal" reached the monitored entity. This @@ -1687,7 +1697,7 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> <p>The current behavior can be viewed as two combined operations: asynchronously send a "demonitor signal" to the monitored entity and ignore any future results of the monitor.</p> - </note> + </change> <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 @@ -1745,9 +1755,9 @@ end</code> otherwise <c>true</c>.</p> </item> </taglist> - <note> + <change> <p>More options can be added in a future release.</p> - </note> + </change> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> @@ -2284,6 +2294,12 @@ example_fun(A1, A2) -> reasons. </p> </warning> + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> </desc> </func> @@ -2545,6 +2561,15 @@ of Floating Point Numbers</seeguide>.</p> <c>Fun</c> was statically allocated when module was loaded (this optimisation is performed for local functions that do not capture the environment).</p> + <change> + <p>In Erlang/OTP 27, we plan to change the return value so that + it always points to the local <c>init</c> process, regardless + of which process or node the fun was originally created on. See + <seeguide marker="system/general_info:upcoming_incompatibilities#fun_creator_pid"> + Upcoming Potential Incompatibilities + </seeguide>. + </p> + </change> </item> <tag><c>{index, Index}</c></tag> <item> @@ -2638,11 +2663,11 @@ of Floating Point Numbers</seeguide>.</p> marker="#fun_info/1"><c>erlang:fun_info/1</c></seemfa> for how to get the environment of a fun.</p> </note> - <note> + <change> <p>The output of <c>fun_to_list/1</c> can differ between Erlang implementations and may change in future versions.</p> - </note> + </change> <p>Examples:</p> <code> -module(test). @@ -2917,6 +2942,12 @@ uncompiled code with the same arity are mapped to the same list by and <seeguide marker="system/design_principles:applications#stopping">OTP design principles</seeguide> related to starting and stopping applications.</p> + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> </desc> </func> @@ -2925,7 +2956,7 @@ uncompiled code with the same arity are mapped to the same list by <fsummary>Halt the Erlang runtime system and indicate normal exit to the calling environment.</fsummary> <desc> - <p>The same as + <p>The same as calling <seemfa marker="#halt/2"><c>halt(0, [])</c></seemfa>. Example:</p> <pre> > <input>halt().</input> @@ -2934,10 +2965,11 @@ os_prompt%</pre> </func> <func> - <name name="halt" arity="1" since=""/> + <name name="halt" arity="1" clause_i="1" + anchor="halt_status_code_1" since=""/> <fsummary>Halt the Erlang runtime system.</fsummary> <desc> - <p>The same as <seemfa marker="#halt/2"> + <p>The same as calling <seemfa marker="#halt/2"> <c>halt(<anno>Status</anno>, [])</c></seemfa>. Example:</p> <pre> > <input>halt(17).</input> @@ -2948,44 +2980,156 @@ os_prompt%</pre> </func> <func> - <name name="halt" arity="2" since="OTP R15B01"/> + <name name="halt" arity="1" clause_i="2" + anchor="halt_abort_1" since="OTP R15B01"/> + <fsummary>Halt the Erlang runtime system by aborting.</fsummary> + <desc> + <p> + The same as calling <seeerl marker="#halt_abort_2"> + <c>halt(abort, [])</c></seeerl>. + </p> + </desc> + </func> + + <func> + <name name="halt" arity="1" clause_i="3" + anchor="halt_crash_dump_1" since=""/> + <fsummary> + Halt the Erlang runtime system and create an Erlang crash dump. + </fsummary> + <desc> + <p> + The same as calling <seeerl marker="#halt_crash_dump_2"> + <c>halt(<anno>CrashDumpSlogan</anno>, [])</c></seeerl>. + </p> + </desc> + </func> + + <func> + <name name="halt" arity="2" clause_i="1" + anchor="halt_status_code_2" since="OTP R15B01"/> <fsummary>Halt the Erlang runtime system.</fsummary> + <type name="halt_options"/> <desc> - <p><c><anno>Status</anno></c> must be a non-negative integer, a string, - or the atom <c>abort</c>. - Halts the Erlang runtime system. Has no return value. - Depending on <c><anno>Status</anno></c>, the following occurs:</p> + <p> + Halt the runtime system with status code + <c><anno>Status</anno></c>. + </p> + <note> + <p> + On many platforms, the OS supports only status codes 0-255. A too + large status code is truncated by clearing the high bits. + </p> + </note> + <p> + Currently the following options are valid: + </p> <taglist> - <tag>integer()</tag> - <item>The runtime system exits with integer value - <c><anno>Status</anno></c> - as status code to the calling environment (OS). - <note> - <p>On many platforms, the OS supports only status - codes 0-255. A too large status code is truncated by clearing - the high bits.</p> - </note> - </item> - <tag>string()</tag> - <item>An Erlang crash dump is produced with <c><anno>Status</anno></c> - as slogan. Then the runtime system exits with status code <c>1</c>. - The string will be truncated if longer than 200 characters. - <note> - <p>Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255 - was accepted in the string. Now any unicode string is valid.</p> - </note> - </item> - <tag><c>abort</c></tag> - <item>The runtime system aborts producing a core dump, if that is - enabled in the OS. + <tag><marker id="halt_flush"/><c>{flush, EnableFlushing}</c></tag> + <item> + <p> + If <c>EnableFlushing</c> equals <c>true</c>, which also is the + default behavior, the runtime system will perform the following + operations before terminating: + </p> + <list> + <item><p> + Flush all outstanding output. + </p></item> + <item><p> + Send all Erlang ports exit signals and wait for them + to exit. + </p></item> + <item><p> + Wait for all async threads to complete all outstanding + async jobs. + </p></item> + <item><p> + Call all installed <seecref marker="erl_nif#on_halt">NIF + <i>on halt</i> callbacks</seecref>. + </p></item> + <item><p> + Wait for all ongoing <seecref marker="erl_nif#delay_halt">NIF + calls with the <i>delay halt</i> setting</seecref> enabled to + return. + </p></item> + <item><p> + Call all installed <c>atexit</c>/<c>on_exit</c> callbacks. + </p></item> + </list> + <p> + If <c>EnableFlushing</c> equals <c>false</c>, the runtime system + will terminate immediately without performing any of the above + listed operations. + </p> + <change> + <p> + Runtime systems prior to OTP @OTP-17771@ called all installed + <c>atexit</c>/<c>on_exit</c> callbacks also when <c>flush</c> + was disabled, but as of OTP @OTP-17771@ this is no longer the case. + </p> + </change> </item> </taglist> - <p>For integer <c><anno>Status</anno></c>, the Erlang runtime system - closes all ports and allows async threads to finish their - operations before exiting. To exit without such flushing, use - <c><anno>Option</anno></c> as <c>{flush,false}</c>.</p> - <p>For statuses <c>string()</c> and <c>abort</c>, option - <c>flush</c> is ignored and flushing is <em>not</em> done.</p> + </desc> + </func> + + <func> + <name name="halt" arity="2" clause_i="2" + anchor="halt_abort_2" since="OTP R15B01"/> + <fsummary>Halt the Erlang runtime system by aborting.</fsummary> + <type name="halt_options"/> + <desc> + <p> + Halt the Erlang runtime system by aborting and produce a core dump + if core dumping has been enabled in the environment that the + runtime system is executing in. + </p> + <note><p> + The <seeerl marker="#halt_flush"><c>{flush, boolean()}</c></seeerl> + option will be ignored, and flushing will be disabled. + </p></note> + </desc> + </func> + + <func> + <name name="halt" arity="2" clause_i="3" + anchor="halt_crash_dump_2" since="OTP R15B01"/> + <fsummary> + Halt the Erlang runtime system and create an Erlang crash dump. + </fsummary> + <type name="halt_options"/> + <desc> + <p> + Halt the Erlang runtime system and generate an + <seeguide marker="crash_dump">Erlang crash dump</seeguide>. The + string <c><anno>CrashDumpSlogan</anno></c> will be used as slogan + in the Erlang crash dump created. The slogan will be trunkated if + <c><anno>CrashDumpSlogan</anno></c> is longer than 1023 characters. + </p> + <note><p> + The <seeerl marker="#halt_flush"><c>{flush, boolean()}</c></seeerl> + option will be ignored, and flushing will be disabled. + </p></note> + <p> + Behavior changes compared to earlier versions: + </p> + <list> + <item> + <p> + Before OTP 24.2, the slogan was truncated if + <c><anno>CrashDumpSlogan</anno></c> was longer than 200 + characters. Now it will be truncated if longer than 1023 + characters. + </p> + </item> + <item> + <p> + Before OTP 20.1, only code points in the range 0-255 were + accepted in the slogan. Now any Unicode string is valid. + </p> + </item> + </list> </desc> </func> @@ -2994,12 +3138,17 @@ os_prompt%</pre> <fsummary>Head of a list.</fsummary> <desc> <p>Returns the head of <c><anno>List</anno></c>, that is, - the first element, for example:</p> + the first element.</p> + <p>It works with improper lists.</p> + <p>Examples:</p> <pre> > <input>hd([1,2,3,4,5]).</input> 1</pre> + <pre> +> <input>hd([first, second, third, so_on | improper_end]).</input> +first</pre> <p>Allowed in guard tests.</p> - <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty + <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is an empty list <c>[]</c>.</p> </desc> </func> @@ -3197,7 +3346,7 @@ os_prompt%</pre> </list> <p>A node can also be alive if it has got a name from a call to <seemfa - marker="kernel:net_kernel#start/1"><c>net_kernel:start/1</c></seemfa> + marker="kernel:net_kernel#start/2"><c>net_kernel:start/2</c></seemfa> and has not been stopped by a call to <seemfa marker="kernel:net_kernel#stop/0"><c>net_kernel:stop/0</c></seemfa>.</p> </desc> @@ -3547,6 +3696,12 @@ is_process_alive(P2Pid), chapter of the <i>ERTS User's Guide</i>. </p> + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> <p>Failure:</p> <list> <item><c>badarg</c> if <c><anno>PidOrPort</anno></c> does not identify @@ -4111,6 +4266,8 @@ is_process_alive(P2Pid), <pre> > <input>max("abc", "b").</input> "b"</pre> + <p>Allowed in guard tests.</p> + <change><p>Allowed in guards tests from Erlang/OTP 26.</p></change> </desc> </func> @@ -4196,7 +4353,7 @@ is_process_alive(P2Pid), <p>The total amount of memory currently allocated for the emulator that is not directly related to any Erlang process. Memory presented as <c>processes</c> is not - included in this memory. <seeerl marker="tools:instrument"> + included in this memory. <seeerl marker="runtime_tools:instrument"> <c>instrument(3)</c></seeerl> can be used to get a more detailed breakdown of what memory is part of this type.</p> @@ -4238,7 +4395,7 @@ is_process_alive(P2Pid), when the emulator is run with instrumentation.</p> <p>For information on how to run the emulator with instrumentation, see - <seeerl marker="tools:instrument"> + <seeerl marker="runtime_tools:instrument"> <c>instrument(3)</c></seeerl> and/or <seecom marker="erl"><c>erl(1)</c></seecom>.</p> </item> @@ -4286,11 +4443,11 @@ RealSystem = system + MissedSystem</code> larger than the total size of the dynamically allocated memory blocks.</p> </note> - <note> + <change> <p>As from ERTS 5.6.4, <c>erlang:memory/0</c> requires that all <seecref marker="erts:erts_alloc"><c>erts_alloc(3)</c></seecref> allocators are enabled (default behavior).</p> - </note> + </change> <p>Failure: <c>notsup</c> if an <seecref marker="erts:erts_alloc"><c>erts_alloc(3)</c></seecref> allocator has been disabled.</p> @@ -4307,12 +4464,12 @@ RealSystem = system + MissedSystem</code> <c><anno>Type</anno></c>. The argument can also be specified 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> + <change> <p>As from ERTS 5.6.4, <c>erlang:memory/1</c> requires that all <seecref marker="erts_alloc"><c>erts_alloc(3)</c></seecref> allocators are enabled (default behavior).</p> - </note> + </change> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> @@ -4363,6 +4520,8 @@ RealSystem = system + MissedSystem</code> <pre> > <input>min("abc", "b").</input> "abc"</pre> + <p>Allowed in guard tests.</p> + <change><p>Allowed in guards tests from Erlang/OTP 26.</p></change> </desc> </func> @@ -4456,7 +4615,7 @@ RealSystem = system + MissedSystem</code> a tuple <c>{RegisteredName, Node}</c> for a registered process, located elsewhere.</p> - <note><p>Before ERTS 10.0 (OTP 21.0), monitoring a process could fail with + <change><p>Before ERTS 10.0 (OTP 21.0), monitoring a process could fail with <c>badarg</c> if the monitored process resided on a primitive node (such as erl_interface or jinterface), where remote process monitoring is not implemented.</p> @@ -4465,7 +4624,7 @@ RealSystem = system + MissedSystem</code> connection. That is, a <c>{'DOWN', _, process, _, noconnection}</c> is the only message that may be received, as the primitive node have no way of reporting the status of the monitored process.</p> - </note> + </change> </item> @@ -4553,6 +4712,12 @@ RealSystem = system + MissedSystem</code> possible values for <c>Tag</c>, <c>Object</c>, and <c>Info</c> in the monitor message will be introduced.</p> </note> + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> </desc> </func> @@ -5203,7 +5368,7 @@ receive_replies(ReqId, N, Acc) -> <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 - <seemfa marker="kernel:os#getenv/1"><c>os:getenv/1</c></seemfa>, + <seemfa marker="kernel:os#getenv/1"><c>os:getenv/1</c></seemfa>), which removes the environment variable. </p> <p> @@ -5691,9 +5856,9 @@ receive_replies(ReqId, N, Acc) -> <c>false</c> is returned. </item> </taglist> - <note> + <change> <p>More options can be added in a future release.</p> - </note> + </change> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> @@ -6184,7 +6349,7 @@ receive_replies(ReqId, N, Acc) -> </p></note> <p> Blocking due to disabled <c>async_dist</c> can be monitored by - <seemfa marker="#system_monitor/2"><c>erlang:system_montor()</c></seemfa> + <seemfa marker="#system_monitor/2"><c>erlang:system_monitor()</c></seemfa> using the <seeerl marker="#busy_dist_port"><c>busy_dist_port</c></seeerl> option. Only data buffered by processes which (at the time of sending @@ -6346,6 +6511,26 @@ receive_replies(ReqId, N, Acc) -> or <seeerl marker="#system_flag_max_heap_size"> <c>erlang:system_flag(max_heap_size, MaxHeapSize)</c></seeerl>.</p> </item> + <tag><c>include_shared_binaries</c></tag> + <item> + <p> + When set to <c>true</c>, off-heap binaries are included in the + total sum compared against the <c>size</c> limit. Off-heap binaries + are typically larger binaries that may be shared between + processes. The size of a shared binary is included by all + processes that are referring it. Also, the entire size of a large + binary may be included even if only a smaller part of it is + referred by the process. + </p> + <p> + If <c>include_shared_binaries</c> is not defined in the map, the + system default is used. The default system default is <c>false</c>. + It can be changed by either the option + <seecom marker="erl#+hmaxib">+hmaxib</seecom> in <c>erl(1)</c>, + or <seeerl marker="#system_flag_max_heap_size"> + <c>erlang:system_flag(max_heap_size, MaxHeapSize)</c></seeerl>. + </p> + </item> </taglist> <p>The heap size of a process is quite hard to predict, especially the amount of memory that is used during the garbage collection. When @@ -6998,12 +7183,12 @@ receive_replies(ReqId, N, Acc) -> <seeerl marker="kernel:code"><c>code(3)</c></seeerl>) and is not to be used elsewhere.</p> </warning> - <note> + <change> <p>As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that still execute the old code is killed by this function. In earlier versions, such incorrect use could cause much more fatal failures, like emulator crash.</p> - </note> + </change> <p>Failure: <c>badarg</c> if there is no old code for <c><anno>Module</anno></c>.</p> </desc> @@ -7313,6 +7498,12 @@ true</pre> <c><anno>Dest</anno></c> is an atom name, but this name is not registered. This is the only case when <c>send</c> fails for an unreachable destination <c><anno>Dest</anno></c> (of correct type).</p> + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> </desc> </func> @@ -7340,6 +7531,12 @@ true</pre> instead. </item> </taglist> + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> <warning> <p>As with <c>erlang:send_nosuspend/2,3</c>: use with extreme care.</p> @@ -8299,6 +8496,12 @@ true</pre> A spawn request can be abandoned by calling <seemfa marker="#spawn_request_abandon/1"><c>spawn_request_abandon/1</c></seemfa>. </p> + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> </desc> </func> @@ -8719,13 +8922,13 @@ lists:map( <pre> > <input>statistics(reductions).</input> {2046,11}</pre> - <note><p>As from ERTS 5.5 (Erlang/OTP R11B), + <change><p>As from ERTS 5.5 (Erlang/OTP R11B), this value does not include reductions performed in current time slices of currently scheduled processes. If an exact value is wanted, use <seeerl marker="#statistics_exact_reductions"> <c>statistics(exact_reductions)</c></seeerl>.</p> - </note> + </change> </desc> </func> @@ -9390,7 +9593,7 @@ ok <p> Sets the default maximum heap size settings for processes. The size is specified in words. The new <c>max_heap_size</c> - effects only processes spawned efter the change has been made. + effects only processes spawned after the change has been made. <c>max_heap_size</c> can be set for individual processes using <seemfa marker="#spawn_opt/4"><c>spawn_opt/2,3,4</c></seemfa> or <seeerl marker="#process_flag_max_heap_size"> @@ -10293,8 +10496,10 @@ Metadata = #{ pid => pid(), system-wide maximum heap size settings for spawned processes. This setting can be set using the command-line flags <seecom marker="erl#+hmax"><c>+hmax</c></seecom>, - <seecom marker="erl#+hmaxk"><c>+hmaxk</c></seecom> and - <seecom marker="erl#+hmaxel"><c>+hmaxel</c></seecom> in + <seecom marker="erl#+hmaxk"><c>+hmaxk</c></seecom>, + <seecom marker="erl#+hmaxel"><c>+hmaxel</c></seecom> and + <seecom marker="erl#+hmaxib"><c>+hmaxibl</c></seecom> in + <c>erl(1)</c>. It can also be changed at runtime using <seeerl marker="#system_flag_max_heap_size"> <c>erlang:system_flag(max_heap_size, MaxHeapSize)</c></seeerl>. @@ -10978,14 +11183,13 @@ Metadata = #{ pid => pid(), <tag><marker id="system_info_creation"/> <c>creation</c></tag> <item> - <p>Returns the creation of the local node as an integer. + <p>Returns the "creation" value of the local node as an integer. The creation is changed when a node is restarted. The creation of a node is stored in process identifiers, port - identifiers, and references. This makes it (to some - extent) possible to distinguish between identifiers from - different incarnations of a node. The valid - creations are integers in the range 1..3, but this will - probably change in a future release. If the node is not + identifiers, and references. This makes it possible to distinguish + between identifiers from different incarnations of a node. + Creation values are currently 32-bit positive integers, but this + may change in future releases. If the node is not alive, <c>0</c> is returned.</p> </item> <tag><marker id="system_info_delayed_node_table_gc"/> @@ -11693,71 +11897,192 @@ hello <desc> <p>Returns a binary data object that is the result of encoding <c><anno>Term</anno></c> according to the Erlang external - term format.</p> - <p>If option <c>compressed</c> is provided, the external term - format is compressed. The compressed format is automatically - recognized by <c>binary_to_term/1</c> as from Erlang/OTP R7B.</p> - <p>A compression level can be specified by giving option - <c>{compressed, <anno>Level</anno>}</c>. - <c><anno>Level</anno></c> is an integer - with range 0..9, where:</p> - <list type="bulleted"> - <item><p><c>0</c> - No compression is done (it is the same as - giving no <c>compressed</c> option).</p></item> - <item><p><c>1</c> - Takes least time but may not compress - as well as the higher levels.</p></item> - <item><p><c>6</c> - Default level when option <c>compressed</c> - is provided.</p></item> - <item><p><c>9</c> - Takes most time and tries to produce a smaller - result. Notice "tries" in the preceding sentence; depending - on the input term, level 9 compression either does or does - not produce a smaller result than level 1 compression.</p></item> - </list> - <p>Option <c>{minor_version, <anno>Version</anno>}</c> - can be used to control some - encoding details. This option was introduced in Erlang/OTP R11B-4. - The valid values for <c><anno>Version</anno></c> are:</p> - <taglist> - <tag><c>0</c></tag> - <item> - <p>Floats are encoded using a textual representation. - This option is useful to ensure that releases before Erlang/OTP - R11B-4 can decode resulting binary.</p> - <p>This version encode atoms that can be represented by a - latin1 string using latin1 encoding while only atoms that - cannot be represented by latin1 are encoded using utf8.</p> - </item> - <tag><c>1</c></tag> - <item> - <p>This is as of Erlang/OTP 17.0 the <em>default</em>. It forces any floats - in the term to be encoded in a more space-efficient and exact way - (namely in the 64-bit IEEE format, rather than converted to a - textual representation). As from Erlang/OTP R11B-4, - <c>binary_to_term/1</c> can decode this representation.</p> - <p>This version encode atoms that can be represented by a - latin1 string using latin1 encoding while only atoms that - cannot be represented by latin1 are encoded using utf8.</p> - </item> - <tag><c>2</c></tag> - <item> - <p>Drops usage of the latin1 atom encoding and unconditionally - use utf8 encoding for all atoms. Erlang/OTP - systems as of R16B can decode this representation.</p> - <note> - <p>In Erlang/OTP 26, the default <c>minor_version</c> is planned - to change from 1 to 2. See - <seeguide marker="system/general_info:upcoming_incompatibilities#atoms_be_utf8"> - Upcoming Potential Incompatibilities - </seeguide>. - </p> - </note> - </item> - </taglist> - <p>Option <c>deterministic</c> (introduced in OTP 24.1) can - be used to ensure that within the same major release of Erlang/OTP, - the same encoded representation is returned for the same - term. There is still no guarantee that the encoded representation - remains the same between major releases of Erlang/OTP.</p> + term format.</p> + <p>Currently supported options:</p> + <taglist> + <tag><c>compressed</c></tag> + <item> + <p> + Compress the external term format. The compressed + format is automatically recognized by <c>binary_to_term/1</c> + as from Erlang/OTP R7B. + </p> + </item> + <tag><c>{compressed, <anno>Level</anno>}</c></tag> + <item> + <p> + Compress the external term format to a given level. + The compression level is specified by <c><anno>Level</anno></c> + which is an integer in the range 0..9, where: + </p> + <taglist> + <tag><c>0</c></tag> + <item><p> + No compression is done (it is the same as giving no + <c>compressed</c> option). + </p></item> + <tag><c>1</c></tag> + <item><p> + Takes least time but may not compress as well as the higher + levels. + </p></item> + <tag><c>6</c></tag> + <item><p> + Default level when option <c>compressed</c> is provided. + </p></item> + <tag><c>9</c></tag> + <item><p> + Takes most time and tries to produce a smaller result. + Notice "tries" in the preceding sentence; depending + on the input term, level 9 compression either does or does + not produce a smaller result than level 1 compression. + </p></item> + </taglist> + </item> + <tag since="R11B-4"><c>{minor_version, <anno>Version</anno>}</c></tag> + <item> + <p> + The option can be used to control some encoding details. Valid + values for <c><anno>Version</anno></c> are: + </p> + <taglist> + <tag><c>0</c></tag> + <item> + <p>Floats are encoded using a textual representation.</p> + <p>Atoms that can be represented by a latin1 string are encoded + using latin1 while only atoms that cannot be represented by latin1 + are encoded using utf8.</p> + </item> + <tag><c>1</c></tag> + <item> + <p>Floats are encoded in a more space-efficient and exact way + (namely in the 64-bit IEEE format, rather than converted to a + textual representation). As from Erlang/OTP R11B-4, + <c>binary_to_term/1</c> can decode this representation.</p> + <p>Atoms that can be represented by a latin1 string are encoded + using latin1 while only atoms that cannot be represented by latin1 + are encoded using utf8.</p> + </item> + <tag><c>2</c></tag> + <item> + <p>This is as of Erlang/OTP 26.0 the <em>default</em>. Atoms are + unconditionally encoded using utf8. Erlang/OTP systems as of R16B + can decode this representation.</p> + </item> + </taglist> + </item> + <tag since="OTP 24.1"><c>deterministic</c></tag> + <item> + <p> + This option can be used to ensure that, within the same major + release of Erlang/OTP, the same encoded representation is returned + for the same term. There is still no guarantee that the encoded + representation remains the same between major releases of + Erlang/OTP. + </p> + <p> + This option cannot be combined with the <c>local</c> option. + </p> + </item> + <tag since="OTP @OTP-18477@"><c>local</c> + <marker id="term_to_binary_local"/></tag> + <item> + <p> + This option will cause encoding of <c><anno>Term</anno></c> + to an alternative local version of the external term format which + when decoded by the same runtime system instance will produce a + term identical to the encoded term even when the node name and/or + <seeerl marker="#system_info_creation">creation</seeerl> of the + current runtime system instance have changed between encoding + and decoding. When encoding without the <c>local</c> option, + local identifiers such as <seetype marker="#pid">pids</seetype>, + <seetype marker="#port">ports</seetype> and + <seetype marker="#reference">references</seetype> will not + be the same if node name and/or creation of the current runtime + system instance changed between encoding and decoding. This since + such identifiers refer to a specific node by node name and + creation. + </p> + <p> + Node name and creation of a runtime system instance change + when the distribution is started or stopped. The distribution is + started when the runtime system is started using the + <seecom marker="erl#name"><c>-name</c></seecom> or + <seecom marker="erl#sname"><c>-sname</c></seecom> command line + arguments. Note that the actual start of the distribution happens + after other code in the startup phase has begun executing. The + distribution can also be started by calling + <seemfa marker="kernel:net_kernel#start/2"><c>net_kernel:start/2</c></seemfa> + and stopped by calling + <seemfa marker="kernel:net_kernel#stop/0"><c>net_kernel:stop/1</c></seemfa> + if it has not been started via the command line. + </p> + <p> + The decoding of a term encoded with the <c>local</c> option, + using for example + <seemfa marker="#term_to_binary/1"><c>binary_to_term()</c></seemfa>, + will try to verify that the term actually was encoded by the same + runtime system instance, and will in the vast majority of cases + fail if the encoding was performed by another runtime system + instance. You should however <em>not</em> trust that this + verification will work in all cases. You <em>should</em> make + sure to <em>only</em> decode terms encoded with the <c>local</c> + option on the same Erlang runtime system instance as the one that + encoded the terms. + </p> + <p> + Since it is only the runtime system that encoded a term using + the <c>local</c> option that can decode it, the local encoding + is typically pieced together with something else to produce a + reply to where the <c>local</c> encoding originates from. + If a term encoded using the <c>local</c> option is stripped of + its leading version number, it can be added as part + of a larger term (for example as an element in a tuple) when + encoding on the external term format using, for example, + <seecref marker="erl_interface:ei">ei</seecref>. In the <c>ei</c> + case, you would strip it of the version number using + <seecref marker="erl_interface:ei#ei_decode_version"><c>ei_decode_version()</c></seecref> + and then add the remaining local encoding to what you are encoding + using for example + <seecref marker="erl_interface:ei#ei_x_append_buf"><c>ei_x_append_buf()</c></seecref>. + </p> + <p> + A good example of when you want to use the <c>local</c> option, is + when you want to make a request from a process to a port + <seecref marker="erl_driver">driver</seecref> and utilize the + <seeguide marker="system/efficiency_guide:processes#receiving-messages">selective + receive optimization</seeguide> when receiving the reply. In + this scenario you want to create a reference, serialize the + reference on the external term format using the <c>local</c> + option, pass this to the driver in the request, and then wait + for the reply message in a selective receive matching on the + reference. The driver should send the reply using either + <seecref marker="erl_driver#erl_drv_output_term"><c>erl_drv_output_term()</c></seecref> + or + <seecref marker="erl_driver#erl_drv_send_term"><c>erl_drv_send_term()</c></seecref> + using the term type + <seecref marker="erl_driver#ERL_DRV_EXT2TERM"><c>ERL_DRV_EXT2TERM</c></seecref> + for the, in the request, previously received reference on the + external term format. Note that you should not strip the + leading version number from the local encoding when using the + term type <c>ERL_DRV_EXT2TERM</c> of this functionality. If you + in this example do not encode the reference using the <c>local</c> + option, and the distribution is started or stopped while the + request is ongoing, the process that made the request will hang + indefinitely since the reference in the reply message will never + match. + </p> + <p> + This option cannot be combined with the <c>deterministic</c> + option. + </p> + <p> + For more information see the + <seeguide marker="erl_ext_dist#LOCAL_EXT"><c>LOCAL_EXT</c></seeguide> + tag in the documentation of the external term format. + </p> + </item> + </taglist> <p>See also <seemfa marker="#binary_to_term/1"> <c>binary_to_term/1</c></seemfa>.</p> </desc> @@ -11954,7 +12279,9 @@ timestamp() -> <fsummary>Tail of a list.</fsummary> <desc> <p>Returns the tail of <c><anno>List</anno></c>, that is, - the list minus the first element, for example:</p> + the list minus the first element</p> + <p>It works with improper lists.</p> + <p>Examples:</p> <pre> > <input>tl([geesties, guilies, beasties]).</input> [guilies, beasties]</pre> @@ -11969,7 +12296,7 @@ timestamp() -> improper_end</pre> <p>Allowed in guard tests.</p> <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> - is the empty list <c>[]</c>.</p> + is an empty list <c>[]</c>.</p> </desc> </func> @@ -12797,6 +13124,21 @@ improper_end</pre> <seemfa marker="#trace_pattern/3"> <c>erlang:trace_pattern/3</c></seemfa>.</p> </item> + <tag><c>call_memory</c></tag> + <item> + <p>Returns the accumulated number of words allocated by this function. + Accumulation stops at the next memory traced function: if there + are <c>outer</c>, <c>middle</c> and <c>inner</c> functions each + allocating 3 words, but only <c>outer</c> is traced, it will report + 9 allocated words. If <c>outer</c> and <c>inner</c> are traced, + 6 words are reported for <c>outer</c> and 3 for <c>inner</c>. + When function is not traced, <c>false</c> is returned. + Returned tuple is <c>[{Pid, Count, Words}]</c>, + for each process that executed the function.</p> + <p>See also + <seemfa marker="#trace_pattern/3"> + <c>erlang:trace_pattern/3</c></seemfa>.</p> + </item> <tag><c>all</c></tag> <item> <p>Returns a list containing the @@ -13099,15 +13441,15 @@ improper_end</pre> </item> <tag><c>restart</c></tag> <item> - <p>For the <c><anno>FlagList</anno></c> options <c>call_count</c> - and <c>call_time</c>: restarts + <p>For the <c><anno>FlagList</anno></c> options <c>call_count</c>, + <c>call_time</c> and <c>call_memory</c>: restarts the existing counters. The behavior is undefined for other <c><anno>FlagList</anno></c> options.</p> </item> <tag><c>pause</c></tag> <item> <p>For the <c><anno>FlagList</anno></c> options - <c>call_count</c> and <c>call_time</c>: pauses + <c>call_count</c>, <c>call_time</c> and <c>call_memory</c>: pauses the existing counters. The behavior is undefined for other <c><anno>FlagList</anno></c> options.</p> </item> @@ -13183,6 +13525,20 @@ improper_end</pre> <seemfa marker="#trace_info/2"> <c>erlang:trace_info/2</c></seemfa>.</p> </item> + <tag><c>call_memory</c></tag> + <item> + <p>Starts (<c><anno>MatchSpec</anno> == true</c>) or stops + (<c><anno>MatchSpec</anno> == false</c>) call memory + tracing for all types of function calls.</p> + <p>If call memory tracing is started while already running, + counters and allocations restart from zero. To pause + running counters, use <c><anno>MatchSpec</anno> == pause</c>. + Paused and running counters can be restarted from zero with + <c><anno>MatchSpec</anno> == restart</c>.</p> + <p>To read the counter value, use + <seemfa marker="#trace_info/2"> + <c>erlang:trace_info/2</c></seemfa>.</p> + </item> </taglist> <p>The options <c>global</c> and <c>local</c> are mutually exclusive, and <c>global</c> is the default (if no options are @@ -13504,7 +13860,12 @@ end</code> protocol</seeguide> can be found in the <i>Distribution Protocol</i> chapter of the <i>ERTS User's Guide</i>. </p> - + <note><p> + For some important information about distributed signals, see the + <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution"> + <i>Blocking Signaling Over Distribution</i></seeguide> section in the + <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>. + </p></note> <p> Failure: <c>badarg</c> if <c>Id</c> does not identify a process or a node local port. diff --git a/erts/doc/src/erlsrv_cmd.xml b/erts/doc/src/erlsrv_cmd.xml index e8f066b21b..4973a163e4 100644 --- a/erts/doc/src/erlsrv_cmd.xml +++ b/erts/doc/src/erlsrv_cmd.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1998</year><year>2021</year> + <year>1998</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -112,8 +112,7 @@ <item> <p>The location of the Erlang emulator. The default is the <c><![CDATA[erl.exe]]></c> located in the same - directory as <c>erlsrv.exe</c>. Do not specify - <c><![CDATA[werl.exe]]></c> as this emulator, it will not work.</p> + directory as <c>erlsrv.exe</c>.</p> <p>If the system uses release handling, this is to be set to a program similar to <c><![CDATA[start_erl.exe]]></c>.</p> </item> diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml index da293f9c45..914c936095 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>2022</year> + <year>2002</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -573,7 +573,7 @@ <item> <p>Adds a small tag to each allocated block that contains basic information about what it is and who allocated it. Use the - <seeerl marker="tools:instrument"><c>instrument</c></seeerl> + <seeerl marker="runtime_tools:instrument"><c>instrument</c></seeerl> module to inspect this information.</p> <p>The runtime overhead is one word per allocation when enabled. This @@ -832,18 +832,6 @@ <p>Configures all allocators as they were configured in respective Erlang/OTP release. These will eventually be removed.</p> </item> - <tag><c>config</c></tag> - <item> - <p>Disables features that cannot be enabled while creating an - allocator configuration with - <seeerl marker="runtime_tools:erts_alloc_config"> - <c>erts_alloc_config(3)</c></seeerl>.</p> - <note> - <p>This option is to be used only while running - <c>erts_alloc_config(3)</c>, <em>not</em> when - using the created configuration.</p> - </note> - </item> </taglist> </item> <tag><marker id="Mlpm"/><c>+Mlpm all|no</c></tag> @@ -899,21 +887,13 @@ <p><c>erts_alloc</c> is not obliged to strictly use the settings that have been passed to it (it can even ignore them).</p> </note> - - <p>The <seeerl marker="runtime_tools:erts_alloc_config"> - <c>erts_alloc_config(3)</c></seeerl> - tool can be used to aid creation of an - <c>erts_alloc</c> configuration that is suitable for a limited - number of runtime scenarios.</p> </section> <section> <title>See Also</title> <p><seecom marker="erl"><c>erl(1)</c></seecom>, <seeerl marker="erlang"><c>erlang(3)</c></seeerl>, - <seeerl marker="runtime_tools:erts_alloc_config"> - <c>erts_alloc_config(3)</c></seeerl>, - <seeerl marker="tools:instrument"> + <seeerl marker="runtime_tools:instrument"> <c>instrument(3)</c></seeerl></p> </section> </cref> diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml index 988f895dde..a62eef43c4 100644 --- a/erts/doc/src/match_spec.xml +++ b/erts/doc/src/match_spec.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1999</year><year>2022</year> + <year>1999</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -87,7 +87,8 @@ <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> | <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | <c><![CDATA[is_map]]></c> | <c><![CDATA[is_map_key]]></c> | - <c><![CDATA[is_binary]]></c> | <c><![CDATA[is_function]]></c> | + <c><![CDATA[is_binary]]></c> | <c><![CDATA[is_bitstring]]></c> | + <c><![CDATA[is_boolean]]></c> | <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | <c><![CDATA[is_seq_trace]]></c> | <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> | @@ -111,11 +112,14 @@ <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> | <c><![CDATA[element]]></c> | <c><![CDATA[hd]]></c> | <c><![CDATA[length]]></c> | <c><![CDATA[map_get]]></c> | - <c><![CDATA[map_size]]></c> | <c><![CDATA[node]]></c> | - <c><![CDATA[round]]></c> | <c><![CDATA[size]]></c> | + <c><![CDATA[map_size]]></c> | + <c><![CDATA[max]]></c> | <c><![CDATA[min]]></c> | + <c><![CDATA[node]]></c> | <c><![CDATA[float]]></c> | + <c><![CDATA[round]]></c> | <c><![CDATA[floor]]></c> | + <c><![CDATA[ceil]]></c> | <c><![CDATA[size]]></c> | <c><![CDATA[bit_size]]></c> | <c><![CDATA[byte_size]]></c> | - <c><![CDATA[tl]]></c> | <c><![CDATA[trunc]]></c> | - <c><![CDATA[binary_part]]></c> | + <c><![CDATA[tuple_size]]></c> | <c><![CDATA[tl]]></c> | + <c><![CDATA[trunc]]></c> | <c><![CDATA[binary_part]]></c> | <c><![CDATA['+']]></c> | <c><![CDATA['-']]></c> | <c><![CDATA['*']]></c> | <c><![CDATA['div']]></c> | <c><![CDATA['rem']]></c> | <c><![CDATA['band']]></c> | @@ -140,7 +144,7 @@ <c><![CDATA[process_dump]]></c> | <c><![CDATA[enable_trace]]></c> | <c><![CDATA[disable_trace]]></c> | <c><![CDATA[trace]]></c> | <c><![CDATA[display]]></c> | <c><![CDATA[caller]]></c> | - <c><![CDATA[caller_line]]></c> | + <c><![CDATA[caller_line]]></c> | <c><![CDATA[current_stacktrace]]></c> | <c><![CDATA[set_tcw]]></c> | <c><![CDATA[silent]]></c> </item> </list> @@ -171,8 +175,9 @@ <c><![CDATA[is_list]]></c> | <c><![CDATA[is_number]]></c> | <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> | <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | - <c><![CDATA[is_map]]></c> | <c><![CDATA[map_is_key]]></c> | - <c><![CDATA[is_binary]]></c> | <c><![CDATA[is_function]]></c> | + <c><![CDATA[is_map]]></c> | <c><![CDATA[is_map_key]]></c> | + <c><![CDATA[is_binary]]></c> | <c><![CDATA[is_bitstring]]></c> | + <c><![CDATA[is_boolean]]></c> | <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> | <c><![CDATA['andalso']]></c> | @@ -195,11 +200,14 @@ <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> | <c><![CDATA[element]]></c> | <c><![CDATA[hd]]></c> | <c><![CDATA[length]]></c> | <c><![CDATA[map_get]]></c> | - <c><![CDATA[map_size]]></c> | <c><![CDATA[node]]></c> | - <c><![CDATA[round]]></c> | <c><![CDATA[size]]></c> | + <c><![CDATA[map_size]]></c> | + <c><![CDATA[max]]></c> | <c><![CDATA[min]]></c> | + <c><![CDATA[node]]></c> | <c><![CDATA[float]]></c> | + <c><![CDATA[round]]></c> | <c><![CDATA[floor]]></c> | + <c><![CDATA[ceil]]></c> | <c><![CDATA[size]]></c> | <c><![CDATA[bit_size]]></c> | <c><![CDATA[byte_size]]></c> | - <c><![CDATA[tl]]></c> | <c><![CDATA[trunc]]></c> | - <c><![CDATA[binary_part]]></c> | + <c><![CDATA[tuple_size]]></c> | <c><![CDATA[tl]]></c> | + <c><![CDATA[trunc]]></c> | <c><![CDATA[binary_part]]></c> | <c><![CDATA['+']]></c> | <c><![CDATA['-']]></c> | <c><![CDATA['*']]></c> | <c><![CDATA['div']]></c> | <c><![CDATA['rem']]></c> | <c><![CDATA['band']]></c> | @@ -224,9 +232,10 @@ follows:</p> <taglist> - <tag><c>is_atom</c>, <c>is_float</c>, <c>is_integer</c>, <c>is_list</c>, - <c>is_number</c>, <c>is_pid</c>, <c>is_port</c>, <c>is_reference</c>, - <c>is_tuple</c>, <c>is_map</c>, <c>is_binary</c>, <c>is_function</c> + <tag><c>is_atom</c>, <c>is_boolean</c>, <c>is_float</c>, + <c>is_integer</c>, <c>is_list</c>, <c>is_number</c>, <c>is_pid</c>, + <c>is_port</c>, <c>is_reference</c>, <c>is_tuple</c>, <c>is_map</c>, + <c>is_binary</c>, <c>is_bitstring</c>, <c>is_function</c> </tag> <item> <p>Same as the corresponding guard tests in Erlang, return @@ -275,8 +284,11 @@ <c><![CDATA['xor']]></c> returns false.</p> </item> <tag><c>abs</c>, <c>element</c>, <c>hd</c>, <c>length</c>, - <c>map_get</c>, <c>map_size</c>, <c>node</c>, <c>round</c>, - <c>size</c>, <c>bit_size</c>, <c>byte_size</c>, <c>tl</c>, + <c>map_get</c>, <c>map_size</c>, + <c>max</c>, <c>min</c>, + <c>node</c>, <c>round</c>, <c>ceil</c>, <c>floor</c>, <c>float</c>, + <c>size</c>, <c>bit_size</c>, <c>byte_size</c>, <c>tuple_size</c>, + <c>tl</c>, <c>trunc</c>, <c>binary_part</c>, <c>'+'</c>, <c>'-'</c>, <c>'*'</c>, <c>'div'</c>, <c>'rem'</c>, <c>'band'</c>, <c>'bor'</c>, <c>'bxor'</c>, <c>'bnot'</c>, <c>'bsl'</c>, @@ -457,6 +469,19 @@ <c><![CDATA[undefined]]></c>. The calling Erlang function is not available during such calls.</p> </item> + <tag><c>current_stacktrace</c></tag> + <item> + <p>Returns the current call stack back-trace + (<seetype marker="erts:erlang#stacktrace">stacktrace</seetype>) + of the calling function. The stack has the same format as in the + <c>catch</c> part of a <c>try</c>. See <seeguide + marker="system/reference_manual:errors#stacktrace">The call-stack back trace (stacktrace)</seeguide>. + The depth of the stacktrace is truncated according to the + <c>backtrace_depth</c> system flag setting.</p> + + <p>Accepts a depth parameter. The depth value will be + <c>backtrace_depth</c> if the argument is greater.</p> + </item> <tag><c>display</c></tag> <item> <p>For debugging purposes only. Displays the single argument as an diff --git a/erts/doc/src/time_correction.xml b/erts/doc/src/time_correction.xml index b3a36b907e..30c514c1a3 100644 --- a/erts/doc/src/time_correction.xml +++ b/erts/doc/src/time_correction.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1999</year><year>2021</year> + <year>1999</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -34,29 +34,42 @@ </header> <section> - <title>New Extended Time Functionality</title> - <note><p>As from Erlang/OTP 18 (ERTS 7.0) the time functionality - has been extended. This includes a + <title>Extended Time Functionality</title> + + <p>As of Erlang/OTP 18 (ERTS 7.0) the time functionality + was extended. This includes a <seeguide marker="#The_New_Time_API">new API</seeguide> for time and <seeguide marker="#Time_Warp_Modes">time warp modes</seeguide> that change the system behavior when system time changes.</p> - <p>The <seeguide marker="#No_Time_Warp_Mode">default - time warp mode</seeguide> has the same behavior as before, and the - old API still works. Thus, you are not required to change - anything unless you want to. However, <em>you are strongly - encouraged to use the new API</em> instead of the old API based - on <seemfa marker="erlang#now/0"><c>erlang:now/0</c></seemfa>. - <c>erlang:now/0</c> is deprecated, as it is and - will be a scalability bottleneck.</p> - - <p>By using the new API, you - automatically get scalability and performance improvements. This - also enables you to use the - <seeguide marker="#Multi_Time_Warp_Mode">multi-time warp mode</seeguide> - that improves accuracy and precision of time measurements.</p> + <note> + <p> + As of Erlang/OTP 26 (ERTS 14.0) the + <seeguide marker="#Multi_Time_Warp_Mode">multi time warp + mode</seeguide> is enabled by default. This assumes that all + code executing on the system is + <seeguide marker="#Time_Warp_Safe_Code">time warp safe</seeguide>. + </p> + <p> + If you have old code in the system that is not time warp + safe, you now explicitly need to start the system in + <seeguide marker="#No_Time_Warp_Mode">no time warp + mode</seeguide> (or + <seeguide marker="#Single_Time_Warp_Mode">singe time warp + mode</seeguide> if it is partially time warp safe) in order + to avoid problems. When starting the system in no time warp + mode, the system behaves as it did prior to the introduction + of the extended time functionality introduced in OTP 18. + </p> + <p> + If you have code that is not time warp safe, you are strongly + encouraged to change this so that you can use multi time + warp mode. Compared to no time warp mode, multi time warp + mode improves scalability and performance as well as accuracy + and precision of time measurements. + </p> </note> </section> @@ -405,13 +418,9 @@ <section> <title>No Time Warp Mode</title> <p>The time offset is determined at runtime system start - and does not change later. This is the default behavior, but - not because it is the best mode (which it is not). It is - default <em>only</em> because this is how the runtime system - behaved until ERTS 7.0. - Ensure that your Erlang code that can execute during a time - warp is <seeguide marker="#Time_Warp_Safe_Code">time warp - safe</seeguide> before enabling other modes.</p> + and does not change later. This is the same behavior as was + default prior to OTP 26 (ERTS 14.0), and the only behavior + prior to OTP 18 (ERTS 7.0).</p> <p>As the time offset is not allowed to change, time correction must adjust the frequency of the Erlang @@ -558,7 +567,8 @@ better, and behave better on almost all platforms. Also, the accuracy and precision of time measurements are better. Only Erlang runtime systems executing on - ancient platforms benefit from another configuration.</p> + ancient platforms benefit from another configuration. + As of OTP 26 (ERTS 14.0) this is also the default.</p> <p>The time offset can change at any time without limitations. That is, Erlang system time can perform time warps both diff --git a/erts/doc/src/tty.xml b/erts/doc/src/tty.xml index e82e2cc807..7670b293cd 100644 --- a/erts/doc/src/tty.xml +++ b/erts/doc/src/tty.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1996</year><year>2020</year> + <year>1996</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -67,7 +67,8 @@ erl</pre> <item><c>C-a</c> means pressing the <em>Ctrl</em> key and the letter <c>a</c> simultaneously.</item> <item><c>M-f</c> means pressing the <em>Esc</em> key and the letter - <c>f</c> in sequence.</item> + <c>f</c> in sequence or pressing the <em>Alt</em> key and the letter + <c>f</c> simultaneously.</item> <item><c>Home</c> and <c>End</c> represent the keys with the same name on the keyboard.</item> <item><c>Left</c> and <c>Right</c> represent the corresponding arrow @@ -141,6 +142,10 @@ erl</pre> </row> <row> <cell align="left" valign="middle">C-l</cell> + <cell align="left" valign="middle">Clears the screen</cell> + </row> + <row> + <cell align="left" valign="middle">M-l</cell> <cell align="left" valign="middle">Redraw line</cell> </row> <row> @@ -149,11 +154,22 @@ erl</pre> buffer</cell> </row> <row> + <cell align="left" valign="middle">C-o</cell> + <cell align="left" valign="middle">Edit the current line using the editor specified in + the environment variable <c>VISUAL</c> or <c>EDITOR</c>. The environment variables can + contain arguments to the editor if needed, for example <c>VISUAL="emacs -nw"</c>. + On Windows the editor cannot be a console based editor.</cell> + </row> + <row> <cell align="left" valign="middle">C-p</cell> <cell align="left" valign="middle">Fetch previous line from the history buffer</cell> </row> <row> + <cell align="left" valign="middle">C-r</cell> + <cell align="left" valign="middle">Search the shell history</cell> + </row> + <row> <cell align="left" valign="middle">C-t</cell> <cell align="left" valign="middle">Transpose characters</cell> </row> |