diff options
Diffstat (limited to 'system')
| -rw-r--r-- | system/doc/general_info/Makefile | 6 | ||||
| -rw-r--r-- | system/doc/general_info/deprecations_22.inc | 6 | ||||
| -rw-r--r-- | system/doc/general_info/deprecations_23.inc | 10 | ||||
| -rw-r--r-- | system/doc/general_info/deprecations_24.inc | 30 | ||||
| -rw-r--r-- | system/doc/general_info/removed_23.inc (renamed from system/doc/general_info/scheduled_for_removal_23.inc) | 9 | ||||
| -rw-r--r-- | system/doc/general_info/removed_24.inc | 26 | ||||
| -rw-r--r-- | system/doc/general_info/scheduled_for_removal_24.inc | 26 | ||||
| -rw-r--r-- | system/doc/general_info/scheduled_for_removal_26.inc | 30 | ||||
| -rw-r--r-- | system/doc/reference_manual/expressions.xml | 5 | ||||
| -rw-r--r-- | system/doc/reference_manual/processes.xml | 255 |
10 files changed, 327 insertions, 76 deletions
diff --git a/system/doc/general_info/Makefile b/system/doc/general_info/Makefile index f7e1a86c5a..7dc5811134 100644 --- a/system/doc/general_info/Makefile +++ b/system/doc/general_info/Makefile @@ -85,13 +85,13 @@ debug opt: DEPRECATIONS_SCRIPT = $(ERL_TOP)/lib/stdlib/scripts/update_deprecations -$(XMLDIR)/deprecations.xml: DEPRECATIONS +$(XMLDIR)/deprecations.xml: DEPRECATIONS $(wildcard deprecations_*.inc) $(gen_verbose)escript $(DEPRECATIONS_SCRIPT) make_xml deprecations $(ERL_TOP) $@ -$(XMLDIR)/scheduled_for_removal.xml: DEPRECATIONS +$(XMLDIR)/scheduled_for_removal.xml: DEPRECATIONS $(wildcard scheduled_*.inc) $(gen_verbose)escript $(DEPRECATIONS_SCRIPT) make_xml scheduled_for_removal $(ERL_TOP) $@ -$(XMLDIR)/removed.xml: DEPRECATIONS +$(XMLDIR)/removed.xml: DEPRECATIONS $(wildcard removed_*.inc) $(gen_verbose)escript $(DEPRECATIONS_SCRIPT) make_xml removed $(ERL_TOP) $@ clean clean_docs: diff --git a/system/doc/general_info/deprecations_22.inc b/system/doc/general_info/deprecations_22.inc index 53da6df594..57ba7d8f33 100644 --- a/system/doc/general_info/deprecations_22.inc +++ b/system/doc/general_info/deprecations_22.inc @@ -2,7 +2,8 @@ <title>VxWorks Support</title> <p>Some parts of OTP has had limited VxWorks support, such as for example <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp>. - This support is now deprecated and has also been scheduled for removal in OTP 23.</p> + This support is as of OTP 22 formally deprecated and has also been + <seeguide marker="removed#otp-23">removed in OTP 23</seeguide>.</p> </section> <section> <title>Legacy parts of erl_interface</title> @@ -13,7 +14,8 @@ the <c>erl_interface</c> library with the use of the <c>ei</c> library which also is part of the <c>erl_interface</c> application. The old legacy <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp> - library has also been scheduled for removal in OTP 23.</p> + library has also been + <seeguide marker="removed#otp-23">removed in OTP 23</seeguide>.</p> </section> <section> <title>System Events</title> diff --git a/system/doc/general_info/deprecations_23.inc b/system/doc/general_info/deprecations_23.inc index 0d968a537f..ef1c6ff12f 100644 --- a/system/doc/general_info/deprecations_23.inc +++ b/system/doc/general_info/deprecations_23.inc @@ -1,8 +1,7 @@ <section> <title>Crypto Old API</title> - <p>The <seeguide marker="crypto:new_api#the-old-api">Old API</seeguide> is now deprecated - and has also been - <seeguide marker="scheduled_for_removal#otp-24">scheduled for removal</seeguide>.</p> + <p>The <seeguide marker="crypto:new_api#the-old-api">Old API</seeguide> is deprecated + as of OTP 23 and has been <seeguide marker="removed#otp-24">removed in OTP 24</seeguide>.</p> <p>For replacement functions see the <seeguide marker="crypto:new_api#the-new-api">New API</seeguide>.</p> </section> @@ -35,8 +34,7 @@ As of OTP 23, the distributed <seeerl marker="kernel:disk_log"><c>disk_log</c></seeerl> feature has been deprecated and it has also been - <seeguide marker="scheduled_for_removal#otp-24">scheduled for removal</seeguide> - in OTP 24. + <seeguide marker="removed#otp-24">removed in OTP 24</seeguide>. </p> </section> @@ -45,6 +43,6 @@ <p> As of OTP 23, the <c>registry</c> functionality part of <c>erl_interface</c> has been deprecated and it has also been - removed in OTP 24. + <seeguide marker="removed#otp-24">removed in OTP 24</seeguide>. </p> </section> diff --git a/system/doc/general_info/deprecations_24.inc b/system/doc/general_info/deprecations_24.inc new file mode 100644 index 0000000000..0eb859789a --- /dev/null +++ b/system/doc/general_info/deprecations_24.inc @@ -0,0 +1,30 @@ + <section> + <title>Erlang Distribution Without Large Node Container Support</title> + <p> + Communication over the Erlang distribution without support for large + <seeguide marker="erts:erl_dist_protocol#DFLAG_V4_NC">node container + data types (version 4)</seeguide> is as of OTP 24 deprecated and is + <seeguide marker="scheduled_for_removal#otp-26">scheduled for removal + in OTP 26</seeguide>. That is, as of OTP 26, support for large + node container data types will become mandatory. + </p> + </section> + + <section> + <title>Old Link Protocol</title> + <p> + The <seeguide marker="erts:erl_dist_protocol#old_link_protocol">old + link protocol</seeguide> used when communicating over the Erlang + distribution is as of OTP 24 deprecated and support for it is + <seeguide marker="scheduled_for_removal#otp-26">scheduled for removal + in OTP 26</seeguide>. As of OTP 26, the + <seeguide marker="erts:erl_dist_protocol#new_link_protocol">new + link protocol</seeguide> will become mandatory. That is, Erlang nodes + will then refuse to connect to nodes not implementing the new + link protocol. If you implement the Erlang distribution yourself, you + are, however, encouraged to implement the new link protocol as soon as + possible since the old protocol can cause links to enter an + inconsistent state. + </p> + </section> + diff --git a/system/doc/general_info/scheduled_for_removal_23.inc b/system/doc/general_info/removed_23.inc index 692d51d09c..258218d460 100644 --- a/system/doc/general_info/scheduled_for_removal_23.inc +++ b/system/doc/general_info/removed_23.inc @@ -2,14 +2,15 @@ <title>VxWorks Support</title> <p>Some parts of OTP has had limited VxWorks support, such as <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp>. - This support will be removed as of OTP 23. This limited support + This support was removed in OTP 23. This limited support was formally deprecated as of OTP 22.</p> </section> + <section> <title>Legacy parts of erl_interface</title> <p>The old legacy <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp> - library (functions with prefix <c>erl_</c>) will be removed as of - OTP 23. These parts of <c>erl_interface</c> has been informally deprecated + library (functions with prefix <c>erl_</c>) was removed in OTP 23. + These parts of <c>erl_interface</c> has been informally deprecated for a very long time, and was formally deprecated in OTP 22. You typically want to replace the usage of the <c>erl_interface</c> library with the use of the <c>ei</c> library which also is part of the <c>erl_interface</c> @@ -28,7 +29,7 @@ <section> <title>inets - httpd Apache config files</title> <p> - Support for the Apache-compatible config files will be removed in + Support for the Apache-compatible config files was removed in OTP 23. A new config file format was introduced in OTP 12. </p> </section> diff --git a/system/doc/general_info/removed_24.inc b/system/doc/general_info/removed_24.inc index 37d514efa4..0274c8dec4 100644 --- a/system/doc/general_info/removed_24.inc +++ b/system/doc/general_info/removed_24.inc @@ -21,3 +21,29 @@ and <url href="https://github.com/richcarl/erl_tidy">github.com/richcarl/erl_tidy</url>, respectively.</p> </section> + <section> + <title>Distributed Disk Logs</title> + <p> + The distributed + <seeerl marker="kernel:disk_log"><c>disk_log</c></seeerl> + feature was as of + <seeguide marker="deprecations#otp-23">OTP 23 deprecated</seeguide> + and was removed in OTP 24. + </p> + </section> + <section> + <title>Old Crypto API</title> + <p>The <seeguide marker="crypto:new_api#the-old-api">Old API</seeguide> was + removed in OTP 24. The support was formally deprecated as of OTP 23.</p> + <p>For replacement functions see the + <seeguide marker="crypto:new_api#the-new-api">New API</seeguide>.</p> + </section> + <section> + <title>Megaco version 3 encoding config</title> + <p>The pre-release version 3 encoding configs; + <c>prev3a</c>, <c>prev3b</c> and <c>prev3c</c> was removed in OTP 24. + Use the full version instead. </p> + <p>The (encoding) config option for the full version, <c>{version3, 3}</c>, + will still be supported, even though its no longer necessary to specify + it this way. </p> + </section> diff --git a/system/doc/general_info/scheduled_for_removal_24.inc b/system/doc/general_info/scheduled_for_removal_24.inc deleted file mode 100644 index 6fddc033b6..0000000000 --- a/system/doc/general_info/scheduled_for_removal_24.inc +++ /dev/null @@ -1,26 +0,0 @@ - <section> - <title>Old Crypto API</title> - <p>The <seeguide marker="crypto:new_api#the-old-api">Old API</seeguide> will be - removed as of OTP 24. The support was formally deprecated as of OTP 23.</p> - <p>For replacement functions see the - <seeguide marker="crypto:new_api#the-new-api">New API</seeguide>.</p> - </section> - <section> - <title>Distributed Disk Logs</title> - <p> - The distributed - <seeerl marker="kernel:disk_log"><c>disk_log</c></seeerl> - feature is as of - <seeguide marker="deprecations#otp-23">OTP 23 deprecated</seeguide> - and will be removed in OTP 24. - </p> - </section> - <section> - <title>Megaco version 3 encoding config</title> - <p>As of OTP 24, the pre-release version 3 encoding configs; - <c>prev3a</c>, <c>prev3b</c> and <c>prev3c</c> will be removed. - Use the full version instead. </p> - <p>The (encoding) config option for the full version, <c>{version3, 3}</c>, - will still be supported, even though its no longer necessary to specify - it this way. </p> - </section> diff --git a/system/doc/general_info/scheduled_for_removal_26.inc b/system/doc/general_info/scheduled_for_removal_26.inc new file mode 100644 index 0000000000..1d59136ce5 --- /dev/null +++ b/system/doc/general_info/scheduled_for_removal_26.inc @@ -0,0 +1,30 @@ + <section> + <title>Erlang Distribution Without Large Node Container Support</title> + <p> + Communication over the Erlang distribution without support for large + <seeguide marker="erts:erl_dist_protocol#DFLAG_V4_NC"> node container + data types (version 4)</seeguide> is as of + <seeguide marker="deprecations#otp-24">OTP 24 deprecated</seeguide> + and support for it is scheduled for removal in OTP 26. That is, as + of OTP 26, support for large node container data types will become + mandatory. + </p> + </section> + + <section> + <title>Old Link Protocol</title> + <p> + The <seeguide marker="erts:erl_dist_protocol#old_link_protocol">old + link protocol</seeguide> used when communicating over the Erlang + distribution is as of <seeguide marker="deprecations#otp-24"> + OTP 24 deprecated</seeguide> and support for it is scheduled for + removal in OTP 26. As of OTP 26 the + <seeguide marker="erts:erl_dist_protocol#new_link_protocol">new + link protocol</seeguide> will become mandatory. That is, Erlang nodes + will then refuse to connect to nodes not implementing the new + link protocol. If you implement the Erlang distribution yourself, you + are, however, encouraged to implement the new link protocol as soon as + possible since the old protocol can cause links to enter an + inconsistent state. + </p> + </section> diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 38b8a7a241..b21ab8eb96 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -402,12 +402,15 @@ Expr1 ! Expr2</pre> <p>Sends the value of <c>Expr2</c> as a message to the process specified by <c>Expr1</c>. The value of <c>Expr2</c> is also the return value of the expression.</p> - <p><c>Expr1</c> must evaluate to a pid, a registered name (atom), or + <p><c>Expr1</c> must evaluate to a pid, an alias (reference), + a port, a registered name (atom), or a tuple <c>{Name,Node}</c>. <c>Name</c> is an atom and <c>Node</c> is a node name, also an atom.</p> <list type="bulleted"> <item>If <c>Expr1</c> evaluates to a name, but this name is not registered, a <c>badarg</c> run-time error occurs.</item> + <item>Sending a message to a reference never fails, even if the + reference is no longer (or never was) an alias.</item> <item>Sending a message to a pid never fails, even if the pid identifies a non-existing process.</item> <item>Distributed message sending, that is, if <c>Expr1</c> diff --git a/system/doc/reference_manual/processes.xml b/system/doc/reference_manual/processes.xml index 2b68be4b31..597258b9fd 100644 --- a/system/doc/reference_manual/processes.xml +++ b/system/doc/reference_manual/processes.xml @@ -122,14 +122,39 @@ spawn(Module, Name, Args) -> pid() <section> <title>Links</title> - <p>Two processes can be <em>linked</em> to each other. A link - between two processes <c>Pid1</c> and <c>Pid2</c> is created - by <c>Pid1</c> calling the BIF <c>link(Pid2)</c> (or conversely). - There also exist a number of <c>spawn_link</c> BIFs, which spawn - and link to a process in one operation.</p> - <p>Links are bidirectional and there can only be one link between - two processes. Repeated calls to <c>link(Pid)</c> have no effect.</p> - <p>A link can be removed by calling the BIF <c>unlink(Pid)</c>.</p> + <p> + Two processes can be <em>linked</em> to each other. Also a + process and a port that reside on the same node can be linked + to each other. A link beteen two processes can be created + if one of them calls the + <seemfa marker="erts:erlang#link/1"><c>link/1</c></seemfa> BIF + with the process identifier of the other process as argument. + Links can also be created using one the following spawn BIFs + <seemfa marker="erts:erlang#spawn_link/4"><c>spawn_link()</c></seemfa>, + <seemfa marker="erts:erlang#spawn_opt/5"><c>spawn_opt()</c></seemfa>, or + <seemfa marker="erts:erlang#spawn_request/5"><c>spawn_request()</c></seemfa>. + The spawn operation and the link operation will + be performed atomically, in these cases. + </p> + <p> + If one of the participants of a link terminates, it will + <seeguide marker="system/reference_manual:processes#sending_exit_signals">send + an exit signal</seeguide> to the other participant. The exit + signal will contain the + <seeguide marker="system/reference_manual:processes#link_exit_signal_reason">exit + reason</seeguide> of the terminated participant. + </p> + <p> + A link can be removed by calling the + <seemfa marker="erts:erlang#unlink/1"><c>unlink/1</c></seemfa> + BIF. + </p> + <p> + Links are bidirectional and there can only be one link between + two processes. Repeated calls to <c>link()</c> have no effect. + Either one of the involved processes may create or remove a + link. + </p> <p>Links are used to monitor the behaviour of other processes, see <seeguide marker="#errors">Error Handling</seeguide>.</p> </section> @@ -149,35 +174,198 @@ spawn(Module, Name, Args) -> pid() OTP supervision trees, which use this feature.</p> <section> - <title>Emitting Exit Signals</title> - <p>When a process terminates, it terminates with an - <em>exit reason</em> as explained in <seeguide marker="#term"> - Process Termination</seeguide>. This exit reason is emitted in - an <em>exit signal</em> to all linked processes.</p> - <p>A process can also call the function <c>exit(Pid,Reason)</c>. - This results in an exit signal with exit reason - <c>Reason</c> being emitted to <c>Pid</c>, but does not affect - the calling process.</p> + <marker id="sending_exit_signals"/> + <title>Sending Exit Signals</title> + <p> + When a process or port + <seeguide marker="#term">terminates</seeguide> it will + send exit signals to all processes and ports that it + is <seeguide marker="#links">linked</seeguide> to. + The exit signal will contain the following information: + </p> + <taglist> + <tag>Sender identifier</tag> + <item><p> + The process or port identifier of the process or port + that terminated. + </p></item> + <tag>Receiver identifier</tag> + <item><p> + The process or port identifier of the process or port + which the exit signal is sent to. + </p></item> + <tag>The <c>link</c> flag</tag> + <item><p> + This flag will be set indicating that the exit signal + was sent due to a link. + </p></item> + <tag><marker id="link_exit_signal_reason"/>Exit reason</tag> + <item><p> + The exit reason of the process or port that + terminated or the atom:</p> + <list> + <item><p> + <c>noproc</c> in case no process or port was + found when setting up a link in a preceeding + call to the + <seemfa marker="erts:erlang#link/1"><c>link(PidOrPort)</c></seemfa> + BIF. The process or port identified as sender + of the exit signal will equal the <c>PidOrPort</c> + argument passed to <c>link/1</c>. + </p></item> + <item><p> + <c>noconnection</c> in case the linked + processes resides on different nodes and + the connection between the nodes was lost or + could not be established. The process or port + identified as sender of the exit signal might + in this case still be alive. + </p></item> + </list> + </item> + </taglist> + + <p> + Exit signals can also be sent explicitly by calling the + <seemfa marker="erts:erlang#exit/2"><c>exit(PidOrPort, + Reason)</c></seemfa> BIF. The exit signal is sent to the + process or port identified by the <c>PidOrPort</c> argument. + The exit signal sent will contain the following information: + </p> + <taglist> + <tag>Sender identifier</tag> + <item><p> + The process identifier of the process that called + <c>exit/2</c>. + </p></item> + <tag>Receiver identifier</tag> + <item><p> + The process or port identifier of the process or port + which the exit signal is sent to. + </p></item> + <tag>The <c>link</c> flag</tag> + <item><p> + This flag will not be set, indicating that this exit + signal was not sent due to a link. + </p></item> + <tag>Exit reason</tag> + <item><p> + The term passed as <c>Reason</c> in the call to + <c>exit/2</c>. If <c>Reason</c> is the atom <c>kill</c>, + the receiver cannot + <seeerl marker="erts:erlang#process_flag_trap_exit">trap + the exit</seeerl> signal and will unconditionally + terminate when it receives the signal. + </p></item> + </taglist> </section> <section> + <marker id="receiving_exit_signals"/> <title>Receiving Exit Signals</title> - <p>The default behaviour when a process receives an exit signal - with an exit reason other than <c>normal</c>, is to terminate - and in turn emit exit signals with the same exit reason to its - linked processes. An exit signal with reason <c>normal</c> is - ignored.</p> - <p>A process can be set to trap exit signals by calling:</p> - <pre> -process_flag(trap_exit, true)</pre> - <p>When a process is trapping exits, it does not terminate when - an exit signal is received. Instead, the signal is transformed - into a message <c>{'EXIT',FromPid,Reason}</c>, which is put into - the mailbox of the process, just like a regular message.</p> - <p>An exception to the above is if the exit reason is <c>kill</c>, - that is if <c>exit(Pid,kill)</c> has been called. This - unconditionally terminates the process, regardless of if it is - trapping exit signals.</p> + + <p>What happens when a process receives an exit signal depends on:</p> + <list> + <item><p> + The <seeerl marker="erts:erlang#process_flag_trap_exit">trap exit</seeerl> + state of the receiver at the time when the exit signal is received. + </p></item> + <item><p> + The exit reason of the exit signal. + </p></item> + <item><p> + The sender of the exit signal. + </p></item> + <item><p> + The state of the <c>link</c> flag of the exit signal. If the + <c>link</c> flag is set, the exit signal was sent due to a + link; otherwise, the exit signal was sent by a call to the + <seemfa marker="erts:erlang#exit/2"><c>exit/2</c></seemfa> BIF. + </p></item> + <item><p> + If the <c>link</c> flag is set, what happens also depends on + whether the <seemfa marker="erts:erlang#unlink/1">link is still active + or not</seemfa> when the exit signal is received. + </p></item> + </list> + + <p> + Based on the above states, the following will happen when an + exit signal is received by a process: + </p> + <list> + <item> + <p>The exit signal is silently dropped if:</p> + <list> + <item><p> + the <c>link</c> flag of the exit signal is set and + the corresponding link has been deactivated. + </p></item> + <item><p> + the exit reason of the exit signal is the atom <c>normal</c>, + the receiver is not trapping exits, and the receiver and + sender are not the same process. + </p></item> + </list> + </item> + <item> + <p>The receiving process is terminated if:</p> + <list> + <item><p> + the <c>link</c> flag of the exit signal + is not set, and the exit reason of the exit signal + is the atom <c>kill</c>. The receiving process will + terminate with the atom <c>killed</c> as exit reason. + </p></item> + <item><p> + the receiver is not trapping exits, and the exit + reason is something other than the atom <c>normal</c>. + Also, if the <c>link</c> flag of the exit signal + is set, the link also needs to be active otherwise the + exit signal will be dropped. The exit reason of the + receiving process will equal the exit reason of the + exit signal. Note that if the <c>link</c> flag + is set, an exit reason of <c>kill</c> will <em>not</em> + be converted to <c>killed</c>. + </p></item> + <item><p> + the exit reason of the exit signal is the atom + <c>normal</c> and the sender of the exit signal is + the same process as the receiver. The <c>link</c> + flag cannot be set in this case. The exit reason + of the receiving process will be the atom <c>normal</c>. + </p></item> + </list> + </item> + <item> + <p> + The exit signal is converted to a message signal and + moved into the message queue of the receiver, if the + receiver is trapping exits, the <c>link</c> flag + of the exit signal is: + </p> + <list> + <item><p> + not set, and the exit reason of the signal is not + the atom <c>kill</c>. + </p></item> + <item><p> + set, and the corresponding link is active. + Note that an exit reason of <c>kill</c> will + <em>not</em> terminate the process in this + case and it will not be converted to + <c>killed</c>. + </p></item> + </list> + <p> + The converted message will be on the form + <c>{'EXIT', SenderID, Reason}</c> where <c>Reason</c> + equals the exit reason of the exit signal and + <c>SenderID</c> is the identifier of the process + or port that sent the exit signal. + </p> + </item> + </list> </section> </section> @@ -216,4 +404,3 @@ erase(Key) erase()</pre> </section> </chapter> - |