From 7241e26a8ac9aa797f046b6150a481563f625476 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 10 May 2016 10:23:35 +0200 Subject: Reword 'dispatch' into 'branch depending' --- lib/stdlib/doc/src/gen_statem.xml | 8 ++++---- 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 Module:StateName/3. 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 gen_statem engine + branches depending on state name. + Notice that in this mode the mandatory callback function Module:terminate/3 makes the state name terminate unusable.

@@ -148,7 +148,7 @@ erlang:'!' -----> Module:StateName/3 is handle_event_function, the state can be any term and the state function name is Module:handle_event/4. - 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) ->

With state_functions, you are restricted to use - atom-only states, and the gen_statem 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 gen_statem 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.

@@ -173,7 +174,8 @@ handle_event(EventType, EventContent, State, Data) -> one event at the time or on one state at the time, but function Module:handle_event/4 - quickly grows too large to handle without introducing dispatching. + quickly grows too large to handle without branching to + helper functions.

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 {StateName,server} or - {StateName,client}. Also, as you do the dispatching - yourself, you make StateName decide where in the code + {StateName,client}, + and make StateName 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 Module:handle_event/4 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:

This section describes what to change in the example to use one handle_event/4 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: