aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2019-04-15 10:58:42 +0200
committerErlang/OTP <[email protected]>2019-04-15 10:58:42 +0200
commit21e5f66c1236ce73fcc677b8c6bfe42e33e3555a (patch)
tree2afdbf35e9f75561f042d29de50a43fd6c16eabc
parent7ad05d6dd4230061e8120ae8c0dec2535f47e294 (diff)
parent3c171041be91f5f79527c660cebae1af7c578c6d (diff)
downloadotp-21e5f66c1236ce73fcc677b8c6bfe42e33e3555a.tar.gz
otp-21e5f66c1236ce73fcc677b8c6bfe42e33e3555a.tar.bz2
otp-21e5f66c1236ce73fcc677b8c6bfe42e33e3555a.zip
Merge branch 'sverker/maint-21/doc-big-creation-tags/OTP-15766' into maint-21
* sverker/maint-21/doc-big-creation-tags/OTP-15766: erts: Document NEW_PID, NEW_PORT, NEWER_REFERENCE erts: Add missing docs for DFLAG_MAP_TAG and DFLAG_BIG_CREATION
-rw-r--r--erts/doc/src/erl_ext_dist.xml251
1 files changed, 181 insertions, 70 deletions
diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml
index b7090d0472..5813af1d57 100644
--- a/erts/doc/src/erl_ext_dist.xml
+++ b/erts/doc/src/erl_ext_dist.xml
@@ -386,44 +386,6 @@
</section>
<section>
- <marker id="REFERENCE_EXT"/>
- <title>REFERENCE_EXT</title>
- <table align="left">
- <row>
- <cell align="center">1</cell>
- <cell align="center">N</cell>
- <cell align="center">4</cell>
- <cell align="center">1</cell>
- </row>
- <row>
- <cell align="center"><c>101</c></cell>
- <cell align="center"><c>Node</c></cell>
- <cell align="center"><c>ID</c></cell>
- <cell align="center"><c>Creation</c></cell>
- </row>
- <tcaption>REFERENCE_EXT</tcaption></table>
- <p>
- Encodes a reference object (an object generated with
- <seealso marker="erlang:make_ref/0">erlang:make_ref/0</seealso>).
- The <c>Node</c> term is an encoded atom, that is,
- <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso>,
- <seealso marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>, or
- <seealso marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seealso>.
- The <c>ID</c> field contains a big-endian unsigned integer,
- but <em>is to be regarded as uninterpreted data</em>,
- as this field is node-specific.
- <c>Creation</c> is a byte containing a node serial number, which
- makes it possible to separate old (crashed) nodes from a new one.
- </p>
- <p>
- In <c>ID</c>, only 18 bits are significant; the rest are to be 0.
- In <c>Creation</c>, only two bits are significant; the rest are to be 0.
- See <seealso marker="#NEW_REFERENCE_EXT">
- <c>NEW_REFERENCE_EXT</c></seealso>.
- </p>
- </section>
-
- <section>
<marker id="PORT_EXT"/>
<title>PORT_EXT</title>
<table align="left">
@@ -441,13 +403,46 @@
</row>
<tcaption>PORT_EXT</tcaption></table>
<p>
- Encodes a port object (obtained from
- <seealso marker="erlang:open_port/2">
- <c>erlang:open_port/2</c></seealso>).
- The <c>ID</c> is a node-specific identifier for a local port.
+ Same as <seealso marker="#NEW_PORT_EXT"><c>NEW_PORT_EXT</c></seealso>
+ except the <c>Creation</c> field is only one byte and only two
+ bits are significant, the rest are to be 0.
+ </p>
+ </section>
+
+ <section>
+ <marker id="NEW_PORT_EXT"/>
+ <title>NEW_PORT_EXT</title>
+ <table align="left">
+ <row>
+ <cell align="center">1</cell>
+ <cell align="center">N</cell>
+ <cell align="center">4</cell>
+ <cell align="center">4</cell>
+ </row>
+ <row>
+ <cell align="center"><c>89</c></cell>
+ <cell align="center"><c>Node</c></cell>
+ <cell align="center"><c>ID</c></cell>
+ <cell align="center"><c>Creation</c></cell>
+ </row>
+ <tcaption>NEW_PORT_EXT</tcaption></table>
+ <p>
+ Encodes a port identifier (obtained from
+ <seealso marker="erlang#open_port/2"><c>erlang:open_port/2</c></seealso>).
+ <c>Node</c> is an encoded atom, that is,
+ <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso>,
+ <seealso marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>
+ or <seealso marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seealso>.
+ <c>ID</c> is a 32-bit big endian unsigned integer. Only 28 bits are
+ significant; the rest are to be 0. The <c>Creation</c> works just like in
+ <seealso marker="#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>.
Port operations are not allowed across node boundaries.
- The <c>Creation</c> works just like in
- <seealso marker="#REFERENCE_EXT"><c>REFERENCE_EXT</c></seealso>.
+ </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>
</section>
@@ -471,12 +466,65 @@
</row>
<tcaption>PID_EXT</tcaption></table>
<p>
- Encodes a process identifier object (obtained from
- <seealso marker="erlang:spawn/3"><c>erlang:spawn/3</c></seealso> or
- friends). The <c>ID</c> and <c>Creation</c> fields works just like in
- <seealso marker="#REFERENCE_EXT"><c>REFERENCE_EXT</c></seealso>, while
- the <c>Serial</c> field is used to improve safety.
- In <c>ID</c>, only 15 bits are significant; the rest are to be 0.
+ Same as <seealso marker="#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>
+ except the <c>Creation</c> field is only one byte and only two
+ bits are significant, the rest are to be 0.
+ </p>
+ </section>
+
+ <section>
+ <marker id="NEW_PID_EXT"/>
+ <title>NEW_PID_EXT</title>
+ <table align="left">
+ <row>
+ <cell align="center">1</cell>
+ <cell align="center">N</cell>
+ <cell align="center">4</cell>
+ <cell align="center">4</cell>
+ <cell align="center">4</cell>
+ </row>
+ <row>
+ <cell align="center"><c>88</c></cell>
+ <cell align="center"><c>Node</c></cell>
+ <cell align="center"><c>ID</c></cell>
+ <cell align="center"><c>Serial</c></cell>
+ <cell align="center"><c>Creation</c></cell>
+ </row>
+ <tcaption>NEW_PID_EXT</tcaption></table>
+ <p>
+ Encodes an Erlang process identifier object.
+ </p>
+ <taglist>
+ <tag><c>Node</c></tag>
+ <item><p>The name of the originating node, encoded using
+ <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso>,
+ <seealso marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>
+ or <seealso
+ marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seealso>.</p>
+ </item>
+ <tag><c>ID</c></tag>
+ <item><p>A 32-bit big endian unsigned integer. Only 15 bits are
+ significant; the rest are to be 0.</p>
+ </item>
+ <tag><c>Serial</c></tag>
+ <item><p>A 32-bit big endian unsigned integer. Only 13 bits are
+ significant; the rest are to be 0.</p>
+ </item>
+ <tag><c>Creation</c></tag>
+ <item><p>A 32-bit big endian unsigned integer. All identifiers
+ originating from the same node incarnation must have identical <c>Creation</c>
+ values. This makes it possible to separate identifiers from old
+ (crashed) nodes from a new one. The value zero should be avoided for
+ normal operations as it is used as a wild card for debug purpose
+ (like a pid returned by <seealso marker="erts:erlang#list_to_pid/1">
+ 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>
</section>
@@ -700,6 +748,30 @@
</section>
<section>
+ <marker id="REFERENCE_EXT"/>
+ <title>REFERENCE_EXT (deprecated)</title>
+ <table align="left">
+ <row>
+ <cell align="center">1</cell>
+ <cell align="center">N</cell>
+ <cell align="center">4</cell>
+ <cell align="center">1</cell>
+ </row>
+ <row>
+ <cell align="center"><c>101</c></cell>
+ <cell align="center"><c>Node</c></cell>
+ <cell align="center"><c>ID</c></cell>
+ <cell align="center"><c>Creation</c></cell>
+ </row>
+ <tcaption>REFERENCE_EXT</tcaption></table>
+ <p>
+ The same as <seealso marker="#NEW_REFERENCE_EXT">
+ <c>NEW_REFERENCE_EXT</c></seealso> except <c>ID</c> is only one word
+ (<c>Len</c> = 1).
+ </p>
+ </section>
+
+ <section>
<marker id="NEW_REFERENCE_EXT"/>
<title>NEW_REFERENCE_EXT</title>
<table align="left">
@@ -719,29 +791,68 @@
</row>
<tcaption>NEW_REFERENCE_EXT</tcaption></table>
<p>
- <c>Node</c> and <c>Creation</c> are as in
- <seealso marker="#REFERENCE_EXT"><c>REFERENCE_EXT</c></seealso>.
- </p>
- <p>
- <c>ID</c> contains a sequence of big-endian unsigned integers
- (4 bytes each, so <c>N'</c> is a multiple of 4),
- but is to be regarded as uninterpreted data.
- </p>
- <p>
- <c>N'</c> = 4 * <c>Len</c>.
- </p>
- <p>
- In the first word (4 bytes) of <c>ID</c>, only 18 bits are
- significant, the rest are to be 0.
- In <c>Creation</c>, only two bits are significant,
- the rest are to be 0.
+ The same as <seealso marker="#NEWER_REFERENCE_EXT">
+ <c>NEWER_REFERENCE_EXT</c></seealso> <em>except</em>:
</p>
+ <taglist>
+ <tag><c>ID</c></tag>
+ <item><p>In the first word (4 bytes) of <c>ID</c>, only 18 bits are
+ significant, the rest must be 0.</p>
+ </item>
+ <tag><c>Creation</c></tag>
+ <item><p>Only one byte long and only two bits are significant, the rest must be 0.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <marker id="NEWER_REFERENCE_EXT"/>
+ <title>NEWER_REFERENCE_EXT</title>
+ <table align="left">
+ <row>
+ <cell align="center">1</cell>
+ <cell align="center">2</cell>
+ <cell align="center">N</cell>
+ <cell align="center">4</cell>
+ <cell align="center">N'</cell>
+ </row>
+ <row>
+ <cell align="center"><c>90</c></cell>
+ <cell align="center"><c>Len</c></cell>
+ <cell align="center"><c>Node</c></cell>
+ <cell align="center"><c>Creation</c></cell>
+ <cell align="center"><c>ID ...</c></cell>
+ </row>
+ <tcaption>NEWER_REFERENCE_EXT</tcaption></table>
<p>
- <c>NEW_REFERENCE_EXT</c> was introduced with distribution version 4.
- In version 4, <c>N'</c> is to be at most 12.
+ Encodes a reference term generated with
+ <seealso marker="erts:erlang#make_ref/0">erlang:make_ref/0</seealso>.
</p>
- <p>
- See <seealso marker="#REFERENCE_EXT"><c>REFERENCE_EXT</c></seealso>.
+ <taglist>
+ <tag><c>Node</c></tag>
+ <item><p>The name of the originating node, encoded using
+ <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso>,
+ <seealso marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>
+ or <seealso marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seealso>.</p>
+ </item>
+ <tag><c>Len</c></tag>
+ <item><p>A 16-bit big endian unsigned integer not larger than 3.</p>
+ </item>
+ <tag><c>ID</c></tag>
+ <item><p>A sequence of <c>Len</c> big-endian unsigned integers
+ (4 bytes each, so <c>N'</c>&nbsp;=&nbsp;4&nbsp;*&nbsp;<c>Len</c>),
+ but is to be regarded as uninterpreted data.</p>
+ </item>
+ <tag><c>Creation</c></tag>
+ <item><p>Works just like in
+ <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>
</section>