From d840b24857a1d54419953661f70716c449c11864 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 3 Mar 2016 10:54:01 +0100 Subject: Fix most of the system docs and emacs mode --- lib/stdlib/doc/src/gen_statem.xml | 87 +++++++++++++++++++++++++++++---------- lib/stdlib/doc/src/proc_lib.xml | 8 ++-- lib/stdlib/doc/src/supervisor.xml | 10 +++-- lib/stdlib/doc/src/sys.xml | 31 +++++++++----- 4 files changed, 97 insertions(+), 39 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 01be3099c1..db6a4e03ea 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -407,7 +407,7 @@ ok

- After a state change (NewState =/= State) + After a state change (NextState =/= State) all postponed events are retried.

@@ -566,7 +566,7 @@ ok

If true postpone the current event and retry it when the state changes that is: - NewState =/= State. + NextState =/= State.

@@ -701,7 +701,47 @@ ok - + + + + next_state + + The gen_statem will do a state transition to + NextStateName + (which may be the same as the current state), + set NewData + and execute all Actions + + +

+ All these terms are tuples or atoms and this property + will hold in any future version of gen_statem, + just in case you need such a promise. +

+ + + + + + + next_state + + The gen_statem will do a state transition to + NextState + (which may be the same as the current state), + set NewData + and execute all Actions + + +

+ All these terms are tuples or atoms and this property + will hold in any future version of gen_statem, + just in case you need such a promise. +

+ + + + stop @@ -723,14 +763,6 @@ ok with Reason and NewData, if given. - next_state - - The gen_statem will do a state transition to - NewState - (which may be the same as the current state), - set NewData - and execute all Actions - keep_state The gen_statem will keep the current state, or @@ -1209,10 +1241,11 @@ ok - Module:StateName(EventType, EventContent, Data) -> Result + Module:StateName(EventType, EventContent, Data) -> + StateFunctionResult Module:handle_event(EventType, EventContent, - State, Data) -> Result + State, Data) -> HandleEventResult Handle an event @@ -1222,7 +1255,7 @@ ok EventContent = term() - State = NewState = + State = state() @@ -1230,9 +1263,15 @@ ok data() - Result = - - state_callback_result() + StateFunctionResult = + + state_function_result() + + + + HandleEventResult = + + handle_event_result() @@ -1260,9 +1299,15 @@ ok reply(Caller, Reply).

- If this function returns with a new state that + If this function returns with a next state that does not match equal (=/=) to the current state - all postponed events will be retried in the new state. + all postponed events will be retried in the next state. +

+

+ The only difference between StateFunctionResult and + HandleEventResult is that for StateFunctionResult + the next state has to be an atom but for HandleEventResult + there is no restriction on the next state.

See action() @@ -1272,7 +1317,7 @@ ok

These functions may use throw, - to return Result. + to return the result.

@@ -1401,7 +1446,7 @@ ok

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

If the function returns Reason, the ongoing diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index 85f0c0c908..245580b1ba 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -4,7 +4,7 @@

- 19962014 + 19962016 Ericsson AB. All Rights Reserved. @@ -34,9 +34,9 @@

This module is used to start processes adhering to the OTP Design Principles. Specifically, the functions in this module are used by the OTP standard behaviors (gen_server, - gen_fsm, ...) when starting new processes. The functions - can also be used to start special processes, user - defined processes which comply to the OTP design principles. See + gen_fsm, gen_statem, ...) when starting new processes. + The functions can also be used to start special processes, + user defined processes which comply to the OTP design principles. See Sys and Proc_Lib in OTP Design Principles for an example.

Some useful information is initialized when a process starts. The registered names, or the process identifiers, of the parent diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index 24ff251ce3..9d81fb0db7 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -4,7 +4,7 @@

- 19962014 + 19962016 Ericsson AB. All Rights Reserved. @@ -34,8 +34,8 @@

A behaviour module for implementing a supervisor, a process which supervises other processes called child processes. A child process can either be another supervisor or a worker process. - Worker processes are normally implemented using one of - the gen_event, gen_fsm, or gen_server + Worker processes are normally implemented using one of the + gen_event, gen_fsm, gen_statem or gen_server behaviours. A supervisor implemented using this module will have a standard set of interface functions and include functionality for tracing and error reporting. Supervisors are used to build a @@ -221,7 +221,8 @@

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, or gen_fsm, + supervisor, gen_server, + gen_fsm or gen_statem this should 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 @@ -633,6 +634,7 @@ 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 d400f72e1d..2255395f46 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. @@ -217,14 +217,18 @@ processes. For example, a gen_server process returns the callback module's state, a gen_fsm process returns information such as its current state name and state data, - and a gen_event process returns information about each of its + a gen_statem process returns information about + its current state and data, and a gen_event process + returns information about each of its registered handlers. Callback modules for gen_server, - gen_fsm, and gen_event can also customise the value + gen_fsm, gen_statem and gen_event + can also customise the value of Misc by exporting a format_status/2 function that contributes module-specific information; - see gen_server:format_status/2, - gen_fsm:format_status/2, and - gen_event:format_status/2 + see gen_server format_status/2, + gen_fsm format_status/2, + gen_statem format_status/2, and + gen_event format_status/2 for more details.

@@ -245,6 +249,8 @@ processes. For a gen_server process, the returned State is simply the callback module's state. For a gen_fsm process, State is the tuple {CurrentStateName, CurrentStateData}. + For a gen_statem process State is + the tuple {CurrentState,CurrentData}. For a gen_event process, State a list of tuples, where each tuple corresponds to an event handler registered in the process and contains {Module, Id, HandlerState}, where Module is the event handler's module name, @@ -263,8 +269,9 @@ details of the exception.

The system_get_state/1 function is primarily useful for user-defined behaviours and modules that implement OTP special - processes. The gen_server, gen_fsm, and gen_event OTP - behaviour modules export this function, and so callback modules for those behaviours + processes. The gen_server, gen_fsm, + gen_statem and gen_event OTP + behaviour modules export this function, so callback modules for those behaviours need not supply their own.

To obtain more information about a process, including its state, see get_status/1 and @@ -290,6 +297,8 @@ gen_fsm process, State is the tuple {CurrentStateName, CurrentStateData}, and NewState is a similar tuple that may contain a new state name, new state data, or both. + The same applies for a gen_statem process but + it names the tuple fields {CurrentState,CurrentData}. For a gen_event process, State is the tuple {Module, Id, HandlerState} where Module is the event handler's module name, Id is the handler's ID (which is the value false if it was registered without @@ -304,7 +313,8 @@ state, then regardless of process type, it may simply return its State argument.

If a StateFun function crashes or throws an exception, then - for gen_server and gen_fsm processes, the original state of the process is + for gen_server, gen_fsm or gen_statem processes, + the original state of the process is unchanged. For gen_event processes, a crashing or failing StateFun function means that only the state of the particular event handler it was working on when it failed or crashed is unchanged; it can still succeed in changing the states of other event @@ -329,7 +339,8 @@ {callback_failed, StateFun, {Class, Reason}}.

The system_replace_state/2 function is primarily useful for user-defined behaviours and modules that implement OTP special processes. The - gen_server, gen_fsm, and gen_event OTP behaviour modules export this function, + gen_server, gen_fsm, gen_statem and + gen_event OTP behaviour modules export this function, and so callback modules for those behaviours need not supply their own.

-- cgit v1.2.3