From 477ab55fe1ac19bb82162bdbedba0b5e46f4e9ad Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Fri, 3 May 2019 19:07:07 +0200
Subject: erl_interface: Document ei_set_compat_rel

The changes in
6465de7e3a5393a80ed0e2c63f012fd126de706f.
---
 lib/erl_interface/doc/src/ei.xml | 56 ++++++++++++++++++++++++++--------------
 1 file changed, 37 insertions(+), 19 deletions(-)

(limited to 'lib/erl_interface/doc/src')

diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml
index 7808bfd94f..c22f3fb0ce 100644
--- a/lib/erl_interface/doc/src/ei.xml
+++ b/lib/erl_interface/doc/src/ei.xml
@@ -849,30 +849,48 @@ ei_encode_tuple_header(buf, &amp;i, 0);</pre>
       </type>
       <desc>
         <marker id="ei_set_compat_rel"></marker>
-        <p>By default, the <c>ei</c> library is only guaranteed
-          to be compatible with other Erlang/OTP components from the same
-          release as the <c>ei</c> library itself. For example,
-          <c>ei</c> from
-          Erlang/OTP R10 is not compatible with an Erlang emulator
-          from Erlang/OTP R9 by default.</p>
-        <p>A call to <c>ei_set_compat_rel(release_number)</c> sets
-          the <c>ei</c> library in compatibility mode of release
-          <c>release_number</c>. Valid range of
-          <c>release_number</c>
-          is <c>[7, current release]</c>. This makes it possible to
-          communicate with Erlang/OTP components from earlier releases.</p>
+        <p>In general, the <c>ei</c> library is guaranteed
+          to be compatible with other Erlang/OTP components that are 2 major
+	  releases older or newer than the <c>ei</c> library itself.</p>
+        <p>Sometimes an exception to the above rule has to be made to make new
+	  features (or even bug fixes) possible. A call to
+	  <c>ei_set_compat_rel(release_number)</c> sets
+          the <c>ei</c> library in compatibility mode of OTP release
+          <c>release_number</c>.</p>
+	<p>The only useful value for <c>release_number</c> is currently
+	  <c>21</c>. This will only be useful and have an effect if <em>bit
+	  strings</em> or <em>export funs</em> are received from a connected
+	  node. Before OTP 22, bit strings and export funs were not supported by
+	  <c>ei</c>. They were instead encoded using an undocumented fallback
+	  tuple format when sent from the emulator to <c>ei</c>:</p>
+	<taglist>
+	  <tag><c>Bit string</c></tag>
+	  <item><p>The term <c>&lt;&lt;42, 1:1>></c> was encoded as
+	    <c>{&lt;&lt;42, 128>>, 1}</c>. The first element of the tuple is a
+	    binary and the second element denotes how many bits of the last bytes
+	    are part of the bit string. In this example only the most significant
+	    bit of the last byte (128) is part of the bit string.</p>
+	  </item>
+	  <tag><c>Export fun</c></tag>
+	  <item><p>The term <c>fun lists:map/2</c> was encoded as
+	    <c>{lists,map}</c>. A tuple with the module, function and a missing
+	    arity.</p>
+	  </item>
+	</taglist>
+	<p>If <c>ei_set_compat_rel(21)</c> is <em>not</em> called then a connected
+	  emulator will send bit strings and export funs correctly encoded. The
+	  functions <seealso marker="#ei_decode_bitstring"><c>ei_decode_bitstring</c></seealso>
+	  and <seealso marker="#ei_decode_fun"><c>ei_decode_fun</c></seealso>
+	  has to be used to decode such terms. Calling
+	  <c>ei_set_compat_rel(21)</c> should only be done as a workaround to
+	  keep an old implementation alive, which expects to receive the
+	  undocumented tuple formats for bit strings and/or export funs.
+	</p>
         <note>
           <p>If this function is called, it can only be called once
             and must be called before any other functions in the
             <c>ei</c> library are called.</p>
         </note>
-        <warning>
-          <p>You can run into trouble if this feature is used
-            carelessly. Always ensure that all communicating
-            components are either from the same Erlang/OTP release, or
-            from release X and release Y where all components
-            from release Y are in compatibility mode of release X.</p>
-        </warning>
       </desc>
     </func>
 
-- 
cgit v1.2.3