diff options
| -rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 77 | ||||
| -rw-r--r-- | lib/stdlib/src/gen_statem.erl | 38 | ||||
| -rw-r--r-- | system/doc/design_principles/statem.xml | 17 |
3 files changed, 101 insertions, 31 deletions
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: <c>hibernate</c> and <c>timeout</c> overrides the current and <c>reply</c> 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. </p> </item> <item> @@ -1002,28 +1005,42 @@ handle_event(_, _, State, Data) -> </desc> </datatype> <datatype> - <name name="common_state_callback_result"/> + <name name="keep_state_callback_result"/> <desc> <taglist> - <tag><c>stop</c></tag> + <tag><c>keep_state</c></tag> <item> <p> - Terminates the <c>gen_statem</c> by calling - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> - with <c>Reason</c> and - <c><anno>NewData</anno></c>, if specified. + 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 + <c>{next_state,CurrentState,<anno>NewData</anno>,<anno>Actions</anno>}</c>. </p> </item> - <tag><c>stop_and_reply</c></tag> + <tag><c>keep_state_and_data</c></tag> <item> <p> - Sends all <c><anno>Replies</anno></c>, - then terminates the <c>gen_statem</c> by calling - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> - with <c>Reason</c> and - <c><anno>NewData</anno></c>, if specified. + 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>. </p> </item> + </taglist> + <p> + All these terms are tuples or atoms and this property + will hold in any future version of <c>gen_statem</c>. + </p> + </desc> + </datatype> + <datatype> + <name name="keep_state_callback_enter_result"/> + <desc> + <taglist> <tag><c>keep_state</c></tag> <item> <p> @@ -1053,6 +1070,36 @@ handle_event(_, _, State, Data) -> </p> </desc> </datatype> + <datatype> + <name name="common_state_callback_result"/> + <desc> + <taglist> + <tag><c>stop</c></tag> + <item> + <p> + Terminates the <c>gen_statem</c> by calling + <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> + with <c>Reason</c> and + <c><anno>NewData</anno></c>, if specified. + </p> + </item> + <tag><c>stop_and_reply</c></tag> + <item> + <p> + Sends all <c><anno>Replies</anno></c>, + then terminates the <c>gen_statem</c> by calling + <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> + with <c>Reason</c> and + <c><anno>NewData</anno></c>, if specified. + </p> + </item> + </taglist> + <p> + All these terms are tuples or atoms and this property + will hold in any future version of <c>gen_statem</c>. + </p> + </desc> + </datatype> </datatypes> <funcs> @@ -1462,7 +1509,7 @@ handle_event(_, _, State, Data) -> CallbackMode = <seealso marker="#type-callback_mode">callback_mode()</seealso> | [ <seealso marker="#type-callback_mode">callback_mode()</seealso> - | <seealso marker="#type-state_entry_mode"><c>state_entry_events</c></seealso> ] + | <seealso marker="#type-state_enter">state_enter()</seealso> ] </v> </type> <desc> @@ -1490,9 +1537,9 @@ handle_event(_, _, State, Data) -> </p> <p> The <c>CallbackMode</c> is either just - <seealso marker="#type-callback_mode">callback_mode()</seealso> + <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso> or a list containing - <seealso marker="#type-callback_mode">callback_mode()</seealso> + <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso> and possibly the atom <seealso marker="#type-state_enter"><c>state_enter</c></seealso>. </p> diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl index aedcfc932f..9f5573af86 100644 --- a/lib/stdlib/src/gen_statem.erl +++ b/lib/stdlib/src/gen_statem.erl @@ -142,7 +142,7 @@ NextStateName :: state_name(), NewData :: data(), Actions :: [action()] | action()} | - common_state_callback_result(). + keep_state_callback_result(). -type state_function_enter_result() :: {'next_state', % {next_state,NextStateName,NewData,[]} NextStateName :: state_name(), @@ -151,7 +151,7 @@ NextStateName :: state_name(), NewData :: data(), Actions :: [enter_action()] | enter_action()} | - common_state_callback_result(). + keep_state_callback_enter_result(). -type handle_event_result() :: {'next_state', % {next_state,NextState,NewData,[]} @@ -161,7 +161,7 @@ NextState :: state(), NewData :: data(), Actions :: [action()] | action()} | - common_state_callback_result(). + keep_state_callback_result(). -type handle_event_enter_result() :: {'next_state', % {next_state,NextState,NewData,[]} NextState :: state(), @@ -170,6 +170,28 @@ NextState :: state(), NewData :: data(), Actions :: [enter_action()] | enter_action()} | + keep_state_callback_enter_result(). + +-type keep_state_callback_result() :: + {'keep_state', % {keep_state,NewData,[]} + NewData :: data()} | + {'keep_state', % Keep state, change data + NewData :: data(), + Actions :: [action()] | action()} | + 'keep_state_and_data' | % {keep_state_and_data,[]} + {'keep_state_and_data', % Keep state and data -> only actions + Actions :: [action()] | action()} | + common_state_callback_result(). + +-type keep_state_callback_enter_result() :: + {'keep_state', % {keep_state,NewData,[]} + NewData :: data()} | + {'keep_state', % Keep state, change data + NewData :: data(), + Actions :: [enter_action()] | enter_action()} | + 'keep_state_and_data' | % {keep_state_and_data,[]} + {'keep_state_and_data', % Keep state and data -> only actions + Actions :: [enter_action()] | enter_action()} | common_state_callback_result(). -type common_state_callback_result() :: @@ -185,15 +207,7 @@ {'stop_and_reply', % Reply then stop the server Reason :: term(), Replies :: [reply_action()] | reply_action(), - NewData :: data()} | - {'keep_state', % {keep_state,NewData,[]} - NewData :: data()} | - {'keep_state', % Keep state, change data - NewData :: data(), - Actions :: [ActionType] | ActionType} | - 'keep_state_and_data' | % {keep_state_and_data,[]} - {'keep_state_and_data', % Keep state and data -> only actions - Actions :: [ActionType] | ActionType}. + NewData :: data()}. %% The state machine init function. It is called only once and diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index d2a9b23570..69d1e8e9fa 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -29,7 +29,7 @@ <rev></rev> <file>statem.xml</file> </header> - <marker id="gen_statem behaviour"></marker> + <marker id="gen_statem Behaviour"></marker> <p> This section is to be read with the <seealso marker="stdlib:gen_statem"><c>gen_statem(3)</c></seealso> @@ -199,7 +199,10 @@ handle_event(EventType, EventContent, State, Data) -> <title>State Enter Calls</title> <p> The <c>gen_statem</c> behavior can regardless of callback mode - automatically call the state function + automatically + <seealso marker="stdlib:gen_statem#type-state_enter"> + call the state function + </seealso> with special arguments whenever the state changes so you can write state entry actions near the rest of the state transition rules. @@ -214,8 +217,13 @@ StateName(EventType, EventContent, Data) -> {next_state, NewStateName, NewData}.</pre> <p> Depending on how your state machine is specified, - this can be a very useful feature, but if you use it - you will have to handle the state enter call in all states. + this can be a very useful feature, + but it forces you to handle the state enter calls in all states. + See also the + <seealso marker="#State Entry Actions"> + State Entry Actions + </seealso> + chapter. </p> </section> @@ -964,6 +972,7 @@ do_unlock() -> <!-- =================================================================== --> <section> + <marker id="State Entry Actions"></marker> <title>State Entry Actions</title> <p> Say you have a state machine specification |