From b54d82fea10c24359d2a315668b6176fc47963b7 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 22 Apr 2016 15:18:07 +0200
Subject: Promote gen_statem over gen_fsm

---
 system/doc/design_principles/des_princ.xml        |  6 ++++--
 system/doc/design_principles/fsm.xml              | 12 +++++++++++-
 system/doc/design_principles/release_handling.xml |  4 ++--
 system/doc/design_principles/statem.xml           |  9 +++++++++
 system/doc/design_principles/sup_princ.xml        |  2 +-
 5 files changed, 27 insertions(+), 6 deletions(-)

(limited to 'system/doc')

diff --git a/system/doc/design_principles/des_princ.xml b/system/doc/design_principles/des_princ.xml
index 0e087cf843..8ab8661c2d 100644
--- a/system/doc/design_principles/des_princ.xml
+++ b/system/doc/design_principles/des_princ.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>1997</year><year>2013</year>
+      <year>1997</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -226,7 +226,9 @@ free(Ch, {Alloc, Free} = Channels) ->
       <item><p><seealso marker="gen_server_concepts">gen_server</seealso></p>
       <p>For implementing the server of a client-server relation</p></item>
       <item><p><seealso marker="fsm">gen_fsm</seealso></p>
-      <p>For implementing finite-state machines</p></item>
+      <p>For implementing finite-state machines (Old)</p></item>
+      <item><p><seealso marker="statem">gen_statem</seealso></p>
+      <p>For implementing state machines (New)</p></item>
       <item><p><seealso marker="events">gen_event</seealso></p>
       <p>For implementing event handling functionality</p></item>
       <item><p><seealso marker="sup_princ">supervisor</seealso></p>
diff --git a/system/doc/design_principles/fsm.xml b/system/doc/design_principles/fsm.xml
index f58b50cbff..3468f93ae0 100644
--- a/system/doc/design_principles/fsm.xml
+++ b/system/doc/design_principles/fsm.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>1997</year><year>2013</year>
+      <year>1997</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -30,6 +30,16 @@
     <file>fsm.xml</file>
   </header>
   <marker id="gen_fsm behaviour"></marker>
+    <note>
+      <p>
+	There is a new behaviour
+	<seealso marker="gen_statem"><c>gen_statem</c></seealso>
+	that is intended to replace <c>gen_fsm</c> for new code.
+	It has the same features and add some really useful.
+	This module will not be removed for the foreseeable future
+	to keep old state machine implementations running.
+      </p>
+    </note>
   <p>This section is to be read with the <c>gen_fsm(3)</c> manual page
     in STDLIB, where all interface functions and callback
     functions are described in detail.</p>
diff --git a/system/doc/design_principles/release_handling.xml b/system/doc/design_principles/release_handling.xml
index 20ddc3dbf5..4f71ad4437 100644
--- a/system/doc/design_principles/release_handling.xml
+++ b/system/doc/design_principles/release_handling.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2003</year><year>2014</year>
+      <year>2003</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -249,7 +249,7 @@
       <p>If <c>Modules=dynamic</c>, which is the case for event
         managers, the event manager process informs the release handler
         about the list of currently installed event handlers
-	(<c>gen_fsm</c>), and it is checked if the module name is in
+	(<c>gen_event</c>), and it is checked if the module name is in
         this list instead.</p>
       <p>The release handler suspends, asks for code change, and
         resumes processes by calling the functions
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index 27b9b7c761..a921a40243 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -36,6 +36,15 @@
     manual page in STDLIB, where all interface functions and callback
     functions are described in detail.
   </p>
+  <p>
+    This is a new behaviour in OTP-19.0.
+    It has been thoroughly reviewed, is stable enough
+    to be used by at least two heavy OTP applications, and is here to stay.
+    But depending on user feedback, we do not expect
+    but might find it necessary to make minor
+    not backwards compatible changes into OTP-20.0,
+    so its state can be designated as "not quite experimental"...
+  </p>
 
 <!-- =================================================================== -->
 
diff --git a/system/doc/design_principles/sup_princ.xml b/system/doc/design_principles/sup_princ.xml
index a6b7dbb68d..749c9f69f2 100644
--- a/system/doc/design_principles/sup_princ.xml
+++ b/system/doc/design_principles/sup_princ.xml
@@ -402,8 +402,8 @@ supervisor:delete_child(Sup, Id)</code>
       restarts.</p>
   </section>
 
-  <marker id="simple"/>
   <section>
+    <marker id="simple"/>
     <title>Simplified one_for_one Supervisors</title>
     <p>A supervisor with restart strategy <c>simple_one_for_one</c> is
       a simplified <c>one_for_one</c> supervisor, where all child
-- 
cgit v1.2.3