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') 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