aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSverker Eriksson <[email protected]>2017-03-08 20:34:55 +0100
committerSverker Eriksson <[email protected]>2017-03-08 20:34:55 +0100
commit1b7b4f7398765188815f697444e42029454dcd3d (patch)
treec0358bb5e60fe7d01afce96e2b09ca0adc4da22e
parent575cc2683af16cc702795108d40d53b3df9d4daa (diff)
downloadotp-1b7b4f7398765188815f697444e42029454dcd3d.tar.gz
otp-1b7b4f7398765188815f697444e42029454dcd3d.tar.bz2
otp-1b7b4f7398765188815f697444e42029454dcd3d.zip
erts: Mark latin1 atom encoding as deprecated
which means tags ATOM_EXT and SMALL_ATOM_EXT.
-rw-r--r--erts/doc/src/erl_ext_dist.xml156
1 files changed, 76 insertions, 80 deletions
diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml
index a436a9ca74..da2dc94e5b 100644
--- a/erts/doc/src/erl_ext_dist.xml
+++ b/erts/doc/src/erl_ext_dist.xml
@@ -51,7 +51,7 @@
term into the external format.
To convert binary data encoding to a term, the BIF
<seealso marker="erts:erlang#binary_to_term/1">
- <c>erlang:binary_to_term/1</c>c></seealso> is used.
+ <c>erlang:binary_to_term/1</c></seealso> is used.
</p>
<p>
The distribution does this implicitly when sending messages across
@@ -119,22 +119,18 @@
<tcaption>Compressed Data Format when Expanded</tcaption></table>
<marker id="utf8_atoms"/>
<note>
- <p>As from ERTS 9.0 (OTP 20), UTF-8 encoded atoms may contain any Unicode
- character. Although the support for UTF-8 encoded atoms in the external
- format is available since ERTS 5.10 (OTP R16), passing atoms that cannot
- be encoded in Latin-1 is an <em>error</em> in versions earlier than
- Erlang/OTP 20, and <em>the behavior is undefined</em>.</p>
- <p>When distribution flag <seealso marker="erl_dist_protocol#dflags">
- <c>DFLAG_UTF8_ATOMS</c></seealso> has been exchanged between both nodes
- in the <seealso marker="erl_dist_protocol#distribution_handshake">
- distribution handshake</seealso>, all atoms in the distribution header
- are encoded in UTF-8, otherwise in Latin-1. The two
- new tags <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso>
- and <seealso marker="#SMALL_ATOM_UTF8_EXT">
- <c>SMALL_ATOM_UTF8_EXT</c></seealso>
- are only used if the distribution flag <c>DFLAG_UTF8_ATOMS</c> has
- been exchanged between nodes, or if an atom containing characters
- that cannot be encoded in Latin-1 is encountered.</p>
+ <p>As from ERTS 9.0 (OTP 20), atoms may contain any Unicode
+ characters and are always encoded using the UTF-8 external formats
+ <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso>
+ or <seealso marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>.
+ The old Latin-1 formats <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>
+ and <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>
+ are deprecated and are only kept for backward
+ compatibility when decoding terms encoded by older nodes.</p>
+ <p>Support for UTF-8 encoded atoms in the external format has been
+ available since ERTS 5.10 (OTP R16). This abillity allows such old nodes
+ to decode, store and encode any Unicode atoms received from a new OTP 20
+ node.</p>
<p>The maximum number of allowed characters in an atom is 255. In the
UTF-8 case, each character can need 4 bytes to be encoded.</p>
</note>
@@ -390,28 +386,6 @@
</section>
<section>
- <marker id="ATOM_EXT"/>
- <title>ATOM_EXT</title>
- <table align="left">
- <row>
- <cell align="center">1</cell>
- <cell align="center">2</cell>
- <cell align="center">Len</cell>
- </row>
- <row>
- <cell align="center"><c>100</c></cell>
- <cell align="center"><c>Len</c></cell>
- <cell align="center"><c>AtomName</c></cell>
- </row>
- <tcaption>ATOM_EXT</tcaption></table>
- <p>
- An atom is stored with a 2 byte unsigned length in big-endian order,
- followed by <c>Len</c> numbers of 8-bit Latin-1 characters that forms
- the <c>AtomName</c>. The maximum allowed value for <c>Len</c> is 255.
- </p>
- </section>
-
- <section>
<marker id="REFERENCE_EXT"/>
<title>REFERENCE_EXT</title>
<table align="left">
@@ -432,8 +406,8 @@
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_EXT"><c>ATOM_EXT</c></seealso>,
- <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>, or
+ <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>,
@@ -772,39 +746,6 @@
</section>
<section>
- <marker id="SMALL_ATOM_EXT"/>
- <title>SMALL_ATOM_EXT</title>
- <table align="left">
- <row>
- <cell align="center">1</cell>
- <cell align="center">1</cell>
- <cell align="center">Len</cell>
- </row>
- <row>
- <cell align="center"><c>115</c></cell>
- <cell align="center"><c>Len</c></cell>
- <cell align="center"><c>AtomName</c></cell>
- </row>
- <tcaption>SMALL_ATOM_EXT</tcaption></table>
- <p>
- An atom is stored with a 1 byte unsigned length,
- followed by <c>Len</c> numbers of 8-bit Latin-1 characters that
- forms the <c>AtomName</c>. Longer atoms can be represented
- by <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>.
- </p>
- <note>
- <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">
- <c>DFLAG_SMALL_ATOM_TAGS</c></seealso> in the
- <seealso marker="erl_dist_protocol#distribution_handshake">
- distribution handshake</seealso>.
- </p>
- </note>
- </section>
-
- <section>
<marker id="FUN_EXT"/>
<title>FUN_EXT</title>
<table align="left">
@@ -838,8 +779,8 @@
<tag><c>Module</c></tag>
<item>
<p>Encoded as an atom, using
- <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>,
- <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>,
+ <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>.
This is the module that the fun is implemented in.
@@ -933,8 +874,8 @@
<tag><c>Module</c></tag>
<item>
<p>Encoded as an atom, using
- <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>,
- <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>,
+ <seealso marker="#ATOM_EXT"><c>ATOM_UTF8_EXT</c></seealso>,
+ <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>,
or <seealso marker="#ATOM_CACHE_REF">
<c>ATOM_CACHE_REF</c></seealso>.
Is the module that the fun is implemented in.
@@ -996,8 +937,8 @@
</p>
<p>
<c>Module</c> and <c>Function</c> are atoms
- (encoded using <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>,
- <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>, or
+ (encoded using <seealso marker="#ATOM_EXT"><c>ATOM_UTF8_EXT</c></seealso>,
+ <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>, or
<seealso marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seealso>).
</p>
<p>
@@ -1109,6 +1050,61 @@
in the beginning of this section.
</p>
</section>
+
+ <section>
+ <marker id="ATOM_EXT"/>
+ <title>ATOM_EXT (deprecated)</title>
+ <table align="left">
+ <row>
+ <cell align="center">1</cell>
+ <cell align="center">2</cell>
+ <cell align="center">Len</cell>
+ </row>
+ <row>
+ <cell align="center"><c>100</c></cell>
+ <cell align="center"><c>Len</c></cell>
+ <cell align="center"><c>AtomName</c></cell>
+ </row>
+ <tcaption>ATOM_EXT</tcaption></table>
+ <p>
+ An atom is stored with a 2 byte unsigned length in big-endian order,
+ followed by <c>Len</c> numbers of 8-bit Latin-1 characters that forms
+ the <c>AtomName</c>. The maximum allowed value for <c>Len</c> is 255.
+ </p>
+ </section>
+
+ <section>
+ <marker id="SMALL_ATOM_EXT"/>
+ <title>SMALL_ATOM_EXT (deprecated)</title>
+ <table align="left">
+ <row>
+ <cell align="center">1</cell>
+ <cell align="center">1</cell>
+ <cell align="center">Len</cell>
+ </row>
+ <row>
+ <cell align="center"><c>115</c></cell>
+ <cell align="center"><c>Len</c></cell>
+ <cell align="center"><c>AtomName</c></cell>
+ </row>
+ <tcaption>SMALL_ATOM_EXT</tcaption></table>
+ <p>
+ An atom is stored with a 1 byte unsigned length,
+ followed by <c>Len</c> numbers of 8-bit Latin-1 characters that
+ forms the <c>AtomName</c>.
+ </p>
+ <note>
+ <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">
+ <c>DFLAG_SMALL_ATOM_TAGS</c></seealso> in the
+ <seealso marker="erl_dist_protocol#distribution_handshake">
+ distribution handshake</seealso>.
+ </p>
+ </note>
+ </section>
+
</chapter>