diff options
| -rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 8 | ||||
| -rw-r--r-- | system/doc/design_principles/statem.xml | 23 |
2 files changed, 17 insertions, 14 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index b1d9799917..0e7d6e53e9 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -136,9 +136,9 @@ erlang:'!' -----> Module:StateName/3 is used as the state function name; see <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso>. This gathers all code for a specific state - in one function and hence dispatches on state first. - Notice that in this mode - the mandatory callback function + in one function as the <c>gen_statem</c> engine + branches depending on state name. + Notice that in this mode the mandatory callback function <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> makes the state name <c>terminate</c> unusable. </p> @@ -148,7 +148,7 @@ erlang:'!' -----> Module:StateName/3 is <c>handle_event_function</c>, the state can be any term and the state function name is <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>. - This makes it easy to dispatch on state or on event as you desire. + This makes it easy to branch depending on state or event as you desire. Be careful about which events you handle in which states so that you do not accidentally postpone an event forever creating an infinite busy loop. diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index 585b1a35f5..b63327291d 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -152,9 +152,10 @@ handle_event(EventType, EventContent, State, Data) -> </p> <p> With <c>state_functions</c>, you are restricted to use - atom-only states, and the <c>gen_statem</c> engine dispatches - on state name for you. This encourages the callback module - to gather the implementation of all event actions particular + atom-only states, and the <c>gen_statem</c> engine + branches depending on state name for you. + This encourages the callback module to gather + the implementation of all event actions particular to one state in the same place in the code, hence to focus on one state at the time. </p> @@ -173,7 +174,8 @@ handle_event(EventType, EventContent, State, Data) -> one event at the time or on one state at the time, but function <seealso marker="stdlib:gen_statem#Module:handle_event/4"><c>Module:handle_event/4</c></seealso> - quickly grows too large to handle without introducing dispatching. + quickly grows too large to handle without branching to + helper functions. </p> <p> The mode enables the use of non-atom states, for example, @@ -181,8 +183,8 @@ handle_event(EventType, EventContent, State, Data) -> If, for example, a state diagram is largely alike for the client side and the server side of a protocol, you can have a state <c>{StateName,server}</c> or - <c>{StateName,client}</c>. Also, as you do the dispatching - yourself, you make <c>StateName</c> decide where in the code + <c>{StateName,client}</c>, + and make <c>StateName</c> determine where in the code to handle most events in the state. The second element of the tuple is then used to select whether to handle special client-side or server-side events. @@ -526,7 +528,8 @@ handle_event({call,From}, code_length, #{code := Code} = Data) -> all events are handled in <seealso marker="stdlib:gen_statem#Module:handle_event/4"><c>Module:handle_event/4</c></seealso> and we can (but do not have to) use an event-centered approach - where we dispatch on event first and then state: + where we first branch depending on event + and then depending on state: </p> <code type="erl"><![CDATA[ ... @@ -1097,9 +1100,9 @@ code_change(_Vsn, State, Data, _Extra) -> <p> This section describes what to change in the example to use one <c>handle_event/4</c> function. - The previously used clean first-dispatch-on-event approach - does not work that well here because of the generated - entry actions so this example dispatches on state first: + The previously used approach to first branch depending on event + does not work that well here because of the generated + entry actions, so this example first branches depending on state: </p> <code type="erl"><![CDATA[ ... |