aboutsummaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
authorSverker Eriksson <[email protected]>2019-05-07 15:32:29 +0200
committerSverker Eriksson <[email protected]>2019-05-07 15:32:29 +0200
commit786bca3dc17b4de45ba6b539dc399d4401995e4a (patch)
treed88e7c9933e9315347e6b8d7e1e33b91e2a47bfa /lib
parent3317a39043dbe7aaa41f04a892a695c105915a32 (diff)
parent477ab55fe1ac19bb82162bdbedba0b5e46f4e9ad (diff)
downloadotp-786bca3dc17b4de45ba6b539dc399d4401995e4a.tar.gz
otp-786bca3dc17b4de45ba6b539dc399d4401995e4a.tar.bz2
otp-786bca3dc17b4de45ba6b539dc399d4401995e4a.zip
Merge branch 'sverker/ei_set_compal_rel-doc'
* sverker/ei_set_compal_rel-doc: erl_interface: Document ei_set_compat_rel
Diffstat (limited to 'lib')
-rw-r--r--lib/erl_interface/doc/src/ei.xml56
1 files changed, 37 insertions, 19 deletions
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>