From e35e6a94e57a651e4837c2391d5b1d3ac57c978b Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Thu, 14 Jul 2016 11:22:49 +0200 Subject: Prepare release --- lib/stdlib/doc/src/notes.xml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index ad2599c5a0..d8fec1147f 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,6 +31,21 @@

This document describes the changes made to the STDLIB application.

+
STDLIB 3.0.1 + +
Fixed Bugs and Malfunctions + + +

Correct a bug regarding typed records in the Erlang + shell. The bug was introduced in OTP-19.0.

+

+ Own Id: OTP-13719 Aux Id: ERL-182

+ + +
+ +
+
STDLIB 3.0
Fixed Bugs and Malfunctions -- cgit v1.2.3 From edd9607b3bea79be718b774b8c58e623b918eee2 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 15 Jul 2016 16:18:06 +0200 Subject: Fix type and template errors from bugs.erlang.org: ERL-172 and ERL-187 --- lib/stdlib/doc/src/gen_statem.xml | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index c57a31fa21..ed44eef912 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -1262,9 +1262,9 @@ handle_event(_, _, State, Data) ->   Vsn = term() OldState = NewState = term() Extra = term() - Result = {NewCallbackMode,NewState,NewData} | Reason + Result = {CallbackMode,NewState,NewData} | Reason - NewCallbackMode = + CallbackMode = callback_mode() @@ -1321,11 +1321,19 @@ handle_event(_, _, State, Data) ->

If successful, the function must return the updated internal state in an - {NewCallbackMode,NewState,NewData} tuple. + {CallbackMode,NewState,NewData} tuple.

- If the function returns Reason, the ongoing - upgrade fails and rolls back to the old release.

+ If the function returns a failure Reason, the ongoing + upgrade fails and rolls back to the old release. + Note that Reason can not be a 3-tuple since that + will be regarded as a + {CallbackMode,NewState,NewData} tuple, + and that a tuple matching {ok,_} + is an invalid failure Reason. + It is recommended to use an atom as Reason since + it will be wrapped in an {error,Reason} tuple. +

This function can use erlang:throw/1 -- cgit v1.2.3 From 259c8c7bde51f0b25707f0101195aff22650e952 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Wed, 27 Jul 2016 14:41:45 +0200 Subject: Rewrite gen_statem docs for M:callback_mode/0 --- lib/stdlib/doc/src/gen_statem.xml | 203 +++++++++++++++++++++++--------------- 1 file changed, 121 insertions(+), 82 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index ed44eef912..f18c1087ab 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 @@ -127,7 +130,8 @@ erlang:'!' -----> Module:StateName/3 in a gen_statem is the callback function that is called for all events in this state. It is selected depending on which callback mode - that the implementation specifies when the server starts. + that the callback module defines with the callback function + Module:callback_mode/0.

When the @@ -138,9 +142,9 @@ erlang:'!' -----> Module:StateName/3 This gathers all code for a specific state in one function as the gen_statem 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 Module:terminate/3 - makes the state name terminate unusable. + makes the state name terminate unusable in this mode.

When the @@ -249,11 +253,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 +273,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 +328,13 @@ ok To compare styles, here follows the same example using callback mode state_functions, or rather the code to replace - from function init/1 of the pushbutton.erl + after function init/1 of the pushbutton.erl example file above:

-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 +423,8 @@ handle_event(_, _, State, Data) ->

Debug option that can be used when starting - a gen_statem server through, for example, - enter_loop/5. + a gen_statem server through, + enter_loop/4-6.

For every entry in Dbgs, @@ -525,12 +522,9 @@ handle_event(_, _, State, Data) ->

The callback mode is selected when starting the - gen_statem using the return value from - Module:init/1 - or when calling - enter_loop/5,6,7, - and with the return value from - Module:code_change/4. + gen_statem and after code change + using the return value from + Module:callback_mode/0.

state_functions @@ -691,7 +685,7 @@ handle_event(_, _, State, Data) -> state function, from Module:init/1 or by giving them to - enter_loop/6,7. + enter_loop/5,6.

Actions are executed in the containing list order. @@ -958,35 +952,36 @@ handle_event(_, _, State, Data) -> - + Enter the gen_statem receive loop.

The same as - enter_loop/7 - except that no + enter_loop/6 + with Actions = [] except that no server_name() - must have been registered. + must have been registered. This creates an anonymous server.

- + Enter the gen_statem receive loop.

If Server_or_Actions is a list(), the same as - enter_loop/7 + enter_loop/6 except that no server_name() must have been registered and Actions = Server_or_Actions. + This creates an anonymous server.

Otherwise the same as - enter_loop/7 + enter_loop/6 with Server = Server_or_Actions and Actions = []. @@ -995,7 +990,7 @@ handle_event(_, _, State, Data) -> - + Enter the gen_statem receive loop.

@@ -1015,21 +1010,31 @@ handle_event(_, _, State, Data) -> the gen_statem behavior provides.

- Module, Opts, and - Server have the same meanings - as when calling + Module, Opts + have the same meaning as when calling start[_link]/3,4. +

+

+ If Server is self() an anonymous + server is created just as when using + start[_link]/3. + If Server is a + server_name() + a named server is created just as when using + start[_link]/4. However, the server_name() name must have been registered accordingly - before this function is called.

+ before this function is called. +

- CallbackMode, State, - Data, and Actions + State, Data, + and Actions have the same meanings as in the return value of Module:init/1. - Also, the callback module Module - does not need to export an init/1 function. + Also, the callback module does not need to export a + Module:init/1 + function.

The function fails if the calling process was not started by a @@ -1252,6 +1257,54 @@ handle_event(_, _, State, Data) ->

+ + Module:callback_mode() -> CallbackMode + Update the internal state during upgrade/downgrade. + + + CallbackMode = + callback_mode() + + + +

+ This function is called by a gen_statem + when it needs to find out the + callback mode + of the callback module. The value is cached by gen_statem + for efficiency reasons, so this function is only called + once after server start and after code change, + but before the first + state function + is called. More occasions may be added in future versions + of gen_statem. +

+

+ Server start happens either when + Module:init/1 + returns or when + enter_loop/4-6 + is called. Code change happens when + Module:code_change/4 + returns. +

+

+ This function can use + erlang:throw/1 + to return CallbackMode, just for symmetry reasons. + There should be no actual reason to use this. +

+ +

+ If this function's body does not consist of solely one of two + possible + atoms + the callback module is doing something strange. +

+ + + + Module:code_change(OldVsn, OldState, OldData, Extra) -> Result @@ -1262,11 +1315,7 @@ handle_event(_, _, State, Data) ->   Vsn = term() OldState = NewState = term() Extra = term() - Result = {CallbackMode,NewState,NewData} | Reason - - CallbackMode = - callback_mode() - + Result = {ok,NewState,NewData} | Reason OldState = NewState = state() @@ -1295,21 +1344,6 @@ handle_event(_, _, State, Data) -> Module. If no such attribute is defined, the version is the checksum of the Beam file.

- -

- If you would dare to change - callback mode - during release upgrade/downgrade, the upgrade is no problem, - as the new code surely knows what callback mode - it needs. However, for a downgrade this function must - know from argument Extra that comes from the - sasl:appup - file what callback mode the old code did use. - It can also be possible to figure this out - from argument {down,Vsn}, as Vsn - in effect defines the old callback module version. -

-

OldState and OldData is the internal state of the gen_statem. @@ -1321,16 +1355,16 @@ handle_event(_, _, State, Data) ->

If successful, the function must return the updated internal state in an - {CallbackMode,NewState,NewData} tuple. + {ok,NewState,NewData} tuple.

If the function returns a failure Reason, the ongoing upgrade fails and rolls back to the old release. - Note that Reason can not be a 3-tuple since that - will be regarded as a - {CallbackMode,NewState,NewData} tuple, + Note that Reason can not be an {ok,_,_} tuple + since that will be regarded as a + {ok,NewState,NewData} tuple, and that a tuple matching {ok,_} - is an invalid failure Reason. + is an also invalid failure Reason. It is recommended to use an atom as Reason since it will be wrapped in an {error,Reason} tuple.

@@ -1344,16 +1378,14 @@ handle_event(_, _, State, Data) -> Module:init(Args) -> Result - Initialize process and internal state. + + Optional function for initializing process and internal state. + Args = term() - Result = {CallbackMode,State,Data} -  | {CallbackMode,State,Data,Actions} + Result = {ok,State,Data} +  | {ok,State,Data,Actions}  | {stop,Reason} | ignore - - CallbackMode = - callback_mode() - State = state() Data = data() @@ -1372,7 +1404,7 @@ handle_event(_, _, State, Data) -> start_link/3,4 or start/3,4, - 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.

@@ -1381,11 +1413,8 @@ handle_event(_, _, State, Data) ->

If the initialization is successful, the function is to - return {CallbackMode,State,Data} or - {CallbackMode,State,Data,Actions}. - CallbackMode selects the - callback mode - of the gen_statem. + return {ok,State,Data} or + {ok,State,Data,Actions}. State is the initial state() and Data the initial server @@ -1408,6 +1437,16 @@ handle_event(_, _, State, Data) -> erlang:throw/1 to return Result.

+ +

+ This callback is optional, so a callback module does not need + to export it, but most do. If this function is not exported, + the gen_statem should be started through + proc_lib + and + enter_loop/4-6. +

+ -- cgit v1.2.3 From 3a60545091d3075e23c4a7af8c18b3641bb084e2 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 9 Aug 2016 08:59:51 +0200 Subject: Doc fixes --- lib/stdlib/doc/src/gen_statem.xml | 56 ++++++++++++++------------------------- 1 file changed, 20 insertions(+), 36 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index f18c1087ab..3322571b2c 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -119,9 +119,11 @@ erlang:'!' -----> Module:StateName/3

If a callback function fails or returns a bad value, - the gen_statem terminates. However, an exception of class + the gen_statem terminates, unless otherwise stated. + However, an exception of class throw - 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.

@@ -917,7 +919,8 @@ handle_event(_, _, State, Data) ->

- To avoid getting a late reply in the caller's + For Timeout =/= infinity, + 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 @@ -1288,12 +1291,6 @@ handle_event(_, _, State, Data) -> Module:code_change/4 returns.

-

- This function can use - erlang:throw/1 - to return CallbackMode, just for symmetry reasons. - There should be no actual reason to use this. -

If this function's body does not consist of solely one of two @@ -1368,11 +1365,6 @@ handle_event(_, _, State, Data) -> It is recommended to use an atom as Reason since it will be wrapped in an {error,Reason} tuple.

-

- This function can use - erlang:throw/1 - to return Result or Reason. -

@@ -1432,11 +1424,6 @@ handle_event(_, _, State, Data) -> or ignore; see start_link/3,4.

-

- This function can use - erlang:throw/1 - to return Result. -

This callback is optional, so a callback module does not need @@ -1477,10 +1464,14 @@ handle_event(_, _, State, Data) -> This callback is optional, so a callback module does not need to export it. The gen_statem module provides a default implementation of this function that returns - {State,Data}. If this callback fails, the default - function returns {State,Info}, - where Info informs of the crash but no details, - to hide possibly sensitive data. + {State,Data}. +

+

+ If this callback is exported but fails, + to hide possibly sensitive data, + the default function will instead return {State,Info}, + where Info says nothing but the fact that + format_status/2 has crashed.

This function is called by a gen_statem process when @@ -1541,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.

-

- This function can use - erlang:throw/1 - to return Status. -

@@ -1620,9 +1606,12 @@ handle_event(_, _, State, Data) -> see action().

- These functions can use - erlang:throw/1, - to return the result. + Note the fact that you can use + throw + to return the result, which can be useful. + For example to bail out with throw(keep_state_and_data) + from deep within complex code that is in no position to + return {next_state,State,Data}.

@@ -1695,11 +1684,6 @@ handle_event(_, _, State, Data) -> and an error report is issued using error_logger:format/2.

-

- This function can use - erlang:throw/1 - to return Ignored, which is ignored anyway. -

-- cgit v1.2.3 From 8b28927aac509704a25a156ca16b799cf5a4d5b3 Mon Sep 17 00:00:00 2001 From: Philip Arndt Date: Sat, 27 Aug 2016 08:16:42 +1000 Subject: Fix typo: specificationc -> specification --- lib/stdlib/doc/src/ets.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') 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]]> specification returned true.

Matches the objects in table Tab using a - match specificationc. If the + match specification. If the match specification returns true 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 -- cgit v1.2.3 From fc69b92df1b6ad6487259ab0e24db9a0c3f3fb77 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Wed, 31 Aug 2016 13:42:02 +0200 Subject: Fix xmllint-warnings --- lib/stdlib/doc/src/queue.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/queue.xml b/lib/stdlib/doc/src/queue.xml index a46ca47033..9f3aff03a3 100644 --- a/lib/stdlib/doc/src/queue.xml +++ b/lib/stdlib/doc/src/queue.xml @@ -401,7 +401,7 @@ - v + Remove the tail item from a queue.

Returns a queue Q2 that is the result of removing -- cgit v1.2.3 From ad6e765bcd4f35a282ef00e38ed9129f3a5c1d83 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 1 Sep 2016 14:32:27 +0200 Subject: doc: Correct errors introduced by Editorial changes Fix some older errors as well. --- lib/stdlib/doc/src/dets.xml | 2 +- lib/stdlib/doc/src/ets.xml | 6 +++--- lib/stdlib/doc/src/notes.xml | 4 ++-- lib/stdlib/doc/src/proc_lib.xml | 4 ++-- lib/stdlib/doc/src/stdlib_app.xml | 8 ++++---- lib/stdlib/doc/src/timer.xml | 2 +- lib/stdlib/doc/src/unicode_usage.xml | 8 ++++---- lib/stdlib/doc/src/zip.xml | 6 +++--- 8 files changed, 20 insertions(+), 20 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/dets.xml b/lib/stdlib/doc/src/dets.xml index 3b134d00b7..2e4261d72e 100644 --- a/lib/stdlib/doc/src/dets.xml +++ b/lib/stdlib/doc/src/dets.xml @@ -391,7 +391,7 @@

{hash, Hash} - Describes which BIF is used to calculate the hash values of the objects stored in the - dets table. Possible values of Hash:

+ Dets table. Possible values of Hash:

hash - Implies that the erlang:hash/2 BIF diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 3653c6a632..5f5d2b7f36 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -369,7 +369,7 @@ variable that in turn is passed to the function.

The parse transform is provided in the ms_transform module and the source must include - file ms_transform.hrl in STDLIB for this + file ms_transform.hrl in STDLIB for this pseudo function to work. Failing to include the hrl file in the source results in a runtime error, not a compile time error. The include file is easiest included by adding line @@ -1644,7 +1644,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]>

Whenever option extended_info is used, it results in a file not readable by versions of ETS before - that in STDLIB 1.15.1

+ that in STDLIB 1.15.1

If option sync is set to true, it ensures that the content of the file is written to the disk before tab2file returns. Defaults to {sync, false}.

@@ -1725,7 +1725,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]>

A tuple {Major,Minor} containing the major and minor version of the file format for ETS table dumps. This - version field was added beginning with STDLIB 1.5.1. + version field was added beginning with STDLIB 1.5.1. Files dumped with older versions return {0,0} in this field.

 diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index d8fec1147f..f0347703e7 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -526,7 +526,7 @@

- The stdlib reference manual is updated to show + The STDLIB reference manual is updated to show correct information about the return value of gen_fsm:reply/2.

@@ -6236,7 +6236,7 @@ documentation for compile on how to provide the key for encrypting, and the documentation for beam_lib on how to provide the key for decryption so that tools such - as the Debugger, xref, or cover can be used.

+ as the Debugger, Xref, or Cover can be used.

The beam_lib:chunks/2 functions now accepts an additional chunk type compile_info to retrieve the compilation information directly as a term. (Thanks diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index 58ca5644cf..da03c39a26 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -59,9 +59,9 @@

When a process that is started using proc_lib terminates abnormally (that is, with another exit reason than normal, shutdown, or {shutdown,Term}), a crash report - is generated, which is written to terminal by the default SASL + is generated, which is written to terminal by the default SASL event handler. That is, the crash report is normally only visible - if the SASL application is started; see + if the SASL application is started; see sasl(6) and section SASL Error Logging in the SASL User's Guide.

diff --git a/lib/stdlib/doc/src/stdlib_app.xml b/lib/stdlib/doc/src/stdlib_app.xml index cde73269a8..f857cc394b 100644 --- a/lib/stdlib/doc/src/stdlib_app.xml +++ b/lib/stdlib/doc/src/stdlib_app.xml @@ -31,14 +31,14 @@ STDLIB The STDLIB application. -

The STDLIB application is mandatory in the sense that the minimal - system based on Erlang/OTP consists of Kernel and STDLIB. - The STDLIB application contains no services.

+

The STDLIB application is mandatory in the sense that the minimal + system based on Erlang/OTP consists of Kernel and STDLIB. + The STDLIB application contains no services.
Configuration -

The following configuration parameters are defined for the STDLIB +

The following configuration parameters are defined for the STDLIB application. For more information about configuration parameters, see the app(4) module in Kernel.

diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml index 8f2ce36b06..fcaccdb2cb 100644 --- a/lib/stdlib/doc/src/timer.xml +++ b/lib/stdlib/doc/src/timer.xml @@ -253,7 +253,7 @@ is needed. This is useful during development, but in a target system the server is to be started explicitly. Use configuration parameters for - Kernel for this.

+ Kernel for this.

diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index 7f79ac88a1..efc8b75075 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -274,8 +274,8 @@ marker="stdlib:io">io module, the file handling, the unicode module, and - the bit syntax). Today most modules in Kernel and - STDLIB, as well as the VM are Unicode-aware.

+ the bit syntax). Today most modules in Kernel and + STDLIB, as well as the VM are Unicode-aware.

File I/O @@ -765,7 +765,7 @@ Eshell V5.10.1 (abort with ^G) file system). The Unicode character list is used to denote filenames or directory names. If the file system content is listed, you also get Unicode lists as return value. The support - lies in the Kernel and STDLIB modules, which is why + lies in the Kernel and STDLIB modules, which is why most applications (that does not explicitly require the filenames to be in the ISO Latin-1 range) benefit from the Unicode support without change.

@@ -843,7 +843,7 @@ Eshell V5.10.1 (abort with ^G) Notes About Raw Filenames

Raw filenames were introduced together with Unicode filename support - in ERTS 5.8.2 (Erlang/OTP R14B01). The reason "raw + in ERTS 5.8.2 (Erlang/OTP R14B01). The reason "raw filenames" were introduced in the system was to be able to represent filenames, specified in different encodings on the same system, diff --git a/lib/stdlib/doc/src/zip.xml b/lib/stdlib/doc/src/zip.xml index de23608046..0b5eac1e16 100644 --- a/lib/stdlib/doc/src/zip.xml +++ b/lib/stdlib/doc/src/zip.xml @@ -138,7 +138,7 @@

File information as in file:read_file_info/1 - in Kernel

+ in Kernel

 comment @@ -345,7 +345,7 @@ prepended to filenames when extracting them from the zip archive. (Acting like - file:set_cwd/1 in Kernel, + file:set_cwd/1 in Kernel, but without changing the global cwd property.)

 @@ -420,7 +420,7 @@ (cwd). This is prepended to filenames when adding them, although not in the zip archive (acting like - file:set_cwd/1 in Kernel, but without + file:set_cwd/1 in Kernel, but without changing the global cwd property.).

{compress, What} -- cgit v1.2.3 From 04c67da5b455416c71fe9bc4c70fe61ceb7aad79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 16 Aug 2016 14:19:59 +0200 Subject: erl_internal: Add add_predefined_functions/1 The sys_pre_expand module used to do a lot more (translate records and funs, for example), but now it does very little. Most of the code is an identify transformation of the abstract format. The identity transformation part of the code must be maintained and kept correct when new forms are added to the abstract format. That adds to the maintance burden. It also adds (slightly) to compilation times. Therefore, we want to eliminate sys_pre_expand, moving all of its (non-identity) transformations to better places. As a preliminary first step, move the code that adds the pre-defined functions (such as module_info/0) to a new function in erl_internal. --- lib/stdlib/doc/src/erl_internal.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/erl_internal.xml b/lib/stdlib/doc/src/erl_internal.xml index cf49df0972..17cd0fb240 100644 --- a/lib/stdlib/doc/src/erl_internal.xml +++ b/lib/stdlib/doc/src/erl_internal.xml @@ -43,6 +43,16 @@ + + + Add code for pre-defined functions. + +

Adds to Forms the code for the standard + pre-defined functions (such as module_info/0) that are + to be included in every module.

+ + + Test for an arithmetic operator. -- cgit v1.2.3 From 44c5d0a729387273a604f687fa2a9d50989f87d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 24 Aug 2016 14:09:46 +0200 Subject: Teach erl_expand_records to translate module-less calls As the next step in eliminating sys_pre_expand, teach erl_expand_records to handle calls without explicit module name. If such call refer to a BIF or imported function, add an explicit module name. That means that any subsequent pass will know that a call without a module name is always to a local function defined in the module. --- lib/stdlib/doc/src/erl_expand_records.xml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/erl_expand_records.xml b/lib/stdlib/doc/src/erl_expand_records.xml index 7e4aa2db37..b6aa75ed03 100644 --- a/lib/stdlib/doc/src/erl_expand_records.xml +++ b/lib/stdlib/doc/src/erl_expand_records.xml @@ -45,8 +45,10 @@ Expand all records in a module. -

Expands all records in a module. The returned module has no - references to records, attributes, or code.

+

Expands all records in a module to use explicit tuple + operations and adds explicit module names to calls to BIFs and + imported functions. The returned module has no references to + records, attributes, or code.

 -- cgit v1.2.3 From 6d40cfd77f1d2f1e1403e4b41c0b53ae6499ea11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Mon, 27 Jun 2016 12:54:04 +0200 Subject: Add math:floor/1 and math:ceil/1 Add math:floor/1 and math:ceil/1 to avoid unnecessary conversions in floating point expressions. That is, instead of having to write float(floor(X)) as part of a floating point expressions, we can write simply math:floor(X). --- lib/stdlib/doc/src/math.xml | 2 ++ 1 file changed, 2 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/math.xml b/lib/stdlib/doc/src/math.xml index 1358ce5cbf..70ca6ae78e 100644 --- a/lib/stdlib/doc/src/math.xml +++ b/lib/stdlib/doc/src/math.xml @@ -57,9 +57,11 @@ + + -- cgit v1.2.3 From f986565050ac30075ef3c0a451bf6dad91c7c446 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 13 Sep 2016 11:15:32 +0200 Subject: Implement call/3 dirty_timeout --- lib/stdlib/doc/src/gen_statem.xml | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 3322571b2c..17f1526a21 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -919,18 +919,40 @@ handle_event(_, _, State, Data) ->

- For Timeout =/= infinity, + For Timeout < infinity, to avoid getting a late reply in the caller's - inbox, this function spawns a proxy process that + inbox if the caller should catch exceptions, + 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 less efficient than using - Timeout =:= infinity. + Timeout == infinity.

- The call can fail, for example, if the gen_statem dies - before or during this function call. + Timeout can also be a tuple + {clean_timeout,T} or + {dirty_timeout,T}, where + T is the timeout time. + {clean_timeout,T} works like + just T described in the note above + and uses a proxy process for T < infinity, + while {dirty_timeout,T} + bypasses the proxy process which is more lightweight. +

+ +

+ If you combine catching exceptions from this function + with {dirty_timeout,T} + to avoid that the calling process dies when the call + times out, you will have to be prepared to handle + a late reply. + So why not just allow the calling process to die? +

+ +

+ The call can also fail, for example, if the gen_statem + dies before or during this function call.

-- cgit v1.2.3 From 6ee0aefd8a0ea9c165211c42d5244182b5aa9210 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 13 Sep 2016 14:00:04 +0200 Subject: Implement state entry events --- lib/stdlib/doc/src/gen_statem.xml | 82 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 76 insertions(+), 6 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 17f1526a21..a4c5438a08 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -70,6 +70,7 @@ The state can be any term. Events can be postponed. Events can be self-generated. + Automatic state entry events can be generated. A reply can be sent from a later state. There can be multiple sys traceable replies. @@ -193,6 +194,12 @@ erlang:'!' -----> Module:StateName/3 gen_fsm to force processing an inserted event before others.

+

+ The gen_statem engine can automatically insert + a special event whenever a new state is entered; see + state_entry_mode(). + This makes it easy to handle code common to all state entries. +

If you in gen_statem, for example, postpone an event in one state and then call another state function @@ -515,7 +522,7 @@ handle_event(_, _, State, Data) -> Type info originates from regular process messages sent to the gen_statem. Also, the state machine implementation can generate events of types - timeout and internal to itself. + timeout, enter and internal to itself.

@@ -550,6 +557,34 @@ handle_event(_, _, State, Data) -> + + + +

+ The state entry mode is selected when starting the + gen_statem and after code change + using the return value from + Module:callback_mode/0. +

+

+ If + Module:callback_mode/0 + returns a list containing state_entry_events, + the gen_statem engine will, at every state change, + insert an event of type + enter + with content OldState. This event will be inserted + before all other events such as those generated by + action() + next_event. +

+

+ If + Module:callback_mode/0 + does not return such a list, no state entry events are inserted. +

+ + @@ -590,6 +625,16 @@ handle_event(_, _, State, Data) -> all other events.

+ +

+ If the state changes or is the initial state, and the + state entry mode + is state_entry_events, an event of type + enter + with content OldState is inserted + to be processed before all other events including those above. +

+

If an @@ -1288,7 +1333,9 @@ handle_event(_, _, State, Data) -> CallbackMode = - callback_mode() + callback_mode() | + [ callback_mode() + | state_entry_events ] @@ -1313,12 +1360,35 @@ handle_event(_, _, State, Data) -> Module:code_change/4 returns.

+

+ The CallbackMode is either just + callback_mode() + or a list containing + callback_mode() + and possibly the atom + state_entry_events. +

+

+ If the atom state_entry_events is present in the list, + the gen_statem engine will, at every state change, + insert an event of type + enter + with content OldState. This event will be inserted + before all other events such as those generated by + action() + next_event. +

+

+ No state entry event will be inserted after a + Module:code_change/4 + since transforming the state to a newer version is regarded + as staying in the same state even if the newer version state + should have a different name. +

- If this function's body does not consist of solely one of two - possible - atoms - the callback module is doing something strange. + If this function's body does not return an inline constant + value the callback module is doing something strange.

-- cgit v1.2.3 From 4ebdabdca2c964887115f21405993f3916843d10 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 16 Sep 2016 10:15:22 +0200 Subject: Improve docs --- lib/stdlib/doc/src/gen_statem.xml | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index a4c5438a08..944e9ab13b 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -583,6 +583,20 @@ handle_event(_, _, State, Data) -> Module:callback_mode/0 does not return such a list, no state entry events are inserted.

+

+ No state entry event will be inserted after a + Module:code_change/4 + since transforming the state to a newer version is regarded + as staying in the same state even if the newer version state + should have a different name. +

+

+ Note that a state entry event will be inserted + when entering the initial state even though this formally + is not a state change. In this case OldState + will be the same as State, which can not happen + for an actual state change. +

@@ -1335,7 +1349,7 @@ handle_event(_, _, State, Data) -> CallbackMode = callback_mode() | [ callback_mode() - | state_entry_events ] + | state_entry_events ] @@ -1368,23 +1382,6 @@ handle_event(_, _, State, Data) -> and possibly the atom state_entry_events.

-

- If the atom state_entry_events is present in the list, - the gen_statem engine will, at every state change, - insert an event of type - enter - with content OldState. This event will be inserted - before all other events such as those generated by - action() - next_event. -

-

- No state entry event will be inserted after a - Module:code_change/4 - since transforming the state to a newer version is regarded - as staying in the same state even if the newer version state - should have a different name. -

If this function's body does not return an inline constant -- cgit v1.2.3 From 37e14c395a0d3621d65552b3954856d1cbeaed9a Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Tue, 20 Sep 2016 09:36:54 +0200 Subject: Prepare release --- lib/stdlib/doc/src/notes.xml | 60 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index f0347703e7..554150380f 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,6 +31,66 @@

This document describes the changes made to the STDLIB application.

+
STDLIB 3.1 + +
Fixed Bugs and Malfunctions + + +

+ The zip:unzip/1,2 and zip:extract/1,2 + 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, cwd, will instead be extracted + in cwd. An error message is printed for any such + element in the zip file during the unzip operation. The + keep_old_files option determines if a file will + overwrite a previous file with the same name within the + zip file.

+

+ Own Id: OTP-13633

+ + +

Correct the contracts for + ets:match_object/1,3.

+

+ Own Id: OTP-13721 Aux Id: PR-1113

+ + +

+ Errors in type specification and Emacs template + generation for gen_statem:code_change/4 has been + fixed from bugs.erlang.org's Jira cases ERL-172 and + ERL-187.

+

+ Own Id: OTP-13746 Aux Id: ERL-172, ERL-187

+ + +
+ + +
Improvements and New Features + + +

+ 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.

+

+ Exception handling from Module:init/1 has also been + improved.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-13752

+ + +
+ +
+
STDLIB 3.0.1
Fixed Bugs and Malfunctions -- cgit v1.2.3 From 04d40c5cd18aca449606c19608e8044f593ee99e Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 22 Sep 2016 17:40:47 +0200 Subject: Change state entry events into state enter calls --- lib/stdlib/doc/src/gen_statem.xml | 305 ++++++++++++++++++++++++++++---------- 1 file changed, 226 insertions(+), 79 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 944e9ab13b..aa34f53d29 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -54,7 +54,8 @@

This is a new behavior in Erlang/OTP 19.0. It has been thoroughly reviewed, is stable enough - to be used by at least two heavy OTP applications, and is here to stay. + to be used by at least two heavy OTP applications, + and is here to stay. Depending on user feedback, we do not expect but can find it necessary to make minor not backward compatible changes into Erlang/OTP 20.0. @@ -70,7 +71,7 @@ The state can be any term. Events can be postponed. Events can be self-generated. - Automatic state entry events can be generated. + Automatic state enter code can be called. A reply can be sent from a later state. There can be multiple sys traceable replies. @@ -195,10 +196,14 @@ erlang:'!' -----> Module:StateName/3 to force processing an inserted event before others.

- The gen_statem engine can automatically insert - a special event whenever a new state is entered; see - state_entry_mode(). - This makes it easy to handle code common to all state entries. + The gen_statem engine can automatically + make a specialized call to the + state function + whenever a new state is entered; see + state_enter(). + This is for writing code common to all state entries. + Another way to do it is to insert events at state transitions, + but you have to do so everywhere it is needed.

If you in gen_statem, for example, postpone @@ -526,6 +531,20 @@ handle_event(_, _, State, Data) ->

+ + + +

+ This is the return type from + Module:callback_mode/0 + and selects + callback mode + and whether to do + state enter calls, + or not. +

+ + @@ -558,44 +577,48 @@ handle_event(_, _, State, Data) -> - +

- The state entry mode is selected when starting the - gen_statem and after code change - using the return value from + If the state machine should use state enter calls + is selected when starting the gen_statem + and after code change using the return value from Module:callback_mode/0.

If Module:callback_mode/0 - returns a list containing state_entry_events, + returns a list containing state_enter, the gen_statem engine will, at every state change, - insert an event of type - enter - with content OldState. This event will be inserted - before all other events such as those generated by - action() - next_event. + call the + state function + with arguments (enter, OldState, Data). + This may look like an event but is really a call + performed after the previous state function returned + and before any event is delivered to the new state function. + See + Module:StateName/3 + and + Module:handle_event/4.

If Module:callback_mode/0 - does not return such a list, no state entry events are inserted. + does not return such a list, no state enter calls are done.

- No state entry event will be inserted after a + If Module:code_change/4 - since transforming the state to a newer version is regarded - as staying in the same state even if the newer version state - should have a different name. + should transform the state to a state with a different + name it is still regarded as the same state so this + does not cause a state enter call.

- Note that a state entry event will be inserted - when entering the initial state even though this formally - is not a state change. In this case OldState - will be the same as State, which can not happen - for an actual state change. + Note that a state enter call will be done + right before entering the initial state even though this + formally is not a state change. + In this case OldState will be the same as State, + which can not happen for a subsequent state change.

@@ -605,8 +628,7 @@ handle_event(_, _, State, Data) ->

Transition options can be set by actions - and they modify the following in how - the state transition is done: + and they modify how the state transition is done:

@@ -636,17 +658,22 @@ handle_event(_, _, State, Data) -> action() next_event are inserted in the queue to be processed before - all other events. + other events.

- If the state changes or is the initial state, and the - state entry mode - is state_entry_events, an event of type - enter - with content OldState is inserted - to be processed before all other events including those above. + If the state changes or is the initial state, and + state enter calls + are used, the gen_statem calls + the new state function with arguments + (enter, OldState, Data). + If this call returns any + actions + that sets transition options + they are merged with the current + That is: hibernate and timeout overrides + the current and reply sends a reply.

@@ -656,8 +683,9 @@ handle_event(_, _, State, Data) -> is set through action() timeout, - an event timer can be started or a time-out zero event - can be enqueued. + an event timer is started if the value is less than + infinity or a time-out zero event + is enqueued if the value is zero.

@@ -732,7 +760,7 @@ handle_event(_, _, State, Data) -> is processed before any not yet received external event.

- Notice that it is not possible or needed to cancel this time-out, + Note that it is not possible or needed to cancel this time-out, as it is cancelled automatically by any other event.

@@ -743,7 +771,10 @@ handle_event(_, _, State, Data) ->

These state transition actions can be invoked by returning them from the - state function, from + state function + when it is called with an + event, + from Module:init/1 or by giving them to enter_loop/5,6. @@ -757,8 +788,8 @@ handle_event(_, _, State, Data) -> override any previous of the same type, so the last in the containing list wins. For example, the last - event_timeout() - overrides any other event_timeout() in the list. + postpone() + overrides any previous postpone() in the list.

postpone @@ -775,6 +806,53 @@ handle_event(_, _, State, Data) -> as there is no event to postpone in those cases.

+ next_event + +

+ Stores the specified EventType + and EventContent for insertion after all + actions have been executed. +

+

+ The stored events are inserted in the queue as the next to process + before any already queued events. The order of these stored events + is preserved, so the first next_event in the containing + list becomes the first to process. +

+

+ An event of type + internal + is to be used when you want to reliably distinguish + an event inserted this way from any external event. +

+ + + + + + + +

+ These state transition actions can be invoked by + returning them from the + state function, from + Module:init/1 + or by giving them to + enter_loop/5,6. +

+

+ Actions are executed in the containing list order. +

+

+ Actions that set + transition options + override any previous of the same type, + so the last in the containing list wins. + For example, the last + event_timeout() + overrides any previous event_timeout() in the list. +

+ hibernate

@@ -805,32 +883,6 @@ handle_event(_, _, State, Data) -> to Time with EventContent.

- reply_action() - -

- Replies to a caller. -

- - next_event - -

- Stores the specified EventType - and EventContent for insertion after all - actions have been executed. -

-

- The stored events are inserted in the queue as the next to process - before any already queued events. The order of these stored events - is preserved, so the first next_event in the containing - list becomes the first to process. -

-

- An event of type - internal - is to be used when you want to reliably distinguish - an event inserted this way from any external event. -

- @@ -838,13 +890,31 @@ handle_event(_, _, State, Data) ->

- Replies to a caller waiting for a reply in + This state transition action can be invoked by + returning it from the + state function, from + Module:init/1 + or by giving it to + enter_loop/5,6. +

+

+ It replies to a caller waiting for a reply in call/2. From must be the term from argument {call,From} - to the + in a call to a state function.

+

+ Note that using this action from + Module:init/1 + or + enter_loop/5,6 + would be weird on the border of whichcraft + since there has been no earlier call to a + state function + in this server. +

@@ -868,6 +938,27 @@ handle_event(_, _, State, Data) ->

+ + + + + next_state + +

+ The gen_statem does a state transition to + NextStateName + (which can be the same as the current state), + sets NewData, + and executes all Actions. +

+ + +

+ All these terms are tuples or atoms and this property + will hold in any future version of gen_statem. +

+ + @@ -889,6 +980,27 @@ handle_event(_, _, State, Data) ->

+ + + + + next_state + +

+ The gen_statem does a state transition to + NextState + (which can be the same as the current state), + sets NewData, + and executes all Actions. +

+ + +

+ All these terms are tuples or atoms and this property + will hold in any future version of gen_statem. +

+ + @@ -1148,10 +1260,11 @@ handle_event(_, _, State, Data) -> {call,From} to the state function. - From and Reply - can also be specified using a - reply_action() - and multiple replies with a list of them. + A reply or multiple replies canalso be sent + using one or several + reply_action()s + from a + state function.

@@ -1362,7 +1475,8 @@ handle_event(_, _, State, Data) -> once after server start and after code change, but before the first state function - is called. More occasions may be added in future versions + in the current code version is called. + More occasions may be added in future versions of gen_statem.

@@ -1380,7 +1494,7 @@ handle_event(_, _, State, Data) -> or a list containing callback_mode() and possibly the atom - state_entry_events. + state_enter.

@@ -1601,7 +1715,8 @@ handle_event(_, _, State, Data) ->

The function is to return Status, a term that - changes the details of the current state and status of + contains the appropriate details + of the current state and status of the gen_statem. There are no restrictions on the form Status can take, but for the sys:get_status/1,2 @@ -1625,11 +1740,17 @@ handle_event(_, _, State, Data) -> + Module:StateName(enter, OldState, Data) -> + StateFunctionEnterResult + Module:StateName(EventType, EventContent, Data) -> StateFunctionResult - Module:handle_event(EventType, EventContent, - State, Data) -> HandleEventResult + Module:handle_event(enter, OldState, State, Data) -> + HandleEventResult + + Module:handle_event(EventType, EventContent, State, Data) -> + HandleEventResult Handle an event. @@ -1650,10 +1771,18 @@ handle_event(_, _, State, Data) -> StateFunctionResult = state_function_result() + + StateFunctionEnterResult = + state_function_enter_result() + HandleEventResult = handle_event_result() + + HandleEventEnterResult = + handle_event_enter_result() +

@@ -1694,6 +1823,24 @@ handle_event(_, _, State, Data) -> by gen_statem after returning from this function, see action().

+

+ When the gen_statem runs with + state enter calls, + these functions are also called with arguments + (enter, OldState, ...) whenever the state changes. + In this case there are some restrictions on the + actions + that may be returned: + postpone() + and + {next_event,_,_} + are not allowed. + You may also not change states from this call. + Should you return {next_state,NextState, ...} + with NextState =/= State the gen_statem crashes. + You are advised to use {keep_state,...} or + keep_state_and_data. +

Note the fact that you can use throw -- cgit v1.2.3 From 800265f49f912dcf66846b13aa8032bf2f380caf Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 30 Sep 2016 11:17:22 +0200 Subject: Improve docs and types --- lib/stdlib/doc/src/gen_statem.xml | 77 +++++++++++++++++++++++++++++++-------- 1 file changed, 62 insertions(+), 15 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index aa34f53d29..bba2de5e77 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -674,6 +674,9 @@ handle_event(_, _, State, Data) -> they are merged with the current That is: hibernate and timeout overrides the current and reply sends a reply. + This has the same effect as if you would have appended + the actions from this state enter call to the actions + returned by the state function that changed states.

@@ -1002,28 +1005,42 @@ handle_event(_, _, State, Data) -> - + - stop + keep_state

