diff options
Diffstat (limited to 'lib/stdlib/doc')
| -rw-r--r-- | lib/stdlib/doc/src/ets.xml | 61 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/filename.xml | 2 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 98 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/notes.xml | 66 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/proplists.xml | 5 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/slave.xml | 19 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/sys.xml | 5 |
7 files changed, 200 insertions, 56 deletions
diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index e67397c6fd..2cb677785d 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -188,6 +188,46 @@ is used to keep the table fixated during the entire traversal.</p> </item> </list> + <note> + <p>Even though the access of a single object is always guaranteed to be + <seealso marker="#concurrency">atomic and isolated</seealso>, each traversal + through a table to find the next key is not done with such guarantees. This is often + not a problem, but may cause rare subtle "unexpected" effects if a concurrent + process inserts objects during a traversal. For example, consider one + process doing</p> +<pre> +ets:new(t, [ordered_set, named_table]), +ets:insert(t, {1}), +ets:insert(t, {2}), +ets:insert(t, {3}), +</pre> + <p>A concurrent call to <c>ets:first(t)</c>, done by another + process, may then in rare cases return <c>2</c> even though + <c>2</c> has never existed in the table ordered as the first key. In + the same way, a concurrent call to <c>ets:next(t, 1)</c> may return + <c>3</c> even though <c>3</c> never existed in the table + ordered directly after <c>1</c>.</p> + <p>Effects like this are improbable but possible. The probability will + further be reduced (if not vanish) if table option + <seealso marker="#new_2_write_concurrency"><c>write_concurrency</c></seealso> + is not enabled. This can also only be a potential concern for + <c>ordered_set</c> where the traversal order is defined.</p> + </note> + <p>Traversals using <c>match</c> and <c>select</c> functions may not need to + scan the entire table depending on how the key is specified. A match + pattern with a <em>fully bound key</em> (without any match variables) will + optimize the operation to a single key lookup without any table traversal + at all. For <c>ordered_set</c> a <em>partially bound key</em> will limit the + traversal to only scan a subset of the table based on term order. A + partially bound key is either a list or a tuple with a prefix that is fully + bound. Example:</p> +<pre> +1> <input>T = ets:new(t,[ordered_set]), ets:insert(T, {"555-1234", "John Smith"}).</input> +true +2> <input>%% Efficient search of all with area code 555</input> +2> <input>ets:match(T,{[$5,$5,$5,$- |'$1'],'$2'}).</input> +[["1234","John Smith"]] +</pre> </section> <section> @@ -602,12 +642,11 @@ Error: fun containing local Erlang function calls <p><marker id="info_2_safe_fixed_monotonic_time"/></p> <p><c>Item=safe_fixed|safe_fixed_monotonic_time, Value={FixationTime,Info}|false</c></p> - <p>If the table has been fixed using + <p>If the table is fixed using <seealso marker="#safe_fixtable/2"> <c>safe_fixtable/2</c></seealso>, the call returns a tuple where <c>FixationTime</c> is the - time when the table was first fixed by a process, which either - is or is not one of the processes it is fixed by now.</p> + last time when the table changed from unfixed to fixed.</p> <p>The format and value of <c>FixationTime</c> depends on <c>Item</c>:</p> <taglist> @@ -639,8 +678,15 @@ Error: fun containing local Erlang function calls table is fixed by now. <c>RefCount</c> is the value of the reference counter and it keeps track of how many times the table has been fixed by the process.</p> - <p>If the table never has been fixed, the call returns - <c>false</c>.</p> + <p>Table fixations are not limited to <seealso marker="#safe_fixtable/2"> + <c>safe_fixtable/2</c></seealso>. Temporary fixations may also + be done by for example <seealso marker="#traversal">traversing + functions</seealso> like <c>select</c> and <c>match</c>. Such + table fixations are automatically released before the + corresponding functions returns, but they may be seen by a + concurrent call to + <c>ets:info(T,safe_fixed|safe_fixed_monotonic_time)</c>.</p> + <p>If the table is not fixed at all, the call returns <c>false</c>.</p> </item> <item> <p><c>Item=stats, Value=tuple()</c></p> @@ -1998,9 +2044,8 @@ true</pre> <p>This function provides an efficient way to update one or more counters, without the trouble of having to look up an object, update the object by incrementing an element, and insert the resulting - object into the table again. (The update is done atomically, - that is, no process - can access the ETS table in the middle of the operation.)</p> + object into the table again. The operation is guaranteed to be + <seealso marker="#concurrency">atomic and isolated</seealso>.</p> <p>This function destructively update the object with key <c><anno>Key</anno></c> in table <c><anno>Tab</anno></c> by adding <c><anno>Incr</anno></c> to the element at position diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index ae42846c6b..60b7eb3436 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -546,7 +546,7 @@ true <p><em>Examples:</em></p> <pre> 20> <input>filename:rootname("/beam.src/kalle").</input> -/beam.src/kalle" +"/beam.src/kalle" 21> <input>filename:rootname("/beam.src/foo.erl").</input> "/beam.src/foo" 22> <input>filename:rootname("/beam.src/foo.erl", ".erl").</input> diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index d678d0436b..d4a4ba268b 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2016</year><year>2018</year> + <year>2016</year><year>2019</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -320,12 +320,13 @@ erlang:'!' -----> Module:StateName/3 </p> <p> There is also a server start option - <seealso marker="#type-hibernate_after_opt"> + <seealso marker="#type-enter_loop_opt"> <c>{hibernate_after, Timeout}</c> </seealso> for - <seealso marker="#start/3"><c>start/3,4</c></seealso> or - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso> + <seealso marker="#start/3"><c>start/3,4</c></seealso>, + <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso> or + <seealso marker="#enter_loop/4"><c>enter_loop/4,5,6</c></seealso>, that may be used to automatically hibernate the server. </p> </description> @@ -514,36 +515,6 @@ handle_event(_, _, State, Data) -> </desc> </datatype> <datatype> - <name name="debug_opt"/> - <desc> - <p> - Debug option that can be used when starting - a <c>gen_statem</c> server through, - <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>. - </p> - <p> - For every entry in <c><anno>Dbgs</anno></c>, - the corresponding function in - <seealso marker="sys"><c>sys</c></seealso> is called. - </p> - </desc> - </datatype> - <datatype> - <name name="hibernate_after_opt"/> - <desc> - <p> - hibernate_after option that can be used when starting - a <c>gen_statem</c> server through, - <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>. - </p> - <p>If option<seealso marker="#type-hibernate_after_opt"><c>{hibernate_after,HibernateAfterTimeout}</c></seealso> is present, the <c>gen_statem</c> - process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and - if no message is received, the process goes into hibernation automatically - (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>). - </p> - </desc> - </datatype> - <datatype> <name name="start_opt"/> <desc> <p> @@ -563,6 +534,37 @@ handle_event(_, _, State, Data) -> </desc> </datatype> <datatype> + <name name="enter_loop_opt"/> + <desc> + <p> + Options that can be used when starting + a <c>gen_statem</c> server through, + <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>. + </p> + <taglist> + <tag><c>hibernate_after</c></tag> + <item> + <p> + <c>HibernateAfterTimeout</c> + specifies that the <c>gen_statem</c> process awaits + any message for <c>HibernateAfterTimeout</c> milliseconds and + if no message is received, the process goes into hibernation + automatically (by calling + <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>). + </p> + </item> + <tag><c>debug</c></tag> + <item> + <p> + For every entry in <c><anno>Dbgs</anno></c>, + the corresponding function in + <seealso marker="sys"><c>sys</c></seealso> is called. + </p> + </item> + </taglist> + </desc> + </datatype> + <datatype> <name name="from"/> <desc> <p> @@ -1701,7 +1703,11 @@ handle_event(_, _, State, Data) -> <list type="bulleted"> <item> <p> - If option <c>{timeout,Time}</c> is present in + If option + <seealso marker="#type-start_opt"> + <c>{timeout,Time}</c> + </seealso> + is present in <c><anno>Opts</anno></c>, the <c>gen_statem</c> is allowed to spend <c>Time</c> milliseconds initializing or it terminates and the start function returns @@ -1709,23 +1715,33 @@ handle_event(_, _, State, Data) -> </p> </item> <item> - <p>If option<seealso marker="#type-hibernate_after_opt"><c>{hibernate_after,HibernateAfterTimeout}</c></seealso> is present, the <c>gen_statem</c> - process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and - if no message is received, the process goes into hibernation automatically - (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>). + <p>If option + <seealso marker="#type-enter_loop_opt"> + <c>{hibernate_after,HibernateAfterTimeout}</c> + </seealso> + is present, the <c>gen_statem</c> + process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and + if no message is received, the process goes into hibernation automatically + (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>). </p> </item> <item> <p> If option - <seealso marker="#type-debug_opt"><c>{debug,Dbgs}</c></seealso> + <seealso marker="#type-enter_loop_opt"> + <c>{debug,Dbgs}</c> + </seealso> is present in <c><anno>Opts</anno></c>, debugging through <seealso marker="sys"><c>sys</c></seealso> is activated. </p> </item> <item> <p> - If option <c>{spawn_opt,SpawnOpts}</c> is present in + If option + <seealso marker="#type-start_opt"> + <c>{spawn_opt,SpawnOpts}</c> + </seealso> + is present in <c><anno>Opts</anno></c>, <c>SpawnOpts</c> is passed as option list to <seealso marker="erts:erlang#spawn_opt/2"><c>erlang:spawn_opt/2</c></seealso>, diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index a682811c6d..23c3f6e981 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,6 +31,72 @@ </header> <p>This document describes the changes made to the STDLIB application.</p> +<section><title>STDLIB 3.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a bug in the Erlang Pretty Printer: long atom + names in combination with <c><<>></c> could + cause a crash. </p> + <p> + Own Id: OTP-15592 Aux Id: ERL-818 </p> + </item> + <item> + <p> Fix bugs that could cause wrong results or bad + performance when formatting lists of characters using the + control sequences <c>p</c> or <c>P</c> and limiting the + output with the option <c>chars_limit</c>. </p> + <p> + Own Id: OTP-15639</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improved ETS documentation about safe table traversal and + the partially bound key optimization for + <c>ordered_set</c>.</p> + <p> + Own Id: OTP-15545 Aux Id: PR-2103, PR-2139 </p> + </item> + <item> + <p> Optimize <c>calendar:gregorian_days_to_date/1</c>. + </p> + <p> + Own Id: OTP-15572 Aux Id: PR-2121 </p> + </item> + <item> + <p> Optimize functions + <c>calendar:rfc3339_to_system_time()</c> and + <c>calendar:system_time_to_rfc3339()</c>. </p> + <p> + Own Id: OTP-15630</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.7.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Optimize pretty printing of terms. The slower + behaviour was introduced in Erlang/OTP 20. </p> + <p> + Own Id: OTP-15573 Aux Id: ERIERL-306 </p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 3.7</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml index 9d7eb55a7e..4465103469 100644 --- a/lib/stdlib/doc/src/proplists.xml +++ b/lib/stdlib/doc/src/proplists.xml @@ -57,6 +57,11 @@ <datatype> <name name="property"/> </datatype> + + <datatype> + <name name="proplist"/> + </datatype> + </datatypes> <funcs> diff --git a/lib/stdlib/doc/src/slave.xml b/lib/stdlib/doc/src/slave.xml index 80fb28b548..778c5f66e5 100644 --- a/lib/stdlib/doc/src/slave.xml +++ b/lib/stdlib/doc/src/slave.xml @@ -39,23 +39,30 @@ done through the master.</p> <p>Slave nodes on other hosts than the current one are started with - the <c>rsh</c> program. The user must be allowed to <c>rsh</c> to + the <c>ssh</c> program. The user must be allowed to <c>ssh</c> to the remote hosts without being prompted for a password. This can - be arranged in a number of ways (for details, see the <c>rsh</c> + be arranged in a number of ways (for details, see the <c>ssh</c> documentation). A slave node started on the same host as the master inherits certain environment values from the master, such as the current directory and the environment variables. For what can be assumed about the environment when a slave is started - on another host, see the documentation for the <c>rsh</c> + on another host, see the documentation for the <c>ssh</c> program.</p> - <p>An alternative to the <c>rsh</c> program can be specified on + <p>An alternative to the <c>ssh</c> program can be specified on the command line to <seealso marker="erts:erl#erl"><c>erl(1)</c></seealso> as follows:</p> <pre> -rsh Program</pre> + <p>Note that the command specified with the <c>-rsh</c> flag is + treated as a file name which may contain spaces. It is thus not + possible to include any command line options. The remote node will + be launched as <c>"$RSH" "$REMOTE_HOSTNAME" erl -detached -noinput + ...</c>, so the + <c>erl</c> command must be found in the path on the remote host.</p> + <p>The slave node is to use the same file system at the master. At least, Erlang/OTP is to be installed in the same place on both computers and the same version of Erlang is to be used.</p> @@ -166,7 +173,9 @@ slave:start(H, Name, Arg).</code> </item> <tag><c>no_rsh</c></tag> <item> - <p>There is no <c>rsh</c> program on the computer.</p> + <p>No remote shell program was found on the computer. Note + that <c>ssh</c> is used by default, but this can be overridden + with the <c>-rsh</c> flag.</p> </item> <tag><c>{already_running, <anno>Node</anno>}</c></tag> <item> diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index c5075f31c5..e22ca89ef5 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2018</year> + <year>1996</year><year>2019</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -271,6 +271,9 @@ <name name="dbg_fun"/> </datatype> <datatype> + <name name="debug_option"/> + </datatype> + <datatype> <name name="format_fun"/> </datatype> </datatypes> |