diff options
Diffstat (limited to 'lib/stdlib/doc')
| -rw-r--r-- | lib/stdlib/doc/src/ets.xml | 46 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 232 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/maps.xml | 34 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/notes.xml | 6 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/rand.xml | 110 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/sys.xml | 166 |
6 files changed, 446 insertions, 148 deletions
diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index b9ceaa1d69..d2ac6a75b1 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -188,6 +188,31 @@ 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 @@ -659,9 +684,8 @@ Error: fun containing local Erlang function calls </item> <item> <p><c>Item=stats, Value=tuple()</c></p> - <p>Returns internal statistics about <c>set</c>, <c>bag</c>, and - <c>duplicate_bag</c> tables on an internal format used by OTP - test suites. Not for production use.</p></item> + <p>Returns internal statistics about tables on an internal format + used by OTP test suites. Not for production use.</p></item> </list> </desc> </func> @@ -1190,11 +1214,17 @@ ets:select(Table, MatchSpec),</code> Functions that makes such promises over many objects (like <seealso marker="#insert/2"><c>insert/2</c></seealso>) gain less (or nothing) from this option.</p> - <p>Table type <c>ordered_set</c> is not affected by this option. - Also, the memory consumption inflicted by - both <c>write_concurrency</c> and <c>read_concurrency</c> is a - constant overhead per table. This overhead can be especially - large when both options are combined.</p> + <p>The memory consumption inflicted by both <c>write_concurrency</c> + and <c>read_concurrency</c> is a constant overhead per table for + <c>set</c>, <c>bag</c> and <c>duplicate_bag</c>. For + <c>ordered_set</c> the memory overhead depends on the number + of inserted objects and the amount of actual detected + concurrency in runtime. The memory overhead can be especially + large when both options are combined.</p> + <note> + <p>Prior to stdlib-3.7 (OTP-22.0) <c>write_concurrency</c> had no + effect on <c>ordered_set</c>.</p> + </note> <marker id="new_2_read_concurrency"></marker> </item> <tag><c>{read_concurrency,boolean()}</c></tag> diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index aaa26df18d..d678d0436b 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -167,7 +167,7 @@ erlang:'!' -----> Module:StateName/3 </p> <marker id="state callback"/> <p> - The "<em>state callback</em>" for a specific + The <em>state callback</em> for a specific <seealso marker="#type-state">state</seealso> in a <c>gen_statem</c> is the callback function that is called for all events in this state. It is selected depending on which @@ -179,7 +179,7 @@ erlang:'!' -----> Module:StateName/3 When the <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> is <c>state_functions</c>, the state must be an atom and - is used as the state callback name; see + is used as the <em>state callback</em> name; see <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso>. This co-locates all code for a specific state in one function as the <c>gen_statem</c> engine @@ -192,7 +192,7 @@ erlang:'!' -----> Module:StateName/3 When the <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> is <c>handle_event_function</c>, the state can be any term - and the state callback name is + and the <em>state callback</em> name is <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>. This makes it easy to branch depending on state or event as you desire. Be careful about which events you handle in which @@ -200,12 +200,36 @@ erlang:'!' -----> Module:StateName/3 forever creating an infinite busy loop. </p> <p> - The <c>gen_statem</c> enqueues incoming events in order of arrival - and presents these to the - <seealso marker="#state callback">state callback</seealso> - 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. + When <c>gen_statem</c> receives a process message it is + converted into an event and the + <seealso marker="#state callback"><em>state callback</em></seealso> + is called with the event as two arguments: type and content. + When the + <seealso marker="#state callback"><em>state callback</em></seealso> + has processed the event it returns to <c>gen_statem</c> + which does a <em>state transition</em>. + If this <em>state transition</em> is to a different state, + that is: <c>NextState =/= State</c>, it is a <em>state change</em>. + </p> + <p> + The + <seealso marker="#state callback"><em>state callback</em></seealso> + may return + <seealso marker="#type-action"><em>transition actions</em></seealso> + for <c>gen_statem</c> + to execute during the <em>state transition</em>, + for example to reply to a + <seealso marker="#call/2"><c>gen_statem:call/2,3</c></seealso>. + </p> + <p> + One of the possible <em>transition actions</em> + is to postpone the current event. + Then it is not retried in the current state. + The <c>gen_statem</c> engine keeps a queue of events + divided into the postponed events + and the events still to process. + After a <em>state change</em> the queue restarts + with the postponed events. </p> <p> The <c>gen_statem</c> event queue model is sufficient @@ -215,13 +239,17 @@ erlang:'!' -----> Module:StateName/3 to entering a new receive statement. </p> <p> - The <seealso marker="#state callback">state callback</seealso> + The + <seealso marker="#state callback"><em>state callback</em></seealso> can insert events using the - <seealso marker="#type-action"><c>action()</c></seealso> + <seealso marker="#type-action"><em>transition actions</em></seealso> <c>next_event</c> - and such an event is inserted as the next to present - to the state callback. That is, as if it is - the oldest incoming event. A dedicated + and such an event is inserted in the event queue + as the next to call the + <seealso marker="#state callback"><em>state callback</em></seealso> + with. + That is, as if it is the oldest incoming event. + A dedicated <seealso marker="#type-event_type"><c>event_type()</c></seealso> <c>internal</c> can be used for such events making them impossible to mistake for external events. @@ -236,24 +264,26 @@ erlang:'!' -----> Module:StateName/3 <p> The <c>gen_statem</c> engine can automatically make a specialized call to the - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> whenever a new state is entered; see <seealso marker="#type-state_enter"><c>state_enter()</c></seealso>. This is for writing code common to all state entries. - Another way to do it is to insert an event at the state transition, - and/or to use a dedicated state transition function, + Another way to do it is to explicitly insert an event + at the <em>state transition</em>, + and/or to use a dedicated <em>state transition</em> function, but that is something you will have to remember - at every state transition to the state(s) that need it. + at every <em>state transition</em> to the state(s) that need it. </p> <note> <p>If you in <c>gen_statem</c>, for example, postpone - 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. + an event in one state and then call another <em>state callback</em> + of yours, you have not done a <em>state change</em> + and hence the postponed event is not retried, + which is logical but can be confusing. </p> </note> <p> - For the details of a state transition, see type + For the details of a <em>state transition</em>, see type <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>. </p> <p> @@ -276,7 +306,8 @@ erlang:'!' -----> Module:StateName/3 The <c>gen_statem</c> process can go into hibernation; see <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>. It is done when a - <seealso marker="#state callback">state callback</seealso> or + <seealso marker="#state callback"><em>state callback</em></seealso> + or <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> specifies <c>hibernate</c> in the returned <seealso marker="#type-action"><c>Actions</c></seealso> @@ -551,7 +582,7 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> is <c>handle_event_function</c>, the state can be any term. - After a state change (<c>NextState =/= State</c>), + After a <em>state change</em> (<c>NextState =/= State</c>), all postponed events are retried. </p> </desc> @@ -564,7 +595,7 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> is <c>state_functions</c>, the state must be of this type. - After a state change (<c>NextState =/= State</c>), + After a <em>state change</em> (<c>NextState =/= State</c>), all postponed events are retried. </p> </desc> @@ -595,7 +626,7 @@ handle_event(_, _, State, Data) -> </p> <p> <c>internal</c> events can only be generated by the - state machine itself through the state transition action + state machine itself through the <em>transition action</em> <seealso marker="#type-action"><c>next_event</c></seealso>. </p> </desc> @@ -633,9 +664,9 @@ handle_event(_, _, State, Data) -> This is the return type from <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> and selects - <seealso marker="#type-callback_mode">callback mode</seealso> + <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> and whether to do - <seealso marker="#type-state_enter">state enter calls</seealso>, + <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>, or not. </p> </desc> @@ -684,13 +715,15 @@ handle_event(_, _, State, Data) -> If <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> returns a list containing <c>state_enter</c>, - the <c>gen_statem</c> engine will, at every state change, + the <c>gen_statem</c> engine will, at every <em>state change</em>, call the <seealso marker="#state callback">state callback</seealso> with arguments <c>(enter, OldState, Data)</c>. This may look like an event but is really a call - performed after the previous state callback returned - and before any event is delivered to the new state callback. + performed after the previous + <seealso marker="#state callback"><em>state callback</em></seealso> + returned and before any event is delivered to the new + <seealso marker="#state callback"><em>state callback</em></seealso>. See <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso> and @@ -703,27 +736,27 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-state_callback_result"> <c>repeat_state_and_data</c> </seealso> - tuple from the state callback. + tuple from the <em>state callback</em>. </p> <p> If <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> - does not return such a list, no state enter calls are done. + does not return such a list, no <em>state enter calls</em> are done. </p> <p> If <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso> should transform the state, - it is regarded as a state rename and not a state change, - which will not cause a state enter call. + it is regarded as a state rename and not a <em>state change</em>, + which will not cause a <em>state enter call</em>. </p> <p> - Note that a state enter call <em>will</em> be done + Note that a <em>state enter call</em> <em>will</em> be done right before entering the initial state even though this - formally is not a state change. - In this case <c>OldState</c> will be the same as <c>State</c>, + actually is not a <em>state change</em>. + In this case <c>OldState =:= State</c>, which can not happen for a subsequent state change, - but will happen when repeating the state enter call. + but will happen when repeating the <em>state enter call</em>. </p> </desc> </datatype> @@ -733,8 +766,11 @@ handle_event(_, _, State, Data) -> <p> Transition options can be set by <seealso marker="#type-action">actions</seealso> - and modify the state transition. - Here are the sequence of steps for a state transition: + and modify the <em>state transition</em>. + The <em>state transition</em> takes place when the + <seealso marker="#state callback"><em>state callback</em></seealso> + has processed an event and returns. + Here are the sequence of steps for a <em>state transition</em>: </p> <list type="ordered"> <item> @@ -765,7 +801,7 @@ handle_event(_, _, State, Data) -> returned by the state callback that caused the state entry. </p> <p> - Should this state enter call return any of + Should this <em>state enter call</em> return any of the mentioned <c>repeat_*</c> callback results it is repeated again, with the updated <c>Data</c>. </p> @@ -787,7 +823,8 @@ handle_event(_, _, State, Data) -> </item> <item> <p> - If the state changes, the queue of incoming events + If this is a <em>state change</em>, + the queue of incoming events is reset to start with the oldest postponed. </p> </item> @@ -821,7 +858,7 @@ handle_event(_, _, State, Data) -> if the event queue is empty. </p> <p> - A state change cancels a + A <em>state change</em> cancels a <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> and any new transition option of this type belongs to the new state. @@ -830,7 +867,7 @@ handle_event(_, _, State, Data) -> <item> <p> If there are enqueued events the - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> for the possibly new state is called with the oldest enqueued event, and we start again from the top of this list. @@ -848,7 +885,7 @@ handle_event(_, _, State, Data) -> the next incoming message awakens the <c>gen_statem</c>, but if it is a system event it goes right back into hibernation. When a new message arrives the - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> is called with the corresponding event, and we start again from the top of this sequence. </p> @@ -861,7 +898,7 @@ handle_event(_, _, State, Data) -> <desc> <p> If <c>true</c>, postpones the current event and retries - it when the state changes + it after a <em>state change</em> (<c>NextState =/= State</c>). </p> </desc> @@ -1021,9 +1058,9 @@ handle_event(_, _, State, Data) -> <name name="action"/> <desc> <p> - These state transition actions can be invoked by + These <em>transition actions</em> can be invoked by returning them from the - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> when it is called with an <seealso marker="#type-event_type">event</seealso>, from @@ -1054,7 +1091,7 @@ handle_event(_, _, State, Data) -> <c>transition_option()</c> </seealso> <seealso marker="#type-postpone"><c>postpone()</c></seealso> - for this state transition. + for this <em>state transition</em>. This action is ignored when returned from <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> or given to @@ -1093,9 +1130,9 @@ handle_event(_, _, State, Data) -> <name name="enter_action"/> <desc> <p> - These state transition actions can be invoked by + These <em>transition actions</em> can be invoked by returning them from the - <seealso marker="#state callback">state callback</seealso>, from + <seealso marker="#state callback"><em>state callback</em></seealso>, from <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> or by giving them to <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. @@ -1119,7 +1156,7 @@ handle_event(_, _, State, Data) -> Sets the <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> <seealso marker="#type-hibernate"><c>hibernate()</c></seealso> - for this state transition. + for this <em>state transition</em>. </p> </item> </taglist> @@ -1129,9 +1166,9 @@ handle_event(_, _, State, Data) -> <name name="timeout_action"/> <desc> <p> - These state transition actions can be invoked by + These <em>transition actions</em> can be invoked by returning them from the - <seealso marker="#state callback">state callback</seealso>, from + <seealso marker="#state callback"><em>state callback</em></seealso>, from <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> or by giving them to <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. @@ -1147,7 +1184,7 @@ handle_event(_, _, State, Data) -> Short for <c>{timeout,Time,Time}</c>, that is, the time-out message is the time-out time. This form exists to make the - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> return value <c>{next_state,NextState,NewData,Time}</c> allowed like for <c>gen_fsm</c>. </p> @@ -1193,9 +1230,9 @@ handle_event(_, _, State, Data) -> <name name="reply_action"/> <desc> <p> - This state transition action can be invoked by + This <em>transition action</em> can be invoked by returning it from the - <seealso marker="#state callback">state callback</seealso>, from + <seealso marker="#state callback"><em>state callback</em></seealso>, from <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> or by giving it to <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. @@ -1210,7 +1247,7 @@ handle_event(_, _, State, Data) -> <c><anno>From</anno></c> must be the term from argument <seealso marker="#type-event_type"><c>{call,<anno>From</anno>}</c></seealso> in a call to a - <seealso marker="#state callback">state callback</seealso>. + <seealso marker="#state callback"><em>state callback</em></seealso>. </p> <p> Note that using this action from @@ -1219,7 +1256,7 @@ handle_event(_, _, State, Data) -> <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso> would be weird on the border of witchcraft since there has been no earlier call to a - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> in this server. </p> </desc> @@ -1239,7 +1276,7 @@ handle_event(_, _, State, Data) -> The <seealso marker="#type-action"><c>Actions</c></seealso> are executed when entering the first <seealso marker="#type-state">state</seealso> just as for a - <seealso marker="#state callback">state callback</seealso>, + <seealso marker="#state callback"><em>state callback</em></seealso>, except that the action <c>postpone</c> is forced to <c>false</c> since there is no event to postpone. </p> @@ -1256,7 +1293,7 @@ handle_event(_, _, State, Data) -> <desc> <p> <c><anno>State</anno></c> is the current state - and it can not be changed since the state callback + and it cannot be changed since the state callback was called with a <seealso marker="#type-state_enter"><em>state enter call</em></seealso>. </p> @@ -1292,11 +1329,13 @@ handle_event(_, _, State, Data) -> <tag><c>next_state</c></tag> <item> <p> - The <c>gen_statem</c> does a state transition to + The <c>gen_statem</c> does a <em>state transition</em> to <c><anno>NextState</anno></c> (which can be the same as the current state), sets <c><anno>NewData</anno></c>, and executes all <c><anno>Actions</anno></c>. + If <c><anno>NextState</anno> =/= CurrentState</c> + the <em>state transition</em> is a <em>state change</em>. </p> </item> </taglist> @@ -1318,54 +1357,33 @@ handle_event(_, _, State, Data) -> <tag><c>keep_state</c></tag> <item> <p> - The <c>gen_statem</c> keeps the current state, or - does a state transition to the current state if you like, - sets <c><anno>NewData</anno></c>, - and executes all <c><anno>Actions</anno></c>. - This is the same as + The same as <c>{next_state,CurrentState,<anno>NewData</anno>,<anno>Actions</anno>}</c>. </p> </item> <tag><c>keep_state_and_data</c></tag> <item> <p> - The <c>gen_statem</c> keeps the current state or - does a state transition to the current state if you like, - keeps the current server data, - and executes all <c><anno>Actions</anno></c>. - This is the same as - <c>{next_state,CurrentState,CurrentData,<anno>Actions</anno>}</c>. + The same as + <c>{keep_state,CurrentData,<anno>Actions</anno>}</c>. </p> </item> <tag><c>repeat_state</c></tag> <item> <p> - The <c>gen_statem</c> keeps the current state, or - does a state transition to the current state if you like, - sets <c><anno>NewData</anno></c>, - and executes all <c><anno>Actions</anno></c>. If the <c>gen_statem</c> runs with <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>, - the state enter call is repeated, see type + the <em>state enter call</em> is repeated, see type <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>, - otherwise <c>repeat_state</c> is the same as + other than that <c>repeat_state</c> is the same as <c>keep_state</c>. </p> </item> <tag><c>repeat_state_and_data</c></tag> <item> <p> - The <c>gen_statem</c> keeps the current state and data, or - does a state transition to the current state if you like, - and executes all <c><anno>Actions</anno></c>. - This is the same as + The same as <c>{repeat_state,CurrentData,<anno>Actions</anno>}</c>. - If the <c>gen_statem</c> runs with - <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>, - the state enter call is repeated, see type - <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>, - otherwise <c>repeat_state_and_data</c> is the same as - <c>keep_state_and_data</c>. </p> </item> <tag><c>stop</c></tag> @@ -1408,14 +1426,15 @@ handle_event(_, _, State, Data) -> by sending a request and waiting until its reply arrives. The <c>gen_statem</c> calls the - <seealso marker="#state callback">state callback</seealso> with + <seealso marker="#state callback"><em>state callback</em></seealso> + with <seealso marker="#type-event_type"><c>event_type()</c></seealso> <c>{call,From}</c> and event content <c><anno>Request</anno></c>. </p> <p> A <c><anno>Reply</anno></c> is generated when a - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> returns with <c>{reply,From,<anno>Reply</anno>}</c> as one <seealso marker="#type-action"><c>action()</c></seealso>, @@ -1484,7 +1503,8 @@ handle_event(_, _, State, Data) -> ignoring if the destination node or <c>gen_statem</c> does not exist. The <c>gen_statem</c> calls the - <seealso marker="#state callback">state callback</seealso> with + <seealso marker="#state callback"><em>state callback</em></seealso> + with <seealso marker="#type-event_type"><c>event_type()</c></seealso> <c>cast</c> and event content <c><anno>Msg</anno></c>. @@ -1598,18 +1618,18 @@ handle_event(_, _, State, Data) -> <seealso marker="#call/2"><c>call/2</c></seealso> when the reply cannot be defined in the return value of a - <seealso marker="#state callback">state callback</seealso>. + <seealso marker="#state callback"><em>state callback</em></seealso>. </p> <p> <c><anno>From</anno></c> must be the term from argument <seealso marker="#type-event_type"><c>{call,<anno>From</anno>}</c></seealso> to the - <seealso marker="#state callback">state callback</seealso>. + <seealso marker="#state callback"><em>state callback</em></seealso>. A reply or multiple replies canalso be sent using one or several <seealso marker="#type-reply_action"><c>reply_action()</c></seealso>s from a - <seealso marker="#state callback">state callback</seealso>. + <seealso marker="#state callback"><em>state callback</em></seealso>. </p> <note> <p> @@ -1826,7 +1846,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 - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> in the current code version is called. More occasions may be added in future versions of <c>gen_statem</c>. @@ -1883,7 +1903,7 @@ handle_event(_, _, State, Data) -> <p> This callback is optional, so callback modules need not export it. If a release upgrade/downgrade with - <c>Change={advanced,Extra}</c> + <c>Change = {advanced,Extra}</c> specified in the <c>.appup</c> file is made when <c>code_change/4</c> is not implemented the process will crash with exit reason <c>undef</c>. @@ -1893,7 +1913,7 @@ handle_event(_, _, State, Data) -> This function is called by a <c>gen_statem</c> when it is to update its internal state during a release upgrade/downgrade, that is, when the instruction <c>{update,Module,Change,...}</c>, - where <c>Change={advanced,Extra}</c>, is specified in the + where <c>Change = {advanced,Extra}</c>, is specified in the <seealso marker="sasl:appup"><c>appup</c></seealso> file. For more information, see <seealso marker="doc/design_principles:release_handling#instr">OTP Design Principles</seealso>. @@ -1922,7 +1942,7 @@ handle_event(_, _, State, Data) -> <p> If the function returns a failure <c>Reason</c>, the ongoing upgrade fails and rolls back to the old release. - Note that <c>Reason</c> can not be an <c>{ok,_,_}</c> tuple + Note that <c>Reason</c> cannot be an <c>{ok,_,_}</c> tuple since that will be regarded as a <c>{ok,NewState,NewData}</c> tuple, and that a tuple matching <c>{ok,_}</c> @@ -1933,13 +1953,13 @@ handle_event(_, _, State, Data) -> <p> Also note when upgrading a <c>gen_statem</c>, this function and hence - the <c>Change={advanced,Extra}</c> parameter in the + the <c>Change = {advanced,Extra}</c> parameter in the <seealso marker="sasl:appup"><c>appup</c></seealso> file is not only needed to update the internal state or to act on the <c>Extra</c> argument. It is also needed if an upgrade or downgrade should change <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>, - or else the callback mode after the code change + or else the <em>callback mode</em> after the code change will not be honoured, most probably causing a server crash. </p> @@ -2148,7 +2168,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <seealso marker="#type-event_type"><c>{call,From}</c></seealso>, the caller waits for a reply. The reply can be sent from this or from any other - <seealso marker="#state callback">state callback</seealso> + <seealso marker="#state callback"><em>state callback</em></seealso> by returning with <c>{reply,From,Reply}</c> in <seealso marker="#type-action"><c>Actions</c></seealso>, in <seealso marker="#type-reply_action"><c>Replies</c></seealso>, @@ -2173,9 +2193,9 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> </p> <p> When the <c>gen_statem</c> runs with - <seealso marker="#type-state_enter">state enter calls</seealso>, + <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>, these functions are also called with arguments - <c>(enter, OldState, ...)</c> whenever the state changes. + <c>(enter, OldState, ...)</c> during every <em>state change</em>. In this case there are some restrictions on the <seealso marker="#type-enter_action">actions</seealso> that may be returned: @@ -2208,7 +2228,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso> to return the result, which can be useful. For example to bail out with <c>throw(keep_state_and_data)</c> - from deep within complex code that can not + from deep within complex code that cannot return <c>{next_state,State,Data}</c> because <c>State</c> or <c>Data</c> is no longer in scope. </p> diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml index e2a62cb397..8e88882b56 100644 --- a/lib/stdlib/doc/src/maps.xml +++ b/lib/stdlib/doc/src/maps.xml @@ -35,9 +35,10 @@ <datatypes> <datatype> - <name name="iterator"/> + <name name="iterator" n_vars="2"/> <desc> - <p>An iterator representing the key value associations in a map.</p> + <p>An iterator representing the associations in a map with keys of type + <c><anno>Key</anno></c> and values of type <c><anno>Value</anno></c>.</p> <p>Created using <seealso marker="#iterator-1"><c>maps:iterator/1</c></seealso>.</p> <p>Consumed by <seealso marker="#next-1"><c>maps:next/1</c></seealso>, <seealso marker="#filter-2"><c>maps:filter/2</c></seealso>, @@ -45,6 +46,10 @@ <seealso marker="#map-2"><c>maps:map/2</c></seealso>.</p> </desc> </datatype> + + <datatype> + <name name="iterator" n_vars="0"/> + </datatype> </datatypes> <funcs> @@ -90,13 +95,13 @@ <name name="fold" arity="3" since="OTP 17.0"/> <fsummary></fsummary> <desc> - <p>Calls <c>F(K, V, AccIn)</c> for every <c><anno>K</anno></c> to value - <c><anno>V</anno></c> association in <c><anno>MapOrIter</anno></c> in - any order. Function <c>fun F/3</c> must return a new - accumulator, which is passed to the next successive call. - This function returns the final value of the accumulator. The initial - accumulator value <c><anno>Init</anno></c> is returned if the map is - empty.</p> + <p>Calls <c>F(Key, Value, AccIn)</c> for every <c><anno>Key</anno></c> + to value <c><anno>Value</anno></c> association in + <c><anno>MapOrIter</anno></c> in any order. Function <c>fun F/3</c> + must return a new accumulator, which is passed to the next successive + call. This function returns the final value of the accumulator. + The initial accumulator value <c><anno>Init</anno></c> is returned + if the map is empty.</p> <p>The call fails with a <c>{badmap,Map}</c> exception if <c><anno>MapOrIter</anno></c> is not a map or valid iterator, or with <c>badarg</c> if <c><anno>Fun</anno></c> is not a @@ -234,11 +239,12 @@ none</code> <fsummary></fsummary> <desc> <p>Produces a new map <c><anno>Map</anno></c> by calling function - <c>fun F(K, V1)</c> for every <c><anno>K</anno></c> to value - <c><anno>V1</anno></c> association in <c><anno>MapOrIter</anno></c> in - any order. Function <c>fun F/2</c> must return value - <c><anno>V2</anno></c> to be associated with key <c><anno>K</anno></c> - for the new map <c><anno>Map</anno></c>.</p> + <c>fun F(Key, Value1)</c> for every <c><anno>Key</anno></c> to value + <c><anno>Value1</anno></c> association in + <c><anno>MapOrIter</anno></c> in any order. Function <c>fun Fun/2</c> + must return value <c><anno>Value2</anno></c> to be associated with + key <c><anno>Key</anno></c> for the new map + <c><anno>Map</anno></c>.</p> <p>The call fails with a <c>{badmap,Map}</c> exception if <c><anno>MapOrIter</anno></c> is not a map or valid iterator, or with <c>badarg</c> if <c><anno>Fun</anno></c> is not a diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 993945b9c7..dee7136eb1 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -3818,7 +3818,7 @@ you use erlang:halt/2 with an integer first argument and an option list containing {flush,false} as the second argument. Note that now is flushing not dependant of the - exit code, and you can not only flush async threads + exit code, and you cannot only flush async threads operations which we deemed as a strange behaviour anyway. </p> <p>Also, erlang:halt/1,2 has gotten a new feature: If the @@ -4332,9 +4332,9 @@ Supervisors should not save child-specs for temporary processes when they terminate as they should not be restarted. Saving the temporary child spec will result in - that you can not start a new temporary process with the + that you cannot start a new temporary process with the same child spec as an already terminated temporary - process. Since R14B02 you can not restart a temporary + process. Since R14B02 you cannot restart a temporary temporary process as arguments are no longer saved, it has however always been semantically incorrect to restart a temporary process. Thanks to Filipe David Manana for diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 27d2d99f3c..b4737b48f8 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -38,25 +38,71 @@ <p> This module provides a pseudo random number generator. The module contains a number of algorithms. - The uniform distribution algorithms use the + The uniform distribution algorithms are based on the <url href="http://xorshift.di.unimi.it"> - xoroshiro116+ and xorshift1024* algorithms by Sebastiano Vigna. + Xoroshiro and Xorshift algorithms </url> + by Sebastiano Vigna. The normal distribution algorithm uses the <url href="http://www.jstatsoft.org/v05/i08"> Ziggurat Method by Marsaglia and Tsang </url> on top of the uniform distribution algorithm. </p> - <p>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. </p> + <p> + For most 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. + </p> <p>The following algorithms are provided:</p> <taglist> + <tag><c>exsss</c></tag> + <item> + <p>Xorshift116**, 58 bits precision and period of 2^116-1</p> + <p>Jump function: equivalent to 2^64 calls</p> + <p> + This is the Xorshift116 generator combined with the StarStar scrambler + from the 2018 paper by David Blackman and Sebastiano Vigna: + <url href="http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf"> + Scrambled Linear Pseudorandom Number Generators + </url> + </p> + <p> + The generator does not need 58-bit rotates so it is faster + than the Xoroshiro116 generator, and when combined with + the StarStar scrambler it does not have any weak low bits + like <c>exrop</c> (Xoroshiro116+). + </p> + <p> + Alas, this combination is about 10% slower than <c>exrop</c>, + but is despite that the default algorithm thanks to its + statistical qualities. + </p> + </item> + <tag><c>exro928ss</c></tag> + <item> + <p>Xoroshiro928**, 58 bits precision and a period of 2^928-1</p> + <p>Jump function: equivalent to 2^512 calls</p> + <p> + This is a 58 bit version of Xoroshiro1024**, + from the 2018 paper by David Blackman and Sebastiano Vigna: + <url href="http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf"> + Scrambled Linear Pseudorandom Number Generators + </url> + that on a 64 bit Erlang system executes only about 40% slower than + the default <c>exsss</c> algorithm but with much longer period + and better statistical properties, and on the flip side + a larger state. + </p> + <p> + Many thanks to Sebastiano Vigna for his help with + the 58 bit adaption. + </p> + </item> <tag><c>exrop</c></tag> <item> <p>Xoroshiro116+, 58 bits precision and period of 2^116-1</p> @@ -83,7 +129,7 @@ </taglist> <p> - The default algorithm is <c>exrop</c> (Xoroshiro116+). + The default algorithm is <c>exsss</c> (Xorshift116**). If a specific algorithm is required, ensure to always use <seealso marker="#seed-1"> <c>seed/1</c></seealso> to initialize the state. @@ -154,19 +200,19 @@ R1 = rand:uniform(),</pre> <p>Use a specified algorithm:</p> <pre> -_ = rand:seed(exs1024s), +_ = rand:seed(exs928ss), R2 = rand:uniform(),</pre> <p>Use a specified algorithm with a constant seed:</p> <pre> -_ = rand:seed(exs1024s, {123, 123534, 345345}), +_ = rand:seed(exs928ss, {123, 123534, 345345}), R3 = rand:uniform(),</pre> <p>Use the functional API with a non-constant seed:</p> <pre> -S0 = rand:seed_s(exrop), +S0 = rand:seed_s(exsss), {R4, S1} = rand:uniform_s(S0),</pre> <p>Textbook basic form Box-Muller standard normal deviate</p> @@ -195,8 +241,9 @@ SND0 = math:sqrt(-2 * math:log(R5)) * math:cos(math:pi() * R6)</pre> </note> <p> - For all these generators the lowest bit(s) has got - a slightly less random behaviour than all other bits. + For all these generators except <c>exro928ss</c> and <c>exsss</c> + the lowest bit(s) has got a slightly less + random behaviour than all other bits. 1 bit for <c>exrop</c> (and <c>exsp</c>), and 3 bits for <c>exs1024s</c>. See for example the explanation in the @@ -211,7 +258,7 @@ 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.</pre> <p> - If this is a problem; to generate a boolean + If this is a problem; to generate a boolean with these algorithms use something like this: </p> <pre>(rand:uniform(16) > 8)</pre> @@ -254,21 +301,50 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </desc> </datatype> <datatype> - <name name="exs64_state"/> - <desc><p>Algorithm specific internal state</p></desc> + <name name="seed"/> + <desc> + <p> + A seed value for the generator. + </p> + <p> + A list of integers sets the generator's internal state directly, + after algorithm-dependent checks of the value + and masking to the proper word size. + </p> + <p> + An integer is used as the initial state for a SplitMix64 generator. + The output values of that is then used for setting + the generator's internal state + after masking to the proper word size + and if needed avoiding zero values. + </p> + <p> + A traditional 3-tuple of integers seed is passed through + algorithm-dependent hashing functions to create + the generator's initial state. + </p> + </desc> </datatype> <datatype> <name name="exsplus_state"/> <desc><p>Algorithm specific internal state</p></desc> </datatype> <datatype> - <name name="exs1024_state"/> + <name name="exro928_state"/> <desc><p>Algorithm specific internal state</p></desc> </datatype> <datatype> <name name="exrop_state"/> <desc><p>Algorithm specific internal state</p></desc> </datatype> + <datatype> + <name name="exs1024_state"/> + <desc><p>Algorithm specific internal state</p></desc> + </datatype> + <datatype> + <name name="exs64_state"/> + <desc><p>Algorithm specific internal state</p></desc> + </datatype> </datatypes> <funcs> diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 6fc508b853..c5075f31c5 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -114,6 +114,154 @@ </datatype> <datatype> <name name="system_event"/> + <desc> + <taglist> + <tag><c>{in,<anno>Msg</anno>}</c></tag> + <item> + <p> + Is produced by <c>gen_server</c> and <c>gen_event</c> + when the message <c>Msg</c> arrives. + </p> + </item> + <tag><c>{in,<anno>Msg</anno>,<anno>State</anno>}</c></tag> + <item> + <p> + Is produced by <c>gen_statem</c> + when the message <c>Msg</c> arrives in state <c>State</c>. + </p> + <p> + For <c>gen_statem</c> the <c><anno>Msg</anno></c> term is + an <c>{EventType,EventContent}</c> tuple. + </p> + </item> + <tag><c>{out,<anno>Msg</anno>,<anno>To</anno>}</c></tag> + <item> + <p> + Is produced by <c>gen_statem</c> when the reply <c>Msg</c> + is sent back to <c>To</c> by returning + a <c>{reply,To,Msg}</c> action from the callback module. + </p> + <p> + <c><anno>To</anno></c> is of the same type + as the first argument to <c>gen_statem:reply/2</c>. + </p> + </item> + <tag> + <c>{out,<anno>Msg</anno>,<anno>To</anno>,<anno>State</anno>}</c> + </tag> + <item> + <p> + Is produced by <c>gen_server</c> + when the reply <c><anno>Msg</anno></c> + is sent back to <c><anno>To</anno></c> + by returning a <c>{reply,...}</c> tuple + from the callback module. + </p> + <p> + <c><anno>To</anno></c> is of the same type + as the first argument to <c>gen_server:reply/2</c>. + </p> + <p> + <c><anno>State</anno></c> is the new server state. + </p> + </item> + <tag> + <c>{noreply,<anno>State</anno>}</c> + </tag> + <item> + <p> + Is produced by <c>gen_server</c> + when a <c>{noreply,...}</c> tuple is returned + from the callback module. + </p> + <p> + <c><anno>State</anno></c> is the new server state. + </p> + </item> + <tag> + <c>{continue,<anno>Continuation</anno>}</c> + </tag> + <item> + <p> + Is produced by <c>gen_server</c> + when a <c>{continue,<anno>Continuation</anno>}</c> + tuple is returned from the callback module. + </p> + </item> + <tag> + <c>{code_change,<anno>Event</anno>,<anno>State</anno>}</c> + </tag> + <item> + <p> + Is produced by <c>gen_statem</c> + when the message <c><anno>Event</anno></c> + arrives in state <c><anno>State</anno></c> + as the first event after a code change. + </p> + <p> + <c><anno>Event</anno></c> is + an <c>{EventType,EventContent}</c> tuple. + </p> + </item> + <tag> + <c> + {postpone,<anno>Event</anno>,<anno>State</anno>,<anno>NextState</anno>} + </c> + </tag> + <item> + <p> + Is produced by <c>gen_statem</c> + when the message <c><anno>Event</anno></c> + is postponed in state <c><anno>State</anno></c>. + <c><anno>NextState</anno></c> is the new state. + </p> + <p> + <c><anno>Event</anno></c> is + an <c>{EventType,EventContent}</c> tuple. + </p> + </item> + <tag> + <c> + {consume,<anno>Event</anno>,<anno>State</anno>,<anno>NextState</anno>} + </c> + </tag> + <item> + <p> + Is produced by <c>gen_statem</c> + when the message <c><anno>Event</anno></c> + is consumed in state <c><anno>State</anno></c>. + <c><anno>NextState</anno></c> is the new state. + </p> + <p> + <c><anno>Event</anno></c> is + an <c>{EventType,EventContent}</c> tuple. + </p> + </item> + <tag> + <c> + {enter,<anno>State</anno>} + </c> + </tag> + <item> + <p> + Is produced by <c>gen_statem</c> + when the first state <c><anno>State</anno></c> is entered. + </p> + </item> + <tag> + <c> + {terminate,<anno>Reason</anno>,<anno>State</anno>} + </c> + </tag> + <item> + <p> + Is produced by <c>gen_statem</c> + when it terminates with reason <c><anno>Reason</anno></c> + in state <c><anno>State</anno></c>. + </p> + </item> + </taglist> + </desc> </datatype> <datatype> <name name="dbg_opt"/> @@ -532,6 +680,12 @@ <name name="get_debug" arity="3" since=""/> <fsummary>Get the data associated with a debug option.</fsummary> <desc> + <warning> + <p> + <c>get_debug/3</c> is deprecated since it returns + data of an internal type only useful for debugging. + </p> + </warning> <p>Gets the data associated with a debug option. <c><anno>Default</anno></c> is returned if <c><anno>Item</anno></c> is not found. Can be @@ -605,6 +759,18 @@ </func> <func> + <name name="get_log" arity="1" since="OTP-22.0"/> + <fsummary>Return the logged events in the debug structure.</fsummary> + <desc> + <p> + Returns the logged system events in the debug structure, + that is the last argument to + <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>. + </p> + </desc> + </func> + + <func> <name since="">Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}</name> <fsummary>Called when the process is to perform a code change.</fsummary> |