- Terminates the gen_statem by calling - Module:terminate/3 - with Reason and - NewData, if specified. + The gen_statem keeps the current state, or + does a state transition to the current state if you like, + sets NewData, + and executes all Actions. + This is the same as + {next_state,CurrentState,NewData,Actions}.

- stop_and_reply + keep_state_and_data

- Sends all Replies, - then terminates the gen_statem by calling - Module:terminate/3 - with Reason and - NewData, if specified. + The gen_statem keeps the current state or + does a state transition to the current state if you like, + keeps the current server data, + and executes all Actions. + This is the same as + {next_state,CurrentState,CurrentData,Actions}.

+ +

+ All these terms are tuples or atoms and this property + will hold in any future version of gen_statem. +

+ + + + + + keep_state

@@ -1053,6 +1070,36 @@ handle_event(_, _, State, Data) ->

+ + + + + stop + +

+ Terminates the gen_statem by calling + Module:terminate/3 + with Reason and + NewData, if specified. +

+ + stop_and_reply + +

+ Sends all Replies, + then terminates the gen_statem by calling + Module:terminate/3 + with Reason and + NewData, if specified. +

+ + +

+ All these terms are tuples or atoms and this property + will hold in any future version of gen_statem. +

+ + @@ -1462,7 +1509,7 @@ handle_event(_, _, State, Data) -> CallbackMode = callback_mode() | [ callback_mode() - | state_entry_events ] + | state_enter() ] @@ -1490,9 +1537,9 @@ handle_event(_, _, State, Data) ->

The CallbackMode is either just - callback_mode() + callback_mode() or a list containing - callback_mode() + callback_mode() and possibly the atom state_enter.

-- cgit v1.2.3 From 77e175589b0ee3c1a4c94aef3cdcdf54cd84c53c Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 30 Sep 2016 18:00:38 +0200 Subject: Implement state timeouts --- lib/stdlib/doc/src/gen_statem.xml | 105 ++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 32 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index bba2de5e77..c0631c8448 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -527,7 +527,8 @@ handle_event(_, _, State, Data) -> Type info originates from regular process messages sent to the gen_statem. Also, the state machine implementation can generate events of types - timeout, enter and internal to itself. + timeout, state_timeout, enter, + and internal to itself.

@@ -657,8 +658,7 @@ handle_event(_, _, State, Data) -> All events stored with action() next_event - are inserted in the queue to be processed before - other events. + are inserted to be processed before the other queued events.

@@ -668,35 +668,36 @@ handle_event(_, _, State, Data) -> are used, the gen_statem calls the new state function with arguments (enter, OldState, Data). - If this call returns any + Any actions - that sets transition options - they are merged with the current - That is: hibernate and timeout overrides - the current and reply sends a reply. - This has the same effect as if you would have appended - the actions from this state enter call to the actions + returned from this call are handled as if they were + appended to the actions returned by the state function that changed states.

- If an - event_timeout() - is set through - action() - timeout, - an event timer is started if the value is less than - infinity or a time-out zero event - is enqueued if the value is zero. + If there are enqueued events the (possibly new) + state function + is called with the oldest enqueued event, + and we start again from the top of this list.

- The (possibly new) + Timeout timers + state_timeout() + and + event_timeout() + are handled. This may lead to a time-out zero event + being generated to the state function - is called with the oldest enqueued event if there is any, - otherwise the gen_statem goes into receive + and we start again from the top of this list. +

+ + +

+ Otherwise the gen_statem goes into receive or hibernation (if hibernate() @@ -704,8 +705,11 @@ handle_event(_, _, State, Data) -> to wait for the next message. In hibernation the next non-system event awakens the gen_statem, or rather the next incoming message awakens the gen_statem, - but if it is a system event - it goes right back into hibernation. + but if it is a system event it goes right back into hibernation. + When a new message arrives the + state function + is called with the corresponding event, + and we start again from the top of this list.

@@ -747,20 +751,20 @@ handle_event(_, _, State, Data) -> event_type() timeout after this time (in milliseconds) unless another - event arrives in which case this time-out is cancelled. - Notice that a retried or inserted event - counts like a new in this respect. + event arrives or has arrived + in which case this time-out is cancelled. + Note that a retried, inserted or state time-out zero + events counts as arrived.

If the value is infinity, no timer is started, as - it never triggers anyway. + it never would trigger anyway.

- If the value is 0, the time-out event is immediately enqueued - unless there already are enqueued events, as the - time-out is then immediately cancelled. - This is a feature ensuring that a time-out 0 event - is processed before any not yet received external event. + If the value is 0 no timer is actually started, + instead the the time-out event is enqueued to ensure + that it gets processed before any not yet + received external event.

Note that it is not possible or needed to cancel this time-out, @@ -768,6 +772,34 @@ handle_event(_, _, State, Data) ->

+ + + +

+ Generates an event of + event_type() + state_timeout + after this time (in milliseconds) unless the gen_statem + changes states (NewState =/= OldState) + which case this time-out is cancelled. +

+

+ If the value is infinity, no timer is started, as + it never would trigger anyway. +

+

+ If the value is 0 no timer is actually started, + instead the the time-out event is enqueued to ensure + that it gets processed before any not yet + received external event. +

+

+ Setting this timer while it is running will restart it with + the new time-out value. Therefore it is possible to cancel + this timeout by setting it to infinity. +

+ + @@ -886,6 +918,15 @@ handle_event(_, _, State, Data) -> to Time with EventContent.

+ state_timeout + +

+ Sets the + transition_option() + state_timeout() + to Time with EventContent. +

+ -- cgit v1.2.3 From f4de3f5887be010db178a178e1f20027f3e5d22b Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Wed, 12 Oct 2016 17:49:26 +0200 Subject: Use parameterized types --- lib/stdlib/doc/src/gen_statem.xml | 216 ++++++++++++++------------------------ 1 file changed, 77 insertions(+), 139 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index c0631c8448..64267c2af5 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -127,9 +127,9 @@ erlang:'!' -----> Module:StateName/3 is not regarded as an error but as a valid return from all callback functions.

- +

- The "state function" for a specific + The "state callback" for a specific state in a gen_statem is the callback function that is called for all events in this state. It is selected depending on which @@ -141,7 +141,7 @@ erlang:'!' -----> Module:StateName/3 When the callback mode is state_functions, the state must be an atom and - is used as the state function name; see + is used as the state callback name; see Module:StateName/3. This gathers all code for a specific state in one function as the gen_statem engine @@ -154,7 +154,7 @@ erlang:'!' -----> Module:StateName/3 When the callback mode is handle_event_function, the state can be any term - and the state function name is + and the state callback name is Module:handle_event/4. This makes it easy to branch depending on state or event as you desire. Be careful about which events you handle in which @@ -164,8 +164,8 @@ erlang:'!' -----> Module:StateName/3

The gen_statem enqueues incoming events in order of arrival and presents these to the - state function - in that order. The state function can postpone an event + state callback + in that order. The state callback can postpone an event so it is not retried in the current state. After a state change the queue restarts with the postponed events.

@@ -177,12 +177,12 @@ erlang:'!' -----> Module:StateName/3 to entering a new receive statement.

- The state function + The state callback can insert events using the action() next_event and such an event is inserted as the next to present - to the state function. That is, as if it is + to the state callback. That is, as if it is the oldest incoming event. A dedicated event_type() internal can be used for such events making them impossible @@ -198,7 +198,7 @@ erlang:'!' -----> Module:StateName/3

The gen_statem engine can automatically make a specialized call to the - state function + state callback whenever a new state is entered; see state_enter(). This is for writing code common to all state entries. @@ -207,7 +207,7 @@ erlang:'!' -----> Module:StateName/3

If you in gen_statem, for example, postpone - an event in one state and then call another state function + an event in one state and then call another state callback of yours, you have not changed states and hence the postponed event is not retried, which is logical but can be confusing.

@@ -236,7 +236,7 @@ erlang:'!' -----> Module:StateName/3 The gen_statem process can go into hibernation; see proc_lib:hibernate/3. It is done when a - state function or + state callback or Module:init/1 specifies hibernate in the returned Actions @@ -294,7 +294,7 @@ init([]) -> {ok,State,Data}. callback_mode() -> state_functions. -%%% State function(s) +%%% state callback(s) off({call,From}, push, Data) -> %% Go to 'on', increment count and reply @@ -348,7 +348,7 @@ ok callback_mode() -> handle_event_function. -%%% State function(s) +%%% state callback(s) handle_event({call,From}, push, off, Data) -> %% Go to 'on', increment count and reply @@ -482,6 +482,10 @@ handle_event(_, _, State, Data) ->

+ If the + callback mode + is handle_event_function, + the state can be any term. After a state change (NextState =/= State), all postponed events are retried.

@@ -495,6 +499,8 @@ handle_event(_, _, State, Data) -> callback mode is state_functions, the state must be of this type. + After a state change (NextState =/= State), + all postponed events are retried.

@@ -592,11 +598,11 @@ handle_event(_, _, State, Data) -> returns a list containing state_enter, the gen_statem engine will, at every state change, call the - state function + state callback with arguments (enter, OldState, Data). This may look like an event but is really a call - performed after the previous state function returned - and before any event is delivered to the new state function. + performed after the previous state callback returned + and before any event is delivered to the new state callback. See Module:StateName/3 and @@ -666,19 +672,19 @@ handle_event(_, _, State, Data) -> If the state changes or is the initial state, and state enter calls are used, the gen_statem calls - the new state function with arguments + the new state callback with arguments (enter, OldState, Data). Any actions returned from this call are handled as if they were appended to the actions - returned by the state function that changed states. + returned by the state callback that changed states.

If there are enqueued events the (possibly new) - state function + state callback is called with the oldest enqueued event, and we start again from the top of this list.

@@ -691,7 +697,7 @@ handle_event(_, _, State, Data) -> event_timeout() are handled. This may lead to a time-out zero event being generated to the - state function + state callback and we start again from the top of this list.

@@ -707,7 +713,7 @@ handle_event(_, _, State, Data) -> the next incoming message awakens the gen_statem, but if it is a system event it goes right back into hibernation. When a new message arrives the - state function + state callback is called with the corresponding event, and we start again from the top of this list.

@@ -806,7 +812,7 @@ handle_event(_, _, State, Data) ->

These state transition actions can be invoked by returning them from the - state function + state callback when it is called with an event, from @@ -870,7 +876,7 @@ handle_event(_, _, State, Data) ->

These state transition actions can be invoked by returning them from the - state function, from + state callback, from Module:init/1 or by giving them to enter_loop/5,6. @@ -903,7 +909,7 @@ handle_event(_, _, State, Data) -> Short for {timeout,Timeout,Timeout}, that is, the time-out message is the time-out time. This form exists to make the - state function + state callback return value {next_state,NextState,NewData,Timeout} allowed like for gen_fsm's Module:StateName/2. @@ -936,7 +942,7 @@ handle_event(_, _, State, Data) ->

This state transition action can be invoked by returning it from the - state function, from + state callback, from Module:init/1 or by giving it to enter_loop/5,6. @@ -947,7 +953,7 @@ handle_event(_, _, State, Data) -> From must be the term from argument {call,From} in a call to a - state function. + state callback.

Note that using this action from @@ -956,77 +962,48 @@ handle_event(_, _, State, Data) -> enter_loop/5,6 would be weird on the border of whichcraft since there has been no earlier call to a - state function + state callback in this server.

- + - - next_state - -

- The gen_statem does a state transition to - NextStateName - (which can be the same as the current state), - sets NewData, - and executes all Actions. -

- -

- All these terms are tuples or atoms and this property - will hold in any future version of gen_statem. + State is the current state + and it can not be changed since the state callback + was called with a + state enter call.

- - - - - next_state

The gen_statem does a state transition to - NextStateName - (which can be the same as the current state), + State, which has to be + the current state, sets NewData, and executes all Actions.

-

- All these terms are tuples or atoms and this property - will hold in any future version of gen_statem. -

- + - - next_state - -

- The gen_statem does a state transition to - NextState - (which can be the same as the current state), - sets NewData, - and executes all Actions. -

- -

- All these terms are tuples or atoms and this property - will hold in any future version of gen_statem. + StateType is + state_name() + if + callback mode + is state_functions, or + state() + if + callback mode + is handle_event_function.

- - - - - next_state @@ -1039,48 +1016,20 @@ handle_event(_, _, State, Data) ->

-

- All these terms are tuples or atoms and this property - will hold in any future version of gen_statem. -

- + - - keep_state - -

- The gen_statem keeps the current state, or - does a state transition to the current state if you like, - sets NewData, - and executes all Actions. - This is the same as - {next_state,CurrentState,NewData,Actions}. -

- - keep_state_and_data - -

- The gen_statem keeps the current state or - does a state transition to the current state if you like, - keeps the current server data, - and executes all Actions. - This is the same as - {next_state,CurrentState,CurrentData,Actions}. -

- -

- All these terms are tuples or atoms and this property - will hold in any future version of gen_statem. + ActionType is + enter_action() + if the state callback was called with a + state enter call + and + action() + if the state callback was called with an event.

- - - - - keep_state @@ -1104,17 +1053,6 @@ handle_event(_, _, State, Data) -> {next_state,CurrentState,CurrentData,Actions}.

- -

- All these terms are tuples or atoms and this property - will hold in any future version of gen_statem. -

- - - - - - stop

@@ -1155,14 +1093,14 @@ handle_event(_, _, State, Data) -> by sending a request and waiting until its reply arrives. The gen_statem calls the - state function with + state callback with event_type() {call,From} and event content Request.

A Reply is generated when a - state function + state callback returns with {reply,From,Reply} as one action(), @@ -1227,7 +1165,7 @@ handle_event(_, _, State, Data) -> ignoring if the destination node or gen_statem does not exist. The gen_statem calls the - state function with + state callback with event_type() cast and event content Msg. @@ -1341,18 +1279,18 @@ handle_event(_, _, State, Data) -> call/2 when the reply cannot be defined in the return value of a - state function. + state callback.

From must be the term from argument {call,From} to the - state function. + state callback. A reply or multiple replies canalso be sent using one or several reply_action()s from a - state function. + state callback.

@@ -1562,7 +1500,7 @@ handle_event(_, _, State, Data) -> for efficiency reasons, so this function is only called once after server start and after code change, but before the first - state function + state callback in the current code version is called. More occasions may be added in future versions of gen_statem. @@ -1707,7 +1645,7 @@ handle_event(_, _, State, Data) -> The Actions are executed when entering the first state just as for a - state function. + state callback.

If the initialization fails, @@ -1829,13 +1767,13 @@ handle_event(_, _, State, Data) -> Module:StateName(enter, OldState, Data) -> - StateFunctionEnterResult + StateEnterResult(StateName) Module:StateName(EventType, EventContent, Data) -> StateFunctionResult Module:handle_event(enter, OldState, State, Data) -> - HandleEventResult + StateEnterResult Module:handle_event(EventType, EventContent, State, Data) -> HandleEventResult @@ -1856,20 +1794,20 @@ handle_event(_, _, State, Data) -> data() - StateFunctionResult = - state_function_result() + StateEnterResult(StateName) = + state_enter_result(StateName) - StateFunctionEnterResult = - state_function_enter_result() + StateFunctionResult = + event_handler_result(state_name()) - HandleEventResult = - handle_event_result() + StateEnterResult = + state_enter_result(state()) - HandleEventEnterResult = - handle_event_enter_result() + HandleEventResult = + event_handler_result(state()) @@ -1888,7 +1826,7 @@ handle_event(_, _, State, Data) -> {call,From}, the caller waits for a reply. The reply can be sent from this or from any other - state function + state callback by returning with {reply,From,Reply} in Actions, in Replies, -- cgit v1.2.3 From 731cee0b06917f7b34b7e75700cb75605d7ebd32 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Sun, 23 Oct 2016 20:46:49 +0200 Subject: Fix doc and type for state enter calls --- lib/stdlib/doc/src/gen_statem.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 64267c2af5..fb1e4e8da2 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -533,7 +533,7 @@ handle_event(_, _, State, Data) -> Type info originates from regular process messages sent to the gen_statem. Also, the state machine implementation can generate events of types - timeout, state_timeout, enter, + timeout, state_timeout, and internal to itself.

@@ -1773,7 +1773,7 @@ handle_event(_, _, State, Data) -> StateFunctionResult Module:handle_event(enter, OldState, State, Data) -> - StateEnterResult + StateEnterResult(State) Module:handle_event(EventType, EventContent, State, Data) -> HandleEventResult @@ -1802,8 +1802,8 @@ handle_event(_, _, State, Data) -> event_handler_result(state_name()) - StateEnterResult = - state_enter_result(state()) + StateEnterResult(State) = + state_enter_result(State) HandleEventResult = -- cgit v1.2.3 From 0b4deedf278273205c9dcd2ed5d0b4b4d4d8fb9d Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 20 Oct 2016 22:28:10 +0200 Subject: Rework timeout handling Handling of timers and timeouts has been cleaned up and generalized. Semantic change regarding state timeout zero: Previously if one state caused a state timeout zero and managed to stay in the same state to insert additional timeout zero(s) in the next state callback invocation, then there would be only one timeout zero event. The mindset was that the machine was faster then the timeout zero. This has changed with the mindset that all state callback invocations should be independent, so now the machine will get one state timeout zero event per started state timeout zero. Note that just using zero timeouts is fairly esoteric... --- lib/stdlib/doc/src/gen_statem.xml | 66 ++++++++++++++++++++++++--------------- 1 file changed, 40 insertions(+), 26 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index fb1e4e8da2..567130875a 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -638,6 +638,20 @@ handle_event(_, _, State, Data) -> and they modify how the state transition is done:

+ +

+ If the state changes or is the initial state, and + state enter calls + are used, the gen_statem calls + the new state callback with arguments + (enter, OldState, Data). + Any + actions + returned from this call are handled as if they were + appended to the actions + returned by the state callback that changed states. +

+

All @@ -667,37 +681,37 @@ handle_event(_, _, State, Data) -> are inserted to be processed before the other queued events.

- -

- If the state changes or is the initial state, and - state enter calls - are used, the gen_statem calls - the new state callback with arguments - (enter, OldState, Data). - Any - actions - returned from this call are handled as if they were - appended to the actions - returned by the state callback that changed states. -

- - -

- If there are enqueued events the (possibly new) - state callback - is called with the oldest enqueued event, - and we start again from the top of this list. -

-

Timeout timers state_timeout() and event_timeout() - are handled. This may lead to a time-out zero event - being generated to the + are handled. Time-outs with zero time are guaranteed to be + delivered to the state machine before any external + not yet received event so if there is such a timeout requested, + the corresponding time-out zero event is enqueued as + the newest event. +

+

+ Any event cancels an + event_timeout() + so a zero time event time-out is only generated + if the event queue is empty. +

+

+ A state change cancels a + state_timeout() + and any new transition option of this type + belongs to the new state. +

+ + +

+ If there are enqueued events the state callback + for the possibly new state + is called with the oldest enqueued event, and we start again from the top of this list.

@@ -802,7 +816,7 @@ handle_event(_, _, State, Data) ->

Setting this timer while it is running will restart it with the new time-out value. Therefore it is possible to cancel - this timeout by setting it to infinity. + this time-out by setting it to infinity.

@@ -1130,7 +1144,7 @@ handle_event(_, _, State, Data) -> Timeout can also be a tuple {clean_timeout,T} or {dirty_timeout,T}, where - T is the timeout time. + T is the time-out time. {clean_timeout,T} works like just T described in the note above and uses a proxy process for T < infinity, -- cgit v1.2.3 From 32485c0499a0893b4fb69c6e26d91b4303cb1cba Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 21 Oct 2016 23:36:26 +0200 Subject: Optimize event timeout Do not start an event timer unless there are no enqueued events. --- lib/stdlib/doc/src/gen_statem.xml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 567130875a..fd498ee82e 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -773,8 +773,9 @@ handle_event(_, _, State, Data) -> after this time (in milliseconds) unless another event arrives or has arrived in which case this time-out is cancelled. - Note that a retried, inserted or state time-out zero - events counts as arrived. + Note that a retried or inserted event counts as arrived. + So does a state time-out zero event, if it was generated + before this timer is requested.

If the value is infinity, no timer is started, as -- cgit v1.2.3 From 9d3a274fd55e5ab4e947b61ee83f83bfc0623eab Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Wed, 26 Oct 2016 12:22:24 +0200 Subject: stdlib: Correct shell_default(3) --- lib/stdlib/doc/src/shell_default.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/shell_default.xml b/lib/stdlib/doc/src/shell_default.xml index 81c99bce10..75bf89ba8d 100644 --- a/lib/stdlib/doc/src/shell_default.xml +++ b/lib/stdlib/doc/src/shell_default.xml @@ -51,7 +51,7 @@

In command one, module lists is called. In command two, no module name is specified. The shell searches module user_default followed by module shell_default for - function foo/1.

+ function c/1.

shell_default is intended for "system wide" customizations to the shell. user_default is intended for -- cgit v1.2.3 From 798f09de48b1a7abe43d54d6fa0377ad15c3f6aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 3 Jun 2016 12:13:09 +0200 Subject: Propagate exceptions fully when using proc_lib This makes proc_lib behaves like a normal process as far as the propagation of exceptions is concerned. Before this commit, the following difference could be observed: 6> spawn_link(fun() -> ssl:send(a,b) end). <0.43.0> 7> flush(). Shell got {'EXIT',<0.43.0>, {function_clause, [{ssl,send,[a,b],[{file,"..."},{line,275}]}]}} ok 8> proc_lib:spawn_link(fun() -> ssl:send(a,b) end). <0.46.0> 9> flush(). Shell got {'EXIT',<0.46.0>,function_clause} After this commit, we get the following instead: 3> flush(). Shell got {'EXIT',<0.61.0>, {function_clause, [{ssl,send,[a,b],[{file,"..."},{line,275}]}, {proc_lib,init_p,3,[{file,"..."},{line,232}]}]}} The stacktrace will show minor differences of course but the form is now the same as without proc_lib. The rationale behind this commit is that: * We now have a single form regardless of how the process was started * We can use the stacktrace to programmatically alter behavior (for example an HTTP server identifying problems in input decoding to send back a generic 400, or a 500 otherwise) * We can access the stacktrace to print it somewhere (for example an HTTP server could send it back to the client when a debug mode is enabled) --- lib/stdlib/doc/src/proc_lib.xml | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index da03c39a26..e64b2ce18a 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -66,6 +66,12 @@ SASL Error Logging in the SASL User's Guide.

+

Unlike in "plain Erlang", proc_lib processes will not generate + error reports, which are written to the terminal by the + emulator and do not require SASL to be started. All exceptions are + converted to exits which are ignored by the default + error_logger handler.

+

The crash report contains the previously stored information, such as ancestors and initial function, the termination reason, and information about other processes that terminate as a result -- cgit v1.2.3 From e21a6c9ec713219b0aa2b2a4224f97e713d7337f Mon Sep 17 00:00:00 2001 From: Guilherme Andrade Date: Tue, 25 Oct 2016 22:05:10 +0100 Subject: Add math:fmod/2 BIF Returns the (floating point) remainder of first argument divided by second argument. --- lib/stdlib/doc/src/math.xml | 1 + 1 file changed, 1 insertion(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/math.xml b/lib/stdlib/doc/src/math.xml index 70ca6ae78e..b4f096217a 100644 --- a/lib/stdlib/doc/src/math.xml +++ b/lib/stdlib/doc/src/math.xml @@ -62,6 +62,7 @@ + -- cgit v1.2.3 From 57746f0707be4fb3e9cde3337015ee555a6a8a99 Mon Sep 17 00:00:00 2001 From: Jxck Date: Tue, 8 Nov 2016 13:53:19 +0900 Subject: fix typo on doc of maps typo --- lib/stdlib/doc/src/maps.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml index e1edbadcd3..8c7270816b 100644 --- a/lib/stdlib/doc/src/maps.xml +++ b/lib/stdlib/doc/src/maps.xml @@ -160,7 +160,7 @@ val1

Example:

> Map = #{"42" => value}. -#{"42"> => value} +#{"42" => value} > maps:is_key("42",Map). true > maps:is_key(value,Map). -- cgit v1.2.3 From ff568b5e818d04048009926a7fa2ea537d2e656d Mon Sep 17 00:00:00 2001 From: Kenji Rikitake Date: Fri, 4 Nov 2016 14:53:10 +0900 Subject: Add jump functions to rand module Jump functions returns the state after performing jump calculation to a rand module internal state, which is equivalent to perform a large number of calls of calculating new states for XorShift*/+ algorithms. This commit add jump functions for exsplus and exs1024 algorithms, and a wrapper function jump/1. The wrapper function will cause error with reason "not_implemented" if the jump function for the algorithm is not implemented. This commit adds following new functionalities: - Add new functions rand:jump/0 and rand:jump/1 - Add the member jump to type alg_handler(), a fun for performing the jump function - Add jump functions for exsplus, equivalent to 2^64 calls - Add jump functions for exs1024, equivalent to 2^512 calls - Revise seed_put/1, seed/1, seed/2 See - Add dummy jump function for exs64 calling erlang:error(not_implemented) - Add jump function test cases as follows: * Add Common Test group reference_jump * Add tests for jump/0 to reference_jump_procdict/1 * Rename tests for jump/1 to reference_jump_state/1 * Rename gen_jump/1 to gen_jump_1/1 * Add Common Tests reference_jump_procdict and reference_jump_state to the group reference_jump - Add jump function documentation This commit also changes the Copyright year for Kenji Rikitake's code from 2015 to 2015-2016. --- lib/stdlib/doc/src/rand.xml | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 1dcc3de000..1364a3277b 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -41,6 +41,11 @@ Sebastiano Vigna. The normal distribution algorithm uses the Ziggurat Method by Marsaglia and Tsang.

+

For some algorithms, jump functions are provided for generating + non-overlapping sequences for parallel computations. + The jump functions perform calculations + equivalent to perform a large number of repeated calls + for calculating new states.

The following algorithms are provided:

@@ -48,14 +53,17 @@ exsplus

Xorshift116+, 58 bits precision and period of 2^116-1

+

Jump function: equivalent to 2^64 calls

 exs64

Xorshift64*, 64 bits precision and a period of 2^64-1

+

Jump function: not available

 exs1024

Xorshift1024*, 64 bits precision and a period of 2^1024-1

+

Jump function: equivalent to 2^512 calls

 @@ -155,6 +163,33 @@ S0 = rand:seed_s(exsplus), + + + Return the seed after performing jump calculation + to the state in the process dictionary. + +

Returns the state + after performing jump calculation + to the state in the process dictionary.

+

This function generates a not_implemented error exception + when the jump function is not implemented for + the algorithm specified in the state + in the process dictionary.

+ + + + + + Return the seed after performing jump calculation. + +

Returns the state after performing jump calculation + to the given state.

+

This function generates a not_implemented error exception + when the jump function is not implemented for + the algorithm specified in the state.

+ + + Return a standard normal distributed random float. -- cgit v1.2.3 From 26b0619b05d36e87849ff249f0e68cf9bfd1d1fd Mon Sep 17 00:00:00 2001 From: Brujo Benavides Date: Thu, 3 Nov 2016 12:59:27 -0300 Subject: Expand on the behavior of supervisors Add additional details on the behavior of supervisors when reaching maximum restart intensity, as stated by @rvirding at [Medium](https://goo.gl/XhwpSL) --- lib/stdlib/doc/src/supervisor.xml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index 294196f746..bb06d3645e 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -133,8 +133,10 @@ sup_flags() = #{strategy => strategy(), % optional map. Assuming the values MaxR for intensity and MaxT for period, then, if more than MaxR restarts occur within MaxT seconds, the supervisor - terminates all child processes and then itself. intensity - defaults to 1 and period defaults to 5.

+ terminates all child processes and then itself. The termination + reason for the supervisor itself in that case will be shutdown. + intensity defaults to 1 and period defaults to + 5.

The type definition of a child specification is as follows:

-- cgit v1.2.3 From b93b7444230ebc358f8b0d64798e65f50a249e5a Mon Sep 17 00:00:00 2001 From: Michal Muskala Date: Wed, 16 Nov 2016 11:54:26 +0100 Subject: Document the ordering used in ordsets and orddicts Right now the exact order of elements is not specified, yet many programs rely on the ordering being the obvious one - erlang term order. It is only beneficial to make this an explicit part of the documentation. --- lib/stdlib/doc/src/orddict.xml | 2 +- lib/stdlib/doc/src/ordsets.xml | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index 076b06fc38..39b43809b6 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -38,7 +38,7 @@

This module provides a Key-Value dictionary. An orddict is a representation of a dictionary, where a list of pairs is used to store the keys and values. The list is - ordered after the keys.

+ ordered after the keys in the Erlang term order.

This module provides the same interface as the dict(3) module diff --git a/lib/stdlib/doc/src/ordsets.xml b/lib/stdlib/doc/src/ordsets.xml index 148281fcf7..7b590932e4 100644 --- a/lib/stdlib/doc/src/ordsets.xml +++ b/lib/stdlib/doc/src/ordsets.xml @@ -39,7 +39,8 @@

Sets are collections of elements with no duplicate elements. An ordset is a representation of a set, where an ordered list is used to store the elements of the set. An ordered list - is more efficient than an unordered list.

+ is more efficient than an unordered list. Elements are ordered + according to the Erlang term order.

This module provides the same interface as the sets(3) module -- cgit v1.2.3 From a4d665795bb744f516e6fe36b97c38e123f8b706 Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Mon, 21 Nov 2016 21:17:21 +0100 Subject: Add shell mm() and lm() functions --- lib/stdlib/doc/src/c.xml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/c.xml b/lib/stdlib/doc/src/c.xml index 92ab59c6b0..55a77d1bc5 100644 --- a/lib/stdlib/doc/src/c.xml +++ b/lib/stdlib/doc/src/c.xml @@ -147,6 +147,15 @@ compile:file(File, Options ++ [report_errors, report_w + + + Loads all modified modules. + +

Reloads all currently loaded modules that have changed on disk (see mm()). + Returns the list of results from calling l(M) for each such M.

+ + + List files in the current directory. @@ -181,6 +190,15 @@ compile:file(File, Options ++ [report_errors, report_w + + + Lists all modified modules. + +

Lists all modified modules. Shorthand for + code:modified_modules/0.

+ + + Memory allocation information. -- cgit v1.2.3 From d2be06f9c113812a1ffd56e0fdc25c28cdbf0abf Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Sat, 29 Oct 2016 17:24:25 +0200 Subject: Add comment-versions of assert macros For all assert macros in assert.hrl, add corresponding versions with an additional last Comment argument, assumed to be chardata. If an exception occurs, it will contain an entry {comment, Comment}, which a reporting tool may pretty-print for better readability. --- lib/stdlib/doc/src/assert_hrl.xml | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/assert_hrl.xml b/lib/stdlib/doc/src/assert_hrl.xml index e2dfc2ab9b..a29f6d6ad7 100644 --- a/lib/stdlib/doc/src/assert_hrl.xml +++ b/lib/stdlib/doc/src/assert_hrl.xml @@ -28,7 +28,7 @@ - assert.hrl.xml + assert.hrl Assert macros.

The include file assert.hrl provides macros for inserting @@ -49,25 +49,33 @@ entries in the Info list are optional; do not rely programatically on any of them being present.

+

Each assert macro has a corresponding version with an extra argument, + for adding comments to assertions. These can for example be printed as + part of error reports, to clarify the meaning of the check that + failed. For example, ?assertEqual(0, fib(0), "Fibonacci is defined + for zero"). The comment text can be any character data (string, + UTF8-binary, or deep list of such data), and will be included in the + error term as {comment, Text}.

+

If the macro NOASSERT is defined when assert.hrl is read by the compiler, the macros are defined as equivalent to the atom - ok. The test is not performed and there is no cost at runtime.

+ ok. The test will not be performed and there is no cost at runtime.

For example, using erlc to compile your modules, the following - disable all assertions:

+ disables all assertions:

erlc -DNOASSERT=true *.erl -

The value of NOASSERT does not matter, only the fact that it is - defined.

+

(The value of NOASSERT does not matter, only the fact that it is + defined.)

A few other macros also have effect on the enabling or disabling of assertions:

-

If NODEBUG is defined, it implies NOASSERT, unless - DEBUG is also defined, which is assumed to take precedence.

+

If NODEBUG is defined, it implies NOASSERT (unless + DEBUG is also defined, which overrides NODEBUG).

If ASSERT is defined, it overrides NOASSERT, that is, the assertions remain enabled.

 @@ -84,16 +92,19 @@ erlc -DNOASSERT=true *.erl Macros assert(BoolExpr) + assert(BoolExpr, Comment)

Tests that BoolExpr completes normally returning true.

 assertNot(BoolExpr) + assertNot(BoolExpr, Comment)

Tests that BoolExpr completes normally returning false.

 assertMatch(GuardedPattern, Expr) + assertMatch(GuardedPattern, Expr, Comment)

Tests that Expr completes normally yielding a value that matches GuardedPattern, for example:

@@ -104,6 +115,7 @@ erlc -DNOASSERT=true *.erl ?assertMatch({bork, X} when X > 0, f()) assertNotMatch(GuardedPattern, Expr) + assertNotMatch(GuardedPattern, Expr, Comment)

Tests that Expr completes normally yielding a value that does not match GuardedPattern.

@@ -111,16 +123,19 @@ erlc -DNOASSERT=true *.erl when part.

 assertEqual(ExpectedValue, Expr) + assertEqual(ExpectedValue, Expr, Comment)

Tests that Expr completes normally yielding a value that is exactly equal to ExpectedValue.

 assertNotEqual(ExpectedValue, Expr) + assertNotEqual(ExpectedValue, Expr, Comment)

Tests that Expr completes normally yielding a value that is not exactly equal to ExpectedValue.

 assertException(Class, Term, Expr) + assertException(Class, Term, Expr, Comment)

Tests that Expr completes abnormally with an exception of type Class and with the associated Term. The assertion fails @@ -130,6 +145,7 @@ erlc -DNOASSERT=true *.erl patterns, as in assertMatch.

 assertNotException(Class, Term, Expr) + assertNotException(Class, Term, Expr, Comment)

Tests that Expr does not evaluate abnormally with an exception of type Class and with the associated Term. @@ -139,14 +155,17 @@ erlc -DNOASSERT=true *.erl be guarded patterns.

 assertError(Term, Expr) + assertError(Term, Expr, Comment)

Equivalent to assertException(error, Term, Expr)

 assertExit(Term, Expr) + assertExit(Term, Expr, Comment)

Equivalent to assertException(exit, Term, Expr)

 assertThrow(Term, Expr) + assertThrow(Term, Expr, Comment)

Equivalent to assertException(throw, Term, Expr)

 -- cgit v1.2.3 From 4c8df9e1c898876865f557681371b52baab970e9 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Tue, 22 Nov 2016 15:50:50 +0100 Subject: stdlib: Remove support for Dets version 8 tables When at it, types have been added to record fields. --- lib/stdlib/doc/src/dets.xml | 61 ++++++++++----------------------------------- 1 file changed, 13 insertions(+), 48 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/dets.xml b/lib/stdlib/doc/src/dets.xml index 2e4261d72e..eb6e32aecf 100644 --- a/lib/stdlib/doc/src/dets.xml +++ b/lib/stdlib/doc/src/dets.xml @@ -100,18 +100,12 @@ provided by Dets, neither is the limited support for concurrent updates that makes a sequence of first and next calls safe to use on fixed ETS tables. Both these - features will be provided by Dets in a future release of + features may be provided by Dets in a future release of Erlang/OTP. Until then, the Mnesia application (or some user-implemented method for locking) must be used to implement safe concurrency. Currently, no Erlang/OTP library has support for ordered disk-based term storage.

-

Two versions of the format used for storing objects on file are - supported by Dets. The first version, 8, is the format always used - for tables created by Erlang/OTP R7 and earlier. The second version, 9, - is the default version of tables created by Erlang/OTP R8 (and later - releases). Erlang/OTP R8 can create version 8 tables, and convert version - 8 tables to version 9, and conversely, upon request.

All Dets functions return {error, Reason} if an error occurs (first/1 and next/2 are exceptions, they @@ -190,9 +184,6 @@ - - - @@ -385,18 +376,13 @@

{bchunk_format, binary()} - An opaque binary describing the format of the objects returned by bchunk/2. The binary can be used as argument to - is_compatible_chunk_format/2. Only available for - version 9 tables.

+ is_compatible_chunk_format/2.

{hash, Hash} - Describes which BIF is used to calculate the hash values of the objects stored in the Dets table. Possible values of Hash:

- -

hash - Implies that the erlang:hash/2 BIF - is used.

-

phash - Implies that the erlang:phash/2 BIF is used.

@@ -413,8 +399,7 @@

{no_keys, integer >= 0()} - The number of different - keys stored in the table. Only available for version 9 - tables.

+ keys stored in the table.

{no_objects, integer >= 0()} - The number of objects @@ -424,8 +409,7 @@

{no_slots, {Min, Used, Max}} - The number of slots of the table. Min is the minimum number of slots, Used is the number of currently used slots, - and Max is the maximum number of slots. Only - available for version 9 tables.

+ and Max is the maximum number of slots.

{owner, pid()} - The pid of the process that @@ -466,10 +450,6 @@ time warp safe. Time warp safe code must use safe_fixed_monotonic_time instead.

 - -

{version, integer()} - The version of the format of - the table.

- @@ -662,8 +642,8 @@ ok objects at a time, until at least one object matches or the end of the table is reached. The default, indicated by giving N the value default, is to let - the number of objects vary depending on the sizes of the objects. If - Name is a version 9 table, all objects with the + the number of objects vary depending on the sizes of the objects. + All objects with the same key are always matched at the same time, which implies that more than N objects can sometimes be matched.

The table is always to be protected using @@ -743,9 +723,9 @@ ok end of the table is reached. The default, indicated by giving N the value default, is to let the number - of objects vary depending on the sizes of the objects. If - Name is a version 9 table, all matching objects - with the same key are always returned in the same reply, which implies + of objects vary depending on the sizes of the objects. All + matching objects with the same key are always returned + in the same reply, which implies that more than N objects can sometimes be returned.

The table is always to be protected using safe_fixtable/2 @@ -842,8 +822,7 @@ ok maximal value. Notice that a higher value can increase the table fragmentation, and a smaller value can decrease the fragmentation, at - the expense of execution time. Only available for version - 9 tables.

+ the expense of execution time.

{min_no_slots, @@ -880,12 +859,7 @@ ok FileName}} is returned if the table must be repaired.

Value force means that a reparation is made even if the table is properly closed. - This is how to convert tables created by older versions of - STDLIB. An example is tables hashed with the deprecated - erlang:hash/2 BIF. Tables created with Dets from - STDLIB version 1.8.2 or later use function - erlang:phash/2 or function erlang:phash2/1, - which is preferred.

+ This is a seldom needed option.

Option repair is ignored if the table is already open.

 @@ -893,15 +867,6 @@ ok type()} - The table type. Defaults to set.

 - -

{version, - version()} - The version of the format - used for the table. Defaults to 9. Tables on the format - used before Erlang/OTP R8 can be created by specifying value - 8. A version 8 table can be converted to a version 9 - table by specifying options {version,9} - and {repair,force}.

- @@ -1041,8 +1006,8 @@ ok a time, until at least one object matches or the end of the table is reached. The default, indicated by giving N the value default, is to let the number - of objects vary depending on the sizes of the objects. If - Name is a version 9 table, all objects with the + of objects vary depending on the sizes of the objects. All + objects with the same key are always handled at the same time, which implies that the match specification can be applied to more than N objects.

-- cgit v1.2.3 From 3eddb0f762de248d3230b38bc9d478bfbc8e7331 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Wed, 7 Dec 2016 13:15:31 +0100 Subject: Update copyright-year --- lib/stdlib/doc/src/assert_hrl.xml | 2 +- lib/stdlib/doc/src/gb_sets.xml | 2 +- lib/stdlib/doc/src/gb_trees.xml | 2 +- lib/stdlib/doc/src/introduction.xml | 2 +- lib/stdlib/doc/src/orddict.xml | 2 +- lib/stdlib/doc/src/rand.xml | 2 +- lib/stdlib/doc/src/sets.xml | 2 +- lib/stdlib/doc/src/sys.xml | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/assert_hrl.xml b/lib/stdlib/doc/src/assert_hrl.xml index e2dfc2ab9b..cb91b1f126 100644 --- a/lib/stdlib/doc/src/assert_hrl.xml +++ b/lib/stdlib/doc/src/assert_hrl.xml @@ -4,7 +4,7 @@
- 20122015 + 20122016 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml index d677dd6f83..7bfe477a11 100644 --- a/lib/stdlib/doc/src/gb_sets.xml +++ b/lib/stdlib/doc/src/gb_sets.xml @@ -4,7 +4,7 @@
- 20012015 + 20012016 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml index 9a49d66820..790d4b8bf1 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -4,7 +4,7 @@
- 20012015 + 20012016 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/introduction.xml b/lib/stdlib/doc/src/introduction.xml index 5bf545c65f..642ca02430 100644 --- a/lib/stdlib/doc/src/introduction.xml +++ b/lib/stdlib/doc/src/introduction.xml @@ -5,7 +5,7 @@
1999 - 2013 + 2016 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index 076b06fc38..d048983c61 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -4,7 +4,7 @@
- 20002015 + 20002016 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 1dcc3de000..eb7870e367 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -4,7 +4,7 @@
- 2015 + 20152016 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index f7668af1ed..44dc104645 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -4,7 +4,7 @@
- 20002015 + 20002016 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 1120b926d5..9091a46df9 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@
- 19962014 + 19962016 Ericsson AB. All Rights Reserved. -- cgit v1.2.3 From fc0427be6d482182ec70f3cd87c73027cfb17ea9 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 9 Dec 2016 11:45:22 +0100 Subject: Prepare release --- lib/stdlib/doc/src/notes.xml | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 554150380f..0143686bb2 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,6 +31,48 @@

This document describes the changes made to the STDLIB application.

+
STDLIB 3.2 + +
Fixed Bugs and Malfunctions + + +

+ 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.

+

+ Own Id: OTP-13907 Aux Id: PR-1158, ERL-163

+ + +

Allow empty list as parameter of the fun used with + dbg:fun2ms/1.

+

+ Own Id: OTP-13974

+ + +
+ + +
Improvements and New Features + + +

+ 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.

+

+ Own Id: OTP-13929 Aux Id: PR-1170, ERL-284

+ + +
+ +
+
STDLIB 3.1
Fixed Bugs and Malfunctions -- cgit v1.2.3 From a2d92dff3a8acc534daeeb3dea5edda406a6ab0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Fri, 16 Dec 2016 12:50:28 +0100 Subject: Add take/2 to all dictionary modules Similar to maps:take/2, add take/2 to the other dictionary modules in STDLIB: orddict:take(Key, Dict) -> {Val,NewDict} | 'error'. dict:take(Key, Dict) -> {Val,NewDict} | 'error'. gb_trees:take(Key, Dict) -> {Val,NewDict}. For gb_trees also add: gb_trees:take_any(Key, Dict) -> {Val,NewDict} | 'error'. gb_trees already has delete() and delete_any(), so we will follow that design pattern. Suggested by Boris Bochkaryov in https://github.com/erlang/otp/pull/1209. --- lib/stdlib/doc/src/dict.xml | 10 ++++++++++ lib/stdlib/doc/src/gb_trees.xml | 22 ++++++++++++++++++++++ lib/stdlib/doc/src/orddict.xml | 9 +++++++++ 3 files changed, 41 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml index c926ff1b5b..c229a18721 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -105,6 +105,16 @@ + + + Return value and new dictionary without element with this value. + +

This function returns value from dictionary and a + new dictionary without this value. + Returns error if the key is not present in the dictionary.

+ + + Select elements that satisfy a predicate. diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml index 790d4b8bf1..5cfff021c1 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -108,6 +108,28 @@ + + + Returns a value and new tree without node with key Key. + +

Returns a value Value from node with key Key + and new Tree2 without the node with this value. + Assumes that the node with key is present in the tree, + crashes otherwise.

+ + + + + + Returns a value and new tree without node with key Key. + +

Returns a value Value from node with key Key + and new Tree2 without the node with this value. + Returns error if the node with the key is not present in + the tree.

+ + + Return an empty tree. diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index 109b038cb5..26bbf499c6 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -112,6 +112,15 @@ + + + Return value and new dictionary without element with this value. + +

This function returns value from dictionary and new dictionary without this value. + Returns error if the key is not present in the dictionary.

+ + + Select elements that satisfy a predicate. -- cgit v1.2.3 From 786604b2c1023158fcd2d22afd0db459954db34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Wed, 4 Jan 2017 17:59:58 +0100 Subject: stdlib: Document gen_event start options --- lib/stdlib/doc/src/gen_event.xml | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index c24542002a..42e952fd46 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -350,13 +350,18 @@ gen_event:stop -----> Module:terminate/2 start() -> Result - start(EventMgrName) -> Result + start(EventMgrName | Options) -> Result + start(EventMgrName, Options) -> Result Create a stand-alone event manager process. - EventMgrName = {local,Name} | {global,GlobalName} - | {via,Module,ViaName} + EventMgrName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}  Name = atom()  GlobalName = ViaName = term() + Options = [Option] +  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts} +   Dbgs = [Dbg] +    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}} +   SOpts = [term()] Result = {ok,Pid} | {error,{already_started,Pid}}  Pid = pid() @@ -371,14 +376,19 @@ gen_event:stop -----> Module:terminate/2 start_link() -> Result - start_link(EventMgrName) -> Result + start_link(EventMgrName | Options) -> Result + start_link(EventMgrName, Options) -> Result Create a generic event manager process in a supervision tree. - EventMgrName = {local,Name} | {global,GlobalName} - | {via,Module,ViaName} + EventMgrName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}  Name = atom()  GlobalName = ViaName = term() + Options = [Option] +  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts} +   Dbgs = [Dbg] +    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}} +   SOpts = [term()] Result = {ok,Pid} | {error,{already_started,Pid}}  Pid = pid() -- cgit v1.2.3 From 4a39593dd5922e546646000d9d5ee24a08baae8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 11 Jan 2017 14:16:52 +0100 Subject: ets: Remove superfluous reference to R11B --- lib/stdlib/doc/src/ets.xml | 4 ---- 1 file changed, 4 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 5f5d2b7f36..05401a2d40 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -541,10 +541,6 @@ Error: fun containing local Erlang function calls Tab is not of the correct type, or if Item is not one of the allowed values, a badarg exception is raised.

