diff options
Diffstat (limited to 'erts/doc/src')
| -rw-r--r-- | erts/doc/src/.gitignore | 3 | ||||
| -rw-r--r-- | erts/doc/src/Makefile | 113 | ||||
| -rw-r--r-- | erts/doc/src/alt_dist.xml | 6 | ||||
| -rw-r--r-- | erts/doc/src/epmd_cmd.xml (renamed from erts/doc/src/epmd.xml) | 13 | ||||
| -rw-r--r-- | erts/doc/src/erl_cmd.xml (renamed from erts/doc/src/erl.xml) | 37 | ||||
| -rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 458 | ||||
| -rw-r--r-- | erts/doc/src/erl_ext_dist.xml | 48 | ||||
| -rw-r--r-- | erts/doc/src/erl_ext_fig.gif | bin | 3834 -> 3840 bytes | |||
| -rw-r--r-- | erts/doc/src/erlang.xml | 736 | ||||
| -rw-r--r-- | erts/doc/src/erlc_cmd.xml (renamed from erts/doc/src/erlc.xml) | 3 | ||||
| -rw-r--r-- | erts/doc/src/erlsrv_cmd.xml (renamed from erts/doc/src/erlsrv.xml) | 13 | ||||
| -rw-r--r-- | erts/doc/src/escript_cmd.xml (renamed from erts/doc/src/escript.xml) | 3 | ||||
| -rw-r--r-- | erts/doc/src/init.xml | 25 | ||||
| -rw-r--r-- | erts/doc/src/ref_man.xml.src | 18 | ||||
| -rw-r--r-- | erts/doc/src/run_erl_cmd.xml (renamed from erts/doc/src/run_erl.xml) | 5 | ||||
| -rw-r--r-- | erts/doc/src/socket.xml | 68 | ||||
| -rw-r--r-- | erts/doc/src/start_cmd.xml (renamed from erts/doc/src/start.xml) | 5 | ||||
| -rw-r--r-- | erts/doc/src/start_erl_cmd.xml (renamed from erts/doc/src/start_erl.xml) | 7 | ||||
| -rw-r--r-- | erts/doc/src/werl_cmd.xml (renamed from erts/doc/src/werl.xml) | 9 |
19 files changed, 1212 insertions, 358 deletions
diff --git a/erts/doc/src/.gitignore b/erts/doc/src/.gitignore new file mode 100644 index 0000000000..abe9a7d858 --- /dev/null +++ b/erts/doc/src/.gitignore @@ -0,0 +1,3 @@ +ref_man.xml +specs.xml +part.xml
\ No newline at end of file diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index bb96293947..3e2eb80b50 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -37,15 +37,15 @@ RELSYSDIR = $(RELEASE_PATH)/$(APPLICATION)-$(VSN) # Target Specs # ---------------------------------------------------- XML_APPLICATION_FILES = ref_man.xml -XML_REF1_FILES = epmd.xml \ - erl.xml \ - erlc.xml \ - escript.xml \ - werl.xml \ - erlsrv.xml \ - start_erl.xml \ - run_erl.xml \ - start.xml +XML_REF1_FILES = epmd_cmd.xml \ + erl_cmd.xml \ + erlc_cmd.xml \ + escript_cmd.xml \ + werl_cmd.xml \ + erlsrv_cmd.xml \ + start_erl_cmd.xml \ + run_erl_cmd.xml \ + start_cmd.xml ifeq ($(USE_ESOCK), yes) XML_REF3_ESOCK_EFILES = socket.xml @@ -72,13 +72,16 @@ XML_REF3_EFILES = \ zlib.xml \ $(XML_REF3_ESOCK_EFILES) -XML_REF3_FILES = \ - $(XML_REF3_EFILES) \ +XML_REF3_CREF = \ driver_entry.xml \ erl_nif.xml \ erl_driver.xml \ erts_alloc.xml +XML_REF3_FILES = \ + $(XML_REF3_EFILES) \ + $(XML_REF3_CREF) + XML_PART_FILES = \ part.xml internal.xml @@ -96,7 +99,6 @@ XML_INTERNAL_FILES = \ SuperCarrier.xml \ CountingInstructions.xml - XML_CHAPTER_FILES = \ introduction.xml \ tty.xml \ @@ -118,32 +120,24 @@ TOPDOCDIR=../../../doc BOOK_FILES = book.xml -GIF_FILES = \ +IMAGE_FILES = \ erl_ext_fig.gif XML_FILES = \ $(BOOK_FILES) $(XML_CHAPTER_FILES) \ $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_REF1_FILES) $(XML_APPLICATION_FILES) +HTML_EXTRA_FILES = $(ERL_TOP)/erts/example/time_compat.erl \ + $(ERL_TOP)/lib/kernel/examples/gen_tcp_dist/src/gen_tcp_dist.erl + XML_GEN_FILES = $(XML_INTERNAL_FILES:%=$(XMLDIR)/%) -# ---------------------------------------------------- +NO_CHUNKS = $(XML_REF3_CREF) erl_tracer.xml -HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ - $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) +# ---------------------------------------------------- -INFO_FILE = ../../info INFO_FILE_SRC = ../../info.src -MAN1_FILES = $(XML_REF1_FILES:%.xml=$(MAN1DIR)/%.1) -MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) - -HTML_REF_MAN_FILE = $(HTMLDIR)/index.html - -TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf - -SPECS_FILES = $(XML_REF3_EFILES:%.xml=$(SPECDIR)/specs_%.xml) - TOP_SPECS_FILE = specs.xml XML_FIGURE_DIR = $(XMLDIR)/figures @@ -153,60 +147,24 @@ PNG_FILES = $(notdir $(INTERNAL_DOC_PNG_FILES)) XMLDIR_PNG_FILES = $(PNG_FILES:%=$(XML_FIGURE_DIR)/%) # ---------------------------------------------------- -# FLAGS -# ---------------------------------------------------- -XML_FLAGS += - -KERNEL_SRC=$(ERL_TOP)/lib/kernel/src -KERNEL_INCLUDE=$(ERL_TOP)/lib/kernel/include -SPECS_FLAGS = -I$(KERNEL_SRC) -I$(KERNEL_INCLUDE) - -# ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(XML_FIGURE_DIR)) +include $(ERL_TOP)/make/doc.mk -$(HTMLDIR)/%.gif: %.gif - $(INSTALL_DATA) $< $@ +_create_dirs := $(shell mkdir -p $(XML_FIGURE_DIR)) $(XML_FIGURE_DIR)/%.png: ../../emulator/internal_doc/figures/%.png $(INSTALL_DATA) $< $@ -docs: part ref_man specs figures man pdf html $(INFO_FILE) - -$(TOP_PDF_FILE): $(XML_FILES) - -pdf: $(TOP_PDF_FILE) - -html: gifs $(HTML_REF_MAN_FILE) - -man: $(MAN1_FILES) $(MAN3_FILES) - -ref_man: ref_man.xml -part: part.xml -specs: specs.xml - -gifs: $(GIF_FILES:%=$(HTMLDIR)/%) +html: figures $(INFO_FILE): $(INFO_FILE_SRC) $(ERL_TOP)/make/$(TARGET)/otp.mk sed -e 's;%RELEASE%;$(SYSTEM_VSN);' $(INFO_FILE_SRC) > $(INFO_FILE) figures: $(XMLDIR_PNG_FILES) -debug opt: - -ldocs: xmllint local_docs - -clean: - rm -rf $(HTMLDIR)/* - rm -rf $(XMLDIR) - rm -f $(MAN1DIR)/* - rm -f $(MAN3DIR)/* - rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) - rm -f $(SPECDIR)/* - rm -f errs core *~ - -$(SPECDIR)/specs_%.xml: +## This rule generate dummy specs for all XML_REF3_CREF's +$(XML_REF3_CREF:%.xml=$(SPECDIR)/specs_%.xml): $(@:%.xml=%.xml) $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ -o$(dir $@) -module $(patsubst $(SPECDIR)/specs_%.xml,%,$@) @@ -229,25 +187,10 @@ specs.xml: specs.xml.src # ---------------------------------------------------- # Release Target # ---------------------------------------------------- -include $(ERL_TOP)/make/otp_release_targets.mk -release_docs_spec: docs - $(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf" - $(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELSYSDIR)/doc/pdf" - $(INSTALL_DIR) "$(RELSYSDIR)/doc/html" +release_html_spec: release_figures + +release_figures: $(INSTALL_DIR) "$(RELSYSDIR)/doc/html/figures" - $(INSTALL_DATA) $(HTMLDIR)/* \ - "$(RELSYSDIR)/doc/html" $(INSTALL_DATA) $(XMLDIR)/figures/* \ "$(RELSYSDIR)/doc/html/figures" - $(INSTALL_DATA) $(ERL_TOP)/erts/example/time_compat.erl \ - "$(RELSYSDIR)/doc/html" - $(INSTALL_DATA) $(ERL_TOP)/lib/kernel/examples/gen_tcp_dist/src/gen_tcp_dist.erl \ - "$(RELSYSDIR)/doc/html" - $(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)" - $(INSTALL_DIR) "$(RELEASE_PATH)/man/man3" - $(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3" - $(INSTALL_DIR) "$(RELEASE_PATH)/man/man1" - $(INSTALL_DATA) $(MAN1_FILES) "$(RELEASE_PATH)/man/man1" - -release_spec: diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml index f72e8acd2c..f2155bcc4d 100644 --- a/erts/doc/src/alt_dist.xml +++ b/erts/doc/src/alt_dist.xml @@ -785,12 +785,14 @@ <taglist> <tag><c>DFLAG_DIST_HDR_ATOM_CACHE</c></tag> <item>Do not use atom cache over this connection.</item> + <tag><c>DFLAG_FRAGMENTS</c></tag> + <item>Split large distribution messages into multiple fragments.</item> </taglist> - <p>Use function <c>dist_util:strict_order_flags/0</c> to get all flags - for features that require strict order delivery.</p> <p> This flag field is optional. </p> + <p>See also <seealso marker="#distribution_data_delivery"> + Distribution Data Delivery</seealso></p> </item> <tag><marker id="hs_data_require_flags"/><c>require_flags</c></tag> diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd_cmd.xml index 75353cbc07..ee886bd68e 100644 --- a/erts/doc/src/epmd.xml +++ b/erts/doc/src/epmd_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,11 +19,11 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>epmd</title> - <prepared>Claes Wikström</prepared> + <prepared>Claes Wikström</prepared> <responsible></responsible> <docno>1</docno> <approved></approved> @@ -295,9 +295,8 @@ <title>Logging</title> <p>On some operating systems <em>syslog</em> will be used for error reporting when <c>epmd</c> runs as a daemon. To enable - the error logging, you must edit the - <path unix="" windows="">/etc/syslog.conf</path> file and add an - entry:</p> + the error logging, you must edit the /etc/syslog.conf file and + add an entry:</p> <code type="none"><![CDATA[ !epmd @@ -334,5 +333,3 @@ <p>To restrict access further, firewall software must be used.</p> </section> </comref> - - diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl_cmd.xml index a37707f7f9..64663ce95e 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -181,7 +181,7 @@ which is used to start the system; see <seealso marker="init"><c>init(3)</c></seealso>. Unless <c><![CDATA[File]]></c> contains an absolute path, the system searches - for <c><![CDATA[File.boot]]></c> in the current and + for <c><![CDATA[File.boot]]></c> in the current and <c><![CDATA[$ROOT/bin]]></c> directories.</p> <p>Defaults to <c><![CDATA[$ROOT/bin/start.boot]]></c>.</p> </item> @@ -207,9 +207,9 @@ <p>Not recommended; use <seealso marker="erlc"><c>erlc</c></seealso> instead.</p> </item> - <tag><c><![CDATA[-config Config]]></c></tag> + <tag><c><![CDATA[-config Config [Config]]]></c></tag> <item> - <p>Specifies the name of a configuration file, + <p>Specifies the name of one or more configuration files, <c><![CDATA[Config.config]]></c>, which is used to configure applications; see <seealso marker="kernel:app"><c>app(4)</c></seealso> and @@ -575,8 +575,8 @@ <tag><marker id="async_thread_pool_size"/><c><![CDATA[+A size]]></c></tag> <item> <p>Sets the number of threads in async thread pool. Valid range - is 0-1024. The async thread pool is used by linked-in drivers to - handle work that may take a very long time. Since OTP-21 there are + is 1-1024. The async thread pool is used by linked-in drivers to + handle work that may take a very long time. Since OTP 21 there are very few linked-in drivers in the default Erlang/OTP distribution that uses the async thread pool. Most of them have been migrated to dirty IO schedulers. Defaults to 1.</p> @@ -852,7 +852,7 @@ <p>Sets the range of characters that the system considers printable in heuristic detection of strings. This typically affects the shell, debugger, and <c>io:format</c> functions (when <c>~tp</c> is used in - the format string).</p> + the format string).</p> <p>Two values are supported for <c>Range</c>:</p> <taglist> <tag><c>latin1</c></tag> @@ -948,14 +948,19 @@ <c><![CDATA[+S Schedulers:SchedulerOnline]]></c></tag> <item> <p>Sets the number of scheduler threads to create and scheduler threads - to set online. The maximum for both - values is 1024. If the Erlang runtime system is able to determine the - number of logical processors configured and logical processors - available, <c>Schedulers</c> defaults to logical processors - configured, and <c>SchedulersOnline</c> defaults to logical processors - available; otherwise the default values are 1. <c>Schedulers</c> can - be omitted if <c>:SchedulerOnline</c> is not and conversely. The - number of schedulers online can be changed at runtime through + to set online. The maximum for both values is 1024. If the Erlang + runtime system is able to determine the number of logical processors + configured and logical processors available, <c>Schedulers</c> + defaults to logical processors configured, and + <c>SchedulersOnline</c> defaults to logical processors available; + otherwise the default values are 1. If the emulator detects that it + is subject to a <seealso marker="erlang#system_info_cpu_quota">CPU + quota</seealso>, the default value for <c>SchedulersOnline</c> will + be limited accordingly.</p> + <p> + <c>Schedulers</c> can be omitted if <c>:SchedulerOnline</c> is not + and conversely. The number of schedulers online can be changed at + runtime through <seealso marker="erlang#system_flag_schedulers_online"> <c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></seealso>.</p> @@ -1270,7 +1275,7 @@ node identifiers can be omitted. If omitted, the thread ID defaults to <c>t0</c>, the core ID defaults to <c>c0</c>, the processor ID defaults to <c>p0</c>, and the node ID is - left undefined. Either each logical processor must + left undefined. Either each logical processor must belong to only one NUMA node, or no logical processors must belong to any NUMA nodes.</p> <p>Both increasing and decreasing <c><![CDATA[<IdRange>]]></c>s diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index f924c8a70b..eeb0049f4f 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -109,7 +109,8 @@ <title>Register a Node in EPMD</title> <p>When a distributed node is started it registers itself in the EPMD. The message <c>ALIVE2_REQ</c> described below is sent from the node to - the EPMD. The response from the EPMD is <c>ALIVE2_RESP</c>.</p> + the EPMD. The response from the EPMD is <c>ALIVE2_X_RESP</c> (or + <c>ALIVE2_RESP</c>).</p> <table align="left"> <row> @@ -154,13 +155,13 @@ </item> <tag><c>HighestVersion</c></tag> <item> - <p>The highest distribution version that this node can handle. - The value in Erlang/OTP R6B and later is 5.</p> + <p>The highest distribution protocol version this node can handle. + The value in OTP 23 and later is 6. Older nodes only support version 5.</p> </item> <tag><c>LowestVersion</c></tag> <item> <p>The lowest distribution version that this node can handle. - The value in Erlang/OTP R6B and later is 5.</p> + Should be 5 to support connections to nodes older than OTP 23.</p> </item> <tag><c>Nlen</c></tag> <item> @@ -184,7 +185,24 @@ node is a distributed node. When the connection is closed, the node is automatically unregistered from the EPMD.</p> - <p>The response message <c>ALIVE2_RESP</c> is as follows:</p> + <p>The response message is either <c>ALIVE2_X_RESP</c> or + <c>ALIVE2_RESP</c> depending on distribution version. If both the node + and EPMD support distribution version 6 then the response is + <c>ALIVE2_X_RESP</c> otherwise it is the older <c>ALIVE2_RESP</c>:</p> + + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">1</cell> + <cell align="center">4</cell> + </row> + <row> + <cell align="center"><c>118</c></cell> + <cell align="center"><c>Result</c></cell> + <cell align="center"><c>Creation</c></cell> + </row> + <tcaption>ALIVE2_X_RESP (118) with 32 bit creation</tcaption> + </table> <table align="left"> <row> @@ -197,7 +215,7 @@ <cell align="center"><c>Result</c></cell> <cell align="center"><c>Creation</c></cell> </row> - <tcaption>ALIVE2_RESP (121)</tcaption> + <tcaption>ALIVE2_RESP (121) with 16-bit creation</tcaption> </table> <p>Result = 0 -> ok, result > 0 -> error.</p> @@ -531,8 +549,14 @@ io:format("old/unused name ~ts at port ~p, fd = ~p ~n", <section> <marker id="distribution_handshake"/> <title>Distribution Handshake</title> - <p>This section describes the distribution handshake protocol introduced - in Erlang/OTP R6. The handshake has remained almost the same since then.</p> + <p> + This section describes the distribution handshake protocol used between + nodes to establishing a connection. The protocol was introduced in + Erlang/OTP R6 and has remained unchanged until OTP 23. The changes made in + OTP 23 were designed to be compatible with the older protocol + version. That is an old node can still connect toward a new node and vice + versa. + </p> <section> <title>General</title> @@ -599,19 +623,68 @@ io:format("old/unused name ~ts at port ~p, fd = ~p ~n", <tag>2) <c>send_name</c>/<c>receive_name</c></tag> <item> <p><c>A</c> sends an initial identification to <c>B</c>, which - receives the message. The message looks as follows (every "square" - is one byte and the packet header is removed):</p> - <pre> -+---+--------+--------+-----+-----+-----+-----+-----+-----+-...-+-----+ -|'n'|Version0|Version1|Flag0|Flag1|Flag2|Flag3|Name0|Name1| ... |NameN| -+---+--------+--------+-----+-----+-----+-----+-----+-----+-... +-----+</pre> - <p>'n' is the message tag. 'Version0' and 'Version1' is the - distribution version selected by <c>A</c>, based on information - from the EPMD. (16-bit big-endian) 'Flag0' ... 'Flag3' are - capability flags, the capabilities are defined in - <c>$ERL_TOP/lib/kernel/include/dist.hrl</c>. (32-bit big-endian) - 'Name0' ... 'NameN' is the full node name of <c>A</c>, as a string - of bytes (the packet length denotes how long it is).</p> + receives the message. The message can have two different formats + which looks as follows (the packet headers are removed): + </p> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">2</cell> + <cell align="center">4</cell> + <cell align="center">Nlen</cell> + </row> + <row> + <cell align="center"><c>'n'</c></cell> + <cell align="center"><c>Version=5</c></cell> + <cell align="center"><c>Flags</c></cell> + <cell align="center"><c>Name</c></cell> + </row> + <tcaption>Old send_name ('n') for protocol version 5</tcaption> + </table> + + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">8</cell> + <cell align="center">4</cell> + <cell align="center">2</cell> + <cell align="center">Nlen</cell> + </row> + <row> + <cell align="center"><c>'N'</c></cell> + <cell align="center"><c>Flags</c></cell> + <cell align="center"><c>Creation</c></cell> + <cell align="center"><c>Nlen</c></cell> + <cell align="center"><c>Name</c></cell> + </row> + <tcaption>New send_name ('N') for protocol version 6</tcaption> + </table> + + <p> + The old <c>send_name</c> format is sent from nodes only supporting version 5 + or to nodes that might only support version 5. The <c>Version</c> is + a 16-bit big endian integer and <em>must</em> always have the value 5, even + if node <c>A</c> supports version 6. <c>Flags</c> are the + <seealso marker="#dflags">capability flags</seealso> + of node <c>A</c> in 32-bit big endian. The flag bit + <seealso marker="#DFLAG_HANDSHAKE_23"><c>DFLAG_HANDSHAKE_23</c></seealso> + should be set if node <c>A</c> supports version 6. + <c>Name</c> is the full node name of <c>A</c>, as a string of bytes + (the packet length denotes how long it is). + </p> + <p> + The new <c>send_name</c> is only sent from nodes supporting version 6 to + nodes known to support version 6. <c>Flags</c> are the + <seealso marker="#dflags">capability flags</seealso> of node + <c>A</c> in 64-bit big endian. The flag bit + <seealso marker="#DFLAG_HANDSHAKE_23"><c>DFLAG_HANDSHAKE_23</c></seealso> + must always be set. <c>Creation</c> is the node incarnation + identifier used by node <c>A</c> to create its pids, ports and + references. <c>Name</c> is the full node name of <c>A</c>, as a + string of bytes. <c>Nlen</c> is the byte length of the node name in + 16-bit big endian. Any extra data after the node <c>Name</c> must be + accepted and ignored. + </p> </item> <tag>3) <c>recv_status</c>/<c>send_status</c></tag> <item> @@ -648,13 +721,19 @@ io:format("old/unused name ~ts at port ~p, fd = ~p ~n", node <c>B</c>. See step 3B below.</p> </item> </taglist> - <p>The format of the status message is as follows:</p> - <pre> -+---+-------+-------+-...-+-------+ -|'s'|Status0|Status1| ... |StatusN| -+---+-------+-------+-...-+-------+</pre> - <p>'s' is the message tag. 'Status0' ... 'StatusN' is the status as a - string (not terminated).</p> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">Slen</cell> + </row> + <row> + <cell align="center"><c>'s'</c></cell> + <cell align="center"><c>Status</c></cell> + </row> + <tcaption>The format of the status message</tcaption> + </table> + <p>'s' is the message tag. <c>Status</c> is the status as a + string (not null terminated).</p> </item> <tag>3B) <c>send_status</c>/<c>recv_status</c></tag> <item> @@ -670,39 +749,136 @@ io:format("old/unused name ~ts at port ~p, fd = ~p ~n", handshake continues with <c>B</c> sending <c>A</c> another message, the challenge. The challenge contains the same type of information as the "name" message initially sent from <c>A</c> to <c>B</c>, plus - a 32-bit challenge:</p> - <pre> -+---+--------+--------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-...-+-----+ -|'n'|Version0|Version1|Flag0|Flag1|Flag2|Flag3|Chal0|Chal1|Chal2|Chal3|Name0|Name1| ... |NameN| -+---+--------+--------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-... +-----+</pre> - <p>'Chal0' ... 'Chal3' is the challenge as a 32-bit big-endian integer - and the other fields are <c>B</c>'s version, flags, and full node - name.</p> + a 32-bit challenge. The challenge message can have two different + formats: + </p> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">2</cell> + <cell align="center">4</cell> + <cell align="center">4</cell> + <cell align="center">Nlen</cell> + </row> + <row> + <cell align="center"><c>'n'</c></cell> + <cell align="center"><c>Version=5</c></cell> + <cell align="center"><c>Flags</c></cell> + <cell align="center"><c>Challenge</c></cell> + <cell align="center"><c>Name</c></cell> + </row> + <tcaption>The old challenge message format (version 5)</tcaption> + </table> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">8</cell> + <cell align="center">4</cell> + <cell align="center">4</cell> + <cell align="center">2</cell> + <cell align="center">Nlen</cell> + </row> + <row> + <cell align="center"><c>'N'</c></cell> + <cell align="center"><c>Flags</c></cell> + <cell align="center"><c>Challenge</c></cell> + <cell align="center"><c>Creation</c></cell> + <cell align="center"><c>Nlen</c></cell> + <cell align="center"><c>Name</c></cell> + </row> + <tcaption>The new challenge message format (version 6)</tcaption> + </table> + <p> + The old challenge message is sent from old <c>B</c> nodes + (supporting only version 5) or if node <c>A</c> had not capability flag + <seealso marker="#DFLAG_HANDSHAKE_23"><c>DFLAG_HANDSHAKE_23</c></seealso> + set. The <c>Version</c> is a 16-bit big endian integer and + <c>must</c> always have the value 5. + </p> + <p> + The new challenge message is sent from new <c>B</c> nodes if node + <c>A</c> had capability flag <seealso marker="#DFLAG_HANDSHAKE_23"> + <c>DFLAG_HANDSHAKE_23</c></seealso> set. Any extra data after the + node <c>Name</c> must be accepted and ignored. + </p> + <p> + <c>Challenge</c> is a 32-bit big-endian integer. The other fields + are node <c>B</c>'s flags, creation and full node name, similar to + the <c>send_name</c> message. + </p> + </item> + + <tag>4B) <c>send_complement</c>/<c>recv_complement</c></tag> + <item> + <p> + The complement message, from <c>A</c> to <c>B</c>, is only sent if + node <c>A</c> initially sent an old name message and received back a + new challenge message from node <c>B</c>. It contains complementary + information missing in the initial old name message from node <c>A</c>. + </p> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">4</cell> + <cell align="center">4</cell> + </row> + <row> + <cell align="center"><c>'c'</c></cell> + <cell align="center"><c>FlagsHigh</c></cell> + <cell align="center"><c>Creation</c></cell> + </row> + <tcaption>The complement message</tcaption> + </table> + <p> + <c>FlagsHigh</c> are the high capability flags (bit 33-64) of node + <c>A</c> as a 32-bit big endian integer. <c>Creation</c> is the + incarnation identifier of node <c>A</c>. + </p> </item> + <tag>5) <c>send_challenge_reply</c>/<c>recv_challenge_reply</c></tag> <item> <p>Now <c>A</c> has generated a digest and its own challenge. Those are sent together in a package to <c>B</c>:</p> - <pre> -+---+-----+-----+-----+-----+-----+-----+-----+-----+-...-+------+ -|'r'|Chal0|Chal1|Chal2|Chal3|Dige0|Dige1|Dige2|Dige3| ... |Dige15| -+---+-----+-----+-----+-----+-----+-----+-----+-----+-...-+------+</pre> - <p>'r' is the tag. 'Chal0' ... 'Chal3' is <c>A</c>'s challenge for - <c>B</c> to handle. 'Dige0' ... 'Dige15' is the digest that <c>A</c> - constructed from the challenge <c>B</c> sent in the previous - step.</p> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">4</cell> + <cell align="center">16</cell> + </row> + <row> + <cell align="center"><c>'r'</c></cell> + <cell align="center"><c>Challenge</c></cell> + <cell align="center"><c>Digest</c></cell> + </row> + <tcaption>The challenge_reply message</tcaption> + </table> + <p> + <c>Challenge</c> is <c>A</c>'s challenge for <c>B</c> to + handle. <c>Digest</c> is the MD5 digest that <c>A</c> constructed + from the challenge <c>B</c> sent in the previous step. + </p> </item> <tag>6) <c>recv_challenge_ack</c>/<c>send_challenge_ack</c></tag> <item> <p><c>B</c> checks that the digest received from <c>A</c> is correct and generates a digest from the challenge received from <c>A</c>. The digest is then sent to <c>A</c>. The message is as follows:</p> - <pre> -+---+-----+-----+-----+-----+-...-+------+ -|'a'|Dige0|Dige1|Dige2|Dige3| ... |Dige15| -+---+-----+-----+-----+-----+-...-+------+</pre> - <p>'a' is the tag. 'Dige0' ... 'Dige15' is the digest calculated by - <c>B</c> for <c>A</c>'s challenge.</p> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">16</cell> + </row> + <row> + <cell align="center"><c>'a'</c></cell> + <cell align="center"><c>Digest</c></cell> + </row> + <tcaption>The challenge_ack message</tcaption> + </table> + <p> + <c>Digest</c> is the digest calculated by <c>B</c> for <c>A</c>'s + challenge. + </p> </item> <tag>7) check</tag> <item> @@ -728,10 +904,15 @@ recv_status (if status was 'alive' send_status - - - - - - - - - - - - - - - - - -> recv_status) - ChB = gen_challenge() - (ChB) + + (ChB) ChB = gen_challenge() <---------------------------------------------- send_challenge recv_challenge + +(if old send_name and new recv_challenge + send_complement - - - - - - - - - - - - - - - -> + recv_complement) + ChA = gen_challenge(), OCA = out_cookie(B), DiA = gen_digest(ChB, OCA) @@ -793,7 +974,8 @@ DiB == gen_digest(ChA, ICA)? </item> <tag><c>-define(DFLAG_NEW_FUN_TAGS,16#80).</c></tag> <item> - <p>The node understand new fun tags.</p> + <p>The node understands the <seealso marker="erl_ext_dist#NEW_FUN_EXT"> + <c>NEW_FUN_EXT</c></seealso> tag.</p> </item> <tag><c>-define(DFLAG_EXTENDED_PIDS_PORTS,16#100).</c></tag> <item> @@ -802,13 +984,18 @@ DiB == gen_digest(ChA, ICA)? </item> <tag><c>-define(DFLAG_EXPORT_PTR_TAG,16#200).</c></tag> <item> + <p>The node understands the <seealso marker="erl_ext_dist#EXPORT_EXT"> + <c>EXPORT_EXT</c></seealso> tag.</p> </item> <tag><c>-define(DFLAG_BIT_BINARIES,16#400).</c></tag> <item> + <p>The node understands the <seealso marker="erl_ext_dist#BIT_BINARY_EXT"> + <c>BIT_BINARY_EXT</c></seealso> tag.</p> </item> <tag><c>-define(DFLAG_NEW_FLOATS,16#800).</c></tag> <item> - <p>The node understands new float format.</p> + <p>The node understands the <seealso marker="erl_ext_dist#NEW_FLOAT_EXT"> + <c>NEW_FLOAT_EXT</c></seealso> tag.</p> </item> <tag><c>-define(DFLAG_UNICODE_IO,16#1000).</c></tag> <item> @@ -817,21 +1004,34 @@ DiB == gen_digest(ChA, ICA)? <item> <p>The node implements atom cache in distribution header.</p> </item> + <marker id="DFLAG_SMALL_ATOM_TAGS"/> <tag><c>-define(DFLAG_SMALL_ATOM_TAGS, 16#4000).</c></tag> <item> - <p>The node understand the <c>SMALL_ATOM_EXT</c> tag.</p> + <p>The node understands the <seealso marker="erl_ext_dist#SMALL_ATOM_EXT"> + <c>SMALL_ATOM_EXT</c></seealso> tag.</p> </item> + <marker id="DFLAG_UTF8_ATOMS"/> <tag><c>-define(DFLAG_UTF8_ATOMS, 16#10000).</c></tag> <item> - <p>The node understand UTF-8 encoded atoms.</p> + <p>The node understands UTF-8 atoms encoded with + <seealso marker="erl_ext_dist#ATOM_UTF8_EXT"> + <c>ATOM_UTF8_EXT</c></seealso> and + <seealso marker="erl_ext_dist#SMALL_ATOM_UTF8_EXT"> + <c>SMALL ATOM_UTF8_EXT</c></seealso>.</p> </item> <tag><c>-define(DFLAG_MAP_TAG, 16#20000).</c></tag> <item> - <p>The node understand the map tag.</p> + <p>The node understands the map tag + <seealso marker="erl_ext_dist#MAP_EXT"><c>MAP_EXT</c></seealso>.</p> </item> + <marker id="DFLAG_BIG_CREATION"/> <tag><c>-define(DFLAG_BIG_CREATION, 16#40000).</c></tag> <item> - <p>The node understand big node creation.</p> + <p>The node understands big node creation tags + <seealso marker="erl_ext_dist#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>, + <seealso marker="erl_ext_dist#NEW_PORT_EXT"><c>NEW_PORT_EXT</c></seealso> and + <seealso marker="erl_ext_dist#NEWER_REFERENCE_EXT"><c>NEWER_REFERENCE_EXT</c></seealso>. + </p> </item> <tag><c>-define(DFLAG_SEND_SENDER, 16#80000).</c></tag> <item> @@ -855,11 +1055,26 @@ DiB == gen_digest(ChA, ICA)? <seealso marker="#control_message">control message</seealso>s instead of the non-PAYLOAD variants.</p> </item> + <marker id="DFLAG_FRAGMENTS"/> <tag><c>-define(DFLAG_FRAGMENTS, 16#800000).</c></tag> <item> <p>Use <seealso marker="erl_ext_dist#fragments">fragmented</seealso> distribution messages to send large messages.</p> </item> + <marker id="DFLAG_HANDSHAKE_23"/> + <tag><c>-define(DFLAG_HANDSHAKE_23, 16#1000000).</c></tag> + <item> + <p>The node supports the new connection setup handshake (version 6) + introduced in OTP 23.</p> + </item> + <tag><marker id="DFLAG_SPAWN"/><c>-define(DFLAG_SPAWN, 16#100000000).</c></tag> + <item> + <p>Set if the <seealso marker="#SPAWN_REQUEST"><c>SPAWN_REQUEST</c></seealso>, + <seealso marker="#SPAWN_REQUEST_TT"><c>SPAWN_REQUEST_TT</c></seealso>, + <seealso marker="#SPAWN_REPLY"><c>SPAWN_REPLY</c></seealso>, + <seealso marker="#SPAWN_REPLY_TT"><c>SPAWN_REPLY_TT</c></seealso> + control messages are supported.</p> + </item> </taglist> <p> There is also function <c>dist_util:strict_order_flags/0</c> @@ -1009,12 +1224,6 @@ DiB == gen_digest(ChA, ICA)? <p><c>{8, FromPid, ToPid, Reason}</c></p> <p>This signal is sent by a call to the erlang:exit/2 bif</p> </item> - </taglist> - </section> - - <section> - <title>New Ctrlmessages for distrvsn = 1 (Erlang/OTP R4)</title> - <taglist> <tag><c>SEND_TT</c></tag> <item> <p><c>{12, Unused, ToPid, TraceToken}</c></p> @@ -1035,24 +1244,6 @@ DiB == gen_digest(ChA, ICA)? <item> <p><c>{18, FromPid, ToPid, TraceToken, Reason}</c></p> </item> - </taglist> - </section> - - <section> - <title>New Ctrlmessages for distrvsn = 2</title> - <p><c>distrvsn</c> 2 was never used.</p> - </section> - - <section> - <title>New Ctrlmessages for distrvsn = 3 (Erlang/OTP R5C)</title> - <p>None, but the version number was increased anyway.</p> - </section> - - <section> - <title>New Ctrlmessages for distrvsn = 4 (Erlang/OTP R6)</title> - <p>These are only recognized by Erlang nodes, not by hidden nodes.</p> - - <taglist> <tag><c>MONITOR_P</c></tag> <item> <p><c>{19, FromPid, ToProc, Ref}</c>, where @@ -1185,7 +1376,108 @@ DiB == gen_digest(ChA, ICA)? has been negotiated in the connection setup handshake. </p> </item> + + </taglist> + </section> + <section> + <title>New Ctrlmessages for Erlang/OTP 23</title> + <taglist> + <tag><marker id="SPAWN_REQUEST"/><c>SPAWN_REQUEST</c></tag> + <item> + <p><c>{29, ReqId, From, GroupLeader, {Module, Function, Arity}, OptList}</c></p> + <p>Followed by <c>ArgList</c>.</p> + <p>This signal is sent by the + <seealso marker="erlang#spawn_request/5"><c>spawn_request()</c></seealso> BIF.</p> + <taglist> + <tag><c>ReqId :: reference()</c></tag> + <item><p>Request identifier. Also used as monitor + reference in case the <c>monitor</c> option has been + passed.</p></item> + <tag><c>From :: pid()</c></tag> + <item><p>Process identifier of the process making the + request. That is, the parent process to be.</p></item> + <tag><c>GroupLeader :: pid()</c></tag> + <item><p>Process identifier of the group leader of the + newly created process.</p></item> + <tag><c>{Module :: atom(), Function :: atom(), Arity :: integer() >= 0}</c></tag> + <item><p>Entry point for the the new process.</p></item> + <tag><c>OptList :: [term()]</c></tag> + <item><p>A proper list of spawn options to use when spawning.</p></item> + <tag><c>ArgList :: [term()]</c></tag> + <item><p>A proper list of arguments to use in the call to the entry point.</p></item> + </taglist> + <p> + Only supported when the + <seealso marker="erl_dist_protocol#DFLAG_SPAWN"><c>DFLAG_SPAWN</c></seealso> + <seealso marker="erl_dist_protocol#dflags">distribution flag</seealso> + has been passed. + </p> + </item> + <tag><marker id="SPAWN_REQUEST_TT"/><c>SPAWN_REQUEST_TT</c></tag> + <item> + <p><c>{30, ReqId, From, GroupLeader, {Module, Function, Arity}, OptList, Token}</c></p> + <p>Followed by <c>ArgList</c>.</p> + <p>Same as <seealso marker="#SPAWN_REQUEST"><c>SPAWN_REQUEST</c></seealso>, but also + with a sequential trace <c>Token</c>. + </p> + <p> + Only supported when the + <seealso marker="erl_dist_protocol#DFLAG_SPAWN"><c>DFLAG_SPAWN</c></seealso> + <seealso marker="erl_dist_protocol#dflags">distribution flag</seealso> + has been passed. + </p> + </item> + <tag><marker id="SPAWN_REPLY"/><c>SPAWN_REPLY</c></tag> + <item> + <p><c>{31, ReqId, To, Flags, Result}</c></p> + <p>This signal is sent as a reply to a process previously sending + a <seealso marker="#SPAWN_REQUEST"><c>SPAWN_REQUEST</c></seealso> signal.</p> + <taglist> + <tag><c>ReqId :: reference()</c></tag> + <item><p>Request identifier. Also used as monitor + reference in case the <c>monitor</c> option has been + passed.</p></item> + <tag><c>To :: pid()</c></tag> + <item><p>Process identifier of the process making the + spawn request.</p></item> + <tag><c>Flags :: integer() >= 0</c></tag> + <item><p>A bit flag field of bit flags bitwise or:ed together. Currently the + following flags are defined:</p> + <taglist> + <tag><c>1</c></tag> + <item><p>A link between <c>To</c> and <c>Result</c> was set up on + the node where <c>Result</c> resides.</p></item> + <tag><c>2</c></tag> + <item><p>A monitor from <c>To</c> to <c>Result</c> was set up on + the node where <c>Result</c> resides.</p></item> + </taglist> + </item> + <tag><c>Result :: pid() | atom()</c></tag> + <item><p>Result of the operation. If <c>Result</c> is a process + identifier, the operation succeeded and the process identifier + is the identifier of the newly created process. If <c>Result</c> + is an atom, the operation failed and the atom identifies failure + reason.</p></item> + </taglist> + <p> + Only supported when the + <seealso marker="erl_dist_protocol#DFLAG_SPAWN"><c>DFLAG_SPAWN</c></seealso> + <seealso marker="erl_dist_protocol#dflags">distribution flag</seealso> + has been passed. + </p> + </item> + <tag><marker id="SPAWN_REPLY_TT"/><c>SPAWN_REPLY_TT</c></tag> + <item> + <p><c>{32, ReqId, To, Flags, Result, Token}</c></p> + <p>Same as <seealso marker="#SPAWN_REPLY"><c>SPAWN_REPLY</c></seealso>, but also + with a sequential trace <c>Token</c>.</p> + <p> + Only supported when the + <seealso marker="erl_dist_protocol#DFLAG_SPAWN"><c>DFLAG_SPAWN</c></seealso> + <seealso marker="erl_dist_protocol#dflags">distribution flag</seealso> + has been passed. + </p> + </item> </taglist> </section> - </chapter> diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index 2ba5994557..c5b2ce1a0a 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -264,7 +264,7 @@ consists of. Length is a 2 byte big-endian integer if flag <c>LongAtoms</c> has been set, otherwise a 1 byte integer. When distribution flag - <seealso marker="erl_dist_protocol#dflags"> + <seealso marker="erl_dist_protocol#DFLAG_UTF8_ATOMS"> <c>DFLAG_UTF8_ATOMS</c></seealso> has been exchanged between both nodes in the <seealso marker="erl_dist_protocol#distribution_handshake"> @@ -316,8 +316,8 @@ </p> <p>Fragmented distribution messages are only used if the receiving node signals that it supports them via the - <seealso marker="erl_dist_protocol#dflags">DFLAG_FRAGMENTS</seealso> distribution - flag.</p> + <seealso marker="erl_dist_protocol#DFLAG_FRAGMENTS">DFLAG_FRAGMENTS</seealso> + distribution flag.</p> <p>A process must complete the sending of a fragmented message before it can start sending any other message on the same distribution channel.</p> @@ -637,11 +637,14 @@ <seealso marker="#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>. Port operations are not allowed across node boundaries. </p> - <p>Introduced in OTP 19, but only to be decoded and echoed back. Not - encoded for local ports. Planned to supersede <seealso marker="#PORT_EXT"> - <c>PORT_EXT</c></seealso> in OTP 23 when - <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_BIG_CREATON</c></seealso> - becomes mandatory. + <p><c>NEW_PORT_EXT</c> was introduced in OTP 19, but only to be decoded + and echoed back. Not encoded for local ports. + </p> + <p>In OTP 23 distribution flag + <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso> + became mandatory. All ports are now + encoded using <c>NEW_PORT_EXT</c>, even external ports received as <seealso + marker="#PORT_EXT"><c>PORT_EXT</c></seealso> from older nodes. </p> </section> @@ -719,11 +722,14 @@ erlang:list_to_pid/1</seealso>).</p> </item> </taglist> - <p>Introduced in OTP 19, but only to be decoded and echoed back. Not - encoded for local processes. Planned to supersede <seealso marker="#PID_EXT"> - <c>PID_EXT</c></seealso> in OTP 23 when - <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_BIG_CREATON</c></seealso> - becomes mandatory. + <p><c>NEW_PID_EXT</c> was introduced in OTP 19, but only to be decoded + and echoed back. Not encoded for local processes. + </p> + <p>In OTP 23 distribution flag + <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso> + became mandatory. All pids are now encoded using <c>NEW_PID_EXT</c>, + even external pids received as + <seealso marker="#PID_EXT"><c>PID_EXT</c></seealso> from older nodes. </p> </section> @@ -1047,11 +1053,15 @@ <seealso marker="#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>.</p> </item> </taglist> - <p>Introduced in OTP 19, but only to be decoded and echoed back. Not - encoded for local references. Planned to supersede <seealso marker="#NEW_REFERENCE_EXT"> - <c>NEW_REFERENCE_EXT</c></seealso> in OTP 23 when - <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_BIG_CREATON</c></seealso> - becomes mandatory. + <p><c>NEWER_REFERENCE_EXT</c> was introduced in OTP 19, but only to be decoded + and echoed back. Not encoded for local references. + </p> + <p>In OTP 23 distribution flag + <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso> + became mandatory. All references are now encoded using + <c>NEWER_REFERENCE_EXT</c>, even external references received as + <seealso marker="#NEW_REFERENCE_EXT"><c>NEW_REFERENCE_EXT</c></seealso> + from older nodes. </p> </section> @@ -1408,7 +1418,7 @@ <p> <c>SMALL_ATOM_EXT</c> was introduced in ERTS 5.7.2 and require an exchange of distribution flag - <seealso marker="erl_dist_protocol#dflags"> + <seealso marker="erl_dist_protocol#DFLAG_SMALL_ATOM_TAGS"> <c>DFLAG_SMALL_ATOM_TAGS</c></seealso> in the <seealso marker="erl_dist_protocol#distribution_handshake"> distribution handshake</seealso>. diff --git a/erts/doc/src/erl_ext_fig.gif b/erts/doc/src/erl_ext_fig.gif Binary files differindex 14d6bbc871..40dd17bd5e 100644 --- a/erts/doc/src/erl_ext_fig.gif +++ b/erts/doc/src/erl_ext_fig.gif diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 2f3d2f9624..7c8591f719 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -60,6 +60,13 @@ </desc> </datatype> <datatype> + <name name="ext_iovec"/> + <desc> + <p>A term of type <seealso marker="#type-iovec"><c>iovec()</c></seealso>, + structured according to the Erlang external term format.</p> + </desc> + </datatype> + <datatype> <name name="iovec"/> <desc> <p>A list of binaries. This datatype is useful to use @@ -205,6 +212,37 @@ </seealso>.</p> </desc> </datatype> + <datatype> + <name name="spawn_opt_option"></name> + <desc> + <p>Options for <seealso marker="#spawn_opt/4"><c>spawn_opt()</c></seealso>.</p> + </desc> + </datatype> + <datatype> + <name name="priority_level"></name> + <desc> + <p>Process priority level. For more info see + <seealso marker="#process_flag_priority"><c>process_flag(priority, + Level)</c></seealso> </p> + </desc> + </datatype> + <datatype> + <name name="max_heap_size"></name> + <desc> + <p>Process max heap size configuration. For more info see + <seealso marker="#process_flag_max_heap_size"><c>process_flag(max_heap_size, + MaxHeapSize)</c></seealso> </p> + </desc> + </datatype> + <datatype> + <name name="message_queue_data"></name> + <desc> + <p>Process message queue data configuration. For more info see + <seealso marker="#process_flag_message_queue_data"><c>process_flag(message_queue_data, + MQD)</c></seealso> </p> + </desc> + </datatype> + </datatypes> @@ -337,6 +375,16 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> + <name name="atom_to_binary" arity="1" since="OTP @OTP-15995@"/> + <fsummary>Return the binary representation of an atom.</fsummary> + <desc> + <p> + The same as <seealso marker="#atom_to_binary/2"><c>atom_to_binary</c> + </seealso><c>(<anno>Atom</anno>, utf8)</c>.</p> + </desc> + </func> + + <func> <name name="atom_to_binary" arity="2" since=""/> <fsummary>Return the binary representation of an atom.</fsummary> <desc> @@ -409,14 +457,21 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> + <name name="binary_to_atom" arity="1" since="OTP @OTP-15995@"/> + <fsummary>Convert from text representation to an atom.</fsummary> + <desc> + <p> + The same as <seealso marker="#binary_to_atom/2"><c>binary_to_atom</c> + </seealso><c>(<anno>Binary</anno>, utf8)</c>.</p> + </desc> + </func> + + <func> <name name="binary_to_atom" arity="2" since=""/> <fsummary>Convert from text representation to an atom.</fsummary> <desc> <p>Returns the atom whose text representation is - <c><anno>Binary</anno></c>. - If <c><anno>Encoding</anno></c> is <c>latin1</c>, no - translation of bytes in the binary is done. - If <c><anno>Encoding</anno></c> + <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> @@ -438,6 +493,17 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> + <name name="binary_to_existing_atom" arity="1" since="OTP @OTP-15995@"/> + <fsummary>Convert from text representation to an atom.</fsummary> + <desc> + <p> + The same as <seealso marker="#binary_to_existing_atom/2"> + <c>binary_to_existing_atom</c></seealso> + <c>(<anno>Binary</anno>, utf8)</c>.</p> + </desc> + </func> + + <func> <name name="binary_to_existing_atom" arity="2" since=""/> <fsummary>Convert from text representation to an atom.</fsummary> <desc> @@ -1045,7 +1111,9 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> as atoms. Others are returned as strings. Strings of unrecognized header fields are formatted with only capital letters first and after hyphen characters, for - example, <c>"Sec-Websocket-Key"</c>.</p> + example, <c>"Sec-Websocket-Key"</c>. Header field names + are also returned in <c><anno>UnmodifiedField</anno></c> + as strings, without any conversion or formatting.</p> <p>The protocol type <c>http</c> is only to be used for the first line when an <c><anno>HttpRequest</anno></c> or an <c><anno>HttpResponse</anno></c> is expected. @@ -1270,9 +1338,10 @@ end</code> <seealso marker="erlang#dist_ctrl_get_data_notification/1"><c>erlang:dist_ctrl_get_data_notification(DHandle)</c></seealso>. </p> <p>The returned value when there are data available depends - on the value of the <c>get_size</c> option configured on the - distribution channel identified by <c><anno>DHandle</anno></c>. - For more information see the documentation of the <c>get_size</c> + on the value of the <c>get_size</c> + option configured on the distribution channel identified + by <c><anno>DHandle</anno></c>. For more information see + the documentation of the <c>get_size</c> option for the <seealso marker="#dist_ctrl_set_opt/3"><c>erlang:dist_ctrl_set_opt/3</c></seealso> function.</p> @@ -1839,7 +1908,7 @@ true</pre> <p>It might point to the <c>init</c> process if the <c>Fun</c> was statically allocated when module was loaded (this optimisation is performed for local - functions that do not capture the enviornment).</p> + functions that do not capture the environment).</p> </item> <tag><c>{index, Index}</c></tag> <item> @@ -2082,8 +2151,9 @@ true</pre> <fsummary>Get the call stack back-trace of the last exception.</fsummary> <type name="stack_item"/> <desc> - <warning><p><c>erlang:get_stacktrace/0</c> is deprecated and will stop working - in a future release.</p></warning> + <warning><p><c>erlang:get_stacktrace/0</c> is deprecated and + will be removed in OTP 24. Starting from OTP 23, + <c>erlang:get_stacktrace/0</c> returns <c>[]</c>.</p></warning> <p>Instead of using <c>erlang:get_stacktrace/0</c> to retrieve the call stack back-trace, use the following syntax:</p> <pre> @@ -2092,53 +2162,6 @@ catch Class:Reason:Stacktrace -> {Class,Reason,Stacktrace} end</pre> - <p><c>erlang:get_stacktrace/0</c> retrieves the call stack back-trace - (<em>stacktrace</em>) for an exception that has just been - caught in the calling process as a list of - <c>{<anno>Module</anno>,<anno>Function</anno>,<anno>Arity</anno>,<anno>Location</anno>}</c> - tuples. Field <c><anno>Arity</anno></c> in the first tuple can - be the argument list of that function call instead of an arity - integer, depending on the exception.</p> - <p>If there has not been any exceptions in a process, the - stacktrace is <c>[]</c>. After a code change for the process, - the stacktrace can also be reset to <c>[]</c>.</p> - <p>The stacktrace is the same data as operator <c>catch</c> - returns, for example:</p> - <pre> -{'EXIT',{badarg,Stacktrace}} = catch abs(x)</pre> - <p><c><anno>Location</anno></c> is a (possibly empty) list - of two-tuples that - can indicate the location in the source code of the function. - The first element is an atom describing the type of - information in the second element. The following - items can occur:</p> - <taglist> - <tag><c>file</c></tag> - <item>The second element of the tuple is a string (list of - characters) representing the filename of the source file - of the function. - </item> - <tag><c>line</c></tag> - <item>The second element of the tuple is the line number - (an integer > 0) in the source file - where the exception occurred or the function was called. - </item> - </taglist> - <warning><p>Developers should rely on stacktrace entries only for - debugging purposes.</p> - <p>The VM performs tail call optimization, which - does not add new entries to the stacktrace, and also limits stacktraces - to a certain depth. Furthermore, compiler options, optimizations and - future changes may add or remove stacktrace entries, causing any code - that expects the stacktrace to be in a certain order or contain specific - items to fail.</p> - <p>The only exception to this rule is <c>error:undef</c> which - guarantees to include the <anno>Module</anno>, <anno>Function</anno> and <anno>Arity</anno> - of the attempted function as the first stacktrace entry.</p> - </warning> - <p>See also - <seealso marker="#error/1"><c>error/1</c></seealso> and - <seealso marker="#error/2"><c>error/2</c></seealso>.</p> </desc> </func> @@ -2675,26 +2698,37 @@ false</code> <name name="link" arity="1" since=""/> <fsummary>Create a link to another process (or port).</fsummary> <desc> - <p>Creates a link between the calling process and another - process (or port) <c><anno>PidOrPort</anno></c>, if there is - not such a link - already. If a process attempts to create a link to itself, - nothing is done. Returns <c>true</c>.</p> - <p>If <c><anno>PidOrPort</anno></c> does not exist, the behavior - of the BIF - depends on if the calling process is trapping exits or not (see - <seealso marker="#process_flag/2"> - <c>process_flag/2</c></seealso>):</p> + + <p>Creates a link between the calling process and another process (or + port) <c><anno>PidOrPort</anno></c>. If the link already exists or a + process attempts to create a link to itself, nothing is done. Returns + <c>true</c> if the link is set up.</p> + + <p>If <c><anno>PidOrPort</anno></c> does not exist and checking it is + cheap, a <c>noproc</c> error is raised. Currently, checking is cheap + if the <c><anno>PidOrPort</anno></c> is local and the caller does not + trap exits (see <seealso marker="#process_flag/2"><c>process_flag/2 + </c></seealso>).</p> + + <p>Apart from any exit signals from the linked process itself, two + special exit signals may be sent to the calling process:</p> + <list type="bulleted"> - <item><p>If the calling process is not trapping exits, and - checking <c><anno>PidOrPort</anno></c> is cheap - (that is, if <c><anno>PidOrPort</anno></c> - is local), <c>link/1</c> fails with reason <c>noproc</c>.</p></item> - <item><p>Otherwise, if the calling process is trapping exits, - and/or <c><anno>PidOrPort</anno></c> is remote, <c>link/1</c> - returns <c>true</c>, but an exit signal with reason <c>noproc</c> - is sent to the calling process.</p></item> + + <item><p><c>noproc</c> is sent immediately if + <c><anno>PidOrPort</anno></c> does not exist at the time of linking + (if the caller is trapping exits or <c><anno>PidOrPort</anno></c> is + remote).</p></item> + + <item><p><c>noconnection</c> if <c><anno>PidOrPort</anno></c> is + remote and a connection between the nodes could not be established + or was severed.</p></item> + </list> + + <p>See <seealso marker="doc/reference_manual:processes#links">Processes + âžœ Links</seealso> in the Erlang Reference Manual for more details.</p> + </desc> </func> @@ -5383,12 +5417,13 @@ RealSystem = system + MissedSystem</code> </item> <tag><c>{current_stacktrace, <anno>Stack</anno>}</c></tag> <item> - <p>Returns the current call stack back-trace (<em>stacktrace</em>) - of the process. The stack has the same format as returned by - <seealso marker="#get_stacktrace/0"> - <c>erlang:get_stacktrace/0</c></seealso>. The depth of the - stacktrace is truncated according to the <c>backtrace_depth</c> - system flag setting.</p> + <p>Returns the current call stack back-trace + (<em>stacktrace</em>) of the process. The stack has the + same format as in the <c>catch</c> part of a + <c>try</c>. See <seealso + marker="doc/reference_manual:errors#stacktrace">The call-stack back trace (stacktrace)</seealso>. + The depth of the stacktrace is truncated according to the + <c>backtrace_depth</c> system flag setting.</p> </item> <tag><c>{dictionary, <anno>Dictionary</anno>}</c></tag> <item> @@ -6280,6 +6315,23 @@ true</pre> </func> <func> + <name name="spawn_monitor" arity="2" since="OTP @OTP-15251@"/> + <fsummary>Create and monitor a new process with a fun as entry point. + </fsummary> + <desc> + <p>Returns the process identifier of a new process, started by + the application of <c><anno>Fun</anno></c> to the empty list + <c>[]</c> on the node <c><anno>Node</anno></c>, + and a reference for a monitor created to the new process. + Otherwise works like + <seealso marker="#spawn/3"><c>spawn/3</c></seealso>.</p> + <p>If the node identified by <c><anno>Node</anno></c> does not + support distributed <c>spawn_monitor()</c>, the call will fail + with a <c>notsup</c> exception.</p> + </desc> + </func> + + <func> <name name="spawn_monitor" arity="3" since=""/> <fsummary>Create and monitor a new process with a function as entry point. </fsummary> @@ -6294,6 +6346,23 @@ true</pre> </func> <func> + <name name="spawn_monitor" arity="4" since="OTP @OTP-15251@"/> + <fsummary>Create and monitor a new process with a function as entry point. + </fsummary> + <desc> + <p>A new process is started by the application + of <c><anno>Module</anno>:<anno>Function</anno></c> + to <c><anno>Args</anno></c> on the node <c><anno>Node</anno></c>. + The process is monitored at the same time. Returns the process + identifier and a reference for the monitor. Otherwise works like + <seealso marker="#spawn/3"><c>spawn/3</c></seealso>.</p> + <p>If the node identified by <c><anno>Node</anno></c> does not + support distributed <c>spawn_monitor()</c>, the call will fail + with a <c>notsup</c> exception.</p> + </desc> + </func> + + <func> <name name="spawn_opt" arity="2" since=""/> <fsummary>Create a new process with a fun as entry point.</fsummary> <type name="priority_level"/> @@ -6315,17 +6384,22 @@ true</pre> <name name="spawn_opt" arity="3" since=""/> <fsummary>Create a new process with a fun as entry point on a specified node.</fsummary> - <type name="priority_level"/> - <type name="max_heap_size"/> - <type name="message_queue_data"/> - <type name="spawn_opt_option"/> <desc> <p>Returns the process identifier (pid) of a new process started by the application of <c><anno>Fun</anno></c> to the empty list <c>[]</c> on <c><anno>Node</anno></c>. If <c><anno>Node</anno></c> does not exist, a useless pid is returned. Otherwise works like - <seealso marker="#spawn_opt/4"><c>spawn_opt/4</c></seealso>.</p> + <seealso marker="#spawn_opt/4"><c>spawn_opt/4</c></seealso>.</p> + <p> + Valid options depends on what options are + supported by the node identified by + <c><anno>Node</anno></c>. A description of + valid <c>Option</c>s for the local node + of current OTP version can be found in the + documentation of + <seealso marker="#spawn_opt/4"><c>spawn_opt/4</c></seealso>. + </p> </desc> </func> @@ -6469,10 +6543,6 @@ true</pre> <name name="spawn_opt" arity="5" since=""/> <fsummary>Create a new process with a function as entry point on a specified node.</fsummary> - <type name="priority_level"/> - <type name="max_heap_size"/> - <type name="message_queue_data"/> - <type name="spawn_opt_option"/> <desc> <p>Returns the process identifier (pid) of a new process started by the application @@ -6480,15 +6550,417 @@ true</pre> <c><anno>Args</anno></c> on <c><anno>Node</anno></c>. If <c><anno>Node</anno></c> does not exist, a useless pid is returned. Otherwise works like - <seealso marker="#spawn_opt/4"><c>spawn_opt/4</c></seealso>.</p> - <note> - <p>Option <c>monitor</c> is not supported by - <c>spawn_opt/5</c>.</p> - </note> + <seealso marker="#spawn_opt/4"><c>spawn_opt/4</c></seealso>.</p> + <p> + Valid options depends on what options are + supported by the node identified by + <c><anno>Node</anno></c>. A description of + valid <c>Option</c>s for the local node + of current OTP version can be found in the + documentation of + <seealso marker="#spawn_opt/4"><c>spawn_opt/4</c></seealso>. + </p> + </desc> + </func> + + <func> + <name name="spawn_request" arity="1" since="OTP @OTP-15251@"/> + <fsummary>Asynchronously send a request to spawn a new process.</fsummary> + <desc> + <p> + The same as the call + <seealso marker="#spawn_request/3"><c>spawn_request(node(),<anno>Fun</anno>,[])</c></seealso>. + That is, a spawn request on the local node with no options. + </p> + </desc> + </func> + + <func> + <name name="spawn_request" arity="2" clause_i="1" since="OTP @OTP-15251@"/> + <fsummary>Asynchronously send a request to spawn a new process.</fsummary> + <desc> + <p> + The same as the call + <seealso marker="#spawn_request/3"><c>spawn_request(node(),<anno>Fun</anno>,<anno>Options</anno>)</c></seealso>. + That is, a spawn request on the local node. + </p> </desc> </func> <func> + <name name="spawn_request" arity="2" clause_i="2" since="OTP @OTP-15251@"/> + <fsummary>Asynchronously send a request to spawn a new process.</fsummary> + <desc> + <p> + The same as the call + <seealso marker="#spawn_request/3"><c>spawn_request(<anno>Node</anno>,<anno>Fun</anno>,[])</c></seealso>. + That is, a spawn request with no options. + </p> + </desc> + </func> + + <func> + <name name="spawn_request" arity="3" clause_i="1" since="OTP @OTP-15251@"/> + <fsummary>Asynchronously send a request to spawn a new process.</fsummary> + <desc> + <p> + The same as + <seealso marker="#spawn_request/5"><c>spawn_request(<anno>Node</anno>,erlang,apply,[<anno>Fun</anno>,[]],<anno>Options</anno>)</c></seealso>. + That is, a spawn request using the fun <c><anno>Fun</anno></c> of + arity zero as entry point. + </p> + <p>This function will fail with a <c>badarg</c> exception if:</p> + <list> + <item><p><c><anno>Node</anno></c> is not a valid + node name atom.</p></item> + <item><p><c><anno>Fun</anno></c> is not a fun of arity zero.</p></item> + <item><p><c><anno>Options</anno></c> is not a proper list + of terms.</p></item> + </list> + </desc> + </func> + + <func> + <name name="spawn_request" arity="3" clause_i="2" since="OTP @OTP-15251@"/> + <fsummary>Asynchronously send a request to spawn a new process.</fsummary> + <desc> + <p> + The same as the call + <seealso marker="#spawn_request/5"><c>spawn_request(node(),<anno>Module</anno>,<anno>Function</anno>,<anno>Args</anno>,[])</c></seealso>. + That is, a spawn request on the local node with no options. + </p> + </desc> + </func> + + <func> + <name name="spawn_request" arity="4" clause_i="1" since="OTP @OTP-15251@"/> + <fsummary>Asynchronously send a request to spawn a new process.</fsummary> + <desc> + <p> + The same as the call + <seealso marker="#spawn_request/5"><c>spawn_request(<anno>Node</anno>,<anno>Module</anno>,<anno>Function</anno>,<anno>Args</anno>,[])</c></seealso>. + That is, a spawn request with no options. + </p> + </desc> + </func> + + <func> + <name name="spawn_request" arity="4" clause_i="2" since="OTP @OTP-15251@"/> + <fsummary>Asynchronously send a request to spawn a new process.</fsummary> + <desc> + <p> + The same as the call + <seealso marker="#spawn_request/5"><c>spawn_request(node(),<anno>Module</anno>,<anno>Function</anno>,<anno>Args</anno>,<anno>Options</anno>)</c></seealso>. + That is, a spawn request on the local node. + </p> + </desc> + </func> + + <func> + <name name="spawn_request" arity="5" since="OTP @OTP-15251@"/> + <fsummary>Asynchronously send a request to spawn a new process.</fsummary> + <desc> + <p> + Asynchronously send a spawn request. Returns a request + identifier <c><anno>ReqId</anno></c>. + </p> + + <marker id="spawn_request_success_message"/> + <p> + If the spawn operation succeeds, a new process is + created on the node identified by <c><anno>Node</anno></c>. + When a spawn operation succeeds, the caller will by + default be sent a message on the form + <c>{<anno>ReplyTag</anno>, <anno>ReqId</anno>, ok, Pid}</c> + where <c>Pid</c> is the process identifier of the + newly created process. Such a message is referred to as a + <i>success message</i> below in the text. + <c><anno>ReplyTag</anno></c> is by default the atom + <c>spawn_reply</c> unless modified by + the <c>{reply_tag, <anno>ReplyTag</anno>}</c> option. The + new process is started by the application of + <c><anno>Module</anno>:<anno>Function</anno></c> + to <c><anno>Args</anno></c>. + </p> + + <marker id="spawn_request_error_message"/> + <p>The spawn operation fails either if creation of a new process + failed or if the spawn operation was interrupted by a connection + failure. When a spawn operation fails, the caller will by default + be sent a message on the form + <c>{<anno>ReplyTag</anno>, <anno>ReqId</anno>, error, Reason}</c> + where <c>Reason</c> is the error reason. Such a message is + referred to as an <i>error message</i> below in the text. + Currently the following spawn error <c>Reason</c>s are defined, + but other reasons can appear at any time without prior notice:</p> + <taglist> + <tag><c>badopt</c></tag> + <item> + <p> + An invalid <c><anno>Option</anno></c> was passed as + argument. Note that different runtime systems may + support different options. + </p> + </item> + <tag><c>notsup</c></tag> + <item> + <p> + The node identified by <c><anno>Node</anno></c> does + not support spawn operations issued by + <c>spawn_request()</c>. + </p> + </item> + <tag><c>noconnection</c></tag> + <item> + <p> + Failure to set up a connection to the node + identified by <c><anno>Node</anno></c> or + the connection to that node was lost during + the spawn operation. In the case the + connection was lost, a process may or may + not have been created. + </p> + </item> + <tag><c>system_limit</c></tag> + <item> + <p> + Could not create a new process due to that some + system limit was reached. Typically the process table + was full. + </p> + </item> + </taglist> + <p>Valid <c><anno>Option</anno></c>s:</p> + <taglist> + <tag><c>monitor</c></tag> + <item> + <p> + In the absence of spawn operation failures, atomically + sets up a monitor to the newly created process. That + is, as if the calling process had called + <seealso marker="#monitor/2"><c>monitor(process, Pid)</c></seealso> + where <c>Pid</c> is the process identifier of the + newly created process. The <c><anno>ReqId</anno></c> + returned by <c>spawn_request()</c> is also used as + monitor reference as if it was returned from + <c>monitor(process, Pid)</c>. + </p> + <p> + The monitor will not be activated for the calling + process until the spawn operation has succeeded. + The monitor can not be + <seealso marker="#demonitor/1">demonitored</seealso> + before the operation has succeeded. A <c>'DOWN'</c> + message for the corresponding monitor is guaranteed + not to be delivered before a + <seealso marker="#spawn_request_success_message"><i>success + message</i></seealso> that corresponds to the spawn + operation. If the spawn operation fails, no + <c>'DOWN'</c> message will be delivered. + </p> + <p> + If the connection between the nodes involved in + the spawn operation is lost during the spawn + operation, the spawn operation will fail with an + error reason of <c>noconnection</c>. A new process + may or may not have been created. + </p> + </item> + <tag><c>link</c></tag> + <item> + <p> + In absence of spawn operation failures, atomically + sets up a link between the calling process and the + newly created process. That is, as if the calling + process had called + <seealso marker="#link/1"><c>link(Pid)</c></seealso> + where <c>Pid</c> is the process identifier of the + newly created process. + </p> + <p> + The link will not be activated for the calling + process until the spawn operation has succeeded. + The link can not be removed before the operation + has succeeded. An exit signal due to the link is + guaranteed not to be delivered before a + <seealso marker="#spawn_request_success_message"><i>success + message</i></seealso> that corresponds to the spawn + operation. If the spawn operation fails, no + exit signal due to the link will be delivered to + the caller of <c>spawn_request()</c>. + </p> + <p> + If the connection between the nodes involved in + the spawn operation is lost during the spawn + operation, the spawn operation will fail with + an error reason of <c>noconnection</c>. A new + process may or may not have been created. If it + has been created, it will be delivered an exit + signal with an exit reason of <c>noconnection</c>. + </p> + </item> + <tag><c>{reply, <anno>Reply</anno>}</c></tag> + <item> + <p>Valid <c>Reply</c> values:</p> + <taglist> + <tag><c>yes</c></tag> + <item><p> + A spawn reply message will be sent to the caller + regardless of whether the operation succeeds or + not. If the call to <c>spawn_request()</c> returns + without raising an exception and the <c>reply</c> + option is set to <c>yes</c>, the caller is + guaranteed to be delivered either a + <seealso marker="#spawn_request_success_message"><i>success + message</i></seealso> or an + <seealso marker="#spawn_request_error_message"><i>error + message</i></seealso>. The <c>reply</c> option is by + default set to <c>yes</c>. + </p></item> + <tag><c>no</c></tag> + <item><p> + No spawn reply message will be sent to the caller + when the spawn operation completes. This regardless of + whether the operation succeeds or not. + </p></item> + <tag><c>error_only</c></tag> + <item><p> + No spawn reply message will be sent to the caller + if the spawn operation succeeds, but an + <seealso marker="#spawn_request_error_message"><i>error + message</i></seealso> will be sent to the caller + if the operation fails. + </p></item> + <tag><c>success_only</c></tag> + <item><p> + No spawn reply message will be sent to the caller + if the spawn operation fails, but a + <seealso marker="#spawn_request_success_message"><i>success + message</i></seealso> will be sent to the caller + if the operation succeeds. + </p></item> + </taglist> + </item> + <tag><c>{reply_tag, <anno>ReplyTag</anno>}</c></tag> + <item> + <p> + Sets the reply tag to <c><anno>ReplyTag</anno></c> in + the reply message. That is, in the + <seealso marker="#spawn_request_success_message"><i>success</i></seealso> + or <seealso marker="#spawn_request_error_message"><i>error</i></seealso> + message that is sent to the caller due to the + spawn operation. The default reply tag is the atom + <c>spawn_reply</c>. + </p> + </item> + <tag><c><anno>OtherOption</anno></c></tag> + <item> + <p> + Other valid options depends on what options are + supported by the node identified by + <c><anno>Node</anno></c>. A description of other + valid <c><anno>Option</anno></c>s for the local node + of current OTP version can be found in the + documentation of + <seealso marker="#spawn_opt/4"><c>spawn_opt/4</c></seealso>. + </p> + </item> + </taglist> + <p>This function will fail with a <c>badarg</c> exception if: + </p> + <list> + <item><p><c><anno>Node</anno></c> is not a valid + node name atom.</p></item> + <item><p><c><anno>Module</anno></c> is not an atom.</p></item> + <item><p><c><anno>Function</anno></c> is not an atom.</p></item> + <item><p><c><anno>Args</anno></c> is not a proper list + of terms.</p></item> + <item><p><c><anno>Options</anno></c> is not a proper list + of terms.</p></item> + </list> + <p> + Note that not all individual <c><anno>Option</anno></c>s + are checked when the spawn request is sent. Some + <c><anno>Option</anno></c>s can only be checked on + reception of the request. Therefore an invalid option + does <em>not</em> cause a <c>badarg</c> exception, but + will cause the spawn operation to fail with an error + reason of <c>badopt</c>. + </p> + <p> + A spawn request can be abandoned by calling + <seealso marker="#spawn_request_abandon/1"><c>spawn_request_abandon/1</c></seealso>. + </p> + </desc> + </func> + + <func> + <name name="spawn_request_abandon" arity="1" since="OTP @OTP-15251@"/> + <fsummary>Abandon a previously issued spawn request.</fsummary> + <desc> + <p> + Abandon a previously issued spawn request. <c><anno>ReqId</anno></c> + corresponds to a request identifier previously returned by + <seealso marker="#spawn_request/5"><c>spawn_request()</c></seealso> + in a call from current process. That is, only the process that + has made the request can abandon the request. + </p> + <p> + A spawn request can only be successfully abandoned until the + spawn request has completed. When a spawn request has been + successfully abandoned, the caller will not be effected by + future direct effects of the spawn request itself. + For example, it will not receive a spawn reply message. The + request is however not withdrawn, so a new process may or may + not be created due to the request. If a new process is created + after the spawn request was abandoned, no monitors nor links + will be set up to the caller of <c>spawn_request_abandon/1</c> + due to the spawn request. If the spawn request included the + <c>link</c> option, the process created due to this request + will be sent an exit signal from its parent with the exit + reason <c>abandoned</c> when it is detected that the + spawn operation has succeeded. + </p> + <note><p> + A process created due to a spawn request that has been + abandoned may communicate with its parent as any other + process. It is <em>only</em> the direct effects on the + parent of the actual spawn request, that will be canceled + by abandoning a spawn request. + </p></note> + <p>Return values:</p> + <taglist> + <tag><c>true</c></tag> + <item><p> + The spawn request was successfully abandoned. + </p></item> + <tag><c>false</c></tag> + <item><p> + No spawn request was abandoned. The <c><anno>ReqId</anno></c> + request identifier did not correspond to an outstanding + spawn request issued by the calling process. The reason for + this is either:</p> + <list> + <item><p> + <c><anno>ReqId</anno></c> corresponds to a spawn request + previoulsy made by the calling process. The spawn operation + has completed and a spawn reply has already been delivered + to the calling process unless the spawn reply was disabled + in the request. + </p></item> + <item><p> + <c><anno>ReqId</anno></c> does not correspond to a spawn + request that has been made by the calling process. + </p></item> + </list> + </item> + </taglist> + <p>This function fail with a <c>badarg</c> exception if + <c><anno>ReqId</anno></c> is not a reference.</p> + </desc> + </func> + + <func> <name name="split_binary" arity="2" since=""/> <fsummary>Split a binary into two.</fsummary> <type_desc variable="Pos">0..byte_size(Bin)</type_desc> @@ -7799,7 +8271,7 @@ Metadata = #{ pid => pid(), </func> <func> - <name name="system_info" arity="1" clause_i="76" since=""/> + <name name="system_info" arity="1" clause_i="77" since=""/> <fsummary>System info overview.</fsummary> <desc> <p>Returns information about the current system. @@ -8218,6 +8690,15 @@ Metadata = #{ pid => pid(), <seealso marker="#system_info_logical_processors">logical processors configured</seealso>.</p> </item> + <tag><marker id="system_info_cpu_quota"/> + <c>cpu_quota</c></tag> + <item> + <p>Returns the detected CPU quota the emulator is limited by. The + return value is an integer saying how many processors' worth of + runtime we get (between 1 and the number of logical processors), + or the atom <c>unknown</c> if the emulator cannot detect a + quota.</p> + </item> <tag><marker id="system_info_update_cpu_info"/> <c>update_cpu_info</c></tag> <item> @@ -8227,8 +8708,9 @@ Metadata = #{ pid => pid(), CPU topology</seealso> and the number of logical processors <seealso marker="#system_info_logical_processors">configured</seealso>, <seealso marker="#system_info_logical_processors_online">online</seealso>, - and <seealso marker="#system_info_logical_processors_available"> - available</seealso>.</p> + <seealso marker="#system_info_logical_processors_available">available</seealso>, + and <seealso marker="#system_info_cpu_quota">cpu + quota</seealso>.</p> <p>If the CPU information has changed since the last time it was read, the atom <c>changed</c> is returned, otherwise the atom <c>unchanged</c>. If the CPU information has changed, @@ -9120,6 +9602,7 @@ Metadata = #{ pid => pid(), <name name="system_info" arity="1" clause_i="75" since=""/> <!-- version --> <name name="system_info" arity="1" clause_i="76" since=""/> <!-- wordsize --> <!-- <name name="system_info" arity="1" clause_i="77"/> overview --> + <!-- When adding any entry, make sure to update the overview clause_i --> <fsummary>Information about the system.</fsummary> <desc> <marker id="system_info_misc_tags"/> @@ -9672,7 +10155,7 @@ hello <func> <name name="term_to_binary" arity="2" since=""/> - <fsummary>Encode a term to en Erlang external term format binary. + <fsummary>Encode a term to an Erlang external term format binary. </fsummary> <desc> <p>Returns a binary data object that is the result of encoding @@ -9736,6 +10219,59 @@ hello </func> <func> + <name name="term_to_iovec" arity="1" since="OTP @OTP-15618@"/> + <fsummary>Encode a term to an Erlang external term format as iovec(). + </fsummary> + <desc> + <p>Returns the encoding of <c><anno>Term</anno></c> according to + the Erlang external term format as + <seealso marker="#type-ext_iovec"><c>ext_iovec()</c></seealso>.</p> + + <p>This function produce the same encoding as + <seealso marker="#term_to_binary/1"><c>term_to_binary/1</c></seealso>, + but with another return type. The call + <c>iolist_to_binary(term_to_iovec(Term))</c> will produce + exactly the same result as the call <c>term_to_binary(Term)</c>.</p> + + <p><c>term_to_iovec()</c> is a pure optimization of the functionality + <c>term_to_binary()</c> provide. <c>term_to_iovec()</c> can for example + refer directly to off heap binaries instead of copying the binary + data into the result.</p> + + <p>See also + <seealso marker="#term_to_binary/1"><c>term_to_binary/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="term_to_iovec" arity="2" since="OTP @OTP-15618@"/> + <fsummary>Encode a term to en Erlang external term format as iovec(). + </fsummary> + <desc> + <p>Returns the encoding of <c><anno>Term</anno></c> according to + the Erlang external term format as + <seealso marker="#type-ext_iovec"><c>ext_iovec()</c></seealso>.</p> + + <p>This function produce the same encoding as + <seealso marker="#term_to_binary/2"><c>term_to_binary/2</c></seealso>, + but with another return type. The call + <c>iolist_to_binary(term_to_iovec(Term, Opts))</c> will produce + exactly the same result as <c>term_to_binary(Term, Opts)</c>.</p> + + <p>Currently recognised options are all options recognised by + <seealso marker="#term_to_binary/2"><c>term_to_binary/2</c></seealso>.</p> + + <p><c>term_to_iovec()</c> is a pure optimization of the functionality + <c>term_to_binary()</c> provide. <c>term_to_iovec()</c> can for example + refer directly to off heap binaries instead of copying the binary + data into the result.</p> + + <p>See also + <seealso marker="#term_to_binary/2"><c>term_to_binary/2</c></seealso>.</p> + </desc> + </func> + + <func> <name name="throw" arity="1" since=""/> <fsummary>Throw an exception.</fsummary> <desc> diff --git a/erts/doc/src/erlc.xml b/erts/doc/src/erlc_cmd.xml index f1f2c786da..55a4712b25 100644 --- a/erts/doc/src/erlc.xml +++ b/erts/doc/src/erlc_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -387,4 +387,3 @@ erlc +export_all file.erl</pre> <seealso marker="snmp:snmp"><c>snmp(3)</c></seealso></p> </section> </comref> - diff --git a/erts/doc/src/erlsrv.xml b/erts/doc/src/erlsrv_cmd.xml index 6c08b25220..1db5fcd9db 100644 --- a/erts/doc/src/erlsrv.xml +++ b/erts/doc/src/erlsrv_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -43,7 +43,7 @@ Windows services applet in a manner similar to other services.</p> <p>Notice that <c>erlsrv</c> is not a general service utility for Windows, - but designed for embedded Erlang systems.</p> + but designed for embedded Erlang systems.</p> <p><c>erlsrv</c> also provides a command-line interface for registering, changing, starting, and stopping services.</p> @@ -471,10 +471,10 @@ <code type="none"><![CDATA[ #include <windows.h> -/* +/* ** A Console control handler that ignores the log off events, ** and lets the default handler take care of other events. -*/ +*/ BOOL WINAPI service_aware_handler(DWORD ctrl){ if(ctrl == CTRL_LOGOFF_EVENT) return TRUE; @@ -485,8 +485,8 @@ BOOL WINAPI service_aware_handler(DWORD ctrl){ void initialize_handler(void){ char buffer[2]; - /* - * We assume we are running as a service if this + /* + * We assume we are running as a service if this * environment variable is defined. */ if(GetEnvironmentVariable("ERLSRV_SERVICE_NAME",buffer, @@ -530,4 +530,3 @@ void initialize_handler(void){ <c>release_handler(3)</c></seealso></p> </section> </comref> - diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript_cmd.xml index be1664b39f..4ca7e46e6e 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -448,4 +448,3 @@ ok </taglist> </section> </comref> - diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml index d6c73a02ec..c4b1478c18 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -48,6 +48,15 @@ the system.</p> </description> + <datatypes> + <datatype> + <name name="mode"/> + <desc> + <p>Code loading mode.</p> + </desc> + </datatype> + </datatypes> + <funcs> <func> <name name="boot" arity="1" since=""/> @@ -165,12 +174,24 @@ <name name="restart" arity="0" since=""/> <fsummary>Restart the running Erlang node.</fsummary> <desc> + <p>The same as + <seealso marker="#restart/1"><c>restart([])</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="restart" arity="1" since="OTP 23.0"/> + <fsummary>Restart the running Erlang node.</fsummary> + <desc> <p>The system is restarted <em>inside</em> the running Erlang node, which means that the emulator is not restarted. All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system is booted again in - the same way as initially started. The same <c>BootArgs</c> - are used again.</p> + the same way as initially started.</p> + <p>The same <c>BootArgs</c> are used when restarting the + system unless the <c>mode</c> option is given, allowing the + code loading mode to be set to either <c>embedded</c> or + <c>interactive</c>. All other <c>BootArgs</c> remain the same.</p> <p>To limit the shutdown time, the time <c>init</c> is allowed to spend taking down applications, command-line flag <c>-shutdown_time</c> is to be used.</p> diff --git a/erts/doc/src/ref_man.xml.src b/erts/doc/src/ref_man.xml.src index 7dd003763c..5b327165d4 100644 --- a/erts/doc/src/ref_man.xml.src +++ b/erts/doc/src/ref_man.xml.src @@ -34,24 +34,24 @@ <xi:include href="atomics.xml"/> <xi:include href="counters.xml"/> <xi:include href="driver_entry.xml"/> - <xi:include href="epmd.xml"/> - <xi:include href="erl.xml"/> + <xi:include href="epmd_cmd.xml"/> + <xi:include href="erl_cmd.xml"/> <xi:include href="erlang.xml"/> - <xi:include href="erlc.xml"/> + <xi:include href="erlc_cmd.xml"/> <xi:include href="erl_driver.xml"/> <xi:include href="erl_nif.xml"/> <xi:include href="erl_prim_loader.xml"/> - <xi:include href="erlsrv.xml"/> + <xi:include href="erlsrv_cmd.xml"/> <xi:include href="erl_tracer.xml"/> <xi:include href="erts_alloc.xml"/> - <xi:include href="escript.xml"/> + <xi:include href="escript_cmd.xml"/> <xi:include href="init.xml"/> <xi:include href="persistent_term.xml"/> - <xi:include href="run_erl.xml"/> + <xi:include href="run_erl_cmd.xml"/> %ESOCK_USE_SOCKET_XML% - <xi:include href="start.xml"/> - <xi:include href="start_erl.xml"/> - <xi:include href="werl.xml"/> + <xi:include href="start_cmd.xml"/> + <xi:include href="start_erl_cmd.xml"/> + <xi:include href="werl_cmd.xml"/> <xi:include href="zlib.xml"/> </application> diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl_cmd.xml index fa36457489..9f1984f784 100644 --- a/erts/doc/src/run_erl.xml +++ b/erts/doc/src/run_erl_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>run_erl</title> @@ -213,4 +213,3 @@ <seealso marker="start_erl"><c>start_erl(1)</c></seealso></p> </section> </comref> - diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml index 2d16ff2074..980479bd99 100644 --- a/erts/doc/src/socket.xml +++ b/erts/doc/src/socket.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2018</year><year>2019</year> + <year>2018</year><year>2020</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -94,7 +94,7 @@ <datatype> <name>socket()</name> <desc><p>As returned by - <seealso marker="#open/2"><c>open/2,3,4</c></seealso> and + <seealso marker="#open/1"><c>open/1,2,3,4</c></seealso> and <seealso marker="#accept/1"><c>accept/1,2</c></seealso>.</p> </desc> </datatype> @@ -513,7 +513,58 @@ </func> <func> - <name name="open" arity="2" since="OTP 22.0"/> + <name name="open" arity="1" since="OTP @OTP-16398@"/> + <name name="open" arity="2" clause_i="1" since="OTP @OTP-16398@"/> + <fsummary>Create an endpoint for communication.</fsummary> + <desc> + <p>Create an endpoint (socket) for communication based on an + already existing file descriptor. + The function attempts to retrieve domain, type and protocol from + the system. This is however not possible on all platforms, and + in those cases it expects it in <c>Opts</c>. </p> + + <p>The <c>Opts</c> argument is intended for providing extra + information for the open call:</p> + <taglist> + <tag><c><![CDATA[dup: boolean()]]></c></tag> + <item> + <p>Shall the provided descriptor be duplicated (dup) or not. + <br/>Defaults to <c>true</c>. </p> + </item> + + <tag><c><![CDATA[debug: boolean()]]></c></tag> + <item> + <p>Enable or disable debug during the open call. + <br/>Defaults to <c>false</c>. </p> + </item> + + <tag><c><![CDATA[domain: socket:domain()]]></c></tag> + <item> + <p>Which domain is the descriptor of. </p> + </item> + + <tag><c><![CDATA[type: socket:type()]]></c></tag> + <item> + <p>Which type is the descriptor of. </p> + </item> + + <tag><c><![CDATA[protocol: socket:protocol()]]></c></tag> + <item> + <p>Which protocol is the descriptor of. </p> + </item> + + </taglist> + + <note> + <p>This function should be used with care! </p> + <p>On some platforms its <em>necessary</em> to provide the + <c>protocol</c> as its impossible to retrieve it. </p> + </note> + </desc> + </func> + + <func> + <name name="open" arity="2" clause_i="2" since="OTP 22.0"/> <name name="open" arity="3" since="OTP 22.0"/> <name name="open" arity="4" since="OTP 22.0"/> <fsummary>Create an endpoint for communication.</fsummary> @@ -526,9 +577,10 @@ And for <c>Domain = local</c>, if a protocol <em>is</em> pecified, it <em>must</em> be <c>default</c>. </p> - <p>The <c>Extra</c> argument is intended for "obscure" options. - Currently the only supported option is <c>netns</c>, which - is only supported on the linux platform.</p> + <p>The <c>Opts</c> argument is intended for "other" options. + Currently the only supported option(s) are <c>netns</c>, which + is only supported on the linux platform and <c>debug</c> (controls debug + printouts during the open call).</p> <note> <p>It may not be possible to specify the default protocol (except @@ -911,7 +963,8 @@ <name name="supports" arity="1" clause_i="4" since="OTP 22.0"/> <name name="supports" arity="1" clause_i="5" since="OTP @OTP-16153@"/> <name name="supports" arity="1" clause_i="6" since="OTP @OTP-16153@"/> - <name name="supports" arity="1" clause_i="7" since="OTP 22.0"/> + <name name="supports" arity="1" clause_i="7" since="OTP @OTP-16432@"/> + <name name="supports" arity="1" clause_i="8" since="OTP 22.0"/> <name name="supports" arity="2" clause_i="1" since="OTP 22.0"/> <name name="supports" arity="2" clause_i="2" since="OTP 22.0"/> <name name="supports" arity="2" clause_i="3" since="OTP 22.0"/> @@ -1014,4 +1067,3 @@ server(Addr, Port) -> </code> </section> </erlref> - diff --git a/erts/doc/src/start.xml b/erts/doc/src/start_cmd.xml index 6eac47fe94..9f208d43bb 100644 --- a/erts/doc/src/start.xml +++ b/erts/doc/src/start_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>start</title> @@ -70,4 +70,3 @@ <seealso marker="start_erl"><c>start_erl(1)</c></seealso></p> </section> </comref> - diff --git a/erts/doc/src/start_erl.xml b/erts/doc/src/start_erl_cmd.xml index 4887d4606e..e9cb248da4 100644 --- a/erts/doc/src/start_erl.xml +++ b/erts/doc/src/start_erl_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>start_erl</title> @@ -89,7 +89,7 @@ only option <c>-rootdir</c> is specified, the directory is assumed to be <Erlang root>\\releases.</p> </item> - <tag><c>-rootdir <Erlang root directory></c></tag> + <tag><c>-rootdir <Erlang root directory></c></tag> <item> <p>Mandatory if <c>-reldir</c> is not specified and no <c><![CDATA[RELDIR]]></c> exists in the environment. This @@ -166,4 +166,3 @@ <c>release_handler(3)</c></seealso></p> </section> </comref> - diff --git a/erts/doc/src/werl.xml b/erts/doc/src/werl_cmd.xml index 792fe204e8..4f25565c64 100644 --- a/erts/doc/src/werl.xml +++ b/erts/doc/src/werl_cmd.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>werl</title> @@ -62,7 +62,7 @@ <p>In cases where you want to redirect standard input and/or standard output or use Erlang in a pipeline, <c>werl</c> is not suitable, and the <c>erl</c> program is to be used instead.</p> - + <p>The <c>werl</c> window is in many ways modeled after the <c>xterm</c> window present on other platforms, as the <c>xterm</c> model fits well with line-oriented command-based interaction. This @@ -102,7 +102,7 @@ use <c>Ctrl-P</c>.</p> </item> </list> - + <p>A drop-down box in the toolbar contains the command history. Selecting a command in the drop-down box inserts the command at the prompt, as if you used the keyboard to retrieve the @@ -115,4 +115,3 @@ </list> </description> </comref> - |
