Merge branch 'raimo/stdlib/gen_statem-change_cb/OTP-16477' into maint

* raimo/stdlib/gen_statem-change_cb/OTP-16477:
  Implement change_callback_module
  Figure out callback mode a wee bit later

1 files changed, 40 insertions, 5 deletions

diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index 360bf958ad..f657e8cb00 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2016</year><year>2019</year>
+      <year>2016</year><year>2020</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -183,6 +183,21 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       handles the system messages, and calls the <em>callback module</em>
       with machine specific events.
     </p>
+    <p>
+      The <em>callback module</em> can be changed for a running server
+      using the
+      <seealso marker="#Transition Actions">transition action</seealso>
+      <seealso marker="stdlib:gen_statem#type-action"><c>{change_callback_module, NewModule}</c></seealso>.
+      Note that this is a pretty esotheric thing to do...
+      The origin for this feature is a protocol that after
+      version negotiation branches off into quite different
+      state machines depending on the protocol version.
+      There <i>might</i> be other use cases.
+      <i>Beware</i> that the <c>NewModule</c>
+      completely replaces the previous behaviour module,
+      so all relevant callback functions has to handle
+      the state and data from the previous callback module.
+    </p>
   </section>
 
 <!-- =================================================================== -->
@@ -216,8 +231,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       </item>
     </taglist>
     <p>
-      The <em>callback mode</em> is selected at server start
-      and may be changed with a code upgrade/downgrade.
+      The <em>callback mode</em> is a property of
+      the <em>callback module</em> and is set at server start.
+      It may be changed due to a code upgrade/downgrade,
+      or when changing the <em>callback module</em>.
     </p>
     <p>
       See the section
@@ -631,6 +648,22 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
 	Generate the next event to handle, see section 
 	<seealso marker="#Inserted Events">Inserted Events</seealso>.
       </item>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-action">
+	  <c>{change_callback_module, NewModule}</c>
+	</seealso>
+      </tag>
+      <item>
+	Change the
+	<seealso marker="#Callback Module">
+	  <em>callback module</em>
+	</seealso>
+	for the running server.
+	This can be done during any <em>state transition</em>,
+	whether it is a <em>state change</em> or not,
+	but it can <i>not</i> be done from a
+	<seealso marker="#State Enter Calls"><em>state enter call</em></seealso>.
+      </item>
     </taglist>
     <p>
       For details, see the <c>gen_statem(3)</c>
@@ -812,8 +845,10 @@ StateName(EventType, EventContent, Data) ->
       <seealso marker="#Transition Actions">State Transition Actions</seealso>.
       You may not change the state,
       <seealso marker="#Postponing Events">postpone</seealso>
-      this non-event, or
-      <seealso marker="#Inserted Events">insert any events</seealso>.
+      this non-event,
+      <seealso marker="#Inserted Events">insert any events</seealso>,
+      or change the
+      <seealso marker="#Callback Module"><em>callback module</em></seealso>.
     </p>
     <p>
       The first state that is entered