From 9796d89cf6ea428e0e564f9071ef3c939443d816 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson
Date: Wed, 10 Apr 2019 20:30:24 +0200
Subject: erts: Document NEW_PID, NEW_PORT, NEWER_REFERENCE
---
erts/doc/src/erl_ext_dist.xml | 251 ++++++++++++++++++++++++++++++------------
1 file changed, 181 insertions(+), 70 deletions(-)
(limited to 'erts/doc/src/erl_ext_dist.xml')
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
@@ -385,44 +385,6 @@
-
-
- REFERENCE_EXT
-
-
- 1 |
- N |
- 4 |
- 1 |
-
-
- 101 |
- Node |
- ID |
- Creation |
-
- REFERENCE_EXT
-
- Encodes a reference object (an object generated with
- erlang:make_ref/0).
- The Node term is an encoded atom, that is,
- ATOM_UTF8_EXT,
- SMALL_ATOM_UTF8_EXT, or
- ATOM_CACHE_REF.
- The ID field contains a big-endian unsigned integer,
- but is to be regarded as uninterpreted data,
- as this field is node-specific.
- Creation is a byte containing a node serial number, which
- makes it possible to separate old (crashed) nodes from a new one.
-
-
- In ID, only 18 bits are significant; the rest are to be 0.
- In Creation, only two bits are significant; the rest are to be 0.
- See
- NEW_REFERENCE_EXT.
-
-
-
PORT_EXT
@@ -441,13 +403,46 @@
PORT_EXT
- Encodes a port object (obtained from
-
- erlang:open_port/2).
- The ID is a node-specific identifier for a local port.
+ Same as NEW_PORT_EXT
+ except the Creation field is only one byte and only two
+ bits are significant, the rest are to be 0.
+
+
+
+
+
+ NEW_PORT_EXT
+
+
+ 1 |
+ N |
+ 4 |
+ 4 |
+
+
+ 89 |
+ Node |
+ ID |
+ Creation |
+
+ NEW_PORT_EXT
+
+ Encodes a port identifier (obtained from
+ erlang:open_port/2).
+ Node is an encoded atom, that is,
+ ATOM_UTF8_EXT,
+ SMALL_ATOM_UTF8_EXT
+ or ATOM_CACHE_REF.
+ ID is a 32-bit big endian unsigned integer. Only 28 bits are
+ significant; the rest are to be 0. The Creation works just like in
+ NEW_PID_EXT.
Port operations are not allowed across node boundaries.
- The Creation works just like in
- REFERENCE_EXT.
+
+ Introduced in OTP 19, but only to be decoded and echoed back. Not
+ encoded for local ports. Planned to supersede
+ PORT_EXT in OTP 23 when
+ DFLAG_BIG_CREATON
+ becomes mandatory.
@@ -471,12 +466,65 @@
PID_EXT
- Encodes a process identifier object (obtained from
- erlang:spawn/3 or
- friends). The ID and Creation fields works just like in
- REFERENCE_EXT, while
- the Serial field is used to improve safety.
- In ID, only 15 bits are significant; the rest are to be 0.
+ Same as NEW_PID_EXT
+ except the Creation field is only one byte and only two
+ bits are significant, the rest are to be 0.
+
+
+
+
+
+ NEW_PID_EXT
+
+
+ 1 |
+ N |
+ 4 |
+ 4 |
+ 4 |
+
+
+ 88 |
+ Node |
+ ID |
+ Serial |
+ Creation |
+
+ NEW_PID_EXT
+
+ Encodes an Erlang process identifier object.
+
+
+ Node
+ The name of the originating node, encoded using
+ ATOM_UTF8_EXT,
+ SMALL_ATOM_UTF8_EXT
+ or ATOM_CACHE_REF.
+
+ ID
+ A 32-bit big endian unsigned integer. Only 15 bits are
+ significant; the rest are to be 0.
+
+ Serial
+ A 32-bit big endian unsigned integer. Only 13 bits are
+ significant; the rest are to be 0.
+
+ Creation
+ A 32-bit big endian unsigned integer. All identifiers
+ originating from the same node incarnation must have identical Creation
+ 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
+ erlang:list_to_pid/1).
+
+
+ Introduced in OTP 19, but only to be decoded and echoed back. Not
+ encoded for local processes. Planned to supersede
+ PID_EXT in OTP 23 when
+ DFLAG_BIG_CREATON
+ becomes mandatory.
@@ -699,6 +747,30 @@
+
+
+ REFERENCE_EXT (deprecated)
+
+
+ 1 |
+ N |
+ 4 |
+ 1 |
+
+
+ 101 |
+ Node |
+ ID |
+ Creation |
+
+ REFERENCE_EXT
+
+ The same as
+ NEW_REFERENCE_EXT except ID is only one word
+ (Len = 1).
+
+
+
NEW_REFERENCE_EXT
@@ -719,29 +791,68 @@
NEW_REFERENCE_EXT
- Node and Creation are as in
- REFERENCE_EXT.
-
-
- ID contains a sequence of big-endian unsigned integers
- (4 bytes each, so N' is a multiple of 4),
- but is to be regarded as uninterpreted data.
-
-
- N' = 4 * Len.
-
-
- In the first word (4 bytes) of ID, only 18 bits are
- significant, the rest are to be 0.
- In Creation, only two bits are significant,
- the rest are to be 0.
+ The same as
+ NEWER_REFERENCE_EXT except:
+
+ ID
+ In the first word (4 bytes) of ID, only 18 bits are
+ significant, the rest must be 0.
+
+ Creation
+ Only one byte long and only two bits are significant, the rest must be 0.
+
+
+
+
+
+
+ NEWER_REFERENCE_EXT
+
+
+ 1 |
+ 2 |
+ N |
+ 4 |
+ N' |
+
+
+ 90 |
+ Len |
+ Node |
+ Creation |
+ ID ... |
+
+ NEWER_REFERENCE_EXT
- NEW_REFERENCE_EXT was introduced with distribution version 4.
- In version 4, N' is to be at most 12.
+ Encodes a reference term generated with
+ erlang:make_ref/0.
-
- See REFERENCE_EXT.
+
+ Node
+ The name of the originating node, encoded using
+ ATOM_UTF8_EXT,
+ SMALL_ATOM_UTF8_EXT
+ or ATOM_CACHE_REF.
+
+ Len
+ A 16-bit big endian unsigned integer not larger than 3.
+
+ ID
+ A sequence of Len big-endian unsigned integers
+ (4 bytes each, so N' = 4 * Len),
+ but is to be regarded as uninterpreted data.
+
+ Creation
+ Works just like in
+ NEW_PID_EXT.
+
+
+
Introduced in OTP 19, but only to be decoded and echoed back. Not
+ encoded for local references. Planned to supersede
+ NEW_REFERENCE_EXT in OTP 23 when
+ DFLAG_BIG_CREATON
+ becomes mandatory.
--
cgit v1.2.3