From 77e175589b0ee3c1a4c94aef3cdcdf54cd84c53c Mon Sep 17 00:00:00 2001
From: Raimo Niskanen
Date: Fri, 30 Sep 2016 18:00:38 +0200
Subject: Implement state timeouts
---
lib/stdlib/doc/src/gen_statem.xml | 105 ++++++++++++++++++++++++++------------
1 file changed, 73 insertions(+), 32 deletions(-)
(limited to 'lib/stdlib/doc/src/gen_statem.xml')
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index bba2de5e77..c0631c8448 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -527,7 +527,8 @@ handle_event(_, _, State, Data) ->
Type info originates from regular process messages sent
to the gen_statem. Also, the state machine
implementation can generate events of types
- timeout, enter and internal to itself.
+ timeout, state_timeout, enter,
+ and internal to itself.
@@ -657,8 +658,7 @@ handle_event(_, _, State, Data) ->
All events stored with
action()
next_event
- are inserted in the queue to be processed before
- other events.
+ are inserted to be processed before the other queued events.
-
@@ -668,35 +668,36 @@ handle_event(_, _, State, Data) ->
are used, the gen_statem calls
the new state function with arguments
(enter, OldState, Data).
- If this call returns any
+ Any
actions
- that sets transition options
- they are merged with the current
- That is: hibernate and timeout overrides
- the current and reply sends a reply.
- This has the same effect as if you would have appended
- the actions from this state enter call to the actions
+ returned from this call are handled as if they were
+ appended to the actions
returned by the state function that changed states.
-
- If an
- event_timeout()
- is set through
- action()
- timeout,
- an event timer is started if the value is less than
- infinity or a time-out zero event
- is enqueued if the value is zero.
+ If there are enqueued events the (possibly new)
+ state function
+ is called with the oldest enqueued event,
+ and we start again from the top of this list.
-
- The (possibly new)
+ Timeout timers
+ state_timeout()
+ and
+ event_timeout()
+ are handled. This may lead to a time-out zero event
+ being generated to the
state function
- is called with the oldest enqueued event if there is any,
- otherwise the gen_statem goes into receive
+ and we start again from the top of this list.
+
+
+ -
+
+ Otherwise the gen_statem goes into receive
or hibernation
(if
hibernate()
@@ -704,8 +705,11 @@ handle_event(_, _, State, Data) ->
to wait for the next message. In hibernation the next
non-system event awakens the gen_statem, or rather
the next incoming message awakens the gen_statem,
- but if it is a system event
- it goes right back into hibernation.
+ but if it is a system event it goes right back into hibernation.
+ When a new message arrives the
+ state function
+ is called with the corresponding event,
+ and we start again from the top of this list.
@@ -747,20 +751,20 @@ handle_event(_, _, State, Data) ->
event_type()
timeout
after this time (in milliseconds) unless another
- event arrives in which case this time-out is cancelled.
- Notice that a retried or inserted event
- counts like a new in this respect.
+ event arrives or has arrived
+ in which case this time-out is cancelled.
+ Note that a retried, inserted or state time-out zero
+ events counts as arrived.
If the value is infinity, no timer is started, as
- it never triggers anyway.
+ it never would trigger anyway.
- If the value is 0, the time-out event is immediately enqueued
- unless there already are enqueued events, as the
- time-out is then immediately cancelled.
- This is a feature ensuring that a time-out 0 event
- is processed before any not yet received external event.
+ If the value is 0 no timer is actually started,
+ instead the the time-out event is enqueued to ensure
+ that it gets processed before any not yet
+ received external event.
Note that it is not possible or needed to cancel this time-out,
@@ -768,6 +772,34 @@ handle_event(_, _, State, Data) ->
+
+
+
+
+ Generates an event of
+ event_type()
+ state_timeout
+ after this time (in milliseconds) unless the gen_statem
+ changes states (NewState =/= OldState)
+ which case this time-out is cancelled.
+
+
+ If the value is infinity, no timer is started, as
+ it never would trigger anyway.
+
+
+ If the value is 0 no timer is actually started,
+ instead the the time-out event is enqueued to ensure
+ that it gets processed before any not yet
+ received external event.
+
+
+ Setting this timer while it is running will restart it with
+ the new time-out value. Therefore it is possible to cancel
+ this timeout by setting it to infinity.
+
+
+
@@ -886,6 +918,15 @@ handle_event(_, _, State, Data) ->
to Time with EventContent.
+ state_timeout
+ -
+
+ Sets the
+ transition_option()
+ state_timeout()
+ to Time with EventContent.
+
+
--
cgit v1.2.3