File 2182-Improve-user-s-guide-on-time-outs.patch of Package erlang
From 4d636ebe55ddd557f62885b724076c1c146f62dd Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 7 Sep 2018 16:49:51 +0200
Subject: [PATCH 2/2] Improve user's guide on time-outs
---
system/doc/design_principles/statem.xml | 161 +++++++++++++++++++++++++++-----
1 file changed, 136 insertions(+), 25 deletions(-)
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index 29e19163a5..07b4284cb8 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -546,7 +546,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
</tag>
<item>
If set postpone the current event, see section
- <seealso marker="#Postponing Events">Postponing Events</seealso>
+ <seealso marker="#Postponing Events">Postponing Events</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-hibernate">
@@ -557,41 +557,44 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
</tag>
<item>
If set hibernate the <c>gen_statem</c>, treated in section
- <seealso marker="#Hibernation">Hibernation</seealso>
+ <seealso marker="#Hibernation">Hibernation</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-state_timeout">
- <c>{state_timeout, Time}</c>
+ <c>{state_timeout, EventContent, Time}</c>
</seealso>
<br />
- <c>{state_timeout, Time, Opts}</c>
+ <c>{state_timeout, EventContent, Time, Opts}</c>
</tag>
<item>
- Start a state time-out, read more in section
- <seealso marker="#State Time-Outs">State Time-Outs</seealso>
+ Start a state time-out, read more in sections
+ <seealso marker="#Time-Outs">Time-Outs</seealso> and
+ <seealso marker="#State Time-Outs">State Time-Outs</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-generic_timeout">
- <c>{{timeout, Name}, Time}</c>
+ <c>{{timeout, Name}, EventContent, Time}</c>
</seealso>
<br />
- <c>{{timeout, Name}, Time, Opts}</c>
+ <c>{{timeout, Name}, EventContent, Time, Opts}</c>
</tag>
<item>
- Start a generic time-out, read more in section
- <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>
+ Start a generic time-out, read more in sections
+ <seealso marker="#Time-Outs">Time-Outs</seealso> and
+ <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-event_timeout">
- <c>{timeout, Time}</c>
+ <c>{timeout, EventContent, Time}</c>
</seealso>
<br />
- <c>{timeout, Time, Opts}</c><br />
+ <c>{timeout, EventContent, Time, Opts}</c><br />
<c>Time</c>
</tag>
<item>
- Start an event time-out, see more in section
- <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>
+ Start an event time-out, see more in sections
+ <seealso marker="#Time-Outs">Time-Outs</seealso> and
+ <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-reply_action">
@@ -600,7 +603,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
</tag>
<item>
Reply to a caller, mentioned at the end of section
- <seealso marker="#All State Events">All State Events</seealso>
+ <seealso marker="#All State Events">All State Events</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-action">
@@ -609,7 +612,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
</tag>
<item>
Generate the next event to handle, see section
- <seealso marker="#Inserted Events">Inserted Events</seealso>
+ <seealso marker="#Inserted Events">Inserted Events</seealso>.
</item>
</taglist>
<p>
@@ -678,10 +681,12 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
</tag>
<item>
Generated by <em>transition action</em>
- <seealso marker="stdlib:gen_statem#type-state_timeout">
+ <seealso marker="stdlib:gen_statem#type-timeout_action">
<c>{state_timeout,Time,EventContent}</c>
</seealso>
- state timer timing out.
+ state timer timing out. Read more in sections
+ <seealso marker="#Time-Outs">Time-Outs</seealso> and
+ <seealso marker="#State Time-Outs">State Time-Outs</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-timeout_event_type">
@@ -690,10 +695,12 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
</tag>
<item>
Generated by <em>transition action</em>
- <seealso marker="stdlib:gen_statem#type-generic_timeout">
+ <seealso marker="stdlib:gen_statem#type-timeout_action">
<c>{{timeout,Name},Time,EventContent}</c>
</seealso>
- generic timer timing out.
+ generic timer timing out. Read more in sections
+ <seealso marker="#Time-Outs">Time-Outs</seealso> and
+ <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-timeout_event_type">
@@ -702,11 +709,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
</tag>
<item>
Generated by <em>transition action</em>
- <seealso marker="stdlib:gen_statem#type-event_timeout">
+ <seealso marker="stdlib:gen_statem#type-timeout_action">
<c>{timeout,Time,EventContent}</c>
</seealso>
(or its short form <c>Time</c>)
- event timer timing out.
+ event timer timing out. Read more in sections
+ <seealso marker="#Time-Outs">Time-Outs</seealso> and
+ <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>.
</item>
<tag>
<seealso marker="stdlib:gen_statem#type-event_type">
@@ -714,10 +723,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
</seealso>
</tag>
<item>
- Generated by <em>state transition</em>
- <seealso marker="stdlib:gen_statem#type-action">action</seealso>
- <c>{next_event,internal,EventContent}</c>.
+ Generated by <em>transition action</em>
+ <seealso marker="stdlib:gen_statem#type-enter_action"><c>{next_event,internal,EventContent}</c></seealso>.
All <em>event types</em> above can also be generated using
+ the <c>next_event</c> action:
<c>{next_event,EventType,EventContent}</c>.
</item>
</taglist>
@@ -780,6 +789,108 @@ StateName(EventType, EventContent, Data) ->
</p>
</section>
+<!-- =================================================================== -->
+
+ <section>
+ <marker id="Time-Outs" />
+ <title>Time-outs</title>
+ <p>
+ Time-outs in <c>gen_statem</c> are started from a
+ <seealso marker="#Transition Actions">
+ <em>transition action</em>
+ </seealso>
+ during a state transition that is when exiting from the
+ <seealso marker="#State Callback"><em>state callback</em></seealso>.
+ </p>
+ <p>
+ There are 3 types of time-outs in <c>gen_statem</c>:
+ </p>
+ <taglist>
+ <tag>
+ <seealso marker="stdlib:gen_statem#type-state_timeout">
+ <c>state_timeout</c>
+ </seealso>
+ </tag>
+ <item>
+ There is one
+ <seealso marker="#State Time-Outs">State Time-Out</seealso>
+ that is automatically cancelled by a <em>state change</em>.
+ </item>
+ <tag>
+ <seealso marker="stdlib:gen_statem#type-generic_timeout">
+ <c>{timeout, Name}</c>
+ </seealso>
+ </tag>
+ <item>
+ There are any number of
+ <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>
+ differing by their <c>Name</c>.
+ They have no automatic cancelling.
+ </item>
+ <tag>
+ <seealso marker="stdlib:gen_statem#type-event_timeout">
+ <c>timeout</c>
+ </seealso>
+ </tag>
+ <item>
+ There is one
+ <seealso marker="#Event Time-Outs">Event Time-Out</seealso>
+ that is automatically cancelled by any event.
+ Note that
+ <seealso marker="#Postponing Events">postponed </seealso>
+ and
+ <seealso marker="#Inserted Events">inserted</seealso>
+ events cancel this timeout just as external events.
+ </item>
+ </taglist>
+ <p>
+ When a time-out is started any running time-out with the same tag,
+ <c>state_timeout</c>, <c>{timeout, Name}</c> or <c>timeout</c>,
+ is cancelled, that is the time-out is restarted with the new time.
+ </p>
+ <p>
+ All time-outs has got an <c>EventContent</c> that is part of the
+ <seealso marker="#Transition Actions">
+ <em>transition action</em>
+ </seealso>
+ that starts the time-out.
+ Different <c>EventContent</c>s does not create different time-outs.
+ The <c>EventContent</c> is delivered to the
+ <seealso marker="#State Callback"><em>state callback</em></seealso>
+ when the time-out expires.
+ </p>
+ <section>
+ <marker id="Cancelling a Time-Out" />
+ <title>Cancelling a Time-Out</title>
+ <p>
+ If a time-out is started with the time <c>infinity</c> it will
+ never time out, in fact it will not even be started, and any
+ running time-out with the same tag will be cancelled.
+ The <c>EventContent</c> will in this case be ignored,
+ so why not set it to <c>undefined</c>.
+ </p>
+ </section>
+ <section>
+ <marker id="Time-Out Zero" />
+ <title>Time-Out Zero</title>
+ <p>
+ If a time-out is started with the time <c>0</c> it will
+ actually not be started. Instead the time-out event will
+ immediately be inserted to be processed after any events
+ already enqueued, and before any not yet received external events.
+ Note that some time-outs are automatically cancelled
+ so if you for example combine
+ <seealso marker="#Postponing Events">postponing</seealso>
+ an event in a <em>state change</em> with starting an
+ <seealso marker="#Event Time-Outs">event time-out</seealso>
+ with time <c>0</c> there will be no timeout event inserted
+ since the event time-out is cancelled by the postponed
+ event that is delivered due to the state change.
+ </p>
+ </section>
+ </section>
+
+
<!-- =================================================================== -->
<section>
--
2.16.4
