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