diff options
Diffstat (limited to 'lib/stdlib/doc/src')
| -rw-r--r-- | lib/stdlib/doc/src/ets.xml | 2 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 249 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/notes.xml | 329 |
3 files changed, 470 insertions, 110 deletions
diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index b8e262208d..3653c6a632 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -1458,7 +1458,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> specification returned <c>true</c>.</fsummary> <desc> <p>Matches the objects in table <c><anno>Tab</anno></c> using a - <seealso marker="#match_spec">match specificationc</seealso>. If the + <seealso marker="#match_spec">match specification</seealso>. If the match specification returns <c>true</c> for an object, that object considered a match and is counted. For any other result from the match specification the object is not considered a match and is diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index c57a31fa21..3322571b2c 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -97,6 +97,9 @@ gen_statem module Callback module gen_statem:start gen_statem:start_link -----> Module:init/1 +Server start or code change + -----> Module:callback_mode/0 + gen_statem:stop -----> Module:terminate/3 gen_statem:call @@ -116,9 +119,11 @@ erlang:'!' -----> Module:StateName/3 </p> <p> If a callback function fails or returns a bad value, - the <c>gen_statem</c> terminates. However, an exception of class + the <c>gen_statem</c> terminates, unless otherwise stated. + However, an exception of class <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso> - is not regarded as an error but as a valid return. + is not regarded as an error but as a valid return + from all callback functions. </p> <marker id="state_function"/> <p> @@ -127,7 +132,8 @@ erlang:'!' -----> Module:StateName/3 in a <c>gen_statem</c> is the callback function that is called for all events in this state. It is selected depending on which <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> - that the implementation specifies when the server starts. + that the callback module defines with the callback function + <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>. </p> <p> When the @@ -138,9 +144,9 @@ erlang:'!' -----> Module:StateName/3 This gathers all code for a specific state in one function as the <c>gen_statem</c> engine branches depending on state name. - Notice that in this mode the mandatory callback function + Notice the fact that there is a mandatory callback function <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> - makes the state name <c>terminate</c> unusable. + makes the state name <c>terminate</c> unusable in this mode. </p> <p> When the @@ -249,11 +255,10 @@ erlang:'!' -----> Module:StateName/3 -behaviour(gen_statem). -export([start/0,push/0,get_count/0,stop/0]). --export([terminate/3,code_change/4,init/1]). +-export([terminate/3,code_change/4,init/1,callback_mode/0]). -export([on/3,off/3]). name() -> pushbutton_statem. % The registered server name -callback_mode() -> state_functions. %% API. This example uses a registered name name() %% and does not link to the caller. @@ -270,15 +275,14 @@ stop() -> terminate(_Reason, _State, _Data) -> void. code_change(_Vsn, State, Data, _Extra) -> - {callback_mode(),State,Data}. + {ok,State,Data}. init([]) -> - %% Set the callback mode and initial state + data. - %% Data is used only as a counter. + %% Set the initial state + data. Data is used only as a counter. State = off, Data = 0, - {callback_mode(),State,Data}. - + {ok,State,Data}. +callback_mode() -> state_functions. -%%% State functions +%%% State function(s) off({call,From}, push, Data) -> %% Go to 'on', increment count and reply @@ -326,18 +330,13 @@ ok To compare styles, here follows the same example using <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> <c>state_functions</c>, or rather the code to replace - from function <c>init/1</c> of the <c>pushbutton.erl</c> + after function <c>init/1</c> of the <c>pushbutton.erl</c> example file above: </p> <code type="erl"> -init([]) -> - %% Set the callback mode and initial state + data. - %% Data is used only as a counter. - State = off, Data = 0, - {handle_event_function,State,Data}. - +callback_mode() -> handle_event_function. -%%% Event handling +%%% State function(s) handle_event({call,From}, push, off, Data) -> %% Go to 'on', increment count and reply @@ -426,8 +425,8 @@ handle_event(_, _, State, Data) -> <desc> <p> Debug option that can be used when starting - a <c>gen_statem</c> server through, for example, - <seealso marker="#enter_loop/5"><c>enter_loop/5</c></seealso>. + a <c>gen_statem</c> server through, + <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>. </p> <p> For every entry in <c><anno>Dbgs</anno></c>, @@ -525,12 +524,9 @@ handle_event(_, _, State, Data) -> <desc> <p> The <em>callback mode</em> is selected when starting the - <c>gen_statem</c> using the return value from - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> - or when calling - <seealso marker="#enter_loop/5"><c>enter_loop/5,6,7</c></seealso>, - and with the return value from - <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso>. + <c>gen_statem</c> and after code change + using the return value from + <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>. </p> <taglist> <tag><c>state_functions</c></tag> @@ -691,7 +687,7 @@ handle_event(_, _, State, Data) -> <seealso marker="#state_function">state function</seealso>, from <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> or by giving them to - <seealso marker="#enter_loop/6"><c>enter_loop/6,7</c></seealso>. + <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. </p> <p> Actions are executed in the containing list order. @@ -923,7 +919,8 @@ handle_event(_, _, State, Data) -> </p> <note> <p> - To avoid getting a late reply in the caller's + For <c><anno>Timeout</anno> =/= infinity</c>, + to avoid getting a late reply in the caller's inbox, this function spawns a proxy process that does the call. A late reply gets delivered to the dead proxy process, hence gets discarded. This is @@ -958,35 +955,36 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="enter_loop" arity="5"/> + <name name="enter_loop" arity="4"/> <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary> <desc> <p> The same as - <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso> - except that no + <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso> + with <c>Actions = []</c> except that no <seealso marker="#type-server_name"><c>server_name()</c></seealso> - must have been registered. + must have been registered. This creates an anonymous server. </p> </desc> </func> <func> - <name name="enter_loop" arity="6"/> + <name name="enter_loop" arity="5"/> <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary> <desc> <p> If <c><anno>Server_or_Actions</anno></c> is a <c>list()</c>, the same as - <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso> + <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso> except that no <seealso marker="#type-server_name"><c>server_name()</c></seealso> must have been registered and <c>Actions = <anno>Server_or_Actions</anno></c>. + This creates an anonymous server. </p> <p> Otherwise the same as - <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso> + <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso> with <c>Server = <anno>Server_or_Actions</anno></c> and <c>Actions = []</c>. @@ -995,7 +993,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="enter_loop" arity="7"/> + <name name="enter_loop" arity="6"/> <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary> <desc> <p> @@ -1015,21 +1013,31 @@ handle_event(_, _, State, Data) -> the <c>gen_statem</c> behavior provides. </p> <p> - <c><anno>Module</anno></c>, <c><anno>Opts</anno></c>, and - <c><anno>Server</anno></c> have the same meanings - as when calling + <c><anno>Module</anno></c>, <c><anno>Opts</anno></c> + have the same meaning as when calling <seealso marker="#start_link/3"><c>start[_link]/3,4</c></seealso>. + </p> + <p> + If <c><anno>Server</anno></c> is <c>self()</c> an anonymous + server is created just as when using + <seealso marker="#start_link/3"><c>start[_link]/3</c></seealso>. + If <c><anno>Server</anno></c> is a + <seealso marker="#type-server_name"><c>server_name()</c></seealso> + a named server is created just as when using + <seealso marker="#start_link/4"><c>start[_link]/4</c></seealso>. However, the <seealso marker="#type-server_name"><c>server_name()</c></seealso> name must have been registered accordingly - <em>before</em> this function is called.</p> + <em>before</em> this function is called. + </p> <p> - <c><anno>CallbackMode</anno></c>, <c><anno>State</anno></c>, - <c><anno>Data</anno></c>, and <c><anno>Actions</anno></c> + <c><anno>State</anno></c>, <c><anno>Data</anno></c>, + and <c><anno>Actions</anno></c> have the same meanings as in the return value of <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>. - Also, the callback module <c><anno>Module</anno></c> - does not need to export an <c>init/1</c> function. + Also, the callback module does not need to export a + <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + function. </p> <p> The function fails if the calling process was not started by a @@ -1253,6 +1261,48 @@ handle_event(_, _, State, Data) -> <funcs> <func> + <name>Module:callback_mode() -> CallbackMode</name> + <fsummary>Update the internal state during upgrade/downgrade.</fsummary> + <type> + <v> + CallbackMode = + <seealso marker="#type-callback_mode">callback_mode()</seealso> + </v> + </type> + <desc> + <p> + This function is called by a <c>gen_statem</c> + when it needs to find out the + <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + of the callback module. The value is cached by <c>gen_statem</c> + for efficiency reasons, so this function is only called + once after server start and after code change, + but before the first + <seealso marker="#state_function">state function</seealso> + is called. More occasions may be added in future versions + of <c>gen_statem</c>. + </p> + <p> + Server start happens either when + <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + returns or when + <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso> + is called. Code change happens when + <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso> + returns. + </p> + <note> + <p> + If this function's body does not consist of solely one of two + possible + <seealso marker="#type-callback_mode">atoms</seealso> + the callback module is doing something strange. + </p> + </note> + </desc> + </func> + + <func> <name>Module:code_change(OldVsn, OldState, OldData, Extra) -> Result </name> @@ -1262,11 +1312,7 @@ handle_event(_, _, State, Data) -> <v> Vsn = term()</v> <v>OldState = NewState = term()</v> <v>Extra = term()</v> - <v>Result = {NewCallbackMode,NewState,NewData} | Reason</v> - <v> - NewCallbackMode = - <seealso marker="#type-callback_mode">callback_mode()</seealso> - </v> + <v>Result = {ok,NewState,NewData} | Reason</v> <v> OldState = NewState = <seealso marker="#type-state">state()</seealso> @@ -1295,21 +1341,6 @@ handle_event(_, _, State, Data) -> <c>Module</c>. If no such attribute is defined, the version is the checksum of the Beam file. </p> - <note> - <p> - If you would dare to change - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> - during release upgrade/downgrade, the upgrade is no problem, - as the new code surely knows what <em>callback mode</em> - it needs. However, for a downgrade this function must - know from argument <c>Extra</c> that comes from the - <seealso marker="sasl:appup"><c>sasl:appup</c></seealso> - file what <em>callback mode</em> the old code did use. - It can also be possible to figure this out - from argument <c>{down,Vsn}</c>, as <c>Vsn</c> - in effect defines the old callback module version. - </p> - </note> <p> <c>OldState</c> and <c>OldData</c> is the internal state of the <c>gen_statem</c>. @@ -1321,31 +1352,32 @@ handle_event(_, _, State, Data) -> <p> If successful, the function must return the updated internal state in an - <c>{NewCallbackMode,NewState,NewData}</c> tuple. + <c>{ok,NewState,NewData}</c> tuple. </p> <p> - If the function returns <c>Reason</c>, the ongoing - upgrade fails and rolls back to the old release.</p> - <p> - This function can use - <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso> - to return <c>Result</c> or <c>Reason</c>. + If the function returns a failure <c>Reason</c>, the ongoing + upgrade fails and rolls back to the old release. + Note that <c>Reason</c> can not be an <c>{ok,_,_}</c> tuple + since that will be regarded as a + <c>{ok,NewState,NewData}</c> tuple, + and that a tuple matching <c>{ok,_}</c> + is an also invalid failure <c>Reason</c>. + It is recommended to use an atom as <c>Reason</c> since + it will be wrapped in an <c>{error,Reason}</c> tuple. </p> </desc> </func> <func> <name>Module:init(Args) -> Result</name> - <fsummary>Initialize process and internal state.</fsummary> + <fsummary> + Optional function for initializing process and internal state. + </fsummary> <type> <v>Args = term()</v> - <v>Result = {CallbackMode,State,Data}</v> - <v> | {CallbackMode,State,Data,Actions}</v> + <v>Result = {ok,State,Data}</v> + <v> | {ok,State,Data,Actions}</v> <v> | {stop,Reason} | ignore</v> - <v> - CallbackMode = - <seealso marker="#type-callback_mode">callback_mode()</seealso> - </v> <v>State = <seealso marker="#type-state">state()</seealso></v> <v> Data = <seealso marker="#type-data">data()</seealso> @@ -1364,7 +1396,7 @@ handle_event(_, _, State, Data) -> <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso> or <seealso marker="#start/3"><c>start/3,4</c></seealso>, - this function is called by the new process to initialize + this optional function is called by the new process to initialize the implementation state and server data. </p> <p> @@ -1373,11 +1405,8 @@ handle_event(_, _, State, Data) -> </p> <p> If the initialization is successful, the function is to - return <c>{CallbackMode,State,Data}</c> or - <c>{CallbackMode,State,Data,Actions}</c>. - <c>CallbackMode</c> selects the - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> - of the <c>gen_statem</c>. + return <c>{ok,State,Data}</c> or + <c>{ok,State,Data,Actions}</c>. <c>State</c> is the initial <seealso marker="#type-state"><c>state()</c></seealso> and <c>Data</c> the initial server @@ -1395,11 +1424,16 @@ handle_event(_, _, State, Data) -> or <c>ignore</c>; see <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>. </p> - <p> - This function can use - <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso> - to return <c>Result</c>. - </p> + <note> + <p> + This callback is optional, so a callback module does not need + to export it, but most do. If this function is not exported, + the <c>gen_statem</c> should be started through + <seealso marker="proc_lib"><c>proc_lib</c></seealso> + and + <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>. + </p> + </note> </desc> </func> @@ -1430,10 +1464,14 @@ handle_event(_, _, State, Data) -> This callback is optional, so a callback module does not need to export it. The <c>gen_statem</c> module provides a default implementation of this function that returns - <c>{State,Data}</c>. If this callback fails, the default - function returns <c>{State,Info}</c>, - where <c>Info</c> informs of the crash but no details, - to hide possibly sensitive data. + <c>{State,Data}</c>. + </p> + <p> + If this callback is exported but fails, + to hide possibly sensitive data, + the default function will instead return <c>{State,Info}</c>, + where <c>Info</c> says nothing but the fact that + <c>format_status/2</c> has crashed. </p> </note> <p>This function is called by a <c>gen_statem</c> process when @@ -1494,11 +1532,6 @@ handle_event(_, _, State, Data) -> printed in log files. Another use is to hide sensitive data from being written to the error log. </p> - <p> - This function can use - <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso> - to return <c>Status</c>. - </p> </desc> </func> @@ -1573,9 +1606,12 @@ handle_event(_, _, State, Data) -> see <seealso marker="#type-action"><c>action()</c></seealso>. </p> <p> - These functions can use - <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso>, - to return the result. + Note the fact that you can use + <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso> + to return the result, which can be useful. + For example to bail out with <c>throw(keep_state_and_data)</c> + from deep within complex code that is in no position to + return <c>{next_state,State,Data}</c>. </p> </desc> </func> @@ -1648,11 +1684,6 @@ handle_event(_, _, State, Data) -> and an error report is issued using <seealso marker="kernel:error_logger#format/2"><c>error_logger:format/2</c></seealso>. </p> - <p> - This function can use - <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso> - to return <c>Ignored</c>, which is ignored anyway. - </p> </desc> </func> </funcs> diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 87f5335723..d8fec1147f 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,6 +31,335 @@ </header> <p>This document describes the changes made to the STDLIB application.</p> +<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> |