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(-) 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