From 2cb268ca68f94707ed9844e3ae2b469a3ef34720 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Mon, 17 Jun 2024 16:53:06 +0200 Subject: [PATCH] Polish documentation --- lib/stdlib/src/gen_statem.erl | 21 +++++++++++++++++++++ system/doc/design_principles/statem.md | 6 +++--- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl index 41808d3d02aa..045e62243281 100644 --- a/lib/stdlib/src/gen_statem.erl +++ b/lib/stdlib/src/gen_statem.erl @@ -548,6 +548,27 @@ State name or state term. If the [_callback mode_](`t:callback_mode/0`) is `handle_event_function`, the state can be any term. After a _state change_ (`NextState =/= State`), all postponed events are retried. + +Comparing two states for strict equality is assumed to be a fast operation, +since for every _state transition_ the `gen_statem` engine has to deduce +if it is a _state change_. + +> #### Note {: .info } +> The smaller the state term, in general, the faster the comparison. +> +> Note that if the "same" state term is returned for a state transition +> (or a return action without a `NextState` field is used), +> the comparison for equality is always fast because that can be seen +> from the term handle. +> +> But if a newly constructed state term is returned, +> both the old and the new state terms will have to be traversed +> until an inequality is found, or until both terms +> have been fully traversed. +> +> So it is possible to use large state terms that are fast to compare, +> but very easy to accidentally mess up. Using small state terms is +> the safe choice. """. -type state() :: state_name() | % For StateName/3 callback functions diff --git a/system/doc/design_principles/statem.md b/system/doc/design_principles/statem.md index 39bc30600686..9b9fcdff2b18 100644 --- a/system/doc/design_principles/statem.md +++ b/system/doc/design_principles/statem.md @@ -1168,9 +1168,9 @@ in the value changes the set of events that is handled, the value should be in the State. Otherwise no postponed events will be retried since only the server `Data` changes. -This is not important if you do not postpone events. But if you later decide -to use event postponing, the design flaw of not having separate states -when they should be, could become a hard-to-find bug. +This is important if events are postponed. But remember that an incorrect +design decision of what belongs in the state, may become a hard to find bug +some time later, when event postponing is introduced. ### Fuzzy State Diagrams