- -

In Erlang/OTP R11B and earlier, this function would not fail but - return undefined for invalid values for Item.

-

In addition to the {Item,Value} pairs defined for info/1, the following items are allowed:

-- cgit v1.2.3 From ec4c519b8c40faaf30d677d01f4b912a2ea526ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 11 Jan 2017 14:22:26 +0100 Subject: gen_{server,fsm}.xml: Remove superfluous reference to R12B --- lib/stdlib/doc/src/gen_fsm.xml | 5 ----- lib/stdlib/doc/src/gen_server.xml | 5 ----- 2 files changed, 10 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index de06987d38..719ab2b558 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -534,11 +534,6 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 the function call fails.

Return value Reply is defined in the return value of Module:StateName/3.

- -

The ancient behavior of sometimes consuming the server - exit message if the server died during the call while - linked to the client was removed in Erlang 5.6/OTP R12B.

- diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 4a7dd60858..662076b5f0 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -162,11 +162,6 @@ gen_server:abcast -----> Module:handle_cast/2 of Module:handle_call/3.

The call can fail for many reasons, including time-out and the called gen_server process dying before or during the call.

- -

The ancient behavior of sometimes consuming the server - exit message if the server died during the call while - linked to the client was removed in Erlang 5.6/OTP R12B.

- -- cgit v1.2.3 From 35985299ae5414fb448d9961071f722ce209f0b6 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 20 Jan 2017 16:22:15 +0100 Subject: Change arity of type to init_result/1 --- lib/stdlib/doc/src/gen_statem.xml | 67 +++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 35 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index fd498ee82e..6fa2d86e0b 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -4,7 +4,7 @@
- 2016 + 2016-2017 Ericsson AB. All Rights Reserved. @@ -982,6 +982,33 @@ handle_event(_, _, State, Data) ->

+ + + +

+ For a succesful initialization, + State is the initial + state() + and Data the initial server + data() + of the gen_statem. +

+

+ The Actions + are executed when entering the first + state just as for a + state callback, + except that the action postpone is forced to + false since there is no event to postpone. +

+

+ For an unsuccesful initialization, + {stop,Reason} + or ignore should be used; see + start_link/3,4. +

+ + @@ -1613,25 +1640,16 @@ handle_event(_, _, State, Data) -> - Module:init(Args) -> Result + Module:init(Args) -> Result(StateType) Optional function for initializing process and internal state. Args = term() - Result = {ok,State,Data} -  | {ok,State,Data,Actions} -  | {stop,Reason} | ignore - State = state() - - Data = data() - - Actions = - [action()] | - action() + Result(StateType) = + init_result(StateType) - Reason = term() @@ -1644,30 +1662,9 @@ handle_event(_, _, State, Data) -> the implementation state and server data.

- Args is the Args argument provided to the start + Args is the Args argument provided to that start function.

-

- If the initialization is successful, the function is to - return {ok,State,Data} or - {ok,State,Data,Actions}. - State is the initial - state() - and Data the initial server - data(). -

-

- The Actions - are executed when entering the first - state just as for a - state callback. -

-

- If the initialization fails, - the function is to return {stop,Reason} - or ignore; see - start_link/3,4. -

This callback is optional, so a callback module does not need -- cgit v1.2.3 From 85e9fed232a6d89e3659cabbb2169cf3e21127e3 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 24 Jan 2017 14:15:26 +0100 Subject: Implement repeat_state and repeat_state_and_data --- lib/stdlib/doc/src/gen_statem.xml | 82 +++++++++++++++++++++++++++++++++------ 1 file changed, 71 insertions(+), 11 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 6fa2d86e0b..b20abbea5d 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -587,8 +587,8 @@ handle_event(_, _, State, Data) ->

- If the state machine should use state enter calls - is selected when starting the gen_statem + Whether the state machine should use state enter calls + or not is selected when starting the gen_statem and after code change using the return value from Module:callback_mode/0.

@@ -606,7 +606,16 @@ handle_event(_, _, State, Data) -> See Module:StateName/3 and - Module:handle_event/4. + Module:handle_event/4. + Such a call can be repeated by returning a + + repeat_state + + or + + repeat_state_and_data + + tuple from the state callback.

If @@ -625,7 +634,8 @@ handle_event(_, _, State, Data) -> right before entering the initial state even though this formally is not a state change. In this case OldState will be the same as State, - which can not happen for a subsequent state change. + which can not happen for a subsequent state change, + but will happen when repeating the state enter call.

@@ -640,7 +650,15 @@ handle_event(_, _, State, Data) ->

- If the state changes or is the initial state, and + If the state changes, is the initial state, + + repeat_state + + or + + repeat_state_and_data + + is used, and also state enter calls are used, the gen_statem calls the new state callback with arguments @@ -1095,6 +1113,37 @@ handle_event(_, _, State, Data) -> {next_state,CurrentState,CurrentData,Actions}.

+ repeat_state + +

+ The gen_statem keeps the current state, or + does a state transition to the current state if you like, + sets NewData, + and executes all Actions. + If the gen_statem runs with + state enter calls, + the state enter call is repeated, see type + transition_option(), + otherwise repeat_state is the same as + keep_state. +

+ + repeat_state_and_data + +

+ The gen_statem keeps the current state and data, or + does a state transition to the current state if you like, + and executes all Actions. + This is the same as + {repeat_state,CurrentData,Actions}. + If the gen_statem runs with + state enter calls, + the state enter call is repeated, see type + transition_option(), + otherwise repeat_state_and_data is the same as + keep_state_and_data. +

+ stop

@@ -1870,22 +1919,33 @@ handle_event(_, _, State, Data) -> actions that may be returned: postpone() - and + is not allowed since a state enter call is not + an event so there is no event to postpone, and {next_event,_,_} - are not allowed. + is not allowed since using state enter calls + should not affect how events are consumed and produced. You may also not change states from this call. Should you return {next_state,NextState, ...} with NextState =/= State the gen_statem crashes. - You are advised to use {keep_state,...} or - keep_state_and_data. + It is possible to use {repeat_state, ...}, + {repeat_state_and_data,_} or + repeat_state_and_data but all of them makes little + sense since you immediately will be called again with a new + state enter call making this just a weird way + of looping, and there are better ways to loop in Erlang. + You are advised to use {keep_state,...}, + {keep_state_and_data,_} or + keep_state_and_data since you can not change states + from a state enter call anyway.

Note the fact that you can use throw to return the result, which can be useful. For example to bail out with throw(keep_state_and_data) - from deep within complex code that is in no position to - return {next_state,State,Data}. + from deep within complex code that can not + return {next_state,State,Data} because + State or Data is no longer in scope.

-- cgit v1.2.3 From 57aaf7d0c7c75cfd8c6b55c21d977b695f460022 Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Wed, 18 Jan 2017 18:28:47 +0100 Subject: Add filelib:find_file/2/3 and filelib:find_source/1/2/3 This moves, extends and exports functionality that previously existed only internally in filename:find_src/1/2, adding the ability to automatically substitute file suffixes and use different rules for different suffixes. --- lib/stdlib/doc/src/filelib.xml | 54 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml index 7c6380ce28..ad73fc254a 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -60,6 +60,12 @@ + + + + + + @@ -226,7 +232,51 @@ filelib:wildcard("lib/**/*.{erl,hrl}") directory.

+ + + + + Find a file relative to a given directory. + +

Looks for a file of the given name by applying suffix rules to + the given directory path. For example, a rule {"ebin", "src"} + means that if the directory path ends with "ebin", the + corresponding path ending in "src" should be searched.

+

If Rules is left out or is an empty list, the + default system rules are used. See also the Kernel application + parameter source_search_rules.

+ + + + + Find the source file for a given object file. + +

Equivalent to find_source(Base, Dir), where Dir is + filename:dirname(FilePath) and Base is + filename:basename(FilePath).

+ + + + + + Find a source file relative to a given directory. + +

Applies file extension specific rules to find the source file for + a given object file relative to the object directory. For example, + for a file with the extension .beam, the default rule is to + look for a file with a corresponding extension .erl by + replacing the suffix "ebin" of the object directory path with + "src". + The file search is done through find_file/3. The directory of + the object file is always tried before any other directory specified + by the rules.

+

If Rules is left out or is an empty list, the + default system rules are used. See also the Kernel application + parameter source_search_rules.

+ + - - -- cgit v1.2.3 From 0eb45e21d406539caaad98bfc1740f9a11e32565 Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Tue, 6 Dec 2016 12:14:18 +0100 Subject: Add shell shortcut for recompiling existing modules This extends the shell function c/1 and c/2 so that if the argument is a module name instead of a file name, it automatically locates the .beam file and the corresponding source file, and then recompiles the module using the same compiler options (plus any options passed to c/2). If compilation fails, the old beam file is preserved. Also adds c(Mod, Opts, Filter), where the Filter argument allows you to remove old compiler options before the new options are added. --- lib/stdlib/doc/src/c.xml | 26 ++++++++++++++++++++------ lib/stdlib/doc/src/shell.xml | 10 +++++----- 2 files changed, 25 insertions(+), 11 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/c.xml b/lib/stdlib/doc/src/c.xml index 55a77d1bc5..7666699183 100644 --- a/lib/stdlib/doc/src/c.xml +++ b/lib/stdlib/doc/src/c.xml @@ -52,13 +52,27 @@ - Compile and load code in a file. + + Compile and load a file or module. -

Compiles and then purges and loads the code for a file. - Options defaults to []. Compilation is - equivalent to:

- -compile:file(File, Options ++ [report_errors, report_warnings]) +

Compiles and then purges and loads the code for a module. + Module can be either a module name or a source + file path, with or without .erl extension. + Options defaults to [].

+

If Module is an atom and is not the path of a + source file, then the code path is searched to locate the object + file for the module and extract its original compiler options and + source path. If the source file is not found in the original + location, filelib:find_source/1 + is used to search for it relative to the directory of the object + file.

+

The source file is compiled with the the original + options appended to the given Options, the + output replacing the old object file if and only if compilation + succeeds. A function Filter can be specified + for removing elements from from the original compiler options + before the new options are added.

Notice that purging the code means that any processes lingering in old code for the module are killed without warning. For more information, see code/3.

diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml index d6e8036d4e..f52bc39deb 100644 --- a/lib/stdlib/doc/src/shell.xml +++ b/lib/stdlib/doc/src/shell.xml @@ -165,12 +165,12 @@

Evaluates shell_default:help().

 - c(File) + c(Mod) -

Evaluates shell_default:c(File). This compiles - and loads code in File and purges old versions of - code, if necessary. Assumes that the file and module names - are the same.

+

Evaluates shell_default:c(Mod). This compiles and + loads the module Mod and purges old versions of the + code, if necessary. Mod can be either a module name or a + a source file path, with or without .erl extension.

 catch_exception(Bool) -- cgit v1.2.3 From 1d886081027c4d4fcfbf7f73d4708694cad582f5 Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Sat, 4 Feb 2017 15:31:14 +0100 Subject: Deprecate filename:find_src/1/2 --- lib/stdlib/doc/src/filename.xml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index 2a413835d0..7acef51ca1 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -356,10 +356,12 @@ true

Finds the source filename and compiler options for a module. The result can be fed to compile:file/2 to compile the file again.

-

It is not recommended to use this function. If possible, - use the beam_lib(3) - module to extract the abstract code format from the Beam file and - compile that instead.

 + +

This function is deprecated. Use + filelib:find_source/1 instead for finding source files.

+

If possible, use the beam_lib(3) + module to extract the compiler options and the abstract code + format from the Beam file and compile that instead.

Argument Beam, which can be a string or an atom, specifies either the module name or the path to the source code, with or without extension ".erl". In either -- cgit v1.2.3 From aa0c4b0df7cdc750450906aff4e8c81627d80605 Mon Sep 17 00:00:00 2001 From: Paul Schoenfelder Date: Tue, 31 Jan 2017 17:40:34 -0600 Subject: Update erl_tar to support PAX format, etc. This commit introduces the following key changes: - Support for reading tar archives in formats currently in common use, such as v7, STAR, USTAR, PAX, and GNU tar's extensions to the STAR/USTAR format. - Support for writing PAX archives, only when necessary, using USTAR when possible for greater portability. These changes result in lifting of some prior restrictions: - Support for reading archives produced by modern tar implementations when other restrictions described below are present. - Support for filenames which exceed 100 bytes in length, or paths which exceed 255 bytes (see USTAR format specification for more details on this restriction). - Support for filenames of arbitrary length - Support for unicode metadata (the previous behaviour of erl_tar was actually violating the spec, by writing unicode-encoded data to fields which are defined to be 7-bit ASCII, even though this technically worked when using erl_tar at source and destination, it may not have worked with other tar utilities, and this implementation now conforms to the spec). - Support for uid/gid values which cannot be converted to octal integers. --- lib/stdlib/doc/src/erl_tar.xml | 72 ++++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 34 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml index 24e7b64b9e..f28d8b425b 100644 --- a/lib/stdlib/doc/src/erl_tar.xml +++ b/lib/stdlib/doc/src/erl_tar.xml @@ -37,12 +37,13 @@

This module archives and extract files to and from - a tar file. This module supports the ustar format - (IEEE Std 1003.1 and ISO/IEC 9945-1). All modern tar - programs (including GNU tar) can read this format. To ensure that - that GNU tar produces a tar file that erl_tar can read, - specify option --format=ustar to GNU tar.

- + a tar file. This module supports reading most common tar formats, + namely v7, STAR, USTAR, and PAX, as well as some of GNU tar's extensions + to the USTAR format (sparse files most notably). It produces tar archives + in USTAR format, unless the files being archived require PAX format due to + restrictions in USTAR (such as unicode metadata, filename length, and more). + As such, erl_tar supports tar archives produced by most all modern + tar utilities, and produces tarballs which should be similarly portable.

By convention, the name of a tar file is to end in ".tar". To abide to the convention, add ".tar" to the name.

@@ -83,6 +84,8 @@

If file:native_name_encoding/0 returns latin1, no translation of path names is done.

+ +

Unicode metadata stored in PAX headers is preserved

@@ -104,21 +107,20 @@ Limitations -

For maximum compatibility, it is safe to archive files with names - up to 100 characters in length. Such tar files can generally be - extracted by any tar program.

- - -

For filenames exceeding 100 characters in length, the resulting tar - file can only be correctly extracted by a POSIX-compatible tar - program (such as Solaris tar or a modern GNU tar).

- - -

Files with longer names than 256 bytes cannot be stored.

+

If you must remain compatible with the USTAR tar format, you must ensure file paths being + stored are less than 255 bytes in total, with a maximum filename component + length of 100 bytes. USTAR uses a header field (prefix) in addition to the name field, and + splits file paths longer than 100 bytes into two parts. This split is done on a directory boundary, + and is done in such a way to make the best use of the space available in those two fields, but in practice + this will often mean that you have less than 255 bytes for a path. erl_tar will + automatically upgrade the format to PAX to handle longer filenames, so this is only an issue if you + need to extract the archive with an older implementation of erl_tar or tar which does + not support PAX. In this case, the PAX headers will be extracted as regular files, and you will need to + apply them manually.

 -

The file name a symbolic link points is always limited - to 100 characters.

+

Like the above, if you must remain USTAR compatible, you must also ensure than paths for + symbolic/hard links are no more than 100 bytes, otherwise PAX headers will be used.
@@ -129,7 +131,9 @@ Add a file to an open tar file. TarDescriptor = term() - Filename = filename() + FilenameOrBin = filename()|binary() + NameInArchive = filename() + Filename = filename()|{NameInArchive,FilenameOrBin} Options = [Option] Option = dereference|verbose|{chunks,ChunkSize} ChunkSize = positive_integer() @@ -139,6 +143,9 @@

Adds a file to a tar file that has been opened for writing by open/1.

+

NameInArchive is the name under which the file becomes + stored in the tar file. The file gets this name when it is + extracted from the tar file.

Options:

dereference @@ -183,9 +190,6 @@ open/2. This function accepts the same options as add/3.

-

NameInArchive is the name under which the file becomes - stored in the tar file. The file gets this name when it is - extracted from the tar file.

 @@ -206,8 +210,8 @@ Create a tar archive. Name = filename() - FileList = [Filename|{NameInArchive, binary()},{NameInArchive, - Filename}] + FileList = [Filename|{NameInArchive, FilenameOrBin}] + FilenameOrBin = filename()|binary() Filename = filename() NameInArchive = filename() RetValue = ok|{error,{Name,Reason}} @@ -225,8 +229,8 @@ Create a tar archive with options. Name = filename() - FileList = [Filename|{NameInArchive, binary()},{NameInArchive, - Filename}] + FileList = [Filename|{NameInArchive, FilenameOrBin}] + FilenameOrBin = filename()|binary() Filename = filename() NameInArchive = filename() OptionList = [Option] @@ -275,7 +279,8 @@ extract(Name) -> RetValue Extract all files from a tar file. - Name = filename() + Name = filename() | {binary,binary()} | {file,Fd} + Fd = file_descriptor() RetValue = ok|{error,{Name,Reason}} Reason = term() @@ -294,8 +299,7 @@ extract(Name, OptionList) Extract files from a tar file. - Name = filename() | {binary,Binary} | {file,Fd} - Binary = binary() + Name = filename() | {binary,binary()} | {file,Fd} Fd = file_descriptor() OptionList = [Option] Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose|memory @@ -521,7 +525,7 @@ erl_tar:close(TarDesc) table(Name) -> RetValue Retrieve the name of all files in a tar file. - Name = filename() + Name = filename()|{binary,binary()}|{file,file_descriptor()} RetValue = {ok,[string()]}|{error,{Name,Reason}} Reason = term() @@ -535,7 +539,7 @@ erl_tar:close(TarDesc) Retrieve name and information of all files in a tar file. - Name = filename() + Name = filename()|{binary,binary()}|{file,file_descriptor()}

Retrieves the names of all files in the tar file Name.

@@ -546,7 +550,7 @@ erl_tar:close(TarDesc) t(Name) Print the name of each file in a tar file. - Name = filename() + Name = filename()|{binary,binary()}|{file,file_descriptor()}

Prints the names of all files in the tar file Name to the @@ -559,7 +563,7 @@ erl_tar:close(TarDesc) Print name and information for each file in a tar file. - Name = filename() + Name = filename()|{binary,binary()}|{file,file_descriptor()}

Prints names and information about all files in the tar file -- cgit v1.2.3 From 8c7a68f3808a8d52f5cfc297a249ca4ef2480238 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 16 Feb 2017 15:55:34 +0100 Subject: filename: Add safe_relative_path/1 Add safe_relative_path/1 to guard against directory traversal attacks. It either returns a shorter path without any ".." or "." components, or 'unsafe' if an ".." component would climb up above the root of the relative path. Here are a few examples: safe_relative_path("a/b/..") => "a" safe_relative_path("a/..") => "" safe_relative_path("a/../..") => unsafe safe_relative_path("/absolute/path") => unsafe The returned path can be used directly or combined with an absolute path using filename:join/2. --- lib/stdlib/doc/src/filename.xml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index 2a413835d0..f7f3f7b504 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -510,6 +510,33 @@ true + + + Sanitize a relative path to avoid directory traversal attacks. + +

Sanitizes the relative path by eliminating ".." and "." + components to protect against directory traversal attacks. + Either returns the sanitized path name, or the atom + unsafe if the path is unsafe. + The path is considered unsafe in the following circumstances:

+ +

The path is not relative.

 +

A ".." component would climb up above the root of + the relative path.

 + +

Examples:

+ 
+1> filename:safe_relative_path("dir/sub_dir/..").
+"dir"
+2> filename:safe_relative_path("dir/..").
+[]
+3> filename:safe_relative_path("dir/../..").
+unsafe
+4> filename:safe_relative_path("/abs/path").
+unsafe
+ + + Split a filename into its path components. -- cgit v1.2.3 From f1365135f1dd0b57849317b77e8bc9a1e0fd6307 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Wed, 22 Feb 2017 15:50:07 +0100 Subject: Clarify code_change and callback mode change --- lib/stdlib/doc/src/gen_statem.xml | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index b20abbea5d..d19602b67c 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -1685,6 +1685,19 @@ handle_event(_, _, State, Data) -> It is recommended to use an atom as Reason since it will be wrapped in an {error,Reason} tuple.

+

+ Also note when upgrading a gen_statem, + this function and hence + the Change={advanced,Extra} parameter in the + appup file + is not only needed to update the internal state + or to act on the Extra argument. + It is also needed if an upgrade or downgrade should change + callback mode, + or else the callback mode after the code change + will not be honoured, + most probably causing a server crash. +

-- cgit v1.2.3 From 913d0b52df1e029fb1728b44ba7da318f3dc49dd Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Wed, 22 Feb 2017 15:41:26 +0100 Subject: Implement fallback for terminate/3 --- lib/stdlib/doc/src/gen_statem.xml | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index d19602b67c..5eb13db1aa 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -1973,6 +1973,11 @@ handle_event(_, _, State, Data) -> Ignored = term() + +

This callback is optional, so callback modules need not + export it. The gen_statem module provides a default + implementation without cleanup.

+

This function is called by a gen_statem when it is about to terminate. It is to be the opposite of -- cgit v1.2.3 From 7d457490f786faef4ab02c300a1e69c21a6aeb21 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Wed, 1 Mar 2017 11:35:22 +0100 Subject: Correct documentation of get_modules message --- lib/stdlib/doc/src/sys.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 9091a46df9..45171f814d 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -83,8 +83,8 @@

If the modules used to implement the process change dynamically during runtime, the process must understand one more message. An example is the gen_event - processes. The message is {get_modules, From}. - The reply to this message is From ! {modules, Modules}, where + processes. The message is {_Label, {From, Ref}, get_modules}. + The reply to this message is From ! {Ref, Modules}, where Modules is a list of the currently active modules in the process.

This message is used by the release handler to find which -- cgit v1.2.3 From eb437db9e7df90d5e72d6314ee7c49cbde77135a Mon Sep 17 00:00:00 2001 From: Myron Marston Date: Wed, 1 Mar 2017 09:34:50 -0800 Subject: Fix typos: lenght -> length --- lib/stdlib/doc/src/notes.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 0143686bb2..0e8bf3d27c 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -3163,7 +3163,7 @@

Two bugs in io:format for ~F.~Ps has been corrected. When length(S) >= abs(F) > P, the precision P was incorrectly - ignored. When F == P > lenght(S) the result was + ignored. When F == P > length(S) the result was incorrectly left adjusted. Bug found by Ali Yakout who also provided a fix.

-- cgit v1.2.3 From 26c3cd82529836cb5b6eefbf7f92f318fd91f847 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Fri, 10 Mar 2017 15:00:46 +0100 Subject: Update copyright year --- lib/stdlib/doc/src/filename.xml | 2 +- lib/stdlib/doc/src/sys.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index f7f3f7b504..f20500709c 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -4,7 +4,7 @@

- 19972016 + 19972017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 45171f814d..0fed649660 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. -- cgit v1.2.3 From 4d658008be5a08ddadbe75ebadb9ef124436b76e Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Tue, 14 Mar 2017 15:59:23 +0100 Subject: Prepare release --- lib/stdlib/doc/src/notes.xml | 104 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 0143686bb2..bb35224182 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,6 +31,110 @@

This document describes the changes made to the STDLIB application.

+
STDLIB 3.3 + +
Fixed Bugs and Malfunctions + + +

An escript with only two lines would not work.

+

+ Own Id: OTP-14098

+ + +

Characters ($char) can be used in constant + pattern expressions. They can also be used in types and + contracts.

+

+ Own Id: OTP-14103 Aux Id: ERL-313

+ + +

The signatures of erl_parse:anno_to_term/1 and + erl_parse:anno_from_term/1 are corrected. Using + these functions no longer results in false Dialyzer + warnings.

+

+ Own Id: OTP-14131

+ + +

Pretty-printing of maps is improved.

+

+ Own Id: OTP-14175 Aux Id: seq13277

+ + +

If any of the following functions in the zip + module crashed, a file would be left open: + extract(), unzip(), create(), or + zip(). This has been corrected.

+

A zip file having a "Unix header" could not be + unpacked.

+

+ Own Id: OTP-14189 Aux Id: ERL-348, ERL-349

+ + +

Improve the Erlang shell's tab-completion of long + names.

+

+ Own Id: OTP-14200 Aux Id: ERL-352

+ + +

+ The reference manual for sys had some faulty + information about the 'get_modules' message used by + processes where modules change dynamically during + runtime. The documentation is now corrected.

+

+ Own Id: OTP-14248 Aux Id: ERL-367

+ + +
+ + +
Improvements and New Features + + +

+ Bug fixes, new features and improvements to gen_statem:

+

+ 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.

+

+ Changing callback modes after code change did not work + since the new callback mode was not recorded. This bug + has been fixed.

+

+ 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.

+

+ State entry calls can now be repeated using (new) state + callback returns {repeat_state,...}, + {repeat_state_and_data,_} and repeat_state_and_data.

+

+ 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.

+

+ 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.

+

+ Own Id: OTP-14114

+ + +

filename:safe_relative_path/1 to sanitize a + relative path has been added.

+

+ Own Id: OTP-14215

+ + +
+ +
+
STDLIB 3.2
Fixed Bugs and Malfunctions -- cgit v1.2.3 From 6fe3935bc51c0fc62b2d740ac43e64ff276bbef8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Fri, 17 Mar 2017 12:33:17 +0100 Subject: Update the documentation regarding Unicode atoms --- lib/stdlib/doc/src/unicode_usage.xml | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index efc8b75075..a8ef8ff5c5 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -62,6 +62,10 @@

In Erlang/OTP 17.0, the encoding default for Erlang source files was switched to UTF-8.

 + +

In Erlang/OTP 20.0, atoms and function can contain + Unicode characters. Module names are still restricted to + the ISO-Latin-1 range.

This section outlines the current Unicode support and gives some @@ -339,9 +343,10 @@ The language

