diff options
Diffstat (limited to 'lib/stdlib/doc/src/notes.xml')
| -rw-r--r-- | lib/stdlib/doc/src/notes.xml | 541 |
1 files changed, 538 insertions, 3 deletions
diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 5d4f9d912f..bb35224182 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2013</year> + <year>2004</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,541 @@ </header> <p>This document describes the changes made to the STDLIB application.</p> +<section><title>STDLIB 3.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>An escript with only two lines would not work.</p> + <p> + Own Id: OTP-14098</p> + </item> + <item> + <p> Characters (<c>$char</c>) can be used in constant + pattern expressions. They can also be used in types and + contracts. </p> + <p> + Own Id: OTP-14103 Aux Id: ERL-313 </p> + </item> + <item> + <p> The signatures of <c>erl_parse:anno_to_term/1</c> and + <c>erl_parse:anno_from_term/1</c> are corrected. Using + these functions no longer results in false Dialyzer + warnings. </p> + <p> + Own Id: OTP-14131</p> + </item> + <item> + <p>Pretty-printing of maps is improved. </p> + <p> + Own Id: OTP-14175 Aux Id: seq13277 </p> + </item> + <item> + <p>If any of the following functions in the <c>zip</c> + module crashed, a file would be left open: + <c>extract()</c>, <c>unzip()</c>, <c>create()</c>, or + <c>zip()</c>. This has been corrected.</p> + <p>A <c>zip</c> file having a "Unix header" could not be + unpacked.</p> + <p> + Own Id: OTP-14189 Aux Id: ERL-348, ERL-349 </p> + </item> + <item> + <p> Improve the Erlang shell's tab-completion of long + names. </p> + <p> + Own Id: OTP-14200 Aux Id: ERL-352 </p> + </item> + <item> + <p> + The reference manual for <c>sys</c> had some faulty + information about the 'get_modules' message used by + processes where modules change dynamically during + runtime. The documentation is now corrected.</p> + <p> + Own Id: OTP-14248 Aux Id: ERL-367 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Bug fixes, new features and improvements to gen_statem:</p> + <p> + A new type init_result/1 has replaced the old + init_result/0, so if you used that old type (that was + never documented) you have to change your code, which may + be regarded as a potential incompatibility.</p> + <p> + Changing callback modes after code change did not work + since the new callback mode was not recorded. This bug + has been fixed.</p> + <p> + The event types state_timeout and {call,From} could not + be generated with a {next_event,EventType,EventContent} + action since they did not pass the runtime type check. + This bug has now been corrected.</p> + <p> + State entry calls can now be repeated using (new) state + callback returns {repeat_state,...}, + {repeat_state_and_data,_} and repeat_state_and_data.</p> + <p> + There have been lots of code cleanup in particular + regarding timer handling. For example is async + cancel_timer now used. Error handling has also been + cleaned up.</p> + <p> + To align with probable future changes to the rest of + gen_*, terminate/3 has now got a fallback and + code_change/4 is not mandatory.</p> + <p> + Own Id: OTP-14114</p> + </item> + <item> + <p><c>filename:safe_relative_path/1</c> to sanitize a + relative path has been added.</p> + <p> + Own Id: OTP-14215</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When a simple_one_for_one supervisor is shutting down, + and a child exits with an exit reason of the form + {shutdown, Term}, an error report was earlier printed. + This is now corrected.</p> + <p> + Own Id: OTP-13907 Aux Id: PR-1158, ERL-163 </p> + </item> + <item> + <p> Allow empty list as parameter of the fun used with + <c>dbg:fun2ms/1</c>. </p> + <p> + Own Id: OTP-13974</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The new behaviour gen_statem has been improved with 3 new + features: the possibility to use old style non-proxy + timeouts for gen_statem:call/2,3, state entry code, and + state timeouts. These are backwards compatible. Minor + code and documentation improvements has been performed + including a borderline semantics correction of timeout + zero handling.</p> + <p> + Own Id: OTP-13929 Aux Id: PR-1170, ERL-284 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The <c>zip:unzip/1,2</c> and <c>zip:extract/1,2</c> + functions have been updated to handle directory traversal + exploits. Any element in the zip file that contains a + path that points to a directory above the top level + working directory, <c>cwd</c>, will instead be extracted + in <c>cwd</c>. An error message is printed for any such + element in the zip file during the unzip operation. The + <c>keep_old_files</c> option determines if a file will + overwrite a previous file with the same name within the + zip file.</p> + <p> + Own Id: OTP-13633</p> + </item> + <item> + <p> Correct the contracts for + <c>ets:match_object/1,3</c>. </p> + <p> + Own Id: OTP-13721 Aux Id: PR-1113 </p> + </item> + <item> + <p> + Errors in type specification and Emacs template + generation for <c>gen_statem:code_change/4</c> has been + fixed from bugs.erlang.org's Jira cases ERL-172 and + ERL-187.</p> + <p> + Own Id: OTP-13746 Aux Id: ERL-172, ERL-187 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + gen_statem has been changed to set the callback mode for + a server to what Module:callback_mode/0 returns. This + facilitates e.g code downgrade since the callback mode + now becomes a property of the currently active code, not + of the server process.</p> + <p> + Exception handling from Module:init/1 has also been + improved.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13752</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Correct a bug regarding typed records in the Erlang + shell. The bug was introduced in OTP-19.0. </p> + <p> + Own Id: OTP-13719 Aux Id: ERL-182 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a race bug affecting <c>dets:open_file/2</c>. + </p> + <p> + Own Id: OTP-13260 Aux Id: seq13002 </p> + </item> + <item> + <p>Don't search for non-existing Map keys twice</p> + <p>For <c>maps:get/2,3</c> and <c>maps:find/2</c>, + searching for an immediate key, e.g. an atom, in a small + map, the search was performed twice if the key did not + exist.</p> + <p> + Own Id: OTP-13459</p> + </item> + <item> + <p> + Avoid stray corner-case math errors on Solaris, e.g. an + error is thrown on underflows in exp() and pow() when it + shouldn't be.</p> + <p> + Own Id: OTP-13531</p> + </item> + <item> + <p>Fix linting of map key variables</p> + <p>Map keys cannot be unbound and then used in parallel + matching.</p> + <p>Example: <c> #{ K := V } = #{ k := K } = M.</c> This + is illegal if <c>'K'</c> is not bound.</p> + <p> + Own Id: OTP-13534 Aux Id: ERL-135 </p> + </item> + <item> + <p> + Fixed a bug in re on openbsd where sometimes re:run would + return an incorrect result.</p> + <p> + Own Id: OTP-13602</p> + </item> + <item> + <p> + To avoid potential timer bottleneck on supervisor + restart, timer server is no longer used when the + supervisor is unable to restart a child.</p> + <p> + Own Id: OTP-13618 Aux Id: PR-1001 </p> + </item> + <item> + <p> The Erlang code preprocessor (<c>epp</c>) can handle + file names spanning over many tokens. Example: + <c>-include("a" "file" "name").</c>. </p> + <p> + Own Id: OTP-13662 Aux Id: seq13136 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>The types of The Abstract Format in the + <c>erl_parse</c> module have been refined. </p> + <p> + Own Id: OTP-10292</p> + </item> + <item> + <p> Undocumented syntax for function specifications, + <c>-spec F/A :: Domain -> Range</c>, has been removed + (without deprecation). </p> <p> Using the + <c>is_subtype(V, T)</c> syntax for constraints (in + function specifications) is no longer documented, and the + newer syntax <c>V :: T</c> should be used instead. The + Erlang Parser still recognizes the <c>is_subtype</c> + syntax, and will continue to do so for some time. </p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11879</p> + </item> + <item> + <p>The '<c>random</c>' module has been deprecated. Use + the '<c>rand</c>' module instead.</p> + <p> + Own Id: OTP-12502 Aux Id: OTP-12501 </p> + </item> + <item> + <p>Background: In record fields with a type declaration + but without an initializer, the Erlang parser inserted + automatically the singleton type <c>'undefined'</c> to + the list of declared types, if that value was not present + there. That is, the record declaration:</p> + <p> + -record(rec, {f1 :: float(), f2 = 42 :: integer(), f3 :: + some_mod:some_typ()}).</p> + <p>was translated by the parser to:</p> + <p> + -record(rec, {f1 :: float() | 'undefined', f2 = 42 :: + integer(), f3 :: some_mod:some_typ() | 'undefined'}).</p> + <p>The rationale for this was that creation of a "dummy" + <c>#rec{}</c> record should not result in a warning from + dialyzer that, for example, the implicit initialization + of the <c>#rec.f1</c> field violates its type + declaration.</p> + <p>Problems: This seemingly innocent action has some + unforeseen consequences.</p> + <p>For starters, there is no way for programmers to + declare that e.g. only floats make sense for the + <c>f1</c> field of <c>#rec{}</c> records when there is no + "obvious" default initializer for this field. (This also + affects tools like PropEr that use these declarations + produced by the Erlang parser to generate random + instances of records for testing purposes.)</p> + <p>It also means that dialyzer does not warn if e.g. an + <c>is_atom/1</c> test or something more exotic like an + <c>atom_to_list/1</c> call is performed on the value of + the <c>f1</c> field.</p> + <p>Similarly, there is no way to extend dialyzer to warn + if it finds record constructions where <c>f1</c> is not + initialized to some float.</p> + <p>Last but not least, it is semantically problematic + when the type of the field is an opaque type: creating a + union of an opaque and a structured type is very + problematic for analysis because it fundamentally breaks + the opacity of the term at that point.</p> + <p>Change: To solve these problems the parser will not + automatically insert the <c>'undefined'</c> value + anymore; instead the user has the option to choose the + places where this value makes sense (for the field) and + where it does not and insert the <c>| 'undefined'</c> + there manually.</p> + <p>Consequences of this change: This change means that + dialyzer will issue a warning for all places where + records with uninitialized fields are created and those + fields have a declared type that is incompatible with + <c>'undefined'</c> (e.g. <c>float()</c>). This warning + can be suppressed easily by adding <c>| 'undefined'</c> + to the type of this field. This also adds documentation + that the user really intends to create records where this + field is uninitialized.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12719</p> + </item> + <item> + <p> Remove deprecated functions in the modules + <c>erl_scan</c> and <c>erl_parse</c>. </p> + <p> + Own Id: OTP-12861</p> + </item> + <item> + <p>The pre-processor can now expand the ?FUNCTION_NAME + and ?FUNCTION_ARITY macros.</p> + <p> + Own Id: OTP-13059</p> + </item> + <item> + <p> A new behaviour <c>gen_statem</c> has been + implemented. It has been thoroughly reviewed, is stable + enough to be used by at least two heavy OTP applications, + and is here to stay. But depending on user feedback, we + do not expect but might find it necessary to make minor + not backwards compatible changes into OTP-20.0, so its + state can be designated as "not quite experimental"... + </p> <p> The <c>gen_statem</c> behaviour is intended to + replace <c>gen_fsm</c> for new code. It has the same + features and add some really useful: </p> <list + type="bulleted"> <item>State code is gathered</item> + <item>The state can be any term</item> <item>Events can + be postponed</item> <item>Events can be self + generated</item> <item>A reply can be sent from a later + state</item> <item>There can be multiple sys traceable + replies</item> </list> <p> The callback model(s) for + <c>gen_statem</c> differs from the one for + <c>gen_fsm</c>, but it is still fairly easy to rewrite + from <c>gen_fsm</c> to <c>gen_statem</c>. </p> + <p> + Own Id: OTP-13065 Aux Id: PR-960 </p> + </item> + <item> + <p> + Optimize binary:split/2 and binary:split/3 with native + BIF implementation.</p> + <p> + Own Id: OTP-13082</p> + </item> + <item> + <p>Background: The types of record fields have since R12B + been put in a separate form by <c>epp:parse_file()</c>, + leaving the record declaration form untyped. The separate + form, however, does not follow the syntax of type + declarations, and parse transforms inspecting + <c>-type()</c> attributes need to know about the special + syntax. Since the compiler stores the return value of + <c>epp:parse_file()</c> as debug information in the + abstract code chunk (<c>"Abst"</c> or + <c>abstract_code</c>), tools too need to know about the + special syntax, if they inspect <c>-type()</c> attributes + in abstract code.</p> + <p>Change: No separate type form is created by + <c>epp:parse_file()</c>, but the type information is kept + in the record fields. This means that all parse + transforms and all tools inspecting <c>-record()</c> + declarations need to recognize <c>{typed_record_field, + Field, Type}</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13148</p> + </item> + <item> + <p> + Unsized fields of the type <c>bytes</c> in binary + generators are now forbidden. (The other ways of writing + unsized fields, such as <c>binary</c>, are already + forbidden.)</p> + <p> + Own Id: OTP-13152</p> + </item> + <item> + <p> The type <c>map()</c> is built-in, and cannot be + redefined. </p> + <p> + Own Id: OTP-13153</p> + </item> + <item> + <p> Let <c>dets:open_file()</c> exit with a <c>badarg</c> + message if given a raw file name (a binary). </p> + <p> + Own Id: OTP-13229 Aux Id: ERL-55 </p> + </item> + <item> + <p> Add <c>filename:basedir/2,3</c></p> <p>basedir + returns suitable path(s) for 'user_cache', 'user_config', + 'user_data', 'user_log', 'site_config' and 'site_data'. + On linux and linux like systems the paths will respect + the XDG environment variables.</p> + <p> + Own Id: OTP-13392</p> + </item> + <item> + <p>There are new preprocessor directives + <c>-error(Term)</c> and <c>-warning(Term)</c> to cause a + compilation error or a compilation warning, + respectively.</p> + <p> + Own Id: OTP-13476</p> + </item> + <item> + <p> + Optimize <c>'++'</c> operator and <c>lists:append/2</c> + by using a single pass to build a new list while checking + for properness.</p> + <p> + Own Id: OTP-13487</p> + </item> + <item> + <p> + Add <c>maps:update_with/3,4</c> and <c>maps:take/2</c></p> + <p> + Own Id: OTP-13522 Aux Id: PR-1025 </p> + </item> + <item> + <p><c>lists:join/2</c> has been added. Similar to + <c>string:join/2</c> but works with arbitrary lists.</p> + <p> + Own Id: OTP-13523</p> + </item> + <item> + <p>Obfuscate asserts to make Dialyzer shut up.</p> + <p> + Own Id: OTP-13524 Aux Id: PR-1002 </p> + </item> + <item> + <p> + Supervisors now explicitly add their callback module in + the return from sys:get_status/1,2. This is to simplify + custom supervisor implementations. The Misc part of the + return value from sys:get_status/1,2 for a supervisor is + now:</p> + <p> + [{data, [{"State", + State}]},{supervisor,[{"Callback",Module}]}]</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13619 Aux Id: PR-1000 </p> + </item> + <item> + <p> + Relax translation of initial calls in <c>proc_lib</c>, + i.e. remove the restriction to only do the translation + for <c>gen_server</c> and <c>gen_fsm</c>. This enables + user defined <c>gen</c> based generic callback modules to + be displayed nicely in <c>c:i()</c> and observer.</p> + <p> + Own Id: OTP-13623</p> + </item> + <item> + <p>The function <c>queue:lait/1</c> (misspelling of + <c>liat/1</c>) is now deprecated.</p> + <p> + Own Id: OTP-13658</p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 2.8</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -197,7 +732,7 @@ </item> <item> <p> - The <c>stdlib</c> reference manual is updated to show + The STDLIB reference manual is updated to show correct information about the return value of <c>gen_fsm:reply/2</c>.</p> <p> @@ -5907,7 +6442,7 @@ documentation for <c>compile</c> on how to provide the key for encrypting, and the documentation for <c>beam_lib</c> on how to provide the key for decryption so that tools such - as the Debugger, <c>xref</c>, or <c>cover</c> can be used.</p> + as the Debugger, Xref, or Cover can be used.</p> <p>The <c>beam_lib:chunks/2</c> functions now accepts an additional chunk type <c>compile_info</c> to retrieve the compilation information directly as a term. (Thanks |