File 0141-erts-Correct-docs-about-atom-external-form... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0141-erts-Correct-docs-about-atom-external-format.patch of Package erlang (Revision b86624bd0b247ddee296914ae2ffe962)

Currently displaying revision b86624bd0b247ddee296914ae2ffe962 , Show latest

From d95365054ae2a0aadaa787ba3f9de4bb922204e5 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Thu, 21 Oct 2021 12:38:47 +0200
Subject: [PATCH 1/2] erts: Correct docs about atom external format

It incorrectly said all atom encoding used UTF-8,
but binary_to_term is still using Latin-1 by default if possible.
---
 erts/doc/src/erl_ext_dist.xml | 70 ++++++++++++++---------------------
 1 file changed, 28 insertions(+), 42 deletions(-)

diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml
index 06e9ac639d..f0bc4dfc70 100644
--- a/erts/doc/src/erl_ext_dist.xml
+++ b/erts/doc/src/erl_ext_dist.xml
@@ -119,18 +119,19 @@
 <tcaption>Compressed Data Format when Expanded</tcaption></table>
 <marker id="utf8_atoms"/>
 <note>
- As from ERTS 9.0 (OTP 20), atoms may contain any Unicode
- characters and are always encoded using the UTF-8 external formats
-	<seeguide marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seeguide>
- or <seeguide marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seeguide>.
-	The old Latin-1 formats <seeguide marker="#ATOM_EXT"><c>ATOM_EXT</c></seeguide>
- and <seeguide marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seeguide>
-	are deprecated and are only kept for backward
-	compatibility when decoding terms encoded by older nodes.
- Support for UTF-8 encoded atoms in the external format has been
- available since ERTS 5.10 (OTP R16). This ability allows such old nodes
-	to decode, store and encode any Unicode atoms received from a new OTP 20
- node.
+ 
+ As from ERTS 9.0 (OTP 20), atoms may contain any Unicode
+ characters. Atoms sent over node distribution are always encoded
+ in UTF-8 using either
+	<seeguide marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seeguide>,
+ <seeguide marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seeguide>
+ or <seeguide marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seeguide>.
+ However, <seemfa marker="erts:erlang#term_to_binary/1">
+ <c>erlang:term_to_binary/1,2</c></seemfa> is by default still using the
+ old deprecated Latin-1 format
+ <seeguide marker="#ATOM_EXT"><c>ATOM_EXT</c></seeguide>
+ for atoms that only contain Latin-1 characters (Unicode code points 0-255).
+ 
 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.
 </note>
@@ -666,10 +667,8 @@
 	
 	 Encodes a port identifier (obtained from
 <seemfa marker="erlang#open_port/2"><c>erlang:open_port/2</c></seemfa>).
-	 <c>Node</c> is an encoded atom, that is,
-	 <seeguide marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seeguide>,
-	 <seeguide marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seeguide>
-	 or <seeguide marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seeguide>.
+	 <c>Node</c> is the originating node,
+ <seeguide marker="#utf8_atoms">encoded as an atom</seeguide>.
 	 <c>ID</c> is a 64-bit big endian unsigned integer. The <c>Creation</c>
 	 works just like in <seeguide marker="#NEW_PID_EXT"><c>NEW_PID_EXT</c></seeguide>.
 	 Port operations are not allowed across node boundaries.
@@ -729,11 +728,8 @@
 	
 	<taglist>
 	 <tag><c>Node</c></tag>
-	 <item>The name of the originating node, encoded using
-	 <seeguide marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seeguide>,
-	 <seeguide marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seeguide>
-	 or <seeguide
-	 marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seeguide>.
+	 <item>The name of the originating node,
+ <seeguide marker="#utf8_atoms">encoded as an atom</seeguide>.
 	 </item>
 	 <tag><c>ID</c></tag>
 	 <item>A 32-bit big endian unsigned integer. If distribution flag
@@ -1072,10 +1068,8 @@
 	
 	<taglist>
 	 <tag><c>Node</c></tag>
-	 <item>The name of the originating node, encoded using
-	 <seeguide marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seeguide>,
-	 <seeguide marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seeguide>
-	 or <seeguide marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seeguide>.
+	 <item>The name of the originating node,
+ <seeguide marker="#utf8_atoms">encoded as an atom</seeguide>.
 	 </item>
 	 <tag><c>Len</c></tag>
 	 <item>A 16-bit big endian unsigned integer not larger than 5 when the
@@ -1137,12 +1131,9 @@
 	 </item>
 	<tag><c>Module</c></tag>
 	<item>
-	 Encoded as an atom, using
-	 <seeguide marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seeguide>,
-	 <seeguide marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seeguide>,
-	 or <seeguide marker="#ATOM_CACHE_REF">
-	 <c>ATOM_CACHE_REF</c></seeguide>.
-	 This is the module that the fun is implemented in.
+	 
+	 The module that the fun is implemented in,
+ <seeguide marker="#utf8_atoms">encoded as an atom</seeguide>.
 	 
 	</item>
 	<tag><c>Index</c></tag>
@@ -1232,13 +1223,10 @@
 	 </item>
 	 <tag><c>Module</c></tag>
 	 <item>
-	 Encoded as an atom, using
-	 <seeguide marker="#ATOM_EXT"><c>ATOM_UTF8_EXT</c></seeguide>, 
-	 <seeguide marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seeguide>,
-	 or <seeguide marker="#ATOM_CACHE_REF">
-	 <c>ATOM_CACHE_REF</c></seeguide>. 
-	 Is the module that the fun is implemented in.
-	 
+ 
+ The module that the fun is implemented in,
+ <seeguide marker="#utf8_atoms">encoded as an atom</seeguide>.
+ 
 	 </item>
 	 <tag><c>OldIndex</c></tag>
 	 <item>
@@ -1295,10 +1283,8 @@
 	 This term is the encoding for external funs: <c>fun M:F/A</c>.
 	
 	
-	 <c>Module</c> and <c>Function</c> are atoms
-	 (encoded using <seeguide marker="#ATOM_EXT"><c>ATOM_UTF8_EXT</c></seeguide>, 
-	 <seeguide marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seeguide>, or
-	 <seeguide marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seeguide>).
+	 <c>Module</c> and <c>Function</c> are
+ <seeguide marker="#utf8_atoms">encoded as atoms</seeguide>.
 	
 	
 	 <c>Arity</c> is an integer encoded using
-- 
2.31.1

Places

File 0141-erts-Correct-docs-about-atom-external-format.patch of Package erlang (Revision b86624bd0b247ddee296914ae2ffe962)

Places