Having the source code in UTF-8 also allows you to write string - literals containing Unicode characters with code points > 255, - although atoms, module names, and function names are restricted to - the ISO Latin-1 range. Binary literals, where you use type + literals, function names, and atoms containing Unicode + characters with code points > 255. + Module names are still restricted to the ISO Latin-1 range. + Binary literals, where you use type /utf8, can also be expressed using Unicode characters > 255. Having module names using characters other than 7-bit ASCII can cause trouble on operating systems with inconsistent file naming schemes, @@ -432,15 +437,17 @@ external_charlist() = maybe_improper_list(char() | external_unicode_binary() |

Basic Language Support -

As from Erlang/OTP R16, Erlang source - files can be written in UTF-8 or bytewise (latin1) encoding. For - information about how to state the encoding of an Erlang source file, see - the epp(3) module. - Strings and comments can be written using Unicode, but functions must - still be named using characters from the ISO Latin-1 character set, and - atoms are restricted to the same ISO Latin-1 range. These restrictions in - the language are of course independent of the encoding of the source - file.

+

As from Erlang/OTP R16, Erlang + source files can be written in UTF-8 or bytewise (latin1) + encoding. For information about how to state the encoding of an + Erlang source file, see the epp(3) module. As + from Erlang/OTP R16, strings and comments can be written using + Unicode. As from Erlang/OTP 20, also atoms and functions can be + written using Unicode. Modules names must still be named using + characters from the ISO Latin-1 character set. (These + restrictions in the language are independent of the encoding of + the source file.)

Bit Syntax -- cgit v1.2.3 From 77039e648c8a62bfc4f0242531d5fd4874b29aad Mon Sep 17 00:00:00 2001 From: Guilherme Andrade Date: Sat, 18 Mar 2017 17:27:35 +0000 Subject: Support cryptographically strong rand plugin --- lib/stdlib/doc/src/rand.xml | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 8745e16908..e7a5fb7fab 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -120,19 +120,27 @@ S0 = rand:seed_s(exsplus), {SND0, S2} = rand:normal_s(S1), -

This random number generator is not cryptographically - strong. If a strong cryptographic random number generator is - needed, use one of functions in the - crypto - module, for example, - crypto:strong_rand_bytes/1.

+

The builtin random number generator algorithms are not + cryptographically strong. If a cryptographically strong + random number generator is needed, use something like + crypto:rand_seed/0. +

+ + + + + + + + +

Algorithm-dependent state.

 @@ -216,7 +224,7 @@ S0 = rand:seed_s(exsplus),

Seeds random number generation with the specifed algorithm and - time-dependent data if AlgOrExpState is an algorithm.

+ time-dependent data if AlgOrStateOrExpState is an algorithm.

Otherwise recreates the exported seed in the process dictionary, and returns the state. See also export_seed/0.

@@ -237,7 +245,7 @@ S0 = rand:seed_s(exsplus), Seed random number generator.

Seeds random number generation with the specifed algorithm and - time-dependent data if AlgOrExpState is an algorithm.

+ time-dependent data if AlgOrStateOrExpState is an algorithm.

Otherwise recreates the exported seed and returns the state. See also export_seed/0.

-- cgit v1.2.3 From 37dfd6cd6f02003ffe9cc08867185ae1ae3ed2a8 Mon Sep 17 00:00:00 2001 From: Sasan Hezarkhani Date: Mon, 20 Mar 2017 21:43:52 +0000 Subject: Minor document fix for proplists --- lib/stdlib/doc/src/proplists.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml index fe6b8cc3bf..990d47b313 100644 --- a/lib/stdlib/doc/src/proplists.xml +++ b/lib/stdlib/doc/src/proplists.xml @@ -344,7 +344,7 @@ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c]) with {K2, true}, thus changing the name of the option and simultaneously negating the value specified by - get_bool(Key, ListIn. + get_bool(Key, ListIn). If the same K1 occurs more than once in Negations, only the first occurrence is used.

For example, substitute_negations([{no_foo, foo}], L) -- cgit v1.2.3 From 5b7e50500f6cb3e680b277f871392ac706c5c1d7 Mon Sep 17 00:00:00 2001 From: Guilherme Andrade Date: Fri, 3 Jun 2016 00:39:01 +0100 Subject: ETS: Allow for matchspec-based replacement --- lib/stdlib/doc/src/ets.xml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 05401a2d40..36c803b40c 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -1490,6 +1490,27 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> + + + Match the objects in an ETS table against a match_spec and + replaces matching objects with the match_spec result + +

Matches the objects in the table Tab using a + match_spec. If the + an object is matched, and the match_spec result is an object with the + same key, the existing object is replaced with the match_spec result. + For any other result from the match_spec the object is kept + unchanged.

+

The function returns the number of objects actually + replaced in the table.

+ +

The match_spec has to return an object with the same key if + the object is to be replaced. No other return value will get the + object replaced.

+ + + + Continue matching objects in an ETS table. -- cgit v1.2.3 From e15319fcdb5c99514cd63d7a02d04c97587e8853 Mon Sep 17 00:00:00 2001 From: Guilherme Andrade Date: Mon, 27 Jun 2016 22:09:37 +0100 Subject: Disable ets:select_replace/2 for bags The existing implementation presented both semantic inconsistencies and performance issues. --- lib/stdlib/doc/src/ets.xml | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 36c803b40c..3e9ad89b26 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -1495,6 +1495,10 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> Match the objects in an ETS table against a match_spec and replaces matching objects with the match_spec result + +

For the moment, due to performance and semantic constraints, + tables of type bag are not yet supported.

+

Matches the objects in the table Tab using a match_spec. If the an object is matched, and the match_spec result is an object with the -- cgit v1.2.3 From ed71ea35bad9a511125c82ce42160cad9fa8311f Mon Sep 17 00:00:00 2001 From: Guilherme Andrade Date: Sat, 25 Feb 2017 22:00:17 +0000 Subject: Reject unsafe matchspecs on ets:select_replace/2 Preemptively fail operation with badarg if the replacement object might have a different key. --- lib/stdlib/doc/src/ets.xml | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 3e9ad89b26..29d22ffae5 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -1492,25 +1492,21 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> - Match the objects in an ETS table against a match_spec and - replaces matching objects with the match_spec result + Match and replace objects atomically in an ETS table

For the moment, due to performance and semantic constraints, tables of type bag are not yet supported.

Matches the objects in the table Tab using a - match_spec. If the - an object is matched, and the match_spec result is an object with the - same key, the existing object is replaced with the match_spec result. - For any other result from the match_spec the object is kept - unchanged.

-

The function returns the number of objects actually - replaced in the table.

+ match specification. If the + an object is matched, the existing object is replaced with + the match specificatoin result.

+

The function returns the total number of replaced objects.

-

The match_spec has to return an object with the same key if - the object is to be replaced. No other return value will get the - object replaced.

+

If there's a risk a match specification might return + a tuple with a different key, the whole operation will fail + with badarg.

 -- cgit v1.2.3 From 25648cad32b782cff5b513cb1e1a72d2f9f4ada7 Mon Sep 17 00:00:00 2001 From: Guilherme Andrade Date: Thu, 23 Mar 2017 00:09:58 +0000 Subject: ets: Polish select_replace/2 documentation --- lib/stdlib/doc/src/ets.xml | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 29d22ffae5..d1ec176f81 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -1494,19 +1494,17 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> Match and replace objects atomically in an ETS table - -

For the moment, due to performance and semantic constraints, - tables of type bag are not yet supported.

-

Matches the objects in the table Tab using a - match specification. If the + match specification. If an object is matched, the existing object is replaced with - the match specificatoin result.

+ the match specification result, which must retain + the original key or the operation will fail with badarg.

+

For the moment, due to performance and semantic constraints, + tables of type bag are not yet supported.

The function returns the total number of replaced objects.

-

If there's a risk a match specification might return - a tuple with a different key, the whole operation will fail - with badarg.

+

The match/replacement operation atomicity scope is limited + to each individual object.

 -- cgit v1.2.3 From 2f166031319ec414712a8a91372ba2bc348dae7a Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Mon, 3 Apr 2017 12:18:58 +0200 Subject: stdlib: Fix xmllint warnings Commit d2be06f introduced xmllint warnings. --- lib/stdlib/doc/src/assert_hrl.xml | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/assert_hrl.xml b/lib/stdlib/doc/src/assert_hrl.xml index 57bb5207df..ea23cca2ee 100644 --- a/lib/stdlib/doc/src/assert_hrl.xml +++ b/lib/stdlib/doc/src/assert_hrl.xml @@ -4,7 +4,7 @@
- 20122016 + 20122017 Ericsson AB. All Rights Reserved. @@ -92,18 +92,21 @@ erlc -DNOASSERT=true *.erl Macros assert(BoolExpr) - assert(BoolExpr, Comment) + + URKAassert(BoolExpr, Comment)

Tests that BoolExpr completes normally returning true.

 assertNot(BoolExpr) + assertNot(BoolExpr, Comment)

Tests that BoolExpr completes normally returning false.

 assertMatch(GuardedPattern, Expr) + assertMatch(GuardedPattern, Expr, Comment)

Tests that Expr completes normally yielding a value that @@ -115,6 +118,7 @@ erlc -DNOASSERT=true *.erl ?assertMatch({bork, X} when X > 0, f()) assertNotMatch(GuardedPattern, Expr) + assertNotMatch(GuardedPattern, Expr, Comment)

Tests that Expr completes normally yielding a value that does @@ -123,18 +127,21 @@ erlc -DNOASSERT=true *.erl when part.

 assertEqual(ExpectedValue, Expr) + assertEqual(ExpectedValue, Expr, Comment)

Tests that Expr completes normally yielding a value that is exactly equal to ExpectedValue.

 assertNotEqual(ExpectedValue, Expr) + assertNotEqual(ExpectedValue, Expr, Comment)

Tests that Expr completes normally yielding a value that is not exactly equal to ExpectedValue.

 assertException(Class, Term, Expr) + assertException(Class, Term, Expr, Comment)

Tests that Expr completes abnormally with an exception of type @@ -145,6 +152,7 @@ erlc -DNOASSERT=true *.erl patterns, as in assertMatch.

 assertNotException(Class, Term, Expr) + assertNotException(Class, Term, Expr, Comment)

Tests that Expr does not evaluate abnormally with an @@ -155,16 +163,19 @@ erlc -DNOASSERT=true *.erl be guarded patterns.

 assertError(Term, Expr) + assertError(Term, Expr, Comment)

Equivalent to assertException(error, Term, Expr)

 assertExit(Term, Expr) + assertExit(Term, Expr, Comment)

Equivalent to assertException(exit, Term, Expr)

 assertThrow(Term, Expr) + assertThrow(Term, Expr, Comment)

Equivalent to assertException(throw, Term, Expr)

-- cgit v1.2.3 From e1a74e3077ca870520a748f29dd7c4b9115ce090 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Mon, 3 Apr 2017 12:29:23 +0200 Subject: Clean up documentation and test cases --- lib/stdlib/doc/src/rand.xml | 43 ++++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index e7a5fb7fab..2ddf3021ac 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -139,7 +139,19 @@ S0 = rand:seed_s(exsplus), - + + + + +

Algorithm specific internal state

 + + + +

Algorithm specific internal state

 + + + +

Algorithm specific internal state

 @@ -147,8 +159,11 @@ S0 = rand:seed_s(exsplus), -

Algorithm-dependent state that can be printed or saved to - file.

 + +

+ Algorithm-dependent state that can be printed or saved to file. +

+ @@ -223,8 +238,11 @@ S0 = rand:seed_s(exsplus), Seed random number generator. -

Seeds random number generation with the specifed algorithm and - time-dependent data if AlgOrStateOrExpState is an algorithm.

+

+ Seeds random number generation with the specifed algorithm and + time-dependent data if AlgOrStateOrExpState + is an algorithm. +

Otherwise recreates the exported seed in the process dictionary, and returns the state. See also export_seed/0.

@@ -244,8 +262,11 @@ S0 = rand:seed_s(exsplus), Seed random number generator. -

Seeds random number generation with the specifed algorithm and - time-dependent data if AlgOrStateOrExpState is an algorithm.

+

+ Seeds random number generation with the specifed algorithm and + time-dependent data if AlgOrStateOrExpState + is an algorithm. +

Otherwise recreates the exported seed and returns the state. See also export_seed/0.

@@ -266,7 +287,7 @@ S0 = rand:seed_s(exsplus), Return a random float.

Returns a random float uniformly distributed in the value - range 0.0 < X < 1.0 and + range 0.0 =< X < 1.0 and updates the state in the process dictionary.

 @@ -277,7 +298,7 @@ S0 = rand:seed_s(exsplus),

Returns, for a specified integer N >= 1, a random integer uniformly distributed in the value range - 1 <= X <= N and + 1 =< X =< N and updates the state in the process dictionary.

 @@ -287,7 +308,7 @@ S0 = rand:seed_s(exsplus), Return a random float.

Returns, for a specified state, random float - uniformly distributed in the value range 0.0 < + uniformly distributed in the value range 0.0 =< X < 1.0 and a new state.

 @@ -298,7 +319,7 @@ S0 = rand:seed_s(exsplus),

Returns, for a specified integer N >= 1 and a state, a random integer uniformly distributed in the value - range 1 <= X <= N and a + range 1 =< X =< N and a new state.

 -- cgit v1.2.3 From 92c79e394041f76d8f676cafe9b6af44522497bd Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Wed, 22 Mar 2017 09:41:57 +0100 Subject: stdlib: Add function to io_lib to handle Unicode atoms --- lib/stdlib/doc/src/io_lib.xml | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 931e50f6f2..5ae400da62 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. @@ -147,7 +147,7 @@ format string (that is, ~ts or ~tc), the resulting list can contain characters beyond the ISO Latin-1 character range (that is, numbers > 255). If so, the - result is not an ordinary Erlang string(), but can well be + result is still an ordinary Erlang string(), and can well be used in any context where Unicode data is allowed.

@@ -383,6 +383,16 @@ + + + Write an atom. + +

Returns the list of characters needed to print atom + Atom. Non-Latin-1 characters + are escaped.

+ + + Write a character. -- cgit v1.2.3 From 46e08e6ac477d1acccb360ad5d616c96dcdfe850 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Tue, 21 Mar 2017 16:34:32 +0100 Subject: stdlib: Fix Erlang shell regarding Unicode atoms --- lib/stdlib/doc/src/shell.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml index f52bc39deb..ab62c2fcdd 100644 --- a/lib/stdlib/doc/src/shell.xml +++ b/lib/stdlib/doc/src/shell.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. @@ -854,7 +854,7 @@ q - quit erlang {history, N}, where N is the current command number. The function is to return a list of characters or an atom. This constraint is because of the Erlang I/O protocol. Unicode characters - beyond code point 255 are allowed in the list. Notice + beyond code point 255 are allowed in the list and the atom. Notice that in restricted mode the call Mod:Func(L) must be allowed or the default shell prompt function is called.

-- cgit v1.2.3 From 6520f78d4b878ff66adcf8d25de331d8ad06dd1d Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Fri, 7 Apr 2017 16:49:56 +0200 Subject: Update documentation --- lib/stdlib/doc/src/re.xml | 310 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 217 insertions(+), 93 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 7f4f0aa18c..aadb5beaba 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -45,9 +45,10 @@

The matching algorithms of the library are based on the PCRE library, but not all of the PCRE library is interfaced and - some parts of the library go beyond what PCRE offers. The sections of - the PCRE documentation that are relevant to this module are included - here.

+ some parts of the library go beyond what PCRE offers. Currently + PCRE version 8.40 (release date 2017-01-11) is used. The sections + of the PCRE documentation that are relevant to this module are + included here.

The Erlang literal syntax for strings uses the "\" @@ -149,13 +150,25 @@ extended -

Whitespace data characters in the pattern are ignored except - when escaped or inside a character class. Whitespace does not - include character 'vt' (ASCII 11). Characters between an - unescaped # outside a character class and the next newline, - inclusive, are also ignored. This is equivalent to Perl option - /x and can be changed within a pattern by a (?x) - option setting.

+

If this option is set, most white space characters in the + pattern are totally ignored except when escaped or inside a + character class. However, white space is not allowed within + sequences such as (?> that introduce various + parenthesized subpatterns, nor within a numerical quantifier + such as {1,3}. However, ignorable white space is permitted + between an item and a following quantifier and between a + quantifier and a following + that indicates possessiveness. +

+

White space did not used to include the VT character (code + 11), because Perl did not treat this character as white space. + However, Perl changed at release 5.18, so PCRE followed at + release 8.34, and VT is now treated as white space. +

+

This also causes characters between an unescaped # + outside a character class and the next newline, inclusive, to + be ignored. This is equivalent to Perl's /x option, and it + can be changed within a pattern by a (?x) option setting. +

With this option, comments inside complicated patterns can be included. However, notice that this applies only to data characters. Whitespace characters can never appear within special @@ -1321,6 +1334,8 @@ re:split("Erlang","[lg]",[{return,list},{parts,4}]). VM. Notice that the recursion limit does not affect the stack depth of the VM, as PCRE for Erlang is compiled in such a way that the match function never does recursion on the C stack.

+

Note that LIMIT_MATCH and LIMIT_RECURSION can only reduce + the value of the limits set by the caller, not increase them.

@@ -1444,12 +1459,17 @@ Pattern PCRE matches Perl matches \nLine feed (hex 0A) \rCarriage return (hex 0D) \tTab (hex 09) + \0ddCharacter with octal code 0dd \dddCharacter with octal code ddd, or back reference + \o{ddd..}character with octal code ddd.. \xhhCharacter with hex code hh \x{hhh..}Character with hex code hhh.. +

Note that \0dd is always an octal code, and that \8 and \9 are + the literal characters "8" and "9".

 +

The precise effect of \cx on ASCII characters is as follows: if x is a lowercase letter, it is converted to upper case. Then bit 6 of the character (hex 40) is inverted. Thus \cA to \cZ become hex 01 to hex 1A @@ -1461,50 +1481,38 @@ Pattern PCRE matches Perl matches

The \c facility was designed for use with ASCII characters, but with the extension to Unicode it is even less useful than it once was.

-

By default, after \x, from zero to two hexadecimal digits are read - (letters can be in upper or lower case). Any number of hexadecimal digits - can appear between \x{ and }, but the character code is constrained as - follows:

- - - 8-bit non-Unicode mode - < 0x100 - 8-bit UTF-8 mode - < 0x10ffff and a valid code point - - -

Invalid Unicode code points are the range 0xd800 to 0xdfff (the so-called - "surrogate" code points), and 0xffef.

- -

If characters other than hexadecimal digits appear between \x{ and }, - or if there is no terminating }, this form of escape is not recognized. - Instead, the initial \x is interpreted as a basic hexadecimal escape, - with no following digits, giving a character whose value is zero.

- -

Characters whose value is < 256 can be defined by either of the two - syntaxes for \x. There is no difference in the way they are handled. For - example, \xdc is the same as \x{dc}.

-

After \0 up to two further octal digits are read. If there are fewer than - two digits, only those that are present are used. Thus the sequence - \0\x\07 specifies two binary zeros followed by a BEL character (code value - 7). Ensure to supply two digits after the initial zero if the pattern - character that follows is itself an octal digit.

+ two digits, just those that are present are used. Thus the sequence + \0\x\015 specifies two binary zeros followed by a CR character (code value + 13). Make sure you supply two digits after the initial zero if the pattern + character that follows is itself an octal digit.

+ +

The escape \o must be followed by a sequence of octal digits, enclosed + in braces. An error occurs if this is not the case. This escape is a recent + addition to Perl; it provides way of specifying character code points as + octal numbers greater than 0777, and it also allows octal numbers and back + references to be unambiguously specified.

+ +

For greater clarity and unambiguity, it is best to avoid following \ by + a digit greater than zero. Instead, use \o{} or \x{} to specify character + numbers, and \g{} to specify back references. The following paragraphs + describe the old, ambiguous syntax.

The handling of a backslash followed by a digit other than 0 is - complicated. Outside a character class, PCRE reads it and any following - digits as a decimal number. If the number is < 10, or if there have + complicated, and Perl has changed in recent releases, causing PCRE also + to change. Outside a character class, PCRE reads the digit and any following + digits as a decimal number. If the number is < 8, or if there have been at least that many previous capturing left parentheses in the expression, the entire sequence is taken as a back reference. A description of how this works is provided later, following the discussion of parenthesized subpatterns.

-

Inside a character class, or if the decimal number is > 9 and there - have not been that many capturing subpatterns, PCRE re-reads up to three - octal digits following the backslash, and uses them to generate a data - character. Any subsequent digits stand for themselves. The value of the - character is constrained in the same way as characters specified in - hexadecimal. For example:

+

Inside a character class, or if the decimal number following \ is > + 7 and there have not been that many capturing subpatterns, PCRE handles + \8 and \9 as the literal characters "8" and "9", and otherwise re-reads + up to three octal digits following the backslash, and using them to + generate a data character. Any subsequent digits stand for themselves. + For example:

\040 @@ -1526,12 +1534,38 @@ Pattern PCRE matches Perl matches \377 Can be a back reference, otherwise value 255 (decimal) \81 - Either a back reference, or a binary zero followed by the two - characters "8" and "1" + Either a back reference, or the two characters "8" and "1" + + +

Notice that octal values >= 100 that are specified using this syntax + must not be introduced by a leading zero, as no more than three octal digits + are ever read.

+ +

By default, after \x that is not followed by {, from zero to two + hexadecimal digits are read (letters can be in upper or lower case). Any + number of hexadecimal digits may appear between \x{ and }. If a character + other than a hexadecimal digit appears between \x{ and }, or if there is no + terminating }, an error occurs. +

+ +

Characters whose value is less than 256 can be defined by either of the + two syntaxes for \x. There is no difference in the way they are handled. For + example, \xdc is exactly the same as \x{dc}.

+ +

Constraints on character values

+ +

Characters that are specified using octal or hexadecimal numbers are + limited to certain values, as follows:

+ + 8-bit non-UTF mode +

< 0x100

 + 8-bit UTF-8 mode +

< 0x10ffff and a valid codepoint

 +

Invalid Unicode codepoints are the range 0xd800 to 0xdfff (the + so-called "surrogate" codepoints), and 0xffef.

-

Notice that octal values >= 100 must not be introduced by a leading - zero, as no more than three octal digits are ever read.

+

Escape sequences in character classes

All the sequences that define a single character value can be used both inside and outside character classes. Also, inside a character class, \b @@ -1597,11 +1631,14 @@ Pattern PCRE matches Perl matches appropriate type. If the current matching point is at the end of the subject string, all fail, as there is no character to match.

-

For compatibility with Perl, \s does not match the VT character - (code 11). This makes it different from the Posix "space" class. The \s - characters are HT (9), LF (10), FF (12), CR (13), and space (32). If "use - locale;" is included in a Perl script, \s can match the VT character. In - PCRE, it never does.

+

For compatibility with Perl, \s did not used to match the VT character (code + 11), which made it different from the the POSIX "space" class. However, Perl + added VT at release 5.18, and PCRE followed suit at release 8.34. The default + \s characters are now HT (9), LF (10), VT (11), FF (12), CR (13), and space + (32), which are defined as white space in the "C" locale. This list may vary if + locale-specific matching is taking place. For example, in some locales the + "non-breaking space" character (\xA0) is recognized as white space, and in + others the VT character is not.

A "word" character is an underscore or any character that is a letter or a digit. By default, the definition of letters and digits is controlled by @@ -1619,9 +1656,9 @@ Pattern PCRE matches Perl matches \dAny character that \p{Nd} matches (decimal digit) - \sAny character that \p{Z} matches, plus HT, LF, FF, CR + \sAny character that \p{Z} or \h or \v - \wAny character that \p{L} or \p{N} matches, plus + \wAny character that matches \p{L} or \p{N} matches, plus underscore @@ -1769,6 +1806,7 @@ Pattern PCRE matches Perl matches Avestan Balinese Bamum + Bassa_Vah Batak Bengali Bopomofo @@ -1777,6 +1815,7 @@ Pattern PCRE matches Perl matches Buhid Canadian_Aboriginal Carian + Caucasian_Albanian Chakma Cham Cherokee @@ -1787,11 +1826,14 @@ Pattern PCRE matches Perl matches Cyrillic Deseret Devanagari + Duployan Egyptian_Hieroglyphs + Elbasan Ethiopic Georgian Glagolitic Gothic + Grantha Greek Gujarati Gurmukhi @@ -1811,40 +1853,56 @@ Pattern PCRE matches Perl matches Kayah_Li Kharoshthi Khmer + Khojki + Khudawadi Lao Latin Lepcha Limbu + Linear_A Linear_B Lisu Lycian Lydian + Mahajani Malayalam Mandaic + Manichaean Meetei_Mayek + Mende_Kikakui Meroitic_Cursive Meroitic_Hieroglyphs Miao + Modi Mongolian + Mro Myanmar + Nabataean New_Tai_Lue Nko Ogham + Ol_Chiki Old_Italic + Old_North_Arabian + Old_Permic Old_Persian Oriya Old_South_Arabian Old_Turkic - Ol_Chiki Osmanya + Pahawh_Hmong + Palmyrene + Pau_Cin_Hau Phags_Pa Phoenician + Psalter_Pahlavi Rejang Runic Samaritan Saurashtra Sharada Shavian + Siddham Sinhala Sora_Sompeng Sundanese @@ -1862,8 +1920,10 @@ Pattern PCRE matches Perl matches Thai Tibetan Tifinagh + Tirhuta Ugaritic Vai + Warang_Citi Yi @@ -2001,10 +2061,10 @@ Pattern PCRE matches Perl matches

In addition to the standard Unicode properties described earlier, PCRE supports four more that make it possible to convert traditional escape - sequences, such as \w and \s, and Posix character classes to use Unicode + sequences, such as \w and \s to use Unicode properties. PCRE uses these non-standard, non-Perl properties internally - when PCRE_UCP is set. However, they can also be used explicitly. - The properties are as follows:

+ when the ucp option is passed. However, they can also be used + explicitly. The properties are as follows:

Xan @@ -2030,6 +2090,16 @@ Pattern PCRE matches Perl matches +

Perl and POSIX space are now the same. Perl added VT to its space + character set at release 5.18 and PCRE changed at release 8.34.

+ +

Xan matches characters that have either the L (letter) or the N (number) + property. Xps matches the characters tab, linefeed, vertical tab, form feed, + or carriage return, and any other character that has the Z (separator) + property. Xsp is the same as Xps; it used to exclude vertical tab, for Perl + compatibility, but Perl changed, and so PCRE followed at release 8.34. Xwd + matches the same characters as Xan, plus underscore. +

There is another non-standard property, Xuc, which matches any character that can be represented by a Universal Character Name in C++ and other programming languages. These are the characters $, @, ` (grave accent), @@ -2062,7 +2132,9 @@ foo\Kbar

Perl documents that the use of \K within assertions is "not well defined". In PCRE, \K is acted upon when it occurs inside positive - assertions, but is ignored in negative assertions.

+ assertions, but is ignored in negative assertions. Note that when a + pattern such as (?=ab\K) matches, the reported start of the match can + be greater than the end of the match.

Simple Assertions

@@ -2301,7 +2373,8 @@ foo\Kbar m, inclusive. If a minus character is required in a class, it must be escaped with a backslash or appear in a position where it cannot be interpreted as indicating a range, typically as the first or last - character in the class.

+ character in the class, or immediately after a range. For example, [b-d-z] + matches letters in the range b to d, a hyphen character, or z.

The literal character "]" cannot be the end character of a range. A pattern such as [W-]46] is interpreted as a class of two characters ("W" @@ -2311,6 +2384,11 @@ foo\Kbar followed by two other characters. The octal or hexadecimal representation of "]" can also be used to end a range.

+

An error is generated if a POSIX character class (see below) or an + escape sequence other than one that defines a single character appears at + a point where a range ending character is expected. For example, [z-\xff] + is valid, but [A-\d] and [A-[:digit:]] are not.

+

Ranges operate in the collating sequence of character values. They can also be used for characters specified numerically, for example, [\000-\037]. Ranges can include any characters that are valid for the @@ -2353,7 +2431,8 @@ foo\Kbar range) Circumflex (only at the start) Opening square bracket (only when it can be interpreted as - introducing a Posix class name; see the next section) + introducing a Posix class name, or for a special compatibility + feature; see the next two sections) Terminating closing square bracket @@ -2385,16 +2464,18 @@ foo\Kbar printPrinting characters, including space punctPrinting characters, excluding letters, digits, and space - spaceWhitespace (not quite the same as \s) + spaceWhitespace (the same as \s from PCRE 8.34) upperUppercase letters word"Word" characters (same as \w) xdigitHexadecimal digits -

The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), - and space (32). Notice that this list includes the VT character (code 11). - This makes "space" different to \s, which does not include VT (for Perl - compatibility).

+

The default "space" characters are HT (9), LF (10), VT (11), FF (12), + CR (13), and space (32). If locale-specific matching is taking place, the + list of space characters may be different; there may be fewer or more of + them. "Space" used to be different to \s, which did not include VT, for + Perl compatibility. However, Perl changed at release 5.18, and PCRE followed + at release 8.34. "Space" and \s now match the same set of characters.

The name "word" is a Perl extension, and "blank" is a GNU extension from Perl 5.8. Another Perl extension is negation, which is indicated by a ^ @@ -2408,11 +2489,11 @@ foo\Kbar "ch" is a "collating element", but these are not supported, and an error is given if they are encountered.

-

By default, in UTF modes, characters with values > 255 do not match +

By default, characters with values > 255 do not match any of the Posix character classes. However, if option PCRE_UCP is passed to pcre_compile(), some of the classes are changed so that - Unicode character properties are used. This is achieved by replacing the - Posix classes by other sequences, as follows:

+ Unicode character properties are used. This is achieved by replacing + certain Posix classes by other sequences, as follows:

[:alnum:]Becomes \p{Xan} @@ -2425,9 +2506,49 @@ foo\Kbar [:word:]Becomes \p{Xwd} -

Negated versions, such as [:^alpha:], use \P instead of \p. The other - Posix classes are unchanged, and match only characters with code points - < 256.

+

Negated versions, such as [:^alpha:], use \P instead of \p. Three other + POSIX classes are handled specially in UCP mode:

+ + [:graph:] +

This matches characters that have glyphs that mark the page + when printed. In Unicode property terms, it matches all characters with + the L, M, N, P, S, or Cf properties, except for:

+ + U+061C

Arabic Letter Mark

 + U+180E

Mongolian Vowel Separator

 + U+2066 - U+2069

Various "isolate"s

 + + + [:print:] +

This matches the same characters as [:graph:] plus space + characters that are not controls, that is, characters with the Zs + property.

 + [:punct:]

This matches all characters that have + the Unicode P (punctuation) property, plus those characters whose code + points are less than 128 that have the S (Symbol) property.

 + +

The other POSIX classes are unchanged, and match only characters with + code points less than 128. +

+ +

Compatibility Feature for Word Boundaries

+ +

In the POSIX.2 compliant library that was included in 4.4BSD Unix, + the ugly syntax [[:<:]] and [[:>:]] is used for matching "start + of word" and "end of word". PCRE treats these items as follows:

+ + [[:<:]]

is converted to \b(?=\w)

 + [[:>:]]

is converted to \b(?<=\w)

 + +

Only these exact character sequences are recognized. A sequence such as + [a[:<:]b] provokes error for an unrecognized POSIX class name. This + support is not compatible with Perl. It is provided to help migrations from + other environments, and is best not used in any new patterns. Note that \b + matches at the start and the end of a word (see "Simple assertions" above), + and in a Perl-style pattern the preceding or following character normally + shows which is wanted, without the need for the assertions that are used + above in order to give exactly the POSIX behaviour.

+
@@ -2476,8 +2597,7 @@ gilbert|sullivan

When one of these option changes occurs at top-level (that is, not inside subpattern parentheses), the change applies to the remainder of the - pattern that follows. If the change is placed right at the start of a - pattern, PCRE extracts it into the global options.

+ pattern that follows.

An option change within a subpattern (see section Subpatterns) affects only that part of the subpattern that follows it. So, the following matches abc and aBc and @@ -2645,9 +2765,9 @@ the ((?:red|white) (king|queen)) parentheses from other parts of the pattern, such as back references, recursion, and conditions, can be made by name and by number.

-

Names consist of up to 32 alphanumeric characters and underscores. Named - capturing parentheses are still allocated numbers as well as names, - exactly as if the names were not present. +

Names consist of up to 32 alphanumeric characters and underscores, but + must start with a non-digit. Named capturing parentheses are still allocated + numbers as well as names, exactly as if the names were not present. The capture specification to run/3 can use named values if they are present in the regular expression.

@@ -3118,7 +3238,14 @@ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa purposes of numbering the capturing subpatterns in the whole pattern. However, substring capturing is done only for positive assertions. (Perl sometimes, but not always, performs capturing in negative assertions.)

- + +

If a positive assertion containing one or more capturing subpatterns + succeeds, but failure to match later in the pattern causes backtracking over + this assertion, the captures within the assertion are reset only if no higher + numbered captures are already set. This is, unfortunately, a fundamental + limitation of the current implementation, and as PCRE1 is now in + maintenance-only status, it is unlikely ever to change.

+

For compatibility with Perl, assertion subpatterns can be repeated. However, it makes no sense to assert the same thing many times, the side effect of capturing parentheses can occasionally be useful. In practice, @@ -3371,12 +3498,7 @@ abcd$

Perl uses the syntax (?(<name>)...) or (?('name')...) to test for a used subpattern by name. For compatibility with earlier versions of PCRE, which had this facility before Perl, the syntax (?(name)...) is also - recognized. However, there is a possible ambiguity with this syntax, as - subpattern names can consist entirely of digits. PCRE looks first for a - named subpattern; if it cannot find one and the name consists entirely of - digits, PCRE looks for a subpattern of that number, which must be > 0. - Using subpattern names that consist entirely of digits is not - recommended.

+ recognized.

Rewriting the previous example to use a named subpattern gives:

@@ -3958,11 +4080,13 @@ a+(*COMMIT)b 2> re:run("xyzabc","(*COMMIT)abc",[{capture,all,list},no_start_optimize]). nomatch -

PCRE knows that any match must start with "a", so the optimization skips - along the subject to "a" before running the first match attempt, which - succeeds. When the optimization is disabled by option - no_start_optimize, the match starts at "x" and so the (*COMMIT) - causes it to fail without trying any other starting points.

+

For this pattern, PCRE knows that any match must start with "a", so the + optimization skips along the subject to "a" before applying the pattern to the + first set of data. The match attempt then succeeds. In the second call the + no_start_optimize disables the optimization that skips along to the + first character. The pattern is now applied starting at "x", and so the + (*COMMIT) causes the match to fail without trying any other starting + points.

The following verb causes the match to fail at the current starting position in the subject if there is a later matching failure that causes @@ -4138,7 +4262,7 @@ A (B(*THEN)C | (*FAIL)) | D ...(*COMMIT)(*PRUNE)...

If there is a matching failure to the right, backtracking onto (*PRUNE) - cases it to be triggered, and its action is taken. There can never be a + causes it to be triggered, and its action is taken. There can never be a backtrack onto (*COMMIT).

Backtracking Verbs in Repeated Groups

-- cgit v1.2.3 From 05f20a9790fa88011c1ce7099e0a660aa83195a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Fri, 7 Apr 2017 13:07:48 +0200 Subject: erl_tar: Handle leading slashes and directory traversal attacks --- lib/stdlib/doc/src/erl_tar.xml | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml index f28d8b425b..fab7c832d5 100644 --- a/lib/stdlib/doc/src/erl_tar.xml +++ b/lib/stdlib/doc/src/erl_tar.xml @@ -292,6 +292,10 @@ Fd is assumed to be a file descriptor returned from function file:open/2.

Otherwise, Name is to be a filename.

+

Leading slashes in tar member names will be removed before + writing the file. That is, absolute paths will be turned into + relative paths. There will be an info message written to the error + logger when paths are changed in this way.

 -- cgit v1.2.3 From f0dc506eac4b6b62a88cb1bb288a29d138d068c7 Mon Sep 17 00:00:00 2001 From: Manuel Rubio Date: Mon, 17 Apr 2017 21:30:21 +0100 Subject: add re:version/0 documentation and update the copyright of the file to 2017 --- lib/stdlib/doc/src/re.xml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 7f4f0aa18c..8072e8fd97 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -5,7 +5,7 @@
2007 - 2016 + 2017 Ericsson AB, All Rights Reserved @@ -77,6 +77,14 @@ + + + Gives the PCRE version of the system in a string format + +

The return of this function is a string with the PCRE version of the system that was used in the Erlang/OTP compilation.

+ + + Compile a regular expression into a match program -- cgit v1.2.3 From d30cae56d82763681b633cba25ad553eb672ec16 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 6 Apr 2017 16:09:38 +0200 Subject: Make Module:init/1 mandatory --- lib/stdlib/doc/src/gen_statem.xml | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 5eb13db1aa..f7baaad5d1 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -146,7 +146,7 @@ erlang:'!' -----> Module:StateName/3 This gathers all code for a specific state in one function as the gen_statem engine branches depending on state name. - Notice the fact that there is a mandatory callback function + Note the fact that the callback function Module:terminate/3 makes the state name terminate unusable in this mode.

@@ -1704,7 +1704,7 @@ handle_event(_, _, State, Data) -> Module:init(Args) -> Result(StateType) - Optional function for initializing process and internal state. + Initializing process and internal state. Args = term() @@ -1720,7 +1720,7 @@ handle_event(_, _, State, Data) -> start_link/3,4 or start/3,4, - this optional function is called by the new process to initialize + this function is called by the new process to initialize the implementation state and server data.

@@ -1729,13 +1729,16 @@ handle_event(_, _, State, Data) ->

- This callback is optional, so a callback module does not need - to export it, but most do. If this function is not exported, - the gen_statem should be started through + Note that if the gen_statem is started trough proc_lib and - enter_loop/4-6. + enter_loop/4-6, + this callback will never be called. + Since this callback is not optional it can + in that case be implemented as:

+ 
+init(Args) -> erlang:error(not_implemented, [Args]).
 -- cgit v1.2.3 From bca4b5c87fd1aae2fdcb78b605181393a0caf9d9 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 7 Feb 2017 22:38:36 +0100 Subject: Implement erlang:start_timer opts --- lib/stdlib/doc/src/gen_statem.xml | 75 ++++++++++++++++++++++++++++----------- 1 file changed, 55 insertions(+), 20 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index f7baaad5d1..44ac1ad8ad 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -785,28 +785,38 @@ handle_event(_, _, State, Data) ->

- Generates an event of + Starts a timer set by + enter_action() + timeout. + When the timer expires an event of event_type() - timeout - after this time (in milliseconds) unless another - event arrives or has arrived - in which case this time-out is cancelled. + timeout will be generated. + See + erlang:start_timer/4 + for how Time and + Options + are interpreted. All Options of erlang:start_timer/4 + will not necessarily be supported in the future. +

+

+ Any event that arrives cancels this time-out. Note that a retried or inserted event counts as arrived. So does a state time-out zero event, if it was generated - before this timer is requested. + before this time-out is requested.

- If the value is infinity, no timer is started, as - it never would trigger anyway. + If Time is infinity, + no timer is started, as it never would expire anyway.

- If the value is 0 no timer is actually started, + If Time is relative and 0 + no timer is actually started, instead the the time-out event is enqueued to ensure that it gets processed before any not yet received external event.

- Note that it is not possible or needed to cancel this time-out, + Note that it is not possible nor needed to cancel this time-out, as it is cancelled automatically by any other event.

@@ -815,19 +825,26 @@ handle_event(_, _, State, Data) ->

- Generates an event of + Starts a timer set by + enter_action() + state_timeout. + When the timer expires an event of event_type() - state_timeout - after this time (in milliseconds) unless the gen_statem - changes states (NewState =/= OldState) - which case this time-out is cancelled. + state_timeout will be generated. + See + erlang:start_timer/4 + for how Time and + Options + are interpreted. All Options of erlang:start_timer/4 + will not necessarily be supported in the future.

- If the value is infinity, no timer is started, as - it never would trigger anyway. + If Time is infinity, + no timer is started, as it never would expire anyway.

- If the value is 0 no timer is actually started, + If Time is relative and 0 + no timer is actually started, instead the the time-out event is enqueued to ensure that it gets processed before any not yet received external event. @@ -839,6 +856,20 @@ handle_event(_, _, State, Data) ->

+ + + +

+ If Abs is true an absolute timer is started, + and if it false a relative, which is the default. + See + erlang:start_timer/4 + for details. +

+

+

+ + @@ -954,7 +985,9 @@ handle_event(_, _, State, Data) -> Sets the transition_option() event_timeout() - to Time with EventContent. + to Time with EventContent + and options + Options.

state_timeout @@ -963,7 +996,9 @@ handle_event(_, _, State, Data) -> Sets the transition_option() state_timeout() - to Time with EventContent. + to Time with EventContent + and options + Options.

-- cgit v1.2.3 From dff85f3d6fdb4b3453d863bf9208073564a9fcf2 Mon Sep 17 00:00:00 2001 From: Guilherme Andrade Date: Sat, 18 Mar 2017 19:48:23 +0000 Subject: rand: Support arbitrary normal distributions --- lib/stdlib/doc/src/rand.xml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 8745e16908..3a5d18dc35 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -119,6 +119,11 @@ S0 = rand:seed_s(exsplus), 
 {SND0, S2} = rand:normal_s(S1),
+

Create a normal deviate with mean -3 and variance 0.5:

+ + 
+{ND0, S3} = rand:normal_s(-3, 0.5, S2),
+

This random number generator is not cryptographically strong. If a strong cryptographic random number generator is @@ -200,6 +205,15 @@ S0 = rand:seed_s(exsplus), + + + Return a normal distributed random float. + +

Returns a normal N(Mean, Variance) deviate float + and updates the state in the process dictionary.

+ + + Return a standard normal distributed random float. @@ -210,6 +224,15 @@ S0 = rand:seed_s(exsplus), + + + Return a normal distributed random float. + +

Returns, for a specified state, a normal N(Mean, Variance) + deviate float and a new state.

+ + + Seed random number generator. -- cgit v1.2.3 From 437555fd6c495915773b0f9ade7aad3fd0a73a1b Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 21 Mar 2017 16:36:33 +0100 Subject: Implement Xoroshiro116+ and improve statisticals Implement Xoroshiro116+ as 'exrop' with fixes. Deprecate all old algorithms but reincarnate 'exs1024' as 'exs1024s' and 'exsplus' as 'exsp' with fixes. Fixes: * Avoid skew for uniform integers caused by using a simple 'rem' operation for range confinement. Correctness requires retry with new random value for an unfortunate first value. * Implement a correct algorithm that collects enough random bits for ranges larger than the generator's precision. * Fix uniform density for floats by acquiring 53 bits then multiplying with 2.0^(-53) which produces floats on the form N * 2.0^(-53). --- lib/stdlib/doc/src/rand.xml | 130 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 107 insertions(+), 23 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 2ddf3021ac..470dc4da97 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -50,26 +50,73 @@

The following algorithms are provided:

- exsplus + exrop -

Xorshift116+, 58 bits precision and period of 2^116-1

+

Xoroshiro116+, 58 bits precision and period of 2^116-1

Jump function: equivalent to 2^64 calls

 - exs64 - -

Xorshift64*, 64 bits precision and a period of 2^64-1

-

Jump function: not available

- - exs1024 + exs1024s

Xorshift1024*, 64 bits precision and a period of 2^1024-1

Jump function: equivalent to 2^512 calls

 + exsp + +

Xorshift116+, 58 bits precision and period of 2^116-1

+

Jump function: equivalent to 2^64 calls

+

+ This is a corrected version of the previous default algorithm, + that now has been superseeded by Xoroshiro116+ (exrop). + Since there is no native 58 bit rotate instruction this + algorithm executes a little (say < 15%) faster than exrop. + See the + algorithms' homepage. +

+ -

The default algorithm is exsplus. If a specific algorithm is +

+ The default algorithm is exrop (Xoroshiro116+). + If a specific algorithm is required, ensure to always use - seed/1 to initialize the state.

+ seed/1 to initialize the state. +

+ +

+ Undocumented (old) algorithms are deprecated but still implemented + so old code relying on them will produce + the same pseudo random sequences as before. +

+ + +

+ There were a number of problems in the implementation + of the now undocumented algorithms, which is why + they are deprecated. The new algorithms are a bit slower + but do not have these problems: +

+

+ Uniform integer ranges had a skew in the probability distribution + that was not noticable for small ranges but for large ranges + less than the generator's precision the probability to produce + a low number could be twice the probability for a high. +

+

+ Uniform integer ranges larger than or equal to the generator's + precision used a floating point fallback that only calculated + with 52 bits which is smaller than the requested range + and therefore were not all numbers in the requested range + even possible to produce. +

+

+ Uniform floats had a non-uniform density so small values + i.e less than 0.5 had got smaller intervals decreasing + as the generated value approached 0.0 although still uniformly + distributed for sufficiently large subranges. The new algorithms + produces uniformly distributed floats on the form N * 2.0^(-53) + hence equally spaced. +

+

Every time a random number is requested, a state is used to calculate it and a new state is produced. The state can either be @@ -99,19 +146,19 @@ R1 = rand:uniform(),

Use a specified algorithm:

-_ = rand:seed(exs1024),
+_ = rand:seed(exs1024s),
 R2 = rand:uniform(),

Use a specified algorithm with a constant seed:

-_ = rand:seed(exs1024, {123, 123534, 345345}),
+_ = rand:seed(exs1024s, {123, 123534, 345345}),
 R3 = rand:uniform(),

Use the functional API with a non-constant seed:

-S0 = rand:seed_s(exsplus),
+S0 = rand:seed_s(exrop),
 {R4, S1} = rand:uniform_s(S0),

Create a standard normal deviate:

@@ -127,6 +174,39 @@ S0 = rand:seed_s(exsplus),

+

+ For all these generators the lowest bit(s) has got + a slightly less random behaviour than all other bits. + 1 bit for exrop (and exsp), + and 3 bits for exs1024s. + See for example the explanation in the + + Xoroshiro128+ + + generator source code: +

+ 
+Beside passing BigCrush, this generator passes the PractRand test suite
+up to (and included) 16TB, with the exception of binary rank tests,
+which fail due to the lowest bit being an LFSR; all other bits pass all
+tests. We suggest to use a sign test to extract a random Boolean value.
+

+ If this is a problem; to generate a boolean + use something like this: +

+ 
(rand:uniform(16) > 8)
+

+ And for a general range, with N = 1 for exrop, + and N = 3 for exs1024s: +

+ 
(((rand:uniform(Range bsl N) - 1) bsr N) + 1)
+

+ The floating point generating functions in this module + waste the lowest bits when converting from an integer + so they avoid this snag. +

+ + @@ -141,6 +221,18 @@ S0 = rand:seed_s(exsplus), + + +

Algorithm-dependent state.

 + + + + +

+ Algorithm-dependent state that can be printed or saved to file. +

+ +

Algorithm specific internal state

 @@ -154,16 +246,8 @@ S0 = rand:seed_s(exsplus),

Algorithm specific internal state

 - -

Algorithm-dependent state.

 - - - - -

- Algorithm-dependent state that can be printed or saved to file. -

- + +

Algorithm specific internal state

 -- cgit v1.2.3 From 8ca53b0f993ffbf2991e3068b76ec15b8f5eca51 Mon Sep 17 00:00:00 2001 From: Zandra Norman Date: Mon, 23 Jan 2017 11:49:32 +0100 Subject: stdlib: Make gen_server callbacks optional --- lib/stdlib/doc/src/gen_server.xml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 662076b5f0..4540449792 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -504,6 +504,13 @@ gen_server:abcast -----> Module:handle_cast/2 Reason = term() + +

This callback is optional, so callback modules need not export it. + If a release upgrade/downgrade with Change={advanced,Extra} + specified in the appup file is made when code_change/3 + isn't implemented the process will crash with an undef exit + reason.

+

This function is called by a gen_server process when it is to update its internal state during a release upgrade/downgrade, that is, when the instruction {update,Module,Change,...}, @@ -690,6 +697,12 @@ gen_server:abcast -----> Module:handle_cast/2  Reason = normal | term() + +

This callback is optional, so callback modules need not + export it. The gen_server module provides a default + implementation of this function that logs about the unexpected + Info message, drops it and returns {noreply, State}.

+

This function is called by a gen_server process when a time-out occurs or when it receives any other message than a synchronous or asynchronous request (or a system message).

@@ -750,6 +763,11 @@ gen_server:abcast -----> Module:handle_cast/2 State = term() + +

This callback is optional, so callback modules need not + export it. The gen_server module provides a default + implementation without cleanup.

+

This function is called by a gen_server process when it is about to terminate. It is to be the opposite of Module:init/1 -- cgit v1.2.3 From db632b91f41c4a01be68d821d6942ff32b86e40b Mon Sep 17 00:00:00 2001 From: Zandra Norman Date: Mon, 23 Jan 2017 16:07:52 +0100 Subject: stdlib: Make gen_event callbacks optional --- lib/stdlib/doc/src/gen_event.xml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 42e952fd46..56cb7974a2 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -579,6 +579,13 @@ gen_event:stop -----> Module:terminate/2 Extra = term() + +

This callback is optional, so callback modules need not export it. + If a release upgrade/downgrade with Change={advanced,Extra} + specified in the .appup file is made when code_change/3 + isn't implemented the event handler will crash with an undef error + reason.

+

This function is called for an installed event handler that is to update its internal state during a release upgrade/downgrade, that is, when the instruction @@ -759,6 +766,12 @@ gen_event:stop -----> Module:terminate/2   Id = term() + +

This callback is optional, so callback modules need not + export it. The gen_event module provides a default + implementation of this function that logs about the unexpected + Info message, drops it and returns {noreply, State}.

+

This function is called for each installed event handler when an event manager receives any other message than an event or a synchronous request (or a system message).

@@ -815,6 +828,11 @@ gen_event:stop -----> Module:terminate/2  Args = Reason = Term = term() + +

This callback is optional, so callback modules need not + export it. The gen_event module provides a default + implementation without cleanup.

+

Whenever an event handler is deleted from an event manager, this function is called. It is to be the opposite of Module:init/1 -- cgit v1.2.3 From 215f61f223a07493d1147a04375d11f3c7819e42 Mon Sep 17 00:00:00 2001 From: Zandra Norman Date: Tue, 24 Jan 2017 13:40:21 +0100 Subject: stdlib: Make gen_fsm callbacks optional --- lib/stdlib/doc/src/gen_fsm.xml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index 719ab2b558..691a039e34 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -562,6 +562,13 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 Extra = term() + +

This callback is optional, so callback modules need not export it. + If a release upgrade/downgrade with Change={advanced,Extra} + specified in the appup file is made when code_change/4 + isn't implemented the process will crash with an undef exit + reason.

+

This function is called by a gen_fsm process when it is to update its internal state data during a release upgrade/downgrade, that is, when instruction {update,Module,Change,...}, @@ -686,6 +693,13 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4  Reason = normal | term() + +

This callback is optional, so callback modules need not + export it. The gen_fsm module provides a default + implementation of this function that logs about the unexpected + Info message, drops it and returns + {next_state, StateName, StateData}.

+

This function is called by a gen_fsm process when it receives any other message than a synchronous or asynchronous event (or a system message).

@@ -899,6 +913,11 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 StateData = term() + +

This callback is optional, so callback modules need not + export it. The gen_fsm module provides a default + implementation without cleanup.

+

This function is called by a gen_fsm process when it is about to terminate. It is to be the opposite of Module:init/1 -- cgit v1.2.3 From 30cae2492d8d8e927d57c0dc656ee2dfbec0a70c Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Mon, 13 Feb 2017 08:20:16 +0100 Subject: Implement {timeout,Name} timeouts --- lib/stdlib/doc/src/gen_statem.xml | 100 +++++++++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 23 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 44ac1ad8ad..1b99b65e09 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -67,13 +67,16 @@ It has the same features and adds some really useful:

- State code is gathered. - The state can be any term. - Events can be postponed. - Events can be self-generated. - Automatic state enter code can be called. - A reply can be sent from a later state. - There can be multiple sys traceable replies. + Gathered state code. + Arbitrary term state. + Event postponing. + Self-generated events. + State time-out. + Multiple generic named time-outs. + Absolute time-out time. + Automatic state enter calls. + Reply from other state than the request. + Multiple sys traceable replies.

The callback model(s) for gen_statem differs from @@ -531,10 +534,12 @@ handle_event(_, _, State, Data) -> originate from the corresponding API functions. For calls, the event contains whom to reply to. Type info originates from regular process messages sent - to the gen_statem. Also, the state machine - implementation can generate events of types - timeout, state_timeout, - and internal to itself. + to the gen_statem. The state machine + implementation can, in addition to the above, + generate + events of types + timeout, {timeout,Name}, + state_timeout, and internal to itself.

@@ -701,13 +706,14 @@ handle_event(_, _, State, Data) ->

- Timeout timers - state_timeout() + Time-out timers + event_timeout(), + generic_timeout() and - event_timeout() + state_timeout() are handled. Time-outs with zero time are guaranteed to be delivered to the state machine before any external - not yet received event so if there is such a timeout requested, + not yet received event so if there is such a time-out requested, the corresponding time-out zero event is enqueued as the newest event.

@@ -795,8 +801,8 @@ handle_event(_, _, State, Data) -> erlang:start_timer/4 for how Time and Options - are interpreted. All Options of erlang:start_timer/4 - will not necessarily be supported in the future. + are interpreted. Future erlang:start_timer/4 Options + will not necessarily be supported.

Any event that arrives cancels this time-out. @@ -821,6 +827,42 @@ handle_event(_, _, State, Data) ->

+ + + +

+ Starts a timer set by + enter_action() + {timeout,Name}. + When the timer expires an event of + event_type() + {timeout,Name} will be generated. + See + erlang:start_timer/4 + for how Time and + Options + are interpreted. Future erlang:start_timer/4 Options + will not necessarily be supported. +

+

+ If Time is infinity, + no timer is started, as it never would expire anyway. +

+

+ If Time is relative and 0 + no timer is actually started, + instead the the time-out event is enqueued to ensure + that it gets processed before any not yet + received external event. +

+

+ Setting a timer with the same Name while it is running + will restart it with the new time-out value. + Therefore it is possible to cancel + a specific time-out by setting it to infinity. +

+ + @@ -835,8 +877,8 @@ handle_event(_, _, State, Data) -> erlang:start_timer/4 for how Time and Options - are interpreted. All Options of erlang:start_timer/4 - will not necessarily be supported in the future. + are interpreted. Future erlang:start_timer/4 Options + will not necessarily be supported.

If Time is infinity, @@ -861,7 +903,7 @@ handle_event(_, _, State, Data) ->

If Abs is true an absolute timer is started, - and if it false a relative, which is the default. + and if it is false a relative, which is the default. See erlang:start_timer/4 for details. @@ -986,7 +1028,19 @@ handle_event(_, _, State, Data) -> transition_option() event_timeout() to Time with EventContent - and options + and time-out options + Options. +

+ + {timeout,Name} + +

+ Sets the + transition_option() + generic_timeout() + to Time for Name + with EventContent + and time-out options Options.

@@ -997,7 +1051,7 @@ handle_event(_, _, State, Data) -> transition_option() state_timeout() to Time with EventContent - and options + and time-out options Options.

@@ -1270,7 +1324,7 @@ handle_event(_, _, State, Data) -> to avoid that the calling process dies when the call times out, you will have to be prepared to handle a late reply. - So why not just allow the calling process to die? + So why not just let the calling process die?

-- cgit v1.2.3 From eff1ee5ebf1d767d610cd6bc059e5f4dea57d2af Mon Sep 17 00:00:00 2001 From: Zandra Norman Date: Mon, 23 Jan 2017 17:06:48 +0100 Subject: stdlib: Make gen_statem callbacks optional --- lib/stdlib/doc/src/gen_statem.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 1b99b65e09..bc86415d28 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -1733,6 +1733,16 @@ handle_event(_, _, State, Data) -> Reason = term() + +

+ This callback is optional, so callback modules need not export it. + If a release upgrade/downgrade with + Change={advanced,Extra} + specified in the .appup file is made + when code_change/4 is not implemented + the process will crash with exit reason undef. +

+

This function is called by a gen_statem when it is to update its internal state during a release upgrade/downgrade, -- cgit v1.2.3 From 75fc94b8b462d7b7f6dd4b706bbe32cff77ee575 Mon Sep 17 00:00:00 2001 From: Dan Gudmundsson Date: Fri, 27 Jan 2017 15:27:37 +0100 Subject: Add nf(k)d, nf(k)c conversion functions to unicode module --- lib/stdlib/doc/src/unicode.xml | 179 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 177 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index 93d0d37456..382b253ba1 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -50,8 +50,35 @@ external entities where this is required. When working inside the Erlang/OTP environment, it is recommended to keep binaries in UTF-8 when representing Unicode characters. ISO Latin-1 encoding is supported both - for backward compatibility and for communication - with external entities not supporting Unicode character sets.

+ for backward compatibility and for communication + with external entities not supporting Unicode character sets.

+

Programs should always operate on a normalized form and compare + canonical-equivalent Unicode characters as equal. All characters + should thus be normalized to one form once on the system borders. + One of the following functions can convert characters to their + normalized forms + characters_to_nfc_list/1, + + characters_to_nfc_binary/1, + + characters_to_nfd_list/1 or + + characters_to_nfd_binary/1. + For general text + + characters_to_nfc_list/1 or + + characters_to_nfc_binary/1 is preferred, and + for identifiers one of the compatibility normalization + functions, such as + + characters_to_nfkc_list/1, + is preferred for security reasons. + The normalization functions where introduced in OTP 20. + Additional information on normalization can be found in the + Unicode FAQ. +

+ @@ -334,6 +361,154 @@ decode_data(Data) -> + + + Normalize characters to a list of canonical equivalent + composed Unicode characters. + +

Converts a possibly deep list of characters and binaries + into a Normalized Form of canonical equivalent Composed + characters according to the Unicode standard.

+

Any binaries in the input must be encoded with utf8 + encoding. +

+

The result is a list of characters.

+ +3> unicode:characters_to_nfc_list([<<"abc..a">>,[778],$a,[776],$o,[776]]). +"abc..åäö" + + + + + + + Normalize characters to a utf8 binary of canonical equivalent + composed Unicode characters. + +

Converts a possibly deep list of characters and binaries + into a Normalized Form of canonical equivalent Composed + characters according to the Unicode standard.

+

Any binaries in the input must be encoded with utf8 + encoding.

+

The result is an utf8 encoded binary.

+ +4> unicode:characters_to_nfc_binary([<<"abc..a">>,[778],$a,[776],$o,[776]]). +<<"abc..åäö"/utf8>> + + + + + + + Normalize characters to a list of canonical equivalent + decomposed Unicode characters. + +

Converts a possibly deep list of characters and binaries + into a Normalized Form of canonical equivalent Decomposed + characters according to the Unicode standard.

+

Any binaries in the input must be encoded with utf8 + encoding. +

+

The result is a list of characters.

+ +1> unicode:characters_to_nfd_list("abc..åäö"). +[97,98,99,46,46,97,778,97,776,111,776] + + + + + + + Normalize characters to a utf8 binary of canonical equivalent + decomposed Unicode characters. + +

Converts a possibly deep list of characters and binaries + into a Normalized Form of canonical equivalent Decomposed + characters according to the Unicode standard.

+

Any binaries in the input must be encoded with utf8 + encoding.

+

The result is an utf8 encoded binary.

+ +2> unicode:characters_to_nfd_binary("abc..åäö"). +<<97,98,99,46,46,97,204,138,97,204,136,111,204,136>> + + + + + + + Normalize characters to a list of canonical equivalent + composed Unicode characters. + +

Converts a possibly deep list of characters and binaries + into a Normalized Form of compatibly equivalent Composed + characters according to the Unicode standard.

+

Any binaries in the input must be encoded with utf8 + encoding. +

+

The result is a list of characters.

+ +3> unicode:characters_to_nfkc_list([<<"abc..a">>,[778],$a,[776],$o,[776],[65299,65298]]). +"abc..åäö32" + + + + + + + Normalize characters to a utf8 binary of compatibly equivalent + composed Unicode characters. + +

Converts a possibly deep list of characters and binaries + into a Normalized Form of compatibly equivalent Composed + characters according to the Unicode standard.

+

Any binaries in the input must be encoded with utf8 + encoding.

+

The result is an utf8 encoded binary.

+ +4> unicode:characters_to_nfkc_binary([<<"abc..a">>,[778],$a,[776],$o,[776],[65299,65298]]). +<<"abc..åäö32"/utf8>> + + + + + + + Normalize characters to a list of compatibly equivalent + decomposed Unicode characters. + +

Converts a possibly deep list of characters and binaries + into a Normalized Form of compatibly equivalent Decomposed + characters according to the Unicode standard.

+

Any binaries in the input must be encoded with utf8 + encoding. +

+

The result is a list of characters.

+ +1> unicode:characters_to_nfkd_list(["abc..åäö",[65299,65298]]). +[97,98,99,46,46,97,778,97,776,111,776,51,50] + + + + + + + Normalize characters to a utf8 binary of compatibly equivalent + decomposed Unicode characters. + +

Converts a possibly deep list of characters and binaries + into a Normalized Form of compatibly equivalent Decomposed + characters according to the Unicode standard.

+

Any binaries in the input must be encoded with utf8 + encoding.

+

The result is an utf8 encoded binary.

+ +2> unicode:characters_to_nfkd_binary(["abc..åäö",[65299,65298]]). +<<97,98,99,46,46,97,204,138,97,204,136,111,204,136,51,50>> + + + + Create a binary UTF byte order mark from encoding. -- cgit v1.2.3 From 2c72e662bad11a41839780f86680d4bb05367c78 Mon Sep 17 00:00:00 2001 From: Dan Gudmundsson Date: Mon, 3 Apr 2017 12:19:21 +0200 Subject: New unicode aware string module that works with unicode:chardata() Works with unicode:chardata() as input as was decided on OTP board meeting as response to EEP-35 a long time ago. Works on graphemes clusters as base, with a few exceptions, does not handle classic (nor nfd'ified) Hangul nor the extended grapheme clusters such as the prepend class. That would make handling binaries as input/output very slow. List input => list output, binary input => binary output and mixed input => mixed output for all find/split functions. So that results can be post-processed without the need to invoke unicode:characters_to_list|binary for intermediate data. pad functions return lists of unicode:chardata() for performance. --- lib/stdlib/doc/src/string.xml | 741 ++++++++++++++++++++++++++++++++--- lib/stdlib/doc/src/unicode_usage.xml | 70 ++-- 2 files changed, 720 insertions(+), 91 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml index dddedf1132..dc83c40a9a 100644 --- a/lib/stdlib/doc/src/string.xml +++ b/lib/stdlib/doc/src/string.xml @@ -36,8 +36,613 @@ String processing functions.

This module provides functions for string processing.

+

A string in this module is represented by + unicode:chardata(), that is, a list of codepoints, + binaries with UTF-8-encoded codepoints + (UTF-8 binaries), or a mix of the two.

+ +"abcd" is a valid string +<<"abcd">> is a valid string +["abcd"] is a valid string +<<"abc..åäö"/utf8>> is a valid string +<<"abc..åäö">> is NOT a valid string, + but a binary with Latin-1-encoded codepoints +[<<"abc">>, "..åäö"] is a valid string +[atom] is NOT a valid string +

+ This module operates on grapheme clusters. A grapheme cluster + is a user-perceived character, which can be represented by several + codepoints. +

+ +"å" [229] or [97, 778] +"e̊" [101, 778] +

+ The string length of "ß↑e̊" is 3, even though it is represented by the + codepoints [223,8593,101,778] or the UTF-8 binary + <<195,159,226,134,145,101,204,138>>. +

+

+ Grapheme clusters for codepoints of class prepend + and non-modern (or decomposed) Hangul is not handled for performance + reasons in + find/3, + replace/3, + split/2, + split/2 and + trim/3. +

+

+ Splitting and appending strings is to be done on grapheme clusters + borders. + There is no verification that the results of appending strings are + valid or normalized. +

+

+ Most of the functions expect all input to be normalized to one form, + see for example + unicode:characters_to_nfc_list/1. +

+

+ Language or locale specific handling of input is not considered + in any function. +

+

+ The functions can crash for non-valid input strings. For example, + the functions expect UTF-8 binaries but not all functions + verify that all binaries are encoded correctly. +

+

+ Unless otherwise specified the return value type is the same as + the input type. That is, binary input returns binary output, + list input returns a list output, and mixed input can return a + mixed output.

+ +1> string:trim(" sarah "). +"sarah" +2> string:trim(<<" sarah ">>). +<<"sarah">> +3> string:lexemes("foo bar", " "). +["foo","bar"] +4> string:lexemes(<<"foo bar">>, " "). +[<<"foo">>,<<"bar">>] +

This module has been reworked in Erlang/OTP 20 to + handle + unicode:chardata() and operate on grapheme + clusters. The old + functions that only work on Latin-1 lists as input + are still available but should not be + used. They will be deprecated in Erlang/OTP 21. +

+ + + + + +

A user-perceived character, consisting of one or more + codepoints.

+ + + + + + + + + Convert a string to a comparable string. + +

+ Converts String to a case-agnostic + comparable string. Function casefold/1 is preferred + over lowercase/1 when two strings are to be compared + for equality. See also equal/4. +

+

Example:

+ 
+1> string:casefold("Ω and ẞ SHARP S").
+"ω and ss sharp s"
+ + + + + + Remove trailing end of line control characters. + +

+ Returns a string where any trailing \n or + \r\n have been removed from String. +

+

Example:

+ 
+182> string:chomp(<<"\nHello\n\n">>).
+<<"\nHello">>
+183> string:chomp("\nHello\r\r\n").
+"\nHello\r"
+ + + + + + + + Test string equality. + +

+ Returns true if A and + B are equal, otherwise false. +

+

+ If IgnoreCase is true + the function does + casefolding on the fly before the equality test. +

+

If Norm is not none + the function applies normalization on the fly before the equality test. + There are four available normalization forms: + nfc, + nfd, + nfkc, and + nfkd. +

+

By default, + IgnoreCase is false and + Norm is none.

+

Example:

+ 
+1> string:equal("åäö", <<"åäö"/utf8>>).
+true
+2> string:equal("åäö", unicode:characters_to_nfd_binary("åäö")).
+false
+3> string:equal("åäö", unicode:characters_to_nfd_binary("ÅÄÖ"), true, nfc).
+true
+ + + + + + + Find start of substring. + +

+ Removes anything before SearchPattern in String + and returns the remainder of the string or nomatch if SearchPattern is not + found. + Dir, which can be leading or + trailing, indicates from which direction characters + are to be searched. +

+

+ By default, Dir is leading. +

+

Example:

+ 
+1> string:find("ab..cd..ef", ".").
+"..cd..ef"
+2> string:find(<<"ab..cd..ef">>, "..", trailing).
+<<"..ef">>
+3> string:find(<<"ab..cd..ef">>, "x", leading).
+nomatch
+4> string:find("ab..cd..ef", "x", trailing).
+nomatch
+ + + + + + Check if the string is empty. + +

Returns true if String is the + empty string, otherwise false.

+

Example:

+ 
+1> string:is_empty("foo").
+false
+2> string:is_empty(["",<<>>]).
+true
+ + + + + + Calculate length of the string. + +

+ Returns the number of grapheme clusters in String. +

+

Example:

+ 
+1> string:length("ß↑e̊").
+3
+2> string:length(<<195,159,226,134,145,101,204,138>>).
+3
+ + + + + + Split string into lexemes. + +

+ Returns a list of lexemes in String, separated + by the grapheme clusters in SeparatorList. +

+

+ Notice that, as shown in this example, two or more + adjacent separator graphemes clusters in String + are treated as one. That is, there are no empty + strings in the resulting list of lexemes. + See also split/3 which returns + empty strings. +

+

Notice that [$\r,$\n] is one grapheme cluster.

+

Example:

+ 
+1> string:lexemes("abc de̊fxxghix jkl\r\nfoo", "x e" ++ [[$\r,$\n]]).
+["abc","de̊f","ghi","jkl","foo"]
+2> string:lexemes(<<"abc de̊fxxghix jkl\r\nfoo"/utf8>>, "x e" ++ [$\r,$\n]).
+[<<"abc">>,<<"de̊f"/utf8>>,<<"ghi">>,<<"jkl\r\nfoo">>]
+ + + + + + Convert a string to lowercase + +

+ Converts String to lowercase. +

+

+ Notice that function casefold/1 + should be used when converting a string to + be tested for equality. +

+

Example:

+ 
+2> string:lowercase(string:uppercase("Michał")).
+"michał"
+ + + + + + Pick the first codepoint. + +

+ Returns the first codepoint in String + and the rest of String in the tail. +

+

Example:

+ 
+1> string:next_codepoint(unicode:characters_to_binary("e̊fg")).
+[101|<<"̊fg"/utf8>>]
+ + + + + + Pick the first grapheme cluster. + +

+ Returns the first grapheme cluster in String + and the rest of String in the tail. +

+

Example:

+ 
+1> string:next_grapheme(unicode:characters_to_binary("e̊fg")).
+["e̊"|<<"fg">>]
+ + + + + + Pick the nth lexeme. + +

Returns lexeme number N in + String, where lexemes are separated by + the grapheme clusters in SeparatorList. +

+

Example:

+ 
+1> string:nth_lexeme("abc.de̊f.ghiejkl", 3, ".e").
+"ghi"
+ + + + + + + + Pad a string to given length. + +

+ Pads String to Length with + grapheme cluster Char. + Dir, which can be leading, trailing, + or both, indicates where the padding should be added. +

+

By default, Char is $\s and + Dir is trailing. +

+

Example:

+ 
+1> string:pad(<<"He̊llö"/utf8>>, 8).
+[<<72,101,204,138,108,108,195,182>>,32,32,32]
+2> io:format("'~ts'~n",[string:pad("He̊llö", 8, leading)]).
+'   He̊llö'
+3> io:format("'~ts'~n",[string:pad("He̊llö", 8, both)]).
+' He̊llö  '
+ + + + + + Remove prefix from string. + +

+ If Prefix is the prefix of + String, removes it and returns the + remainder of String, otherwise returns + nomatch. +

+

Example:

+ 
+1> string:prefix(<<"prefix of string">>, "pre").
+<<"fix of string">>
+2> string:prefix("pre", "prefix").
+nomatch
+ + + + + + + Replace a pattern in string. + +

+ Replaces SearchPattern in String + with Replacement. + Where, default leading, indicates whether + the leading, the trailing or all encounters of + SearchPattern are to be replaced. +

+

Can be implemented as:

+ 
lists:join(Replacement, split(String, SearchPattern, Where)).
+

Example:

+ 
+1> string:replace(<<"ab..cd..ef">>, "..", "*").
+[<<"ab">>,"*",<<"cd..ef">>]
+2> string:replace(<<"ab..cd..ef">>, "..", "*", all).
+[<<"ab">>,"*",<<"cd">>,"*",<<"ef">>]
+ + + + + + Reverses a string + +

+ Returns the reverse list of the grapheme clusters in String. +

+

Example:

+ 
+1> Reverse = string:reverse(unicode:characters_to_nfd_binary("ÅÄÖ")).
+[[79,776],[65,776],[65,778]]
+2> io:format("~ts~n",[Reverse]).
+ÖÄÅ
+ + + + + + + Extract a part of string + +

Returns a substring of String of + at most Length grapheme clusters, starting at position + Start.

+

By default, Length is infinity.

+

Example:

+ 
+1> string:slice(<<"He̊llö Wörld"/utf8>>, 4).
+<<"ö Wörld"/utf8>>
+2> string:slice(["He̊llö ", <<"Wörld"/utf8>>], 4,4).
+"ö Wö"
+3> string:slice(["He̊llö ", <<"Wörld"/utf8>>], 4,50).
+"ö Wörld"
+ + + + + + + Split a string into substrings. + +

+ Splits String where SearchPattern + is encountered and return the remaining parts. + Where, default leading, indicates whether + the leading, the trailing or all encounters of + SearchPattern will split String. +

+

Example:

+ 
+0> string:split("ab..bc..cd", "..").
+["ab","bc..cd"]
+1> string:split(<<"ab..bc..cd">>, "..", trailing).
+[<<"ab..bc">>,<<"cd">>]
+2> string:split(<<"ab..bc....cd">>, "..", all).
+[<<"ab">>,<<"bc">>,<<>>,<<"cd">>]
+ + + + + + + + Take leading or trailing parts. + +

Takes characters from String as long as + the characters are members of set Characters + or the complement of set Characters. + Dir, + which can be leading or trailing, indicates from + which direction characters are to be taken. +

+

Example:

+ 
+5> string:take("abc0z123", lists:seq($a,$z)).
+{"abc","0z123"}
+6> string:take(<<"abc0z123">>, lists:seq($0,$9), true, leading).
+{<<"abc">>,<<"0z123">>}
+7> string:take("abc0z123", lists:seq($0,$9), false, trailing).
+{"abc0z","123"}
+8> string:take(<<"abc0z123">>, lists:seq($a,$z), true, trailing).
+{<<"abc0z">>,<<"123">>}
+ + + + + + Convert a string to titlecase. + +

+ Converts String to titlecase. +

+

Example:

+ 
+1> string:titlecase("ß is a SHARP s").
+"Ss is a SHARP s"
+ + + + + + Return a float whose text representation is the integers + (ASCII values) of a string. + +

Argument String is expected to start with a + valid text represented float (the digits are ASCII values). + Remaining characters in the string after the float are returned in + Rest.

+

Example:

+ 
+> {F1,Fs} = string:to_float("1.0-1.0e-1"),
+> {F2,[]} = string:to_float(Fs),
+> F1+F2.
+0.9
+> string:to_float("3/2=1.5").
+{error,no_float}
+> string:to_float("-1.5eX").
+{-1.5,"eX"}
+ + + + + + Return an integer whose text representation is the integers + (ASCII values) of a string. + +

Argument String is expected to start with a + valid text represented integer (the digits are ASCII values). + Remaining characters in the string after the integer are returned in + Rest.

+

Example:

+ 
+> {I1,Is} = string:to_integer("33+22"),
+> {I2,[]} = string:to_integer(Is),
+> I1-I2.
+11
+> string:to_integer("0.5").
+{0,".5"}
+> string:to_integer("x=2").
+{error,no_integer}
+ + + + + + Convert a string to a list of grapheme clusters. + +

+ Converts String to a list of grapheme clusters. +

+

Example:

+ 
+1> string:to_graphemes("ß↑e̊").
+[223,8593,[101,778]]
+2> string:to_graphemes(<<"ß↑e̊"/utf8>>).
+[223,8593,[101,778]]
+ + + + + + + + Trim leading or trailing, or both, characters. + +

+ Returns a string, where leading or trailing, or both, + Characters have been removed. + Dir which can be leading, trailing, + or both, indicates from which direction characters + are to be removed. +

+

Default Characters are the set of + nonbreakable whitespace codepoints, defined as + Pattern_White_Space in + Unicode Standard Annex #31. + By default, Dir is both. +

+

+ Notice that [$\r,$\n] is one grapheme cluster according + to the Unicode Standard. +

+

Example:

+ 
+1> string:trim("\t  Hello  \n").
+"Hello"
+2> string:trim(<<"\t  Hello  \n">>, leading).
+<<"Hello  \n">>
+3> string:trim(<<".Hello.\n">>, trailing, "\n.").
+<<".Hello">>
+ + + + + + Convert a string to uppercase. + +

+ Converts String to uppercase. +

+

See also titlecase/1.

+

Example:

+ 
+1> string:uppercase("Michał").
+"MICHAŁ"
+ + + + + +
+ + Obsolete API functions +

Here follows the function of the old API. + These functions only work on a list of Latin-1 characters. +

+

+ The functions are kept for backward compatibility, but are + not recommended. + They will be deprecated in Erlang/OTP 21. +

+

Any undocumented functions in string are not to be used.

+ +
+ @@ -47,17 +652,24 @@

Returns a string, where String is centered in the string and surrounded by blanks or Character. The resulting string has length Number.

+

This function is obsolete. + Use + pad/3. +

- Returns a string consisting of numbers of characters. + Return a string consisting of numbers of characters.

Returns a string consisting of Number characters Character. Optionally, the string can end with string Tail.

+

This function is obsolete. + Use + lists:duplicate/2.

 @@ -69,6 +681,9 @@

Returns the index of the first occurrence of Character in String. Returns 0 if Character does not occur.

+

This function is obsolete. + Use + find/2.

 @@ -79,6 +694,16 @@

Concatenates String1 and String2 to form a new string String3, which is returned.

+

+ This function is obsolete. + Use [String1, String2] as + Data argument, and call + + unicode:characters_to_list/2 or + + unicode:characters_to_binary/2 + to flatten the output. +

@@ -88,6 +713,9 @@

Returns a string containing String repeated Number times.

+

This function is obsolete. + Use + lists:duplicate/2.

 @@ -98,6 +726,9 @@

Returns the length of the maximum initial segment of String, which consists entirely of characters not from Chars.

+

This function is obsolete. + Use + take/3.

Example:

> string:cspan("\t abcdef", " \t"). @@ -105,21 +736,15 @@ - - - Test string equality. - -

Returns true if String1 and - String2 are equal, otherwise false.

- - - Join a list of strings with separator.

Returns a string with the elements of StringList separated by the string in Separator.

+

This function is obsolete. + Use + lists:join/2.

Example:

> join(["one", "two", "three"], ", "). @@ -137,6 +762,10 @@ fixed. If length(String) < Number, then String is padded with blanks or Characters.

+

This function is obsolete. + Use + pad/2 or + pad/3.

Example:

> string:left("Hello",10,$.). @@ -149,6 +778,9 @@ Return the length of a string.

Returns the number of characters in String.

+

This function is obsolete. + Use + length/1.

 @@ -160,6 +792,9 @@

Returns the index of the last occurrence of Character in String. Returns 0 if Character does not occur.

+

This function is obsolete. + Use + find/3.

@@ -173,6 +808,9 @@ fixed. If the length of (String) < Number, then String is padded with blanks or Characters.

+

This function is obsolete. + Use + pad/3.

Example:

> string:right("Hello", 10, $.). @@ -188,6 +826,9 @@ SubString begins in String. Returns 0 if SubString does not exist in String.

+

This function is obsolete. + Use + find/3.

Example:

> string:rstr(" Hello Hello World World ", "Hello World"). @@ -202,6 +843,9 @@

Returns the length of the maximum initial segment of String, which consists entirely of characters from Chars.

+

This function is obsolete. + Use + take/2.

Example:

> string:span("\t abcdef", " \t"). @@ -217,6 +861,9 @@ SubString begins in String. Returns 0 if SubString does not exist in String.

+

This function is obsolete. + Use + find/2.

Example:

> string:str(" Hello Hello World World ", "Hello World"). @@ -230,12 +877,15 @@ Strip leading or trailing characters. -

Returns a string, where leading and/or trailing blanks or a +

Returns a string, where leading or trailing, or both, blanks or a number of Character have been removed. Direction, which can be left, right, or both, indicates from which direction blanks are to be removed. strip/1 is equivalent to strip(String, both).

+

This function is obsolete. + Use + trim/3.

Example:

> string:strip("...Hello.....", both, $.). @@ -251,6 +901,9 @@

Returns a substring of String, starting at position Start to the end of the string, or to and including position Stop.

+

This function is obsolete. + Use + slice/3.

Example:

sub_string("Hello World", 4, 8). @@ -266,6 +919,9 @@ sub_string("Hello World", 4, 8).

Returns a substring of String, starting at position Start, and ending at the end of the string or at length Length.

+

This function is obsolete. + Use + slice/3.

Example:

> substr("Hello World", 4, 5). @@ -281,6 +937,9 @@ sub_string("Hello World", 4, 8).

Returns the word in position Number of String. Words are separated by blanks or Characters.

+

This function is obsolete. + Use + nth_lexeme/3.

Example:

> string:sub_word(" Hello old boy !",3,$o). @@ -288,50 +947,6 @@ sub_string("Hello World", 4, 8). - - - Returns a float whose text representation is the integers - (ASCII values) in a string. - -

Argument String is expected to start with a - valid text represented float (the digits are ASCII values). - Remaining characters in the string after the float are returned in - Rest.

-

Example:

- -> {F1,Fs} = string:to_float("1.0-1.0e-1"), -> {F2,[]} = string:to_float(Fs), -> F1+F2. -0.9 -> string:to_float("3/2=1.5"). -{error,no_float} -> string:to_float("-1.5eX"). -{-1.5,"eX"} - - - - - - Returns an integer whose text representation is the integers - (ASCII values) in a string. - -

Argument String is expected to start with a - valid text represented integer (the digits are ASCII values). - Remaining characters in the string after the integer are returned in - Rest.

-

Example:

- -> {I1,Is} = string:to_integer("33+22"), -> {I2,[]} = string:to_integer(Is), -> I1-I2. -11 -> string:to_integer("0.5"). -{0,".5"} -> string:to_integer("x=2"). -{error,no_integer} - - - @@ -346,6 +961,11 @@ sub_string("Hello World", 4, 8).

The specified string or character is case-converted. Notice that the supported character set is ISO/IEC 8859-1 (also called Latin 1); all values outside this set are unchanged

+

This function is obsolete use + lowercase/1, + uppercase/1, + titlecase/1 or + casefold/1.

 @@ -363,6 +983,9 @@ sub_string("Hello World", 4, 8). adjacent separator characters in String are treated as one. That is, there are no empty strings in the resulting list of tokens.

+

This function is obsolete. + Use + lexemes/2.

@@ -373,6 +996,9 @@ sub_string("Hello World", 4, 8).

Returns the number of words in String, separated by blanks or Character.

+

This function is obsolete. + Use + lexemes/2.

Example:

> words(" Hello old boy!", $o). @@ -387,10 +1013,7 @@ sub_string("Hello World", 4, 8). other. The reason is that this string package is the combination of two earlier packages and all functions of both packages have been retained.

- - -

Any undocumented functions in string are not to be used.

-
+ diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index a8ef8ff5c5..11b84f552a 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -65,7 +65,10 @@

In Erlang/OTP 20.0, atoms and function can contain Unicode characters. Module names are still restricted to - the ISO-Latin-1 range.

 + the ISO-Latin-1 range.

+

Support was added for normalizations forms in + unicode and the string module now handles + utf8-encoded binaries.

This section outlines the current Unicode support and gives some @@ -110,23 +113,27 @@ -

So, a conversion function must know not only one character at a time, - but possibly the whole sentence, the natural language to translate to, - the differences in input and output string length, and so on. - Erlang/OTP has currently no Unicode to_upper/to_lower - functionality, but publicly available libraries address these issues.

- -

Another example is the accented characters, where the same glyph has two - different representations. The Swedish letter "ö" is one example. - The Unicode standard has a code point for it, but you can also write it - as "o" followed by "U+0308" (Combining Diaeresis, with the simplified - meaning that the last letter is to have "¨" above). They have the same - glyph. They are for most purposes the same, but have different - representations. For example, MacOS X converts all filenames to use - Combining Diaeresis, while most other programs (including Erlang) try to - hide that by doing the opposite when, for example, listing directories. - However it is done, it is usually important to normalize such - characters to avoid confusion.

+

So, a conversion function must know not only one character at a + time, but possibly the whole sentence, the natural language to + translate to, the differences in input and output string length, + and so on. Erlang/OTP has currently no Unicode + uppercase/lowercase functionality with language + specific handling, but publicly available libraries address these + issues.

+ +

Another example is the accented characters, where the same + glyph has two different representations. The Swedish letter "ö" is + one example. The Unicode standard has a code point for it, but + you can also write it as "o" followed by "U+0308" (Combining + Diaeresis, with the simplified meaning that the last letter is to + have "¨" above). They have the same glyph, user perceived + character. They are for most purposes the same, but have different + representations. For example, MacOS X converts all filenames to + use Combining Diaeresis, while most other programs (including + Erlang) try to hide that by doing the opposite when, for example, + listing directories. However it is done, it is usually important + to normalize such characters to avoid confusion. +

The list of examples can be made long. One need a kind of knowledge that was not needed when programs only considered one or two languages. The @@ -273,7 +280,7 @@ them. In some cases functionality has been added to already existing interfaces (as the string module now can - handle lists with any code points). In some cases new + handle strings with any code points). In some cases new functionality or options have been added (as in the io module, the file handling, the Fortunately, most textual data has been stored in lists and range checking has been sparse, so modules like string work well for - Unicode lists with little need for conversion or extension.

+ Unicode strings with little need for conversion or extension.

Some modules are, however, changed to be explicitly Unicode-aware. These modules include:

@@ -1028,18 +1035,17 @@ Eshell V5.10.1 (abort with ^G) has extensive support for Unicode text.

-

The string module works - perfectly for Unicode strings and ISO Latin-1 strings, except the - language-dependent functions - string:to_upper/1 - and - string:to_lower/1, - which are only correct for the ISO Latin-1 character set. These two - functions can never function correctly for Unicode characters in their - current form, as there are language and locale issues as well as - multi-character mappings to consider when converting text between cases. - Converting case in an international environment is a large subject not - yet addressed in OTP.

+

The string + module works perfectly for Unicode strings and ISO Latin-1 + strings, except the language-dependent functions string:uppercase/1 + and string:lowercase/1. + These two functions can never function correctly for Unicode + characters in their current form, as there are language and locale + issues to consider when converting text between cases. Converting + case in an international environment is a large subject not yet + addressed in OTP.

-- cgit v1.2.3 From 3175fbd5e1ae985d09dcb2e546bd9a1c2a365f08 Mon Sep 17 00:00:00 2001 From: Krzysztof Jurewicz Date: Mon, 24 Apr 2017 14:46:49 +0200 Subject: =?UTF-8?q?stdlib:=20Fix=20documentation=20on=20sets=E2=80=99=20re?= =?UTF-8?q?presentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- lib/stdlib/doc/src/sets.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index 44dc104645..4dc5d68151 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -40,7 +40,7 @@

This module provides the same interface as the ordsets(3) module - but with a defined representation. One difference is + but with an undefined representation. One difference is that while this module considers two elements as different if they do not match (=:=), ordsets considers two elements as different if and only if they do not compare equal (==).

-- cgit v1.2.3 From ef0dbc4f2a43d629d086c3e2b9a762bbc00d034b Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Wed, 19 Apr 2017 16:10:15 +0200 Subject: stdlib: Add Unicode modifier t to control sequences w and W As of the introduction of Unicode characters in atoms, the control sequences 'w' and 'W' can return non-Latin-1 characters, unless some measure is taken. This commit makes sure that '~w' and '~W' always return Latin-1 characters, or bytes, which can be output to ports or written to raw files. The Unicode translation modifier 't' is needed to return non-Latin-1 characters. --- lib/stdlib/doc/src/io.xml | 4 +++- lib/stdlib/doc/src/io_lib.xml | 3 ++- 2 files changed, 5 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index 11a64c7f8a..74b57457ea 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. @@ -265,6 +265,8 @@ ok

Writes data with the standard syntax. This is used to output Erlang terms. Atoms are printed within quotes if they contain embedded non-printable characters. + Atom characters > 255 are escaped unless the + Unicode translation modifier (t) is used. Floats are printed accurately as the shortest, correctly rounded string.

diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 5ae400da62..bc1d77ac83 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -356,7 +356,8 @@ - + + Write a term.

Returns a character list that represents Term. -- cgit v1.2.3 From 4567b6afc41a5d18384916c171ae413112ee57cc Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Mon, 24 Apr 2017 14:46:57 +0200 Subject: stdlib: Add Unicode modifier t to control sequence a The Unicode translation modifier 't' is added to the io:fread/2,3 control sequence 'a'. --- lib/stdlib/doc/src/io.xml | 2 -- 1 file changed, 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index 74b57457ea..64fcf4379f 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.xml @@ -569,8 +569,6 @@ Prompt> <Characters beyond latin1 range not printable in this medium&g

Similar to s, but the resulting string is converted into an atom.

-

The Unicode translation modifier is not allowed (atoms - cannot contain characters beyond the latin1 range).

c -- cgit v1.2.3 From dfb899c0229f7ff7dbfad34d496e0429562728bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Wed, 8 Mar 2017 13:25:35 +0100 Subject: Store abstract code in the Dbgi chunk The new Dbgi chunk returns data in the following format: {debug_info_v1, Backend, Data} This allows compilers to store the debug info in different formats. In order to retrieve a particular format, for instance, Erlang Abstract Format, one may invoke: Backend:debug_info(erlang_v1, Module, Data, Opts) Besides introducing the chunk above, this commit also: * Changes beam_lib:chunk(Beam, [:abstract_code]) to read from the new Dbgi chunk while keeping backwards compatibility with old .beams * Adds the {debug_info, {Backend, Data}} option to compile:file/2 and friends that are stored in the Dbgi chunk. This allows the debug info encryption mechanism to work across compilers * Improves dialyzer to work directly on Core Erlang, allowing languages that do not have the Erlang Abstract Format to be dialyzer as long as they emit the new chunk and their backend implementation is available Backwards compatibility is kept across the board except for those calling beam_lib:chunk(Beam, ["Abst"]), as the old chunk is no longer available. Note however the "Abst" chunk has always been optional. Future OTP versions may remove parsing the "Abst" chunk altogether from beam_lib once Erlang 19 and earlier is no longer supported. The current Dialyzer implementation still supports earlier .beam files and such may also be removed in future versions. --- lib/stdlib/doc/src/beam_lib.xml | 46 ++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 12 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index d5ec90b060..031d79d0e2 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -42,10 +42,10 @@ and the corresponding identifiers are as follows:

- abstract_code ("Abst") atoms ("Atom") attributes ("Attr") compile_info ("CInf") + debug_info ("Dbgi") exports ("ExpT") imports ("ImpT") indexed_imports ("ImpT") @@ -60,9 +60,8 @@ Debug Information/Abstract Code

Option debug_info can be specified to the Compiler (see compile(3)) - to have debug information in the form of abstract code (see section - The Abstract Format in the - ERTS User's Guide) stored in the abstract_code chunk. + to have debug information, such as Erlang + Abstract Format, stored in the debug_info chunk. Tools such as Debugger and Xref require the debug information to be included.

@@ -79,7 +78,7 @@
Reconstruct Source Code -

The following example shows how to reconstruct source code from +

The following example shows how to reconstruct Erlang source code from the debug information in a BEAM file Beam:

@@ -117,7 +116,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]). -

Use Compiler option {debug_info,Key}, see +

Use Compiler option {debug_info_key,Key}, see compile(3) and function crypto_key_fun/1 @@ -198,18 +197,40 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]). -

"Abst" | "Attr" | "CInf" | "ExpT" | "ImpT" | "LocT" | "Atom"

+

"Attr" | "CInf" | "Dbgi" | "ExpT" | "ImpT" | "LocT" | "AtU8"

+ + + +

The format stored in the debug_info chunk. + To retrieve particular code representation from the backend, + Backend:debug_info(Format, Module, Data, Opts) must be + invoked. Format is an atom, such as erlang_v1 for + the Erlang Abstract Format or core_v1 for Core Erlang. + Module is the module represented by the beam file and + Data is the value stored in the debug info chunk. + Opts is any list of values supported by the Backend. + Backend:debug_info/4 must return {ok, Code} or + {error, Term}.

+ +

Developers must always invoke the debug_info/4 function + and never rely on the Data stored in the debug_info + chunk, as it is opaque and may change at any moment. no_debug_info + means that chunk "Dbgi" is present, but empty.

+ +

It is not checked that the forms conform to the abstract format indicated by AbstVersion. no_abstract_code means that chunk "Abst" is present, but empty.

+

For modules compiled with OTP 20 onwards, the abst_code chunk + is automatically computed from the debug_info chunk.

 @@ -346,7 +367,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).

Registers an unary fun that is called if beam_lib must read an - abstract_code chunk that has been encrypted. The fun + debug_info chunk that has been encrypted. The fun is held in a process that is started by the function.

If a fun is already registered when attempting to register a fun, {error, exists} is returned.

@@ -443,7 +464,8 @@ CryptoKeyFun(clear) -> term()

Removes all chunks from a BEAM file except those needed by the loader. In particular, - the debug information (chunk abstract_code) is removed.

+ the debug information (chunk debug_info and abstract_code) + is removed.

 @@ -454,9 +476,9 @@ CryptoKeyFun(clear) -> term()

Removes all chunks except those needed by the loader from BEAM files. In particular, - the debug information (chunk abstract_code) is removed. - The returned list contains one element for each specified filename, - in the same order as in Files.

+ the debug information (chunk debug_info and abstract_code) + is removed. The returned list contains one element for each + specified filename, in the same order as in Files.

 -- cgit v1.2.3 From a75bda102900c4a7ae3184efa8250c46a86f8588 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Fri, 21 Apr 2017 15:17:31 +0200 Subject: Document that app names and nodes names are restricted to latin-1 --- lib/stdlib/doc/src/unicode_usage.xml | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index a8ef8ff5c5..1e7f08db86 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -63,9 +63,9 @@

In Erlang/OTP 17.0, the encoding default for Erlang source files was switched to UTF-8.

 -

In Erlang/OTP 20.0, atoms and function can contain - Unicode characters. Module names are still restricted to - the ISO-Latin-1 range.

 +

In Erlang/OTP 20.0, atoms and function names can contain + Unicode characters. Module names, application names, and node + names are still restricted to the ISO Latin-1 range.

This section outlines the current Unicode support and gives some @@ -345,10 +345,11 @@

Having the source code in UTF-8 also allows you to write string literals, function names, and atoms containing Unicode characters with code points > 255. - Module names are still restricted to the ISO Latin-1 range. - Binary literals, where you use type + Module names, application names, and node names are still restricted + to the ISO Latin-1 range. Binary literals, where you use type /utf8, can also be expressed using Unicode characters > 255. - Having module names using characters other than 7-bit ASCII can cause + Having module names or application names using characters other than + 7-bit ASCII can cause trouble on operating systems with inconsistent file naming schemes, and can hurt portability, so it is not recommended.

EEP 40 suggests that the language is also to allow for Unicode @@ -444,8 +445,8 @@ external_charlist() = maybe_improper_list(char() | external_unicode_binary() | marker="stdlib:epp#encoding">epp(3) module. As from Erlang/OTP R16, strings and comments can be written using Unicode. As from Erlang/OTP 20, also atoms and functions can be - written using Unicode. Modules names must still be named using - characters from the ISO Latin-1 character set. (These + written using Unicode. Modules, applications, and nodes must still be + named using characters from the ISO Latin-1 character set. (These restrictions in the language are independent of the encoding of the source file.)

@@ -773,7 +774,7 @@ Eshell V5.10.1 (abort with ^G) filenames or directory names. If the file system content is listed, you also get Unicode lists as return value. The support lies in the Kernel and STDLIB modules, which is why - most applications (that does not explicitly require the filenames + most applications (that do not explicitly require the filenames to be in the ISO Latin-1 range) benefit from the Unicode support without change.

-- cgit v1.2.3 From 6edb6a45d8b2d2993f50176b3324d3fff97fe123 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 9 Mar 2017 10:12:31 +0100 Subject: stdlib: Improve the Erlang shell's handling of references As of Erlang/OTP 20.0, the type of ETS tables, ets:tid(), is a reference(). A request was put forward that the Erlang shell should be able to handle references in its input. This commit introduces an extended parser in module lib. It can parse pids, ports, references, and external funs under the condition that they can be created in the running system. The parser is meant to be used internally in Erlang/OTP. The alternative, to extend erl_scan and erl_parse, was deemed inferior as it would require the abstract format be able to represent pids, ports, references, and funs, which would be confusing as they are not expressions as such, but data types. --- lib/stdlib/doc/src/shell.xml | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml index ab62c2fcdd..2593d3690b 100644 --- a/lib/stdlib/doc/src/shell.xml +++ b/lib/stdlib/doc/src/shell.xml @@ -569,7 +569,7 @@ Hello Number: 3378 
 42> E = ets:new(t, []).
-17
+#Ref<0.1662103692.2407923716.214192>

Command 42 creates an ETS table.

@@ -602,7 +602,7 @@ false 
 47> E = ets:new(t, []).
-18
+#Ref<0.1662103692.2407923716.214197>
 48> ets:insert({d,1,2}).
 * exception error: undefined function ets:insert/1
@@ -617,10 +617,23 @@ true

Command 49 successfully inserts the tuple into the ETS table.

-50> halt().
+50> ets:insert(#Ref<0.1662103692.2407923716.214197>, {e,3,4}).
+true
+ +

Command 50 inserts another tuple into the ETS table. This time + the first argument is the table identifier itself. The shell can + parse commands with pids (<0.60.0>), ports + (#Port<0.536>), references + (#Ref<0.1662103692.2407792644.214210>), and external + functions (#Fun<a.b.1>), but the command fails unless + the corresponding pid, port, reference, or function can be created + in the running system.

+ + 
+51> halt().
 strider 2>
-

Command 50 exits the Erlang runtime system.

+

Command 51 exits the Erlang runtime system.

-- cgit v1.2.3 From c6bdd67b33b70d862e2a2d0f582106f2e930d970 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Thu, 6 Apr 2017 16:03:11 +0200 Subject: stdlib: Deprecate gen_fsm --- lib/stdlib/doc/src/gen_fsm.xml | 1091 ++++++------------------------------- lib/stdlib/doc/src/gen_server.xml | 1 - lib/stdlib/doc/src/gen_statem.xml | 11 +- lib/stdlib/doc/src/proc_lib.xml | 2 +- lib/stdlib/doc/src/supervisor.xml | 6 +- lib/stdlib/doc/src/sys.xml | 28 +- 6 files changed, 184 insertions(+), 955 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index 719ab2b558..d74665060e 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -4,14 +4,14 @@
- 19962016 + 1996-2017 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -29,926 +29,177 @@
gen_fsm - Generic finite state machine behavior. - - -

- There is a new behaviour - gen_statem - that is intended to replace gen_fsm for new code. - gen_fsm will not be removed for the foreseeable future - to keep old state machine implementations running. -

- -

This behavior module provides a finite state machine. - A generic finite state machine process (gen_fsm) implemented - using this module has a standard set of interface functions - and includes functionality for tracing and error reporting. It - also fits into an OTP supervision tree. For more information, see - OTP Design Principles. -

- -

A gen_fsm process assumes all specific parts to be located in a - callback module exporting a predefined set of functions. The relationship - between the behavior functions and the callback functions is as - follows:

- - 
-gen_fsm module                    Callback module
---------------                    ---------------
-gen_fsm:start
-gen_fsm:start_link                -----> Module:init/1
-
-gen_fsm:stop                      -----> Module:terminate/3
-
-gen_fsm:send_event                -----> Module:StateName/2
-
-gen_fsm:send_all_state_event      -----> Module:handle_event/3
-
-gen_fsm:sync_send_event           -----> Module:StateName/3
-
-gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
-
--                                 -----> Module:handle_info/3
-
--                                 -----> Module:terminate/3
+  Deprecated and replaced by gen_statem 
 
--                                 -----> Module:code_change/4
- -

If a callback function fails or returns a bad value, the gen_fsm - process terminates.

- -

A gen_fsm process handles system messages as described in - sys(3). The sys module - can be used for debugging a gen_fsm process.

- -

Notice that a gen_fsm process does not trap exit signals - automatically, this must be explicitly initiated in the callback - module.

- -

Unless otherwise stated, all functions in this module fail if - the specified gen_fsm process does not exist or if bad arguments - are specified.

- -

The gen_fsm process can go into hibernation - (see - erlang:hibernate/3) if a callback function - specifies 'hibernate' instead of a time-out value. This - can be useful if the server is expected to be idle for a long - time. However, use this feature with care, as hibernation - implies at least two garbage collections (when hibernating and - shortly after waking up) and is not something you want to do - between each call to a busy state machine.

+ +

Deprecated and replaced by gen_statem

- - - - cancel_timer(Ref) -> RemainingTime | false - Cancel an internal timer in a generic FSM. - - Ref = reference() - RemainingTime = integer() - - -

Cancels an internal timer referred by Ref in the - gen_fsm process that calls this function.

-

Ref is a reference returned from - - send_event_after/2 or - start_timer/2.

-

If the timer has already timed out, but the event not yet - been delivered, it is cancelled as if it had not - timed out, so there is no false timer event after - returning from this function.

-

Returns the remaining time in milliseconds until the timer would - have expired if Ref referred to an active timer, otherwise - false.

- - - - - enter_loop(Module, Options, StateName, StateData) - enter_loop(Module, Options, StateName, StateData, FsmName) - enter_loop(Module, Options, StateName, StateData, Timeout) - enter_loop(Module, Options, StateName, StateData, FsmName, Timeout) - Enter the gen_fsm receive loop. - - Module = atom() - Options = [Option] -  Option = {debug,Dbgs} -   Dbgs = [Dbg] -    Dbg = trace | log | statistics -     | {log_to_file,FileName} | {install,{Func,FuncState}} - StateName = atom() - StateData = term() - FsmName = {local,Name} | {global,GlobalName} -   | {via,Module,ViaName} -  Name = atom() -  GlobalName = ViaName = term() - Timeout = int() | infinity - - -

Makes an existing process into a gen_fsm process. - Does not return, - instead the calling process enters the gen_fsm receive - loop and becomes a gen_fsm process. The process must - have been started using one of the start functions in - proc_lib(3). The user is - responsible for any initialization of the process, including - registering a name for it.

-

This function is useful when a more complex initialization - procedure is needed than the gen_fsm behavior provides.

-

Module, Options, and FsmName have - the same meanings as when calling - start[_link]/3,4. - However, if FsmName is specified, the process must have - been registered accordingly before this function is - called.

-

StateName, StateData, and Timeout have - the same meanings as in the return value of - Module:init/1. - The callback module Module does not need to - export an init/1 function.

-

The function fails if the calling process was not started by a - proc_lib start function, or if it is not registered - according to FsmName.

- - - - - reply(Caller, Reply) -> Result - Send a reply to a caller. - - Caller - see below - Reply = term() - Result = term() - - -

This function can be used by a gen_fsm process to - explicitly send a reply to a client process that called - - sync_send_event/2,3 or - - sync_send_all_state_event/2,3 - when the reply cannot be defined in the return value of - - Module:StateName/3 or - - Module:handle_sync_event/4.

-

Caller must be the From argument provided to - the callback function. Reply is any term - given back to the client as the return value of - sync_send_event/2,3 or - sync_send_all_state_event/2,3.

-

Return value Result is not further defined, and - is always to be ignored.

- - - - - send_all_state_event(FsmRef, Event) -> ok - Send an event asynchronously to a generic FSM. - - FsmRef = Name | {Name,Node} | {global,GlobalName} -   | {via,Module,ViaName} | pid() -  Name = Node = atom() -  GlobalName = ViaName = term() - Event = term() - - -

Sends an event asynchronously to the FsmRef of the - gen_fsm process and returns ok immediately. - The gen_fsm process calls - - Module:handle_event/3 to handle the event.

-

For a description of the arguments, see - send_event/2.

-

The difference between send_event/2 and - send_all_state_event/2 is which callback function is - used to handle the event. This function is useful when - sending events that are handled the same way in every state, - as only one handle_event clause is needed to handle - the event instead of one clause in each state name function.

- - - - - send_event(FsmRef, Event) -> ok - Send an event asynchronously to a generic FSM. - - FsmRef = Name | {Name,Node} | {global,GlobalName} -   | {via,Module,ViaName} | pid() -  Name = Node = atom() -  GlobalName = ViaName = term() - Event = term() - - -

Sends an event asynchronously to the FsmRef of the - gen_fsm process - and returns ok immediately. The gen_fsm process calls - - Module:StateName/2 to handle the event, where - StateName is the name of the current state of - the gen_fsm process.

-

FsmRef can be any of the following:

- - The pid - Name, if the gen_fsm process is locally - registered - {Name,Node}, if the gen_fsm process is locally - registered at another node - {global,GlobalName}, if the gen_fsm process is - globally registered - {via,Module,ViaName}, if the gen_fsm process is - registered through an alternative process registry - -

Event is any term that is passed as one of - the arguments to Module:StateName/2.

- - - - - send_event_after(Time, Event) -> Ref - Send a delayed event internally in a generic FSM. - - Time = integer() - Event = term() - Ref = reference() - - -

Sends a delayed event internally in the gen_fsm process - that calls this function after Time milliseconds. - Returns immediately a - reference that can be used to cancel the delayed send using - cancel_timer/1.

-

The gen_fsm process calls - - Module:StateName/2 to handle - the event, where StateName is the name of the current - state of the gen_fsm process at the time the delayed event is - delivered.

-

Event is any term that is passed as one of - the arguments to Module:StateName/2.

- - - - - start(Module, Args, Options) -> Result - start(FsmName, Module, Args, Options) -> Result - Create a standalone gen_fsm process. - - FsmName = {local,Name} | {global,GlobalName} -   | {via,Module,ViaName} -  Name = atom() -  GlobalName = ViaName = term() - Module = atom() - Args = term() - Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts} -   Dbgs = [Dbg] -    Dbg = trace | log | statistics -     | {log_to_file,FileName} | {install,{Func,FuncState}} -   SOpts = [term()] - Result = {ok,Pid} | ignore | {error,Error} -  Pid = pid() -  Error = {already_started,Pid} | term() - - -

Creates a standalone gen_fsm process, that is, a process that - is not part of a supervision tree and thus has no supervisor.

-

For a description of arguments and return values, see - start_link/3,4.

- - - - - start_link(Module, Args, Options) -> Result - start_link(FsmName, Module, Args, Options) -> Result - Create a gen_fsm process in a supervision tree. - - - FsmName = {local,Name} | {global,GlobalName} -   | {via,Module,ViaName} -  Name = atom() -  GlobalName = ViaName = term() - Module = atom() - Args = term() - Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts} -   Dbgs = [Dbg] -    Dbg = trace | log | statistics -     | {log_to_file,FileName} | {install,{Func,FuncState}} -   SOpts = [SOpt] -    SOpt - see erlang:spawn_opt/2,3,4,5 - Result = {ok,Pid} | ignore | {error,Error} -  Pid = pid() -  Error = {already_started,Pid} | term() - - -

Creates a gen_fsm process as part of a supervision tree. - The function is to be called, directly or indirectly, by - the supervisor. For example, it ensures that - the gen_fsm process is linked to the supervisor.

-

The gen_fsm process calls - Module:init/1 to - initialize. To ensure a synchronized startup procedure, - start_link/3,4 does not return until - Module:init/1 has returned.

- - -

If FsmName={local,Name}, the gen_fsm process is - registered locally as Name using register/2.

- - -

If FsmName={global,GlobalName}, the gen_fsm process - is registered globally as GlobalName using - - global:register_name/2.

- - -

If FsmName={via,Module,ViaName}, the gen_fsm - process registers with the registry represented by Module. - The Module callback is to export the functions - register_name/2, unregister_name/1, - whereis_name/1, and send/2, which are to behave - like the corresponding functions in - global. - Thus, {via,global,GlobalName} is a valid reference.

- - -

If no name is provided, the gen_fsm process is not - registered.

-

Module is the name of the callback module.

-

Args is any term that is passed as - the argument to Module:init/1.

-

If option {timeout,Time} is present, the gen_fsm - process is allowed to spend Time milliseconds initializing - or it terminates and the start function returns - {error,timeout}.

-

If option {debug,Dbgs} is present, the corresponding - sys function is called for each item in Dbgs; see - sys(3).

-

If option {spawn_opt,SOpts} is present, SOpts is - passed as option list to the spawn_opt BIF that is used to - spawn the gen_fsm process; see - - spawn_opt/2.

- -

Using spawn option monitor is not - allowed, it causes the function to fail with reason - badarg.

- -

If the gen_fsm process is successfully created and - initialized, the function returns {ok,Pid}, where Pid - is the pid of the gen_fsm process. If a process with the - specified FsmName exists already, the function returns - {error,{already_started,Pid}}, where Pid is - the pid of that process.

-

If Module:init/1 fails with Reason, - the function returns {error,Reason}. If - Module:init/1 returns {stop,Reason} or - ignore, the process is terminated and the function - returns {error,Reason} or ignore, respectively.

- - - - - start_timer(Time, Msg) -> Ref - Send a time-out event internally in a generic FSM. - - Time = integer() - Msg = term() - Ref = reference() - - -

Sends a time-out event internally in the gen_fsm - process that calls this function after Time milliseconds. - Returns immediately a - reference that can be used to cancel the timer using - cancel_timer/1.

-

The gen_fsm process calls - - Module:StateName/2 to handle - the event, where StateName is the name of the current - state of the gen_fsm process at the time the time-out - message is delivered.

-

Msg is any term that is passed in the - time-out message, {timeout, Ref, Msg}, as one of - the arguments to Module:StateName/2.

- - - - - stop(FsmRef) -> ok - stop(FsmRef, Reason, Timeout) -> ok - Synchronously stop a generic FSM. - - FsmRef = Name | {Name,Node} | {global,GlobalName} -   | {via,Module,ViaName} | pid() -  Node = atom() -  GlobalName = ViaName = term() - Reason = term() - Timeout = int()>0 | infinity - - -

Orders a generic finite state machine to exit with the specified - Reason and waits for it to terminate. The gen_fsm - process calls - Module:terminate/3 before exiting.

-

The function returns ok if the generic finite state machine - terminates with the expected reason. Any other reason than - normal, shutdown, or {shutdown,Term} causes an - error report to be issued using - - error_logger:format/2. - The default Reason is normal.

-

Timeout is an integer greater than zero that - specifies how many milliseconds to wait for the generic FSM - to terminate, or the atom infinity to wait - indefinitely. The default value is infinity. If the - generic finite state machine has not terminated within the specified - time, a timeout exception is raised.

-

If the process does not exist, a noproc exception - is raised.

- - - - - sync_send_all_state_event(FsmRef, Event) -> Reply - sync_send_all_state_event(FsmRef, Event, Timeout) -> Reply - Send an event synchronously to a generic FSM. - - FsmRef = Name | {Name,Node} | {global,GlobalName} -   | {via,Module,ViaName} | pid() -  Name = Node = atom() -  GlobalName = ViaName = term() - Event = term() - Timeout = int()>0 | infinity - Reply = term() - - -

Sends an event to the FsmRef of the gen_fsm - process and waits until a reply arrives or a time-out occurs. - The gen_fsm process calls - - Module:handle_sync_event/4 to handle the event.

-

For a description of FsmRef and Event, see - send_event/2. - For a description of Timeout and Reply, see - - sync_send_event/3.

-

For a discussion about the difference between - sync_send_event and sync_send_all_state_event, see - - send_all_state_event/2.

- - - - - sync_send_event(FsmRef, Event) -> Reply - sync_send_event(FsmRef, Event, Timeout) -> Reply - Send an event synchronously to a generic FSM. - - FsmRef = Name | {Name,Node} | {global,GlobalName} -   | {via,Module,ViaName} | pid() -  Name = Node = atom() -  GlobalName = ViaName = term() - Event = term() - Timeout = int()>0 | infinity - Reply = term() - - -

Sends an event to the FsmRef of the gen_fsm - process and waits until a reply arrives or a time-out occurs. - The gen_fsm process calls - - Module:StateName/3 to handle the event, where - StateName is the name of the current state of - the gen_fsm process.

-

For a description of FsmRef and Event, see - send_event/2.

-

Timeout is an integer greater than zero that - specifies how many milliseconds to wait for a reply, or - the atom infinity to wait indefinitely. Defaults - to 5000. If no reply is received within the specified time, - the function call fails.

-

Return value Reply is defined in the return value - of Module:StateName/3.

- - - - -
- Callback Functions -

The following functions are to be exported from a gen_fsm - callback module.

- -

state name denotes a state of the state machine.

- -

state data denotes the internal state of the Erlang process - that implements the state machine.

-
- - - - Module:code_change(OldVsn, StateName, StateData, Extra) -> {ok, NextStateName, NewStateData} - Update the internal state data during upgrade/downgrade. - - - OldVsn = Vsn | {down, Vsn} -   Vsn = term() - StateName = NextStateName = atom() - StateData = NewStateData = term() - Extra = term() - - -

This function is called by a gen_fsm process when it is to - update its internal state data during a release upgrade/downgrade, - that is, when instruction {update,Module,Change,...}, - where Change={advanced,Extra}, is given in - the appup file; see section - - Release Handling Instructions in OTP Design Principles.

-

For an upgrade, OldVsn is Vsn, and for a downgrade, - OldVsn is {down,Vsn}. Vsn is defined by the - vsn attribute(s) of the old version of the callback module - Module. If no such attribute is defined, the version is - the checksum of the Beam file.

-

StateName is the current state name and StateData the - internal state data of the gen_fsm process.

-

Extra is passed "as is" from the {advanced,Extra} - part of the update instruction.

-

The function is to return the new current state name and - updated internal data.

- - - - - Module:format_status(Opt, [PDict, StateData]) -> Status - Optional function for providing a term describing the - current gen_fsm process status. - - Opt = normal | terminate - PDict = [{Key, Value}] - StateData = term() - Status = term() - - - -

This callback is optional, so callback modules need not - export it. The gen_fsm module provides a default - implementation of this function that returns the callback - module state data.

- -

This function is called by a gen_fsm process in the - following situations:

- - One of - sys:get_status/1,2 - is invoked to get the gen_fsm status. Opt is set to - the atom normal for this case. - The gen_fsm process terminates abnormally and logs an - error. Opt is set to the atom terminate for - this case. - -

This function is useful for changing the form and - appearance of the gen_fsm status for these cases. A callback - module wishing to change the sys:get_status/1,2 - return value as well as how its status appears in - termination error logs, exports an instance - of format_status/2 that returns a term describing the - current status of the gen_fsm process.

-

PDict is the current value of the process dictionary of the - gen_fsm process.

-

StateData is the internal state data of the - gen_fsm process.

-

The function is to return Status, a term that - change the details of the current state and status of - the gen_fsm process. There are no restrictions on the - form Status can take, but for - the sys:get_status/1,2 case (when Opt - is normal), the recommended form for - the Status value is [{data, [{"StateData", - Term}]}], where Term provides relevant details of - the gen_fsm state data. Following this recommendation is not - required, but it makes the callback module status - consistent with the rest of the sys:get_status/1,2 - return value.

-

One use for this function is to return compact alternative - state data representations to avoid that large state terms - are printed in log files.

- - - - - Module:handle_event(Event, StateName, StateData) -> Result - Handle an asynchronous event. - - Event = term() - StateName = atom() - StateData = term() - Result = {next_state,NextStateName,NewStateData} -   | {next_state,NextStateName,NewStateData,Timeout} -   | {next_state,NextStateName,NewStateData,hibernate} -   | {stop,Reason,NewStateData} -  NextStateName = atom() -  NewStateData = term() -  Timeout = int()>0 | infinity -  Reason = term() - - -

Whenever a gen_fsm process receives an event sent using - - send_all_state_event/2, - this function is called to handle the event.

-

StateName is the current state name of the gen_fsm - process.

-

For a description of the other arguments and possible return values, - see - Module:StateName/2.

- - - - - Module:handle_info(Info, StateName, StateData) -> Result - Handle an incoming message. - - Info = term() - StateName = atom() - StateData = term() - Result = {next_state,NextStateName,NewStateData} -   | {next_state,NextStateName,NewStateData,Timeout} -   | {next_state,NextStateName,NewStateData,hibernate} -   | {stop,Reason,NewStateData} -  NextStateName = atom() -  NewStateData = term() -  Timeout = int()>0 | infinity -  Reason = normal | term() - - -

This function is called by a gen_fsm process when it receives - any other message than a synchronous or asynchronous event (or a - system message).

-

Info is the received message.

-

For a description of the other arguments and possible return values, - see - Module:StateName/2.

- - - - - Module:handle_sync_event(Event, From, StateName, StateData) -> Result - Handle a synchronous event. - - Event = term() - From = {pid(),Tag} - StateName = atom() - StateData = term() - Result = {reply,Reply,NextStateName,NewStateData} -   | {reply,Reply,NextStateName,NewStateData,Timeout} -   | {reply,Reply,NextStateName,NewStateData,hibernate} -   | {next_state,NextStateName,NewStateData} -   | {next_state,NextStateName,NewStateData,Timeout} -   | {next_state,NextStateName,NewStateData,hibernate} -   | {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData} -  Reply = term() -  NextStateName = atom() -  NewStateData = term() -  Timeout = int()>0 | infinity -  Reason = term() - - -

Whenever a gen_fsm process receives an event sent using - - sync_send_all_state_event/2,3, - this function is called to handle the event.

-

StateName is the current state name of the gen_fsm - process.

-

For a description of the other arguments and possible return values, - see - Module:StateName/3.

- - - - - Module:init(Args) -> Result - Initialize process and internal state name and state data. - - - Args = term() - Result = {ok,StateName,StateData} | {ok,StateName,StateData,Timeout} -   | {ok,StateName,StateData,hibernate} -   | {stop,Reason} | ignore -  StateName = atom() -  StateData = term() -  Timeout = int()>0 | infinity -  Reason = term() - - - -

Whenever a gen_fsm process is started using - start/3,4 or - start_link/3,4, - this function is called by the new process to initialize.

-

Args is the Args argument provided to the start - function.

-

If initialization is successful, the function is to return - {ok,StateName,StateData}, - {ok,StateName,StateData,Timeout}, or - {ok,StateName,StateData,hibernate}, where StateName - is the initial state name and StateData the initial - state data of the gen_fsm process.

-

If an integer time-out value is provided, a time-out occurs - unless an event or a message is received within Timeout - milliseconds. A time-out is represented by the atom - timeout and is to be handled by the - - Module:StateName/2 callback functions. The atom - infinity can be used to wait indefinitely, this is - the default value.

-

If hibernate is specified instead of a time-out value, the - process goes into hibernation when waiting for the next message - to arrive (by calling - proc_lib:hibernate/3).

-

If the initialization fails, the function returns - {stop,Reason}, where Reason is any term, - or ignore.

- - - - - Module:StateName(Event, StateData) -> Result - Handle an asynchronous event. - - Event = timeout | term() - StateData = term() - Result = {next_state,NextStateName,NewStateData} -   | {next_state,NextStateName,NewStateData,Timeout} -   | {next_state,NextStateName,NewStateData,hibernate} -   | {stop,Reason,NewStateData} -  NextStateName = atom() -  NewStateData = term() -  Timeout = int()>0 | infinity -  Reason = term() - - -

There is to be one instance of this function for each - possible state name. Whenever a gen_fsm process receives - an event sent using - send_event/2, - the instance of this function with the same name as - the current state name StateName is called to handle - the event. It is also called if a time-out occurs.

-

Event is either the atom timeout, if a time-out - has occurred, or the Event argument provided to - send_event/2.

-

StateData is the state data of the gen_fsm process.

-

If the function returns - {next_state,NextStateName,NewStateData}, - {next_state,NextStateName,NewStateData,Timeout}, or - {next_state,NextStateName,NewStateData,hibernate}, the - gen_fsm process continues executing with the current state - name set to NextStateName and with the possibly - updated state data NewStateData. For a description of - Timeout and hibernate, see - Module:init/1.

-

If the function returns {stop,Reason,NewStateData}, - the gen_fsm process calls - Module:terminate(Reason,StateName,NewStateData) and - terminates.

- - - - - Module:StateName(Event, From, StateData) -> Result - Handle a synchronous event. - - Event = term() - From = {pid(),Tag} - StateData = term() - Result = {reply,Reply,NextStateName,NewStateData} -   | {reply,Reply,NextStateName,NewStateData,Timeout} -   | {reply,Reply,NextStateName,NewStateData,hibernate} -   | {next_state,NextStateName,NewStateData} -   | {next_state,NextStateName,NewStateData,Timeout} -   | {next_state,NextStateName,NewStateData,hibernate} -   | {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData} -  Reply = term() -  NextStateName = atom() -  NewStateData = term() -  Timeout = int()>0 | infinity -  Reason = normal | term() - - -

There is to be one instance of this function for each - possible state name. Whenever a gen_fsm process receives an - event sent using - sync_send_event/2,3, - the instance of this function with the same name as - the current state name StateName is called to handle - the event.

-

Event is the Event argument provided to - sync_send_event/2,3.

-

From is a tuple {Pid,Tag} where Pid is - the pid of the process that called sync_send_event/2,3 - and Tag is a unique tag.

-

StateData is the state data of the gen_fsm process.

- - -

If {reply,Reply,NextStateName,NewStateData}, - {reply,Reply,NextStateName,NewStateData,Timeout}, or - {reply,Reply,NextStateName,NewStateData,hibernate} is - returned, Reply is given back to From as the return - value of sync_send_event/2,3. The gen_fsm process - then continues executing with the current state name set to - NextStateName and with the possibly updated state data - NewStateData. For a description of Timeout and - hibernate, see - - Module:init/1.

- - -

If {next_state,NextStateName,NewStateData}, - {next_state,NextStateName,NewStateData,Timeout}, or - {next_state,NextStateName,NewStateData,hibernate} is - returned, the gen_fsm process continues executing in - NextStateName with NewStateData. - Any reply to From must be specified explicitly using - reply/2.

- - -

If the function returns - {stop,Reason,Reply,NewStateData}, Reply is - given back to From. If the function returns - {stop,Reason,NewStateData}, any reply to From - must be specified explicitly using reply/2. - The gen_fsm process then calls - Module:terminate(Reason,StateName,NewStateData) and - terminates.

- - - - - - - Module:terminate(Reason, StateName, StateData) - Clean up before termination. - - Reason = normal | shutdown | {shutdown,term()} | term() - StateName = atom() - StateData = term() - - -

This function is called by a gen_fsm process when it is about - to terminate. It is to be the opposite of - Module:init/1 - and do any necessary cleaning up. When it returns, the gen_fsm - process terminates with Reason. The return value is ignored. -

-

Reason is a term denoting the stop reason, - StateName is the current state name, and - StateData is the state data of the gen_fsm process.

-

Reason depends on why the gen_fsm process is - terminating. If - it is because another callback function has returned a stop - tuple {stop,..}, Reason has the value - specified in that tuple. If it is because of a failure, - Reason is the error reason.

-

If the gen_fsm process is part of a supervision tree and is - ordered by its supervisor to terminate, this function is called - with Reason=shutdown if the following conditions apply:

- - -

The gen_fsm process has been set to trap exit signals.

- - -

The shutdown strategy as defined in the child specification of - the supervisor is an integer time-out value, not - brutal_kill.

- - -

Even if the gen_fsm process is not part of a - supervision tree, - this function is called if it receives an 'EXIT' - message from its parent. Reason is the same as in - the 'EXIT' message.

-

Otherwise, the gen_fsm process terminates immediately.

-

Notice that for any other reason than normal, - shutdown, or {shutdown,Term} the gen_fsm process - is assumed to terminate because of an error and an error report is - issued using - error_logger:format/2.

- - - - +
- See Also -

gen_event(3), - gen_server(3), - gen_statem(3), - proc_lib(3), - supervisor(3), - sys(3)

+ + Migration to gen_statem + +

Here follows a simple example of turning a gen_fsm into + a gen_statem. The example comes + from the previous Users Guide for gen_fsm

+ + +-module(code_lock). +-define(NAME, code_lock). +%-define(BEFORE_REWRITE, true). + +-ifdef(BEFORE_REWRITE). +-behaviour(gen_fsm). +-else. +-behaviour(gen_statem). +-endif. + +-export([start_link/1, button/1, stop/0]). + +-ifdef(BEFORE_REWRITE). +-export([init/1, locked/2, open/2, handle_sync_event/4, handle_event/3, + handle_info/3, terminate/3, code_change/4]). +-else. +-export([init/1, callback_mode/0, locked/3, open/3, terminate/3, code_change/4]). +%% Add callback__mode/0 +%% Change arity of the state functions +%% Remove handle_info/3 +-endif. + +-ifdef(BEFORE_REWRITE). +start_link(Code) -> + gen_fsm:start_link({local, ?NAME}, ?MODULE, Code, []). +-else. +start_link(Code) -> + gen_statem:start_link({local,?NAME}, ?MODULE, Code, []). +-endif. + +-ifdef(BEFORE_REWRITE). +button(Digit) -> + gen_fsm:send_event(?NAME, {button, Digit}). +-else. +button(Digit) -> + gen_statem:cast(?NAME, {button,Digit}). + %% send_event is asynchronous and becomes a cast +-endif. + +-ifdef(BEFORE_REWRITE). +stop() -> + gen_fsm:sync_send_all_state_event(?NAME, stop). +-else. +stop() -> + gen_statem:call(?NAME, stop). + %% sync_send is synchronous and becomes call + %% all_state is handled by callback code in gen_statem +-endif. + +init(Code) -> + do_lock(), + Data = #{code => Code, remaining => Code}, + {ok, locked, Data}. + +-ifdef(BEFORE_REWRITE). +-else. +callback_mode() -> + state_functions. +%% state_functions mode is the mode most similar to +%% gen_fsm. There is also handle_event mode which is +%% a fairly different concept. +-endif. + +-ifdef(BEFORE_REWRITE). +locked({button, Digit}, Data0) -> + case analyze_lock(Digit, Data0) of + {open = StateName, Data} -> + {next_state, StateName, Data, 10000}; + {StateName, Data} -> + {next_state, StateName, Data} + end. +-else. +locked(cast, {button,Digit}, Data0) -> + case analyze_lock(Digit, Data0) of + {open = StateName, Data} -> + {next_state, StateName, Data, 10000}; + {StateName, Data} -> + {next_state, StateName, Data} + end; +locked({call, From}, Msg, Data) -> + handle_call(From, Msg, Data); +locked({info, Msg}, StateName, Data) -> + handle_info(Msg, StateName, Data). +%% Arity differs +%% All state events are dispatched to handle_call and handle_info help +%% functions. If you want to handle a call or cast event specifically +%% for this state you would add a special clause for it above. +-endif. + +-ifdef(BEFORE_REWRITE). +open(timeout, State) -> + do_lock(), + {next_state, locked, State}; +open({button,_}, Data) -> + {next_state, locked, Data}. +-else. +open(timeout, _, Data) -> + do_lock(), + {next_state, locked, Data}; +open(cast, {button,_}, Data) -> + {next_state, locked, Data}; +open({call, From}, Msg, Data) -> + handle_call(From, Msg, Data); +open(info, Msg, Data) -> + handle_info(Msg, open, Data). +%% Arity differs +%% All state events are dispatched to handle_call and handle_info help +%% functions. If you want to handle a call or cast event specifically +%% for this state you would add a special clause for it above. +-endif. + +-ifdef(BEFORE_REWRITE). +handle_sync_event(stop, _From, _StateName, Data) -> + {stop, normal, ok, Data}. + +handle_event(Event, StateName, Data) -> + {stop, {shutdown, {unexpected, Event, StateName}}, Data}. + +handle_info(Info, StateName, Data) -> + {stop, {shutdown, {unexpected, Info, StateName}}, StateName, Data}. +-else. +-endif. + +terminate(_Reason, State, _Data) -> + State =/= locked andalso do_lock(), + ok. +code_change(_Vsn, State, Data, _Extra) -> + {ok, State, Data}. + +%% Internal functions +-ifdef(BEFORE_REWRITE). +-else. +handle_call(From, stop, Data) -> + {stop_and_reply, normal, {reply, From, ok}, Data}. + +handle_info(Info, StateName, Data) -> + {stop, {shutdown, {unexpected, Info, StateName}}, StateName, Data}. +%% These are internal functions for handling all state events +%% and not behaviour callbacks as in gen_fsm +-endif. + +analyze_lock(Digit, #{code := Code, remaining := Remaining} = Data) -> + case Remaining of + [Digit] -> + do_unlock(), + {open, Data#{remaining := Code}}; + [Digit|Rest] -> % Incomplete + {locked, Data#{remaining := Rest}}; + _Wrong -> + {locked, Data#{remaining := Code}} + end. + +do_lock() -> + io:format("Lock~n", []). +do_unlock() -> + io:format("Unlock~n", []). +
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 662076b5f0..74fbfcc1bb 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -796,7 +796,6 @@ gen_server:abcast -----> Module:handle_cast/2
See Also

gen_event(3), - gen_fsm(3), gen_statem(3), proc_lib(3), supervisor(3), diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 5eb13db1aa..18089a8191 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -62,8 +62,8 @@

- The gen_statem behavior is intended to replace - gen_fsm for new code. + The gen_statem behavior replaces + gen_fsm in Erlang/OTP 20.0. It has the same features and adds some really useful:

@@ -78,8 +78,10 @@

The callback model(s) for gen_statem differs from the one for gen_fsm, - but it is still fairly easy to rewrite - from gen_fsm to gen_statem. + but it is still fairly easy to + + rewrite from + gen_fsm to gen_statem.

A generic state machine process (gen_statem) implemented @@ -945,7 +947,6 @@ handle_event(_, _, State, Data) -> state callback return value {next_state,NextState,NewData,Timeout} allowed like for gen_fsm's - Module:StateName/2.

timeout diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index e64b2ce18a..7939a0ef61 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -36,7 +36,7 @@ the OTP Design Principles. Specifically, the functions in this module are used by the OTP standard behaviors (for example, - gen_server, gen_fsm, and gen_statem) + gen_server and gen_statem) when starting new processes. The functions can also be used to start special processes, user-defined processes that comply to the OTP design principles. For an example, diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index bb06d3645e..a42cfdd567 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -36,7 +36,6 @@ process can either be another supervisor or a worker process. Worker processes are normally implemented using one of the gen_event, - gen_fsm, gen_server, or gen_statem behaviors. A supervisor implemented using this module has @@ -237,8 +236,8 @@ child_spec() = #{id => child_id(), % mandatory

modules is used by the release handler during code replacement to determine which processes are using a certain module. As a rule of thumb, if the child process is a - supervisor, gen_server, - gen_statem, or gen_fsm, + supervisor, gen_server or, + gen_statem, this is to be a list with one element [Module], where Module is the callback module. If the child process is an event manager (gen_event) with a @@ -706,7 +705,6 @@ child_spec() = #{id => child_id(), % mandatory

See Also

gen_event(3), - gen_fsm(3), gen_statem(3), gen_server(3), sys(3)

diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 45171f814d..78840aaaf3 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -166,12 +166,6 @@ process, the returned State is the state of the callback module.

- -

For a - gen_fsm - process, State is the tuple - {CurrentStateName, CurrentStateData}.

-

For a gen_statem @@ -222,7 +216,7 @@

Function system_get_state/1 is primarily useful for user-defined behaviors and modules that implement OTP special processes. - The gen_server, gen_fsm, + The gen_server, gen_statem, and gen_event OTP behavior modules export this function, so callback modules for those behaviors need not to supply their own.

@@ -245,11 +239,6 @@

A gen_server process returns the state of the callback module.

 - -

A gen_fsm - process returns information, such as its current - state name and state data.

-

A gen_statem process returns information, such as its current @@ -262,14 +251,12 @@

Callback modules for gen_server, - gen_fsm, gen_statem, and gen_event + gen_statem, and gen_event can also change the value of Misc by exporting a function format_status/2, which contributes module-specific information. For details, see gen_server:format_status/2, - - gen_fsm:format_status/2, gen_statem:format_status/2, and @@ -372,13 +359,6 @@ module and NewState is a new instance of that state.

 - -

For a gen_fsm process, - State is the tuple {CurrentStateName, - CurrentStateData}, and NewState is a - similar tuple, which can contain - a new state name, new state data, or both.

-

For a gen_statem process, State is the @@ -422,7 +402,7 @@ return its State argument.

If a StateFun function crashes or throws an exception, the original state of the process is unchanged for - gen_server, gen_fsm, and gen_statem processes. + gen_server, and gen_statem processes. For gen_event processes, a crashing or failing StateFun function means that only the state of the particular event handler it was @@ -462,7 +442,7 @@ user-defined behaviors and modules that implement OTP special processes. The OTP behavior modules gen_server, - gen_fsm, gen_statem, and gen_event + gen_statem, and gen_event export this function, so callback modules for those behaviors need not to supply their own.

-- cgit v1.2.3 From aefd914b8a8216e16dbf211c6359398877f71405 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Fri, 28 Apr 2017 11:39:23 +0200 Subject: stdlib: Adhere to DTD --- lib/stdlib/doc/src/gen_fsm.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index e70f347479..7187630b43 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -29,7 +29,7 @@
gen_fsm - Deprecated and replaced by gen_statem + Deprecated and replaced by gen_statem

Deprecated and replaced by gen_statem

-- cgit v1.2.3 From 42faed747858483506c12e722573e48d0f5f7996 Mon Sep 17 00:00:00 2001 From: Anton N Ryabkov Date: Wed, 12 Apr 2017 15:06:39 +0700 Subject: Added support of auto_hibernate_timeout option for gen_server, gen_fsm, gen_event process's. There is realized gen_server, gen_fsm, gen_event automatic hibernation functionality. Added unit tests for realized functionality. Added documentation for auto_hibernate_timeout option. --- lib/stdlib/doc/src/gen_event.xml | 10 ++++++++-- lib/stdlib/doc/src/gen_server.xml | 12 +++++++++--- 2 files changed, 17 insertions(+), 5 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 56cb7974a2..fbd6cf220a 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -358,7 +358,7 @@ gen_event:stop -----> Module:terminate/2  Name = atom()  GlobalName = ViaName = term() Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts} +  Option = {debug,Dbgs} | {timeout,Time} | {auto_hibernate_timeout,AutoHibernateTimeout} | {spawn_opt,SOpts}   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] @@ -385,7 +385,7 @@ gen_event:stop -----> Module:terminate/2  Name = atom()  GlobalName = ViaName = term() Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts} +  Option = {debug,Dbgs} | {timeout,Time} | {auto_hibernate_timeout,AutoHibernateTimeout} | {spawn_opt,SOpts}   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] @@ -419,6 +419,12 @@ gen_event:stop -----> Module:terminate/2 global. Thus, {via,global,GlobalName} is a valid reference.

+ +

If option {auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_event + process wait any message AutoHibernateTimeout milliseconds and + in case of no message was received, process goes into hibernation automatically + (by calling proc_lib:hibernate/3).

+

If the event manager is successfully created, the function returns {ok,Pid}, where Pid is the pid of diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 0bcbbc2805..f6053d501f 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -199,7 +199,7 @@ gen_server:abcast -----> Module:handle_cast/2 Module = atom() Options = [Option] -  Option = {debug,Dbgs} +  Option = {debug,Dbgs} | {auto_hibernate_timeout,AutoHibernateTimeout}   Dbgs = [Dbg]    Dbg = trace | log | statistics     | {log_to_file,FileName} | {install,{Func,FuncState}} @@ -334,7 +334,7 @@ gen_server:abcast -----> Module:handle_cast/2 Module = atom() Args = term() Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts} +  Option = {debug,Dbgs} | {timeout,Time} | {auto_hibernate_timeout,AutoHibernateTimeout} | {spawn_opt,SOpts}   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] @@ -364,7 +364,7 @@ gen_server:abcast -----> Module:handle_cast/2 Module = atom() Args = term() Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts} +  Option = {debug,Dbgs} | {timeout,Time} | {auto_hibernate_timeout,AutoHibernateTimeout} | {spawn_opt,SOpts}   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] @@ -416,6 +416,12 @@ gen_server:abcast -----> Module:handle_cast/2 initializing or it is terminated and the start function returns {error,timeout}.

+ +

If option {auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_server + process wait any message AutoHibernateTimeout milliseconds and + in case of no message was received, process goes into hibernation automatically + (by calling proc_lib:hibernate/3).

+

If option {debug,Dbgs} is present, the corresponding sys function is called for each -- cgit v1.2.3 From 4a60e2df0ff2a95ed899768d8698d419b067d371 Mon Sep 17 00:00:00 2001 From: Anton N Ryabkov Date: Thu, 20 Apr 2017 14:25:43 +0700 Subject: Fixed typos in the gen_event, gen_fsm, gen_server documentation. --- lib/stdlib/doc/src/gen_event.xml | 4 ++-- lib/stdlib/doc/src/gen_server.xml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index fbd6cf220a..efcf80390b 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -421,8 +421,8 @@ gen_event:stop -----> Module:terminate/2

If option {auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_event - process wait any message AutoHibernateTimeout milliseconds and - in case of no message was received, process goes into hibernation automatically + process awaits any message for AutoHibernateTimeout milliseconds and + if no message is received, the process goes into hibernation automatically (by calling proc_lib:hibernate/3).

 diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index f6053d501f..9df2b45fe0 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -418,8 +418,8 @@ gen_server:abcast -----> Module:handle_cast/2

If option {auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_server - process wait any message AutoHibernateTimeout milliseconds and - in case of no message was received, process goes into hibernation automatically + process awaits any message for AutoHibernateTimeout milliseconds and + if no message is received, the process goes into hibernation automatically (by calling proc_lib:hibernate/3).

 -- cgit v1.2.3 From 063bebc88358f66cea17e3cf777b8b561a5f14c0 Mon Sep 17 00:00:00 2001 From: Anton N Ryabkov Date: Mon, 24 Apr 2017 12:54:09 +0700 Subject: Added support of auto_hibernate_timeout option for gen_statem. --- lib/stdlib/doc/src/gen_statem.xml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 17a3a3c83c..9405868c78 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -452,6 +452,21 @@ handle_event(_, _, State, Data) ->

+ + + +

+ auto_hibernate_timeout option that can be used when starting + a gen_statem server through, + enter_loop/4-6. +

+

If option{auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_statem + process awaits any message for AutoHibernateTimeout milliseconds and + if no message is received, the process goes into hibernation automatically + (by calling proc_lib:hibernate/3). +

+ + @@ -1550,6 +1565,13 @@ handle_event(_, _, State, Data) -> {error,timeout}.

+ +

If option{auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_statem + process awaits any message for AutoHibernateTimeout milliseconds and + if no message is received, the process goes into hibernation automatically + (by calling proc_lib:hibernate/3). +

+

If option -- cgit v1.2.3 From 38294da512781e44b44b9331bf613003397d529b Mon Sep 17 00:00:00 2001 From: Anton N Ryabkov Date: Mon, 24 Apr 2017 13:41:59 +0700 Subject: "auto_hibernate_timeout" option renamed to "hibernate_after". It was done because "hibernate_after" option already used in ssl for the same reason. --- lib/stdlib/doc/src/gen_event.xml | 8 ++++---- lib/stdlib/doc/src/gen_server.xml | 10 +++++----- lib/stdlib/doc/src/gen_statem.xml | 12 ++++++------ 3 files changed, 15 insertions(+), 15 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index efcf80390b..5576f50bc0 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -358,7 +358,7 @@ gen_event:stop -----> Module:terminate/2  Name = atom()  GlobalName = ViaName = term() Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {auto_hibernate_timeout,AutoHibernateTimeout} | {spawn_opt,SOpts} +  Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] @@ -385,7 +385,7 @@ gen_event:stop -----> Module:terminate/2  Name = atom()  GlobalName = ViaName = term() Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {auto_hibernate_timeout,AutoHibernateTimeout} | {spawn_opt,SOpts} +  Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] @@ -420,8 +420,8 @@ gen_event:stop -----> Module:terminate/2 Thus, {via,global,GlobalName} is a valid reference.

 -

If option {auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_event - process awaits any message for AutoHibernateTimeout milliseconds and +

If option {hibernate_after,HibernateAfterTimeout} is present, the gen_event + process awaits any message for HibernateAfterTimeout milliseconds and if no message is received, the process goes into hibernation automatically (by calling proc_lib:hibernate/3).

 diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 9df2b45fe0..e1d95e0046 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -199,7 +199,7 @@ gen_server:abcast -----> Module:handle_cast/2 Module = atom() Options = [Option] -  Option = {debug,Dbgs} | {auto_hibernate_timeout,AutoHibernateTimeout} +  Option = {debug,Dbgs} | {hibernate_after,HibernateAfterTimeout}   Dbgs = [Dbg]    Dbg = trace | log | statistics     | {log_to_file,FileName} | {install,{Func,FuncState}} @@ -334,7 +334,7 @@ gen_server:abcast -----> Module:handle_cast/2 Module = atom() Args = term() Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {auto_hibernate_timeout,AutoHibernateTimeout} | {spawn_opt,SOpts} +  Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] @@ -364,7 +364,7 @@ gen_server:abcast -----> Module:handle_cast/2 Module = atom() Args = term() Options = [Option] -  Option = {debug,Dbgs} | {timeout,Time} | {auto_hibernate_timeout,AutoHibernateTimeout} | {spawn_opt,SOpts} +  Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] @@ -417,8 +417,8 @@ gen_server:abcast -----> Module:handle_cast/2 returns {error,timeout}.

-

If option {auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_server - process awaits any message for AutoHibernateTimeout milliseconds and +

If option {hibernate_after,HibernateAfterTimeout} is present, the gen_server + process awaits any message for HibernateAfterTimeout milliseconds and if no message is received, the process goes into hibernation automatically (by calling proc_lib:hibernate/3).

 diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 9405868c78..1aac88c308 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -453,15 +453,15 @@ handle_event(_, _, State, Data) -> - +

- auto_hibernate_timeout option that can be used when starting + hibernate_after option that can be used when starting a gen_statem server through, enter_loop/4-6.

-

If option{auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_statem - process awaits any message for AutoHibernateTimeout milliseconds and +

If option{hibernate_after,HibernateAfterTimeout} is present, the gen_statem + process awaits any message for HibernateAfterTimeout milliseconds and if no message is received, the process goes into hibernation automatically (by calling proc_lib:hibernate/3).

@@ -1566,8 +1566,8 @@ handle_event(_, _, State, Data) ->

-

If option{auto_hibernate_timeout,AutoHibernateTimeout} is present, the gen_statem - process awaits any message for AutoHibernateTimeout milliseconds and +

If option{hibernate_after,HibernateAfterTimeout} is present, the gen_statem + process awaits any message for HibernateAfterTimeout milliseconds and if no message is received, the process goes into hibernation automatically (by calling proc_lib:hibernate/3).

-- cgit v1.2.3 From 83e20c62057ebc1d8064bf57b01be560cd244e1d Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 4 May 2017 15:42:21 +0200 Subject: Update copyright year --- lib/stdlib/doc/src/beam_lib.xml | 2 +- lib/stdlib/doc/src/erl_tar.xml | 2 +- lib/stdlib/doc/src/ets.xml | 2 +- lib/stdlib/doc/src/filelib.xml | 2 +- lib/stdlib/doc/src/filename.xml | 2 +- lib/stdlib/doc/src/gen_event.xml | 2 +- lib/stdlib/doc/src/gen_server.xml | 2 +- lib/stdlib/doc/src/notes.xml | 2 +- lib/stdlib/doc/src/proc_lib.xml | 2 +- lib/stdlib/doc/src/proplists.xml | 2 +- lib/stdlib/doc/src/sets.xml | 2 +- lib/stdlib/doc/src/string.xml | 2 +- lib/stdlib/doc/src/supervisor.xml | 2 +- lib/stdlib/doc/src/sys.xml | 2 +- lib/stdlib/doc/src/unicode.xml | 2 +- lib/stdlib/doc/src/unicode_usage.xml | 2 +- 16 files changed, 16 insertions(+), 16 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index 031d79d0e2..26d0724aaf 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -4,7 +4,7 @@
- 20002016 + 20002017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml index fab7c832d5..337028568a 100644 --- a/lib/stdlib/doc/src/erl_tar.xml +++ b/lib/stdlib/doc/src/erl_tar.xml @@ -4,7 +4,7 @@
- 20032016 + 20032017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index d1ec176f81..0d1e5c6e3a 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml index ad73fc254a..80c4acffdb 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -4,7 +4,7 @@
- 20032016 + 20032017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index 0ccca37a9d..14fd5ef787 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -4,7 +4,7 @@
- 19972016 + 19972017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 56cb7974a2..09bde3e397 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 0bcbbc2805..a8006bb870 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 428d8a6e70..a8a252cb35 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -4,7 +4,7 @@
- 20042016 + 20042017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index 7939a0ef61..cb152d1935 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml index 990d47b313..f9a54bf804 100644 --- a/lib/stdlib/doc/src/proplists.xml +++ b/lib/stdlib/doc/src/proplists.xml @@ -4,7 +4,7 @@
- 20022016 + 20022017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index 4dc5d68151..4934bed365 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -4,7 +4,7 @@
- 20002016 + 20002017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml index dc83c40a9a..343904a49a 100644 --- a/lib/stdlib/doc/src/string.xml +++ b/lib/stdlib/doc/src/string.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index a42cfdd567..6d5065ca02 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 78840aaaf3..f24e42bcee 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@
- 19962016 + 19962017 Ericsson AB. All Rights Reserved. diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index 382b253ba1..e86f45431f 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -5,7 +5,7 @@
1996 - 2016 + 2017 Ericsson AB, All Rights Reserved diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index 6af2fa9fa3..26dc46719e 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -5,7 +5,7 @@
1999 - 2016 + 2017 Ericsson AB. All Rights Reserved. -- cgit v1.2.3 From dc57404252c47520f352834ad9be45ad684f96c9 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Thu, 4 May 2017 17:05:25 +0200 Subject: Prepare release --- lib/stdlib/doc/src/notes.xml | 378 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 378 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index a8a252cb35..b4b6eac9d3 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,6 +31,384 @@

This document describes the changes made to the STDLIB application.

+
STDLIB 3.4 + +
Fixed Bugs and Malfunctions + + +

For many releases, it has been legal to override a BIF + with a local function having the same name. However, + calling a local function with the same name as guard BIF + as filter in a list comprehension was not allowed.

+

+ Own Id: OTP-13690

+ + +

A new (default) pseudo-random number generator + algorithm Xoroshiro116+ has been implemented in the + rand module.

The old algorithm + implementations had a number of flaws so they are all + deprecated, but corrected versions of two of them have + been added. See the documentation.

+

+ Own Id: OTP-14295 Aux Id: PR-1372

+ + +

The Erlang shell, qlc:string_to_handle(), and + the Debugger (the Evaluator area and Edit variable window + of the Bindings area) can parse pids, ports, references, + and external funs, as long as they can be created in the + running system.

+

+ Own Id: OTP-14296

+ + +

The state machine engine gen_statem can now + handle generic time-outs (multiple named) as well as + absolute time-out time. See the documentation.

+ The gen_statem callback Module:init/1 has + become mandatory to harmonize with other gen_* + modules. This may be an incompatibility for + gen_statem callback modules that use + gen_statem:enter_loop/4-6.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14531

+ + +
+ + +
Improvements and New Features + + +

+ Improved unicode support for strings. Added normalization + functions in the unicode module. Extended the + string module API with new functions with improved + unicode handling and that works on grapheme clusters. The + new functions operates on the unicode:chardata() + type, thus they also accept UTF-8 binaries as + input.

+

+ The old string API have been marked as obsolete. The + return values have been changed for some error cases.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-10289 Aux Id: OTP-10309

+ + +

There are two new guard BIFs 'floor/1' and + 'ceil/1'. They both return integers. In the + 'math' module, there are two new BIFs with the + same names that return floating point values.

+

+ Own Id: OTP-13692

+ + +

+ Making code_change, terminate and handle_info callbacks + optional in the OTP behaviours.

+

+ Own Id: OTP-13801

+ + +

The support for Dets files created with Erlang/OTP R7 + and earlier is removed.

+

+ Own Id: OTP-13830

+ + +

Replaced usage of deprecated symbolic time + unit representations.

+

+ Own Id: OTP-13831 Aux Id: OTP-13735

+ + +

The function fmod/2 has been added to the + math module.

+

+ Own Id: OTP-14000

+ + +

The EXIT signals received from processes using + proc_lib now looks like EXIT signals from + processes that were spawned using spawn_link. In + particular, that means that the stack trace is now + included in the EXIT signal so that it can see where the + process crashed.

+

+ Own Id: OTP-14001

+ + +

sets:add_element/2 is faster when adding an + element that is already present, and + sets:del_element/2 is faster when the element to + be deleted is not present. This optimization can make + certain operations, such as sets:union/2 with many + overlapping elements, up to two orders of magnitude + faster.

+

+ Own Id: OTP-14035

+ + +

+ Add information in doc about supervisor shutdown reason + when maximum restart frequency is reached.

+

+ Own Id: OTP-14037 Aux Id: PR-1233

+ + +

+ Added rand:jump/[0|1] functions.

+

+ Own Id: OTP-14038 Aux Id: PR-1235

+ + +

Functions for detecting changed code has been added. + code:modified_modules/0 returns all currently + loaded modules that have changed on disk. + code:module_status/1 returns the status for a + module. In the shell and in c module, mm/0 + is short for code:modified_modules/0, and + lm/0 reloads all currently loaded modules that + have changed on disk.

+

+ Own Id: OTP-14059

+ + +

Each assert macro in assert.hrl now has a + corresponding version with an extra argument, for adding + comments to assertions. These can for example be printed + as part of error reports, to clarify the meaning of the + check that failed.

+

+ Own Id: OTP-14066

+ + +

error_logger_tty_h and + error_logger_file_h now inserts the node + information for nonlocal messages before the message + itself instead of after, both for readability and so as + not to change the line termination property at the end of + the message.

+

+ Own Id: OTP-14068

+ + +

The Erlang code linter checks for badly formed type + constraints.

+

+ Own Id: OTP-14070 Aux Id: PR-1214

+ + +

By default, there will now be a warning when + export_all is used. The warning can be disabled + using nowarn_export_all.

+

+ Own Id: OTP-14071

+ + +

When a gen_server process crashes, the + stacktrace for the client will be printed to facilitate + debugging.

+

+ Own Id: OTP-14089

+ + +

+ Optimized ETS operations by changing table identifier + type from integer to reference. The reference enables a + more direct mapping to the table with less potential lock + contention and makes especially creation and deletion of + tables scale much better.

+

+ The change of the opaque type for the ETS table + identifiers may cause failure in code that make faulty + assumptions about this opaque type.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14094

+ + +

take/2 has been added to dict, + orddict, and gb_trees. take_any/2 + has been added to gb_trees.

+

+ Own Id: OTP-14102

+ + +

+ Extend gen_event API to handle options as well.

+

+ Own Id: OTP-14123

+ + +

+ Advice on how to tune the supervisor restart frequency + (intensity and period) is added to System Documentation - + Design Principles - Supervisor Behaviour.

+

+ Own Id: OTP-14168 Aux Id: PR-1289

+ + +

+ Replace gen_fsm with gen_statem

+

+ Own Id: OTP-14183

+ + +

The shell functions c/1 and c/2 have + been extended so that if the argument is a module name + instead of a file name, it automatically locates the + .beam file and the corresponding source file, and then + recompiles the module using the same compiler options + (plus any options passed to c/2). If compilation fails, + the old beam file is preserved. Also adds c(Mod, Opts, + Filter), where the Filter argument allows you to + remove old compiler options before the new options are + added.

New utility functions file_find/2/3 + and find_source/1/2/3 have been added to + filelib.

+

+ Own Id: OTP-14190

+ + +

erl_tar in previous versions of OTP only + supports the USTAR format. That limited path names to at + most 255 bytes, and did not support Unicode characters in + names in a portable way.

+

erl_tar now has support for reading tar + archives in the formats currently in common use, such as + v7, STAR, USTAR, PAX, and GNU tar's extensions to the + STAR/USTAR format. When writing tar archives, + erl_tar can now write them in the PAX + format if necessary (for example, to support very long + filenames or filenames with Unicode characters). If + possible, erl_tar will still write tar archives in + the USTAR for maximum portability.

+

+ Own Id: OTP-14226

+ + +

base64:mime_decode/1 has been optimized so that + it is now almost as fast asbase64:decode/1; it + used be noticably slower.

+

+ Own Id: OTP-14245

+ + +

erl_tar will now strip any leading '/' + from pathnames when extracting files from a tar archive + and write a message to the error logger. There is also + new check for directory traversal attacks; if a relative + path points above the current working directory the + extraction will be aborted.

+

+ Own Id: OTP-14278

+ + +

Miscellaneous updates due to atoms containing + arbitrary Unicode characters.

+

+ Own Id: OTP-14285

+ + +

+ The Crypto application now supports generation of + cryptographically strong random numbers (floats < 1.0 + and integer arbitrary ranges) as a plugin to the 'rand' + module.

+

+ Own Id: OTP-14317 Aux Id: PR-1372

+ + +

+ Add new function ets:select_replace/2 which + performs atomic "compare-and-swap" operations for ETS + objects using match specifications.

+

+ Own Id: OTP-14319 Aux Id: PR-1076

+ + +

The Erlang code linter checks for bad dialyzer + attributes.

+

+ Own Id: OTP-14323

+ + +

Two new functions has been implemented in the + rand module; normal/2 and + normal_s/3, that both produce normal distribution + (pseudo) random numbers with mean value and variance + according to arguments.

+

+ Own Id: OTP-14328 Aux Id: PR-1382

+ + +

+ Upgraded the OTP internal PCRE library from version 8.33 + to version 8.40. This library is used for implementation + of the re + regular expressions module.

+

+ Besides various bug fixes, the new version allows for + better stack protection. In order to utilize this + feature, the stack size of normal scheduler threads is + now by default set to 128 kilo words on all platforms. + The stack size of normal scheduler threads can be set + upon system start by passing the +sss + command line argument to the erl command.

+

+ See http://pcre.org/original/changelog.txt + for information about changes made to PCRE between the + versions 8.33 and 8.40.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14331 Aux Id: ERL-208

+ + +

+ Added function re:version/0 which returns + information about the OTP internal PCRE version used for + implementation of the re module.

+

+ Own Id: OTP-14347 Aux Id: PR-1412

+ + +

The format of debug information that is stored in BEAM + files (when debug_info is used) has been changed. + The purpose of the change is to better support other + BEAM-based languages such as Elixir or LFE.

+

All tools included in OTP (dialyzer, debugger, cover, + and so on) will handle both the new format and the + previous format. Tools that retrieve the debug + information using beam_lib:chunk(Beam, + [abstract_code]) will continue to work with both the + new and old format. Tools that call + beam_lib:chunk(Beam, ["Abst"]) will not work with + the new format.

+

For more information, see the description of + debug_info in the documentation for + beam_lib and the description of the + {debug_info,{Backend,Data}} option in the + documentation for compile.

+

+ Own Id: OTP-14369 Aux Id: PR-1367

+ + +
+ +
+
STDLIB 3.3
Fixed Bugs and Malfunctions -- cgit v1.2.3 From eace29905be436d77245656b2511c9a9c2c67c90 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 5 May 2017 13:15:42 +0200 Subject: Revert "Prepare release" This reverts commit dc57404252c47520f352834ad9be45ad684f96c9. --- lib/stdlib/doc/src/notes.xml | 378 ------------------------------------------- 1 file changed, 378 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index b4b6eac9d3..a8a252cb35 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,384 +31,6 @@

This document describes the changes made to the STDLIB application.

-
STDLIB 3.4 - -
Fixed Bugs and Malfunctions - - -

For many releases, it has been legal to override a BIF - with a local function having the same name. However, - calling a local function with the same name as guard BIF - as filter in a list comprehension was not allowed.

-

- Own Id: OTP-13690

- - -

A new (default) pseudo-random number generator - algorithm Xoroshiro116+ has been implemented in the - rand module.

The old algorithm - implementations had a number of flaws so they are all - deprecated, but corrected versions of two of them have - been added. See the documentation.

-

- Own Id: OTP-14295 Aux Id: PR-1372

- - -

The Erlang shell, qlc:string_to_handle(), and - the Debugger (the Evaluator area and Edit variable window - of the Bindings area) can parse pids, ports, references, - and external funs, as long as they can be created in the - running system.

-

- Own Id: OTP-14296

- - -

The state machine engine gen_statem can now - handle generic time-outs (multiple named) as well as - absolute time-out time. See the documentation.

- The gen_statem callback Module:init/1 has - become mandatory to harmonize with other gen_* - modules. This may be an incompatibility for - gen_statem callback modules that use - gen_statem:enter_loop/4-6.

-

- *** POTENTIAL INCOMPATIBILITY ***

-

- Own Id: OTP-14531

- - -
- - -
Improvements and New Features - - -

- Improved unicode support for strings. Added normalization - functions in the unicode module. Extended the - string module API with new functions with improved - unicode handling and that works on grapheme clusters. The - new functions operates on the unicode:chardata() - type, thus they also accept UTF-8 binaries as - input.

-

- The old string API have been marked as obsolete. The - return values have been changed for some error cases.

-

- *** POTENTIAL INCOMPATIBILITY ***

-

- Own Id: OTP-10289 Aux Id: OTP-10309

- - -

There are two new guard BIFs 'floor/1' and - 'ceil/1'. They both return integers. In the - 'math' module, there are two new BIFs with the - same names that return floating point values.

-

- Own Id: OTP-13692

- - -

- Making code_change, terminate and handle_info callbacks - optional in the OTP behaviours.

-

- Own Id: OTP-13801

- - -

The support for Dets files created with Erlang/OTP R7 - and earlier is removed.

-

- Own Id: OTP-13830

- - -

Replaced usage of deprecated symbolic time - unit representations.

-

- Own Id: OTP-13831 Aux Id: OTP-13735

- - -

The function fmod/2 has been added to the - math module.

-

- Own Id: OTP-14000

- - -

The EXIT signals received from processes using - proc_lib now looks like EXIT signals from - processes that were spawned using spawn_link. In - particular, that means that the stack trace is now - included in the EXIT signal so that it can see where the - process crashed.

-

- Own Id: OTP-14001

- - -

sets:add_element/2 is faster when adding an - element that is already present, and - sets:del_element/2 is faster when the element to - be deleted is not present. This optimization can make - certain operations, such as sets:union/2 with many - overlapping elements, up to two orders of magnitude - faster.

-

- Own Id: OTP-14035

- - -

- Add information in doc about supervisor shutdown reason - when maximum restart frequency is reached.

-

- Own Id: OTP-14037 Aux Id: PR-1233

- - -

- Added rand:jump/[0|1] functions.

-

- Own Id: OTP-14038 Aux Id: PR-1235

- - -

Functions for detecting changed code has been added. - code:modified_modules/0 returns all currently - loaded modules that have changed on disk. - code:module_status/1 returns the status for a - module. In the shell and in c module, mm/0 - is short for code:modified_modules/0, and - lm/0 reloads all currently loaded modules that - have changed on disk.

-

- Own Id: OTP-14059

- - -

Each assert macro in assert.hrl now has a - corresponding version with an extra argument, for adding - comments to assertions. These can for example be printed - as part of error reports, to clarify the meaning of the - check that failed.

-

- Own Id: OTP-14066

- - -

error_logger_tty_h and - error_logger_file_h now inserts the node - information for nonlocal messages before the message - itself instead of after, both for readability and so as - not to change the line termination property at the end of - the message.

-

- Own Id: OTP-14068

- - -

The Erlang code linter checks for badly formed type - constraints.

-

- Own Id: OTP-14070 Aux Id: PR-1214

- - -

By default, there will now be a warning when - export_all is used. The warning can be disabled - using nowarn_export_all.

-

- Own Id: OTP-14071

- - -

When a gen_server process crashes, the - stacktrace for the client will be printed to facilitate - debugging.

-

- Own Id: OTP-14089

- - -

- Optimized ETS operations by changing table identifier - type from integer to reference. The reference enables a - more direct mapping to the table with less potential lock - contention and makes especially creation and deletion of - tables scale much better.

-

- The change of the opaque type for the ETS table - identifiers may cause failure in code that make faulty - assumptions about this opaque type.

-

- *** POTENTIAL INCOMPATIBILITY ***

-

- Own Id: OTP-14094

- - -

take/2 has been added to dict, - orddict, and gb_trees. take_any/2 - has been added to gb_trees.

-

- Own Id: OTP-14102

- - -

- Extend gen_event API to handle options as well.

-

- Own Id: OTP-14123

- - -

- Advice on how to tune the supervisor restart frequency - (intensity and period) is added to System Documentation - - Design Principles - Supervisor Behaviour.

-

- Own Id: OTP-14168 Aux Id: PR-1289

- - -

- Replace gen_fsm with gen_statem

-

- Own Id: OTP-14183

- - -

The shell functions c/1 and c/2 have - been extended so that if the argument is a module name - instead of a file name, it automatically locates the - .beam file and the corresponding source file, and then - recompiles the module using the same compiler options - (plus any options passed to c/2). If compilation fails, - the old beam file is preserved. Also adds c(Mod, Opts, - Filter), where the Filter argument allows you to - remove old compiler options before the new options are - added.

New utility functions file_find/2/3 - and find_source/1/2/3 have been added to - filelib.

-

- Own Id: OTP-14190

- - -

erl_tar in previous versions of OTP only - supports the USTAR format. That limited path names to at - most 255 bytes, and did not support Unicode characters in - names in a portable way.

-

erl_tar now has support for reading tar - archives in the formats currently in common use, such as - v7, STAR, USTAR, PAX, and GNU tar's extensions to the - STAR/USTAR format. When writing tar archives, - erl_tar can now write them in the PAX - format if necessary (for example, to support very long - filenames or filenames with Unicode characters). If - possible, erl_tar will still write tar archives in - the USTAR for maximum portability.

-

- Own Id: OTP-14226

- - -

base64:mime_decode/1 has been optimized so that - it is now almost as fast asbase64:decode/1; it - used be noticably slower.

-

- Own Id: OTP-14245

- - -

erl_tar will now strip any leading '/' - from pathnames when extracting files from a tar archive - and write a message to the error logger. There is also - new check for directory traversal attacks; if a relative - path points above the current working directory the - extraction will be aborted.

-

- Own Id: OTP-14278

- - -

Miscellaneous updates due to atoms containing - arbitrary Unicode characters.

-

- Own Id: OTP-14285

- - -

- The Crypto application now supports generation of - cryptographically strong random numbers (floats < 1.0 - and integer arbitrary ranges) as a plugin to the 'rand' - module.

-

- Own Id: OTP-14317 Aux Id: PR-1372

- - -

- Add new function ets:select_replace/2 which - performs atomic "compare-and-swap" operations for ETS - objects using match specifications.

-

- Own Id: OTP-14319 Aux Id: PR-1076

- - -

The Erlang code linter checks for bad dialyzer - attributes.

-

- Own Id: OTP-14323

- - -

Two new functions has been implemented in the - rand module; normal/2 and - normal_s/3, that both produce normal distribution - (pseudo) random numbers with mean value and variance - according to arguments.

-

- Own Id: OTP-14328 Aux Id: PR-1382

- - -

- Upgraded the OTP internal PCRE library from version 8.33 - to version 8.40. This library is used for implementation - of the re - regular expressions module.

-

- Besides various bug fixes, the new version allows for - better stack protection. In order to utilize this - feature, the stack size of normal scheduler threads is - now by default set to 128 kilo words on all platforms. - The stack size of normal scheduler threads can be set - upon system start by passing the +sss - command line argument to the erl command.

-

- See http://pcre.org/original/changelog.txt - for information about changes made to PCRE between the - versions 8.33 and 8.40.

-

- *** POTENTIAL INCOMPATIBILITY ***

-

- Own Id: OTP-14331 Aux Id: ERL-208

- - -

- Added function re:version/0 which returns - information about the OTP internal PCRE version used for - implementation of the re module.

-

- Own Id: OTP-14347 Aux Id: PR-1412

- - -

The format of debug information that is stored in BEAM - files (when debug_info is used) has been changed. - The purpose of the change is to better support other - BEAM-based languages such as Elixir or LFE.

-

All tools included in OTP (dialyzer, debugger, cover, - and so on) will handle both the new format and the - previous format. Tools that retrieve the debug - information using beam_lib:chunk(Beam, - [abstract_code]) will continue to work with both the - new and old format. Tools that call - beam_lib:chunk(Beam, ["Abst"]) will not work with - the new format.

-

For more information, see the description of - debug_info in the documentation for - beam_lib and the description of the - {debug_info,{Backend,Data}} option in the - documentation for compile.

-

- Own Id: OTP-14369 Aux Id: PR-1367

- - -
- -
-
STDLIB 3.3
Fixed Bugs and Malfunctions -- cgit v1.2.3 From 6c3265b86582d4848e1c77efee3a649a137694d6 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Fri, 5 May 2017 14:51:58 +0200 Subject: stdlib: Add examples for ets:select_replace docs --- lib/stdlib/doc/src/ets.xml | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index d1ec176f81..62e97218cd 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -1495,17 +1495,37 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> Match and replace objects atomically in an ETS table

Matches the objects in the table Tab using a - match specification. If - an object is matched, the existing object is replaced with - the match specification result, which must retain - the original key or the operation will fail with badarg.

+ match specification. For each + matched object, the existing object is replaced with + the match specification result.

+

The match-and-replace operation for each individual object is guaranteed to be + atomic and isolated. The + select_replace table iteration as a whole, like all other select functions, + does not give such guarantees.

+

The match specifiction must be guaranteed to retain the key + of any matched object. If not, select_replace will fail with badarg + without updating any objects.

For the moment, due to performance and semantic constraints, tables of type bag are not yet supported.

The function returns the total number of replaced objects.

- -

The match/replacement operation atomicity scope is limited - to each individual object.

- +

Example

+

For all 2-tuples with a list in second position, add atom 'marker' first in the list:

+ 
+1> T = ets:new(x,[]), ets:insert(T, {key, [1, 2, 3]}).
+true
+2> MS = ets:fun2ms(fun({K, L}) when is_list(L) -> {K, [marker | L]} end).
+[{{'$1','$2'},[{is_list,'$2'}],[{{'$1',[marker|'$2']}}]}]
+3> ets:select_replace(T, MS).
+1
+4> ets:tab2list(T).
+[{key,[marker,1,2,3]}]
+
+

A generic single object compare-and-swap operation:

+ 
+[Old] = ets:lookup(T, Key),
+New = update_object(Old),
+Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])),
+
-- cgit v1.2.3 From 51c44f09553b13194ee8346266b0930d1a135590 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 19 May 2017 11:52:35 +0200 Subject: Fix documentation details --- lib/stdlib/doc/src/gen_statem.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index bc86415d28..e71de1523b 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -4,7 +4,7 @@
- 2016-2017 + 20162017 Ericsson AB. All Rights Reserved. @@ -344,7 +344,7 @@ ok

To compare styles, here follows the same example using callback mode - state_functions, or rather the code to replace + handle_event_function, or rather the code to replace after function init/1 of the pushbutton.erl example file above:

-- cgit v1.2.3 From e1370f924df65e72843b5f81400230e1c2591485 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Fri, 19 May 2017 16:06:08 +0200 Subject: Return error tuple on unicode normalization functions Prior to this patch, the normalization functions in the unicode module would raise a function clause error for non-utf8 binaries. This patch changes it so it returns {error, SoFar, Invalid} as characters_to_binary and characters_to_list does in the unicode module. Note string:next_codepoint/1 and string:next_grapheme had to be changed accordingly and also return an error tuple. --- lib/stdlib/doc/src/string.xml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml index 343904a49a..9d5edd9ecf 100644 --- a/lib/stdlib/doc/src/string.xml +++ b/lib/stdlib/doc/src/string.xml @@ -311,7 +311,9 @@ true

Returns the first codepoint in String - and the rest of String in the tail. + and the rest of String in the tail. Returns + an empty list if String is empty or an + {error, String} tuple if the next byte is invalid.

Example:

@@ -326,7 +328,9 @@ true

Returns the first grapheme cluster in String - and the rest of String in the tail. + and the rest of String in the tail. Returns + an empty list if String is empty or an + {error, String} tuple if the next byte is invalid.

Example:

-- 
cgit v1.2.3


From eaf8ca41dfa4850437ad270d3897399c9358ced0 Mon Sep 17 00:00:00 2001
From: Erlang/OTP 
Date: Tue, 30 May 2017 16:15:30 +0200
Subject: Prepare release

---
 lib/stdlib/doc/src/notes.xml | 412 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 412 insertions(+)

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

diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml
index a8a252cb35..fad0896d9b 100644
--- a/lib/stdlib/doc/src/notes.xml
+++ b/lib/stdlib/doc/src/notes.xml
@@ -31,6 +31,418 @@

This document describes the changes made to the STDLIB application.

+
STDLIB 3.4 + +
Fixed Bugs and Malfunctions + + +

For many releases, it has been legal to override a BIF + with a local function having the same name. However, + calling a local function with the same name as guard BIF + as filter in a list comprehension was not allowed.

+

+ Own Id: OTP-13690

+ + +

A new (default) pseudo-random number generator + algorithm Xoroshiro116+ has been implemented in the + rand module.

The old algorithm + implementations had a number of flaws so they are all + deprecated, but corrected versions of two of them have + been added. See the documentation.

+

+ Own Id: OTP-14295 Aux Id: PR-1372

+ + +

The Erlang shell, qlc:string_to_handle(), and + the Debugger (the Evaluator area and Edit variable window + of the Bindings area) can parse pids, ports, references, + and external funs, as long as they can be created in the + running system.

+

+ Own Id: OTP-14296

+ + +

Internal code change: Calls to catch followed + by a call to erlang:get_stacktrace/0 has been + rewritten to use try instead of catch to + make the code future-proof.

+

+ Own Id: OTP-14400

+ + +

The state machine engine gen_statem can now + handle generic time-outs (multiple named) as well as + absolute time-out time. See the documentation.

+ The gen_statem callback Module:init/1 has + become mandatory to harmonize with other gen_* + modules. This may be an incompatibility for + gen_statem callback modules that use + gen_statem:enter_loop/4-6.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14531

+ + +
+ + +
Improvements and New Features + + +

+ Improved unicode support for strings. Added normalization + functions in the unicode module. Extended the + string module API with new functions with improved + unicode handling and that works on grapheme clusters. The + new functions operates on the unicode:chardata() + type, thus they also accept UTF-8 binaries as + input.

+

+ The old string API have been marked as obsolete. The + return values have been changed for some error cases.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-10289 Aux Id: OTP-10309

+ + +

There are two new guard BIFs 'floor/1' and + 'ceil/1'. They both return integers. In the + 'math' module, there are two new BIFs with the + same names that return floating point values.

+

+ Own Id: OTP-13692

+ + +

+ Making code_change, terminate and handle_info callbacks + optional in the OTP behaviours.

+

+ Own Id: OTP-13801

+ + +

The support for Dets files created with Erlang/OTP R7 + and earlier is removed.

+

+ Own Id: OTP-13830

+ + +

Replaced usage of deprecated symbolic time + unit representations.

+

+ Own Id: OTP-13831 Aux Id: OTP-13735

+ + +

The function fmod/2 has been added to the + math module.

+

+ Own Id: OTP-14000

+ + +

The EXIT signals received from processes using + proc_lib now looks like EXIT signals from + processes that were spawned using spawn_link. In + particular, that means that the stack trace is now + included in the EXIT signal so that it can see where the + process crashed.

+

+ Own Id: OTP-14001

+ + +

sets:add_element/2 is faster when adding an + element that is already present, and + sets:del_element/2 is faster when the element to + be deleted is not present. This optimization can make + certain operations, such as sets:union/2 with many + overlapping elements, up to two orders of magnitude + faster.

+

+ Own Id: OTP-14035

+ + +

+ Add information in doc about supervisor shutdown reason + when maximum restart frequency is reached.

+

+ Own Id: OTP-14037 Aux Id: PR-1233

+ + +

+ Added rand:jump/[0|1] functions.

+

+ Own Id: OTP-14038 Aux Id: PR-1235

+ + +

Functions for detecting changed code has been added. + code:modified_modules/0 returns all currently + loaded modules that have changed on disk. + code:module_status/1 returns the status for a + module. In the shell and in c module, mm/0 + is short for code:modified_modules/0, and + lm/0 reloads all currently loaded modules that + have changed on disk.

+

+ Own Id: OTP-14059

+ + +

Each assert macro in assert.hrl now has a + corresponding version with an extra argument, for adding + comments to assertions. These can for example be printed + as part of error reports, to clarify the meaning of the + check that failed.

+

+ Own Id: OTP-14066

+ + +

error_logger_tty_h and + error_logger_file_h now inserts the node + information for nonlocal messages before the message + itself instead of after, both for readability and so as + not to change the line termination property at the end of + the message.

+

+ Own Id: OTP-14068

+ + +

The Erlang code linter checks for badly formed type + constraints.

+

+ Own Id: OTP-14070 Aux Id: PR-1214

+ + +

By default, there will now be a warning when + export_all is used. The warning can be disabled + using nowarn_export_all.

+

+ Own Id: OTP-14071

+ + +

When a gen_server process crashes, the + stacktrace for the client will be printed to facilitate + debugging.

+

+ Own Id: OTP-14089

+ + +

+ Optimized ETS operations by changing table identifier + type from integer to reference. The reference enables a + more direct mapping to the table with less potential lock + contention and makes especially creation and deletion of + tables scale much better.

+

+ The change of the opaque type for the ETS table + identifiers may cause failure in code that make faulty + assumptions about this opaque type.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14094

+ + +

take/2 has been added to dict, + orddict, and gb_trees. take_any/2 + has been added to gb_trees.

+

+ Own Id: OTP-14102

+ + +

+ Extend gen_event API to handle options as well.

+

+ Own Id: OTP-14123

+ + +

+ Advice on how to tune the supervisor restart frequency + (intensity and period) is added to System Documentation - + Design Principles - Supervisor Behaviour.

+

+ Own Id: OTP-14168 Aux Id: PR-1289

+ + +

+ gen_fsm is deprecated and is replaced by gen_statem, + however for backwards compatibility reasons gen_fsm may + continue to exist as an undocumented feature for quite + some time.

+

+ Own Id: OTP-14183

+ + +

The shell functions c/1 and c/2 have + been extended so that if the argument is a module name + instead of a file name, it automatically locates the + .beam file and the corresponding source file, and then + recompiles the module using the same compiler options + (plus any options passed to c/2). If compilation fails, + the old beam file is preserved. Also adds c(Mod, Opts, + Filter), where the Filter argument allows you to + remove old compiler options before the new options are + added.

New utility functions file_find/2/3 + and find_source/1/2/3 have been added to + filelib.

+

+ Own Id: OTP-14190

+ + +

erl_tar in previous versions of OTP only + supports the USTAR format. That limited path names to at + most 255 bytes, and did not support Unicode characters in + names in a portable way.

+

erl_tar now has support for reading tar + archives in the formats currently in common use, such as + v7, STAR, USTAR, PAX, and GNU tar's extensions to the + STAR/USTAR format. When writing tar archives, + erl_tar can now write them in the PAX + format if necessary (for example, to support very long + filenames or filenames with Unicode characters). If + possible, erl_tar will still write tar archives in + the USTAR for maximum portability.

+

+ Own Id: OTP-14226

+ + +

base64:mime_decode/1 has been optimized so that + it is now almost as fast asbase64:decode/1; it + used be noticably slower.

+

+ Own Id: OTP-14245

+ + +

erl_tar will now strip any leading '/' + from pathnames when extracting files from a tar archive + and write a message to the error logger. There is also + new check for directory traversal attacks; if a relative + path points above the current working directory the + extraction will be aborted.

+

+ Own Id: OTP-14278

+ + +

Miscellaneous updates due to atoms containing + arbitrary Unicode characters.

+

+ Own Id: OTP-14285

+ + +

+ The Crypto application now supports generation of + cryptographically strong random numbers (floats < 1.0 + and integer arbitrary ranges) as a plugin to the 'rand' + module.

+

+ Own Id: OTP-14317 Aux Id: PR-1372

+ + +

+ Add new function ets:select_replace/2 which + performs atomic "compare-and-swap" operations for ETS + objects using match specifications.

+

+ Own Id: OTP-14319 Aux Id: PR-1076

+ + +

The Erlang code linter checks for bad dialyzer + attributes. It also checks for bad type variables in type + declarations.

+

+ Own Id: OTP-14323

+ + +

Two new functions has been implemented in the + rand module; normal/2 and + normal_s/3, that both produce normal distribution + (pseudo) random numbers with mean value and variance + according to arguments.

+

+ Own Id: OTP-14328 Aux Id: PR-1382

+ + +

+ Upgraded the OTP internal PCRE library from version 8.33 + to version 8.40. This library is used for implementation + of the re + regular expressions module.

+

+ Besides various bug fixes, the new version allows for + better stack protection. In order to utilize this + feature, the stack size of normal scheduler threads is + now by default set to 128 kilo words on all platforms. + The stack size of normal scheduler threads can be set + upon system start by passing the +sss + command line argument to the erl command.

+

+ See http://pcre.org/original/changelog.txt + for information about changes made to PCRE between the + versions 8.33 and 8.40.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14331 Aux Id: ERL-208

+ + +

+ Added function re:version/0 which returns + information about the OTP internal PCRE version used for + implementation of the re module.

+

+ Own Id: OTP-14347 Aux Id: PR-1412

+ + +

The format of debug information that is stored in BEAM + files (when debug_info is used) has been changed. + The purpose of the change is to better support other + BEAM-based languages such as Elixir or LFE.

+

All tools included in OTP (dialyzer, debugger, cover, + and so on) will handle both the new format and the + previous format. Tools that retrieve the debug + information using beam_lib:chunk(Beam, + [abstract_code]) will continue to work with both the + new and old format. Tools that call + beam_lib:chunk(Beam, ["Abst"]) will not work with + the new format.

+

For more information, see the description of + debug_info in the documentation for + beam_lib and the description of the + {debug_info,{Backend,Data}} option in the + documentation for compile.

+

+ Own Id: OTP-14369 Aux Id: PR-1367

+ + +

+ Add option hibernate_after to gen_server, gen_statem and + gen_event. Also added to the deprecated gen_fsm + behaviour.

+

+ Own Id: OTP-14405

+ + +

The size of crash reports created by + gen_server, gen_statem and proc_lib + is limited with aid of the Kernel application variable + error_logger_format_depth. The purpose is to limit + the size of the error_logger process when + processes with huge message queues or states crash.

+

The new function + error_logger:get_format_depth/0 can be used to + retrieve the value of the Kernel application variable + error_logger_format_depth.

+

+ Own Id: OTP-14417

+ + +
+ +
+
STDLIB 3.3
Fixed Bugs and Malfunctions -- cgit v1.2.3 From 32275a2fc0b86d1f1b124706afc80f3ff92216eb Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Wed, 31 May 2017 16:21:00 +0200 Subject: Revert "Prepare release" This reverts commit eaf8ca41dfa4850437ad270d3897399c9358ced0. --- lib/stdlib/doc/src/notes.xml | 412 ------------------------------------------- 1 file changed, 412 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index fad0896d9b..a8a252cb35 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,418 +31,6 @@

This document describes the changes made to the STDLIB application.

-
STDLIB 3.4 - -
Fixed Bugs and Malfunctions - - -

For many releases, it has been legal to override a BIF - with a local function having the same name. However, - calling a local function with the same name as guard BIF - as filter in a list comprehension was not allowed.

-

- Own Id: OTP-13690

- - -

A new (default) pseudo-random number generator - algorithm Xoroshiro116+ has been implemented in the - rand module.

The old algorithm - implementations had a number of flaws so they are all - deprecated, but corrected versions of two of them have - been added. See the documentation.

-

- Own Id: OTP-14295 Aux Id: PR-1372

- - -

The Erlang shell, qlc:string_to_handle(), and - the Debugger (the Evaluator area and Edit variable window - of the Bindings area) can parse pids, ports, references, - and external funs, as long as they can be created in the - running system.

-

- Own Id: OTP-14296

- - -

Internal code change: Calls to catch followed - by a call to erlang:get_stacktrace/0 has been - rewritten to use try instead of catch to - make the code future-proof.

-

- Own Id: OTP-14400

- - -

The state machine engine gen_statem can now - handle generic time-outs (multiple named) as well as - absolute time-out time. See the documentation.

- The gen_statem callback Module:init/1 has - become mandatory to harmonize with other gen_* - modules. This may be an incompatibility for - gen_statem callback modules that use - gen_statem:enter_loop/4-6.

-

- *** POTENTIAL INCOMPATIBILITY ***

-

- Own Id: OTP-14531

- - -
- - -
Improvements and New Features - - -

- Improved unicode support for strings. Added normalization - functions in the unicode module. Extended the - string module API with new functions with improved - unicode handling and that works on grapheme clusters. The - new functions operates on the unicode:chardata() - type, thus they also accept UTF-8 binaries as - input.

-

- The old string API have been marked as obsolete. The - return values have been changed for some error cases.

-

- *** POTENTIAL INCOMPATIBILITY ***

-

- Own Id: OTP-10289 Aux Id: OTP-10309

- - -

There are two new guard BIFs 'floor/1' and - 'ceil/1'. They both return integers. In the - 'math' module, there are two new BIFs with the - same names that return floating point values.

-

- Own Id: OTP-13692

- - -

- Making code_change, terminate and handle_info callbacks - optional in the OTP behaviours.

-

- Own Id: OTP-13801

- - -

The support for Dets files created with Erlang/OTP R7 - and earlier is removed.

-

- Own Id: OTP-13830

- - -

Replaced usage of deprecated symbolic time - unit representations.

-

- Own Id: OTP-13831 Aux Id: OTP-13735

- - -

The function fmod/2 has been added to the - math module.

-

- Own Id: OTP-14000

- - -

The EXIT signals received from processes using - proc_lib now looks like EXIT signals from - processes that were spawned using spawn_link. In - particular, that means that the stack trace is now - included in the EXIT signal so that it can see where the - process crashed.

-

- Own Id: OTP-14001

- - -

sets:add_element/2 is faster when adding an - element that is already present, and - sets:del_element/2 is faster when the element to - be deleted is not present. This optimization can make - certain operations, such as sets:union/2 with many - overlapping elements, up to two orders of magnitude - faster.

-

- Own Id: OTP-14035

- - -

- Add information in doc about supervisor shutdown reason - when maximum restart frequency is reached.

-

- Own Id: OTP-14037 Aux Id: PR-1233

- - -

- Added rand:jump/[0|1] functions.

-

- Own Id: OTP-14038 Aux Id: PR-1235

- - -

Functions for detecting changed code has been added. - code:modified_modules/0 returns all currently - loaded modules that have changed on disk. - code:module_status/1 returns the status for a - module. In the shell and in c module, mm/0 - is short for code:modified_modules/0, and - lm/0 reloads all currently loaded modules that - have changed on disk.

-

- Own Id: OTP-14059

- - -

Each assert macro in assert.hrl now has a - corresponding version with an extra argument, for adding - comments to assertions. These can for example be printed - as part of error reports, to clarify the meaning of the - check that failed.

-

- Own Id: OTP-14066

- - -

error_logger_tty_h and - error_logger_file_h now inserts the node - information for nonlocal messages before the message - itself instead of after, both for readability and so as - not to change the line termination property at the end of - the message.

-

- Own Id: OTP-14068

- - -

The Erlang code linter checks for badly formed type - constraints.

-

- Own Id: OTP-14070 Aux Id: PR-1214

- - -

By default, there will now be a warning when - export_all is used. The warning can be disabled - using nowarn_export_all.

-

- Own Id: OTP-14071

- - -

When a gen_server process crashes, the - stacktrace for the client will be printed to facilitate - debugging.

-

- Own Id: OTP-14089

- - -

- Optimized ETS operations by changing table identifier - type from integer to reference. The reference enables a - more direct mapping to the table with less potential lock - contention and makes especially creation and deletion of - tables scale much better.

-

- The change of the opaque type for the ETS table - identifiers may cause failure in code that make faulty - assumptions about this opaque type.

-

- *** POTENTIAL INCOMPATIBILITY ***

-

- Own Id: OTP-14094

- - -

take/2 has been added to dict, - orddict, and gb_trees. take_any/2 - has been added to gb_trees.

-

- Own Id: OTP-14102

- - -

- Extend gen_event API to handle options as well.

-

- Own Id: OTP-14123

- - -

- Advice on how to tune the supervisor restart frequency - (intensity and period) is added to System Documentation - - Design Principles - Supervisor Behaviour.

-

- Own Id: OTP-14168 Aux Id: PR-1289

- - -

- gen_fsm is deprecated and is replaced by gen_statem, - however for backwards compatibility reasons gen_fsm may - continue to exist as an undocumented feature for quite - some time.

-

- Own Id: OTP-14183

- - -

The shell functions c/1 and c/2 have - been extended so that if the argument is a module name - instead of a file name, it automatically locates the - .beam file and the corresponding source file, and then - recompiles the module using the same compiler options - (plus any options passed to c/2). If compilation fails, - the old beam file is preserved. Also adds c(Mod, Opts, - Filter), where the Filter argument allows you to - remove old compiler options before the new options are - added.

New utility functions file_find/2/3 - and find_source/1/2/3 have been added to - filelib.

-

- Own Id: OTP-14190

- - -

erl_tar in previous versions of OTP only - supports the USTAR format. That limited path names to at - most 255 bytes, and did not support Unicode characters in - names in a portable way.

-

erl_tar now has support for reading tar - archives in the formats currently in common use, such as - v7, STAR, USTAR, PAX, and GNU tar's extensions to the - STAR/USTAR format. When writing tar archives, - erl_tar can now write them in the PAX - format if necessary (for example, to support very long - filenames or filenames with Unicode characters). If - possible, erl_tar will still write tar archives in - the USTAR for maximum portability.

-

- Own Id: OTP-14226

- - -

base64:mime_decode/1 has been optimized so that - it is now almost as fast asbase64:decode/1; it - used be noticably slower.

-

- Own Id: OTP-14245

- - -

erl_tar will now strip any leading '/' - from pathnames when extracting files from a tar archive - and write a message to the error logger. There is also - new check for directory traversal attacks; if a relative - path points above the current working directory the - extraction will be aborted.

-

- Own Id: OTP-14278

- - -

Miscellaneous updates due to atoms containing - arbitrary Unicode characters.

-

- Own Id: OTP-14285

- - -

- The Crypto application now supports generation of - cryptographically strong random numbers (floats < 1.0 - and integer arbitrary ranges) as a plugin to the 'rand' - module.

-

- Own Id: OTP-14317 Aux Id: PR-1372

- - -

- Add new function ets:select_replace/2 which - performs atomic "compare-and-swap" operations for ETS - objects using match specifications.

-

- Own Id: OTP-14319 Aux Id: PR-1076

- - -

The Erlang code linter checks for bad dialyzer - attributes. It also checks for bad type variables in type - declarations.

-

- Own Id: OTP-14323

- - -

Two new functions has been implemented in the - rand module; normal/2 and - normal_s/3, that both produce normal distribution - (pseudo) random numbers with mean value and variance - according to arguments.

-

- Own Id: OTP-14328 Aux Id: PR-1382

- - -

- Upgraded the OTP internal PCRE library from version 8.33 - to version 8.40. This library is used for implementation - of the re - regular expressions module.

-

- Besides various bug fixes, the new version allows for - better stack protection. In order to utilize this - feature, the stack size of normal scheduler threads is - now by default set to 128 kilo words on all platforms. - The stack size of normal scheduler threads can be set - upon system start by passing the +sss - command line argument to the erl command.

-

- See http://pcre.org/original/changelog.txt - for information about changes made to PCRE between the - versions 8.33 and 8.40.

-

- *** POTENTIAL INCOMPATIBILITY ***

-

- Own Id: OTP-14331 Aux Id: ERL-208

- - -

- Added function re:version/0 which returns - information about the OTP internal PCRE version used for - implementation of the re module.

-

- Own Id: OTP-14347 Aux Id: PR-1412

- - -

The format of debug information that is stored in BEAM - files (when debug_info is used) has been changed. - The purpose of the change is to better support other - BEAM-based languages such as Elixir or LFE.

-

All tools included in OTP (dialyzer, debugger, cover, - and so on) will handle both the new format and the - previous format. Tools that retrieve the debug - information using beam_lib:chunk(Beam, - [abstract_code]) will continue to work with both the - new and old format. Tools that call - beam_lib:chunk(Beam, ["Abst"]) will not work with - the new format.

-

For more information, see the description of - debug_info in the documentation for - beam_lib and the description of the - {debug_info,{Backend,Data}} option in the - documentation for compile.

-

- Own Id: OTP-14369 Aux Id: PR-1367

- - -

- Add option hibernate_after to gen_server, gen_statem and - gen_event. Also added to the deprecated gen_fsm - behaviour.

-

- Own Id: OTP-14405

- - -

The size of crash reports created by - gen_server, gen_statem and proc_lib - is limited with aid of the Kernel application variable - error_logger_format_depth. The purpose is to limit - the size of the error_logger process when - processes with huge message queues or states crash.

-

The new function - error_logger:get_format_depth/0 can be used to - retrieve the value of the Kernel application variable - error_logger_format_depth.

-

- Own Id: OTP-14417

- - -
- -
-
STDLIB 3.3
Fixed Bugs and Malfunctions -- cgit v1.2.3 From 8cee96fe5d9e3ee3b4bcb527c5a75076ba2b59b0 Mon Sep 17 00:00:00 2001 From: Graham Hay Date: Sun, 4 Jun 2017 14:05:01 +0100 Subject: Fix typo --- lib/stdlib/doc/src/gen_statem.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 5eb13db1aa..07e76accb5 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -993,7 +993,7 @@ handle_event(_, _, State, Data) -> Module:init/1 or enter_loop/5,6 - would be weird on the border of whichcraft + would be weird on the border of witchcraft since there has been no earlier call to a state callback in this server. -- cgit v1.2.3 From ad39b74bfc30d532a622d693bc4a182becfa5471 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Wed, 14 Jun 2017 17:54:29 +0200 Subject: Update documentation of ERL_MAX_ETS_TABLES --- lib/stdlib/doc/src/ets.xml | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 342be80f98..f6f3d18d6a 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -49,13 +49,22 @@ associated with each key. A bag or duplicate_bag table can have many objects associated with each key.

-

The number of tables stored at one Erlang node is limited. - The current default limit is about 1400 tables. The upper - limit can be increased by setting environment variable - ERL_MAX_ETS_TABLES before starting the Erlang runtime - system (that is, with option -env to - erl/werl). The actual limit can be slightly higher - than the one specified, but never lower.

+ +

+ The number of tables stored at one Erlang node used to + be limited. This is no longer the case (except by memory usage). + The previous default limit was about 1400 tables and + could be increased by setting the environment variable + ERL_MAX_ETS_TABLES before starting the Erlang runtime + system. This hard limit has been removed, but it is currently + useful to set the ERL_MAX_ETS_TABLES anyway. It should be + set to an approximate of the maximum amount of tables used. This since + an internal table for named tables is sized using this value. If + large amounts of named tables are used and ERL_MAX_ETS_TABLES + hasn't been increased, the performance of named table lookup will + degrade. +

+

Notice that there is no automatic garbage collection for tables. Even if there are no references to a table from any process, it -- cgit v1.2.3 From 24b35460a12799f595da2430cc2904c88873c7a7 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Fri, 9 Jun 2017 17:47:34 +0200 Subject: [stdlib] Open sys debug logs as utf8 This allows the use of ~ts/~tp/~tw in the formatting fun to sys:handle_debug/4. --- lib/stdlib/doc/src/sys.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index f24e42bcee..64d8789016 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -308,7 +308,7 @@ format to the file. The events are formatted with a function that is defined by the process that generated the event (with a call to handle_debug/4). -

+ The file is opened with encoding UTF-8.

-- cgit v1.2.3 From c18b13d4c8aa31b145703bbbf228fb07d6b2a0a5 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Wed, 21 Jun 2017 10:53:19 +0200 Subject: Prepare release --- lib/stdlib/doc/src/notes.xml | 438 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 438 insertions(+) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index a8a252cb35..46454e9b80 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,6 +31,444 @@

This document describes the changes made to the STDLIB application.

+
STDLIB 3.4 + +
Fixed Bugs and Malfunctions + + +

For many releases, it has been legal to override a BIF + with a local function having the same name. However, + calling a local function with the same name as guard BIF + as filter in a list comprehension was not allowed.

+

+ Own Id: OTP-13690

+ + +

A new (default) pseudo-random number generator + algorithm Xoroshiro116+ has been implemented in the + rand module.

The old algorithm + implementations had a number of flaws so they are all + deprecated, but corrected versions of two of them have + been added. See the documentation.

+

+ Own Id: OTP-14295 Aux Id: PR-1372

+ + +

The Erlang shell, qlc:string_to_handle(), and + the Debugger (the Evaluator area and Edit variable window + of the Bindings area) can parse pids, ports, references, + and external funs, as long as they can be created in the + running system.

+

+ Own Id: OTP-14296

+ + +

Internal code change: Calls to catch followed + by a call to erlang:get_stacktrace/0 has been + rewritten to use try instead of catch to + make the code future-proof.

+

+ Own Id: OTP-14400

+ + +

The ms_transform module, used by + ets:fun2ms/1 and dbg:fun2ms/1, evaluates + constant arithmetic expressions. This is necessary since + the Erlang compiler, which normally evaluates constant + expressions, does not recognize the format generated by + ms_transform.

+

+ Own Id: OTP-14454 Aux Id: ERIERL-29

+ + +

The state machine engine gen_statem can now + handle generic time-outs (multiple named) as well as + absolute time-out time. See the documentation.

+ The gen_statem callback Module:init/1 has + become mandatory to harmonize with other gen_* + modules. This may be an incompatibility for + gen_statem callback modules that use + gen_statem:enter_loop/4-6.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14531

+ + +
+ + +
Improvements and New Features + + +

+ Improved unicode support for strings. Added normalization + functions in the unicode module. Extended the + string module API with new functions with improved + unicode handling and that works on grapheme clusters. The + new functions operates on the unicode:chardata() + type, thus they also accept UTF-8 binaries as + input.

+

+ The old string API have been marked as obsolete. The + return values have been changed for some error cases.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-10289 Aux Id: OTP-10309

+ + +

There are two new guard BIFs 'floor/1' and + 'ceil/1'. They both return integers. In the + 'math' module, there are two new BIFs with the + same names that return floating point values.

+

+ Own Id: OTP-13692

+ + +

+ Making code_change, terminate and handle_info callbacks + optional in the OTP behaviours.

+

+ Own Id: OTP-13801

+ + +

The support for Dets files created with Erlang/OTP R7 + and earlier is removed.

+

+ Own Id: OTP-13830

+ + +

Replaced usage of deprecated symbolic time + unit representations.

+

+ Own Id: OTP-13831 Aux Id: OTP-13735

+ + +

The function fmod/2 has been added to the + math module.

+

+ Own Id: OTP-14000

+ + +

The EXIT signals received from processes using + proc_lib now looks like EXIT signals from + processes that were spawned using spawn_link. In + particular, that means that the stack trace is now + included in the EXIT signal so that it can see where the + process crashed.

+

+ Own Id: OTP-14001

+ + +

sets:add_element/2 is faster when adding an + element that is already present, and + sets:del_element/2 is faster when the element to + be deleted is not present. This optimization can make + certain operations, such as sets:union/2 with many + overlapping elements, up to two orders of magnitude + faster.

+

+ Own Id: OTP-14035

+ + +

+ Add information in doc about supervisor shutdown reason + when maximum restart frequency is reached.

+

+ Own Id: OTP-14037 Aux Id: PR-1233

+ + +

+ Added rand:jump/[0|1] functions.

+

+ Own Id: OTP-14038 Aux Id: PR-1235

+ + +

Functions for detecting changed code has been added. + code:modified_modules/0 returns all currently + loaded modules that have changed on disk. + code:module_status/1 returns the status for a + module. In the shell and in c module, mm/0 + is short for code:modified_modules/0, and + lm/0 reloads all currently loaded modules that + have changed on disk.

+

+ Own Id: OTP-14059

+ + +

Each assert macro in assert.hrl now has a + corresponding version with an extra argument, for adding + comments to assertions. These can for example be printed + as part of error reports, to clarify the meaning of the + check that failed.

+

+ Own Id: OTP-14066

+ + +

error_logger_tty_h and + error_logger_file_h now inserts the node + information for nonlocal messages before the message + itself instead of after, both for readability and so as + not to change the line termination property at the end of + the message.

+

+ Own Id: OTP-14068

+ + +

The Erlang code linter checks for badly formed type + constraints.

+

+ Own Id: OTP-14070 Aux Id: PR-1214

+ + +

By default, there will now be a warning when + export_all is used. The warning can be disabled + using nowarn_export_all.

+

+ Own Id: OTP-14071

+ + +

When a gen_server process crashes, the + stacktrace for the client will be printed to facilitate + debugging.

+

+ Own Id: OTP-14089

+ + +

Optimized ETS operations by changing table identifier + type from integer to reference. The reference enables a + more direct mapping to the table with less potential lock + contention and makes especially creation and deletion of + tables scale much better.

The change of the opaque + type for the ETS table identifiers may cause failure in + code that make faulty assumptions about this opaque + type.

The number of tables stored at one + Erlang node used to be limited. This is no + longer the case (except by memory usage). The previous + default limit was about 1400 tables and could be + increased by setting the environment variable + ERL_MAX_ETS_TABLES before starting the Erlang + runtime system. This hard limit has been removed, but it + is currently useful to set the ERL_MAX_ETS_TABLES + anyway. It should be set to an approximate of the maximum + amount of tables used. This since an internal table for + named tables is sized using this value. If large amounts + of named tables are used and ERL_MAX_ETS_TABLES + hasn't been increased, the performance of named table + lookup will degrade.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14094

+ + +

take/2 has been added to dict, + orddict, and gb_trees. take_any/2 + has been added to gb_trees.

+

+ Own Id: OTP-14102

+ + +

+ Extend gen_event API to handle options as well.

+

+ Own Id: OTP-14123

+ + +

+ Advice on how to tune the supervisor restart frequency + (intensity and period) is added to System Documentation - + Design Principles - Supervisor Behaviour.

+

+ Own Id: OTP-14168 Aux Id: PR-1289

+ + +

+ gen_fsm is deprecated and is replaced by gen_statem, + however for backwards compatibility reasons gen_fsm may + continue to exist as an undocumented feature for quite + some time.

+

+ Own Id: OTP-14183

+ + +

The shell functions c/1 and c/2 have + been extended so that if the argument is a module name + instead of a file name, it automatically locates the + .beam file and the corresponding source file, and then + recompiles the module using the same compiler options + (plus any options passed to c/2). If compilation fails, + the old beam file is preserved. Also adds c(Mod, Opts, + Filter), where the Filter argument allows you to + remove old compiler options before the new options are + added.

New utility functions file_find/2/3 + and find_source/1/2/3 have been added to + filelib.

+

+ Own Id: OTP-14190

+ + +

erl_tar in previous versions of OTP only + supports the USTAR format. That limited path names to at + most 255 bytes, and did not support Unicode characters in + names in a portable way.

+

erl_tar now has support for reading tar + archives in the formats currently in common use, such as + v7, STAR, USTAR, PAX, and GNU tar's extensions to the + STAR/USTAR format. When writing tar archives, + erl_tar can now write them in the PAX + format if necessary (for example, to support very long + filenames or filenames with Unicode characters). If + possible, erl_tar will still write tar archives in + the USTAR for maximum portability.

+

+ Own Id: OTP-14226

+ + +

base64:mime_decode/1 has been optimized so that + it is now almost as fast asbase64:decode/1; it + used be noticeably slower.

+

+ Own Id: OTP-14245

+ + +

erl_tar will now strip any leading '/' + from pathnames when extracting files from a tar archive + and write a message to the error logger. There is also + new check for directory traversal attacks; if a relative + path points above the current working directory the + extraction will be aborted.

+

+ Own Id: OTP-14278

+ + +

Miscellaneous updates due to atoms containing + arbitrary Unicode characters.

+

+ Own Id: OTP-14285

+ + +

+ The Crypto application now supports generation of + cryptographically strong random numbers (floats < 1.0 + and integer arbitrary ranges) as a plugin to the 'rand' + module.

+

+ Own Id: OTP-14317 Aux Id: PR-1372

+ + +

+ Add new function ets:select_replace/2 which + performs atomic "compare-and-swap" operations for ETS + objects using match specifications.

+

+ Own Id: OTP-14319 Aux Id: PR-1076

+ + +

The Erlang code linter checks for bad dialyzer + attributes. It also checks for bad type variables in type + declarations.

+

+ Own Id: OTP-14323

+ + +

Two new functions has been implemented in the + rand module; normal/2 and + normal_s/3, that both produce normal distribution + (pseudo) random numbers with mean value and variance + according to arguments.

+

+ Own Id: OTP-14328 Aux Id: PR-1382

+ + +

+ Upgraded the OTP internal PCRE library from version 8.33 + to version 8.40. This library is used for implementation + of the re + regular expressions module.

+

+ Besides various bug fixes, the new version allows for + better stack protection. In order to utilize this + feature, the stack size of normal scheduler threads is + now by default set to 128 kilo words on all platforms. + The stack size of normal scheduler threads can be set + upon system start by passing the +sss + command line argument to the erl command.

+

+ See http://pcre.org/original/changelog.txt + for information about changes made to PCRE between the + versions 8.33 and 8.40.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-14331 Aux Id: ERL-208

+ + +

+ Added function re:version/0 which returns + information about the OTP internal PCRE version used for + implementation of the re module.

+

+ Own Id: OTP-14347 Aux Id: PR-1412

+ + +

The format of debug information that is stored in BEAM + files (when debug_info is used) has been changed. + The purpose of the change is to better support other + BEAM-based languages such as Elixir or LFE.

+

All tools included in OTP (dialyzer, debugger, cover, + and so on) will handle both the new format and the + previous format. Tools that retrieve the debug + information using beam_lib:chunk(Beam, + [abstract_code]) will continue to work with both the + new and old format. Tools that call + beam_lib:chunk(Beam, ["Abst"]) will not work with + the new format.

+

For more information, see the description of + debug_info in the documentation for + beam_lib and the description of the + {debug_info,{Backend,Data}} option in the + documentation for compile.

+

+ Own Id: OTP-14369 Aux Id: PR-1367

+ + +

+ Add option hibernate_after to gen_server, gen_statem and + gen_event. Also added to the deprecated gen_fsm + behaviour.

+

+ Own Id: OTP-14405

+ + +

The size of crash reports created by + gen_server, gen_statem and proc_lib + is limited with aid of the Kernel application variable + error_logger_format_depth. The purpose is to limit + the size of the messages sent to the error_logger + process when processes with huge message queues or states + crash.

The crash report generated by + proc_lib includes the new tag + message_queue_len. The neighbour report also + includes the new tag current_stacktrace. Finally, + the neighbour report no longer includes the tags + messages and dictionary.

The new + function error_logger:get_format_depth/0 can be + used to retrieve the value of the Kernel application + variable error_logger_format_depth.

+

+ Own Id: OTP-14417

+ + +
+ +
+
STDLIB 3.3
Fixed Bugs and Malfunctions -- cgit v1.2.3