From 4d636ebe55ddd557f62885b724076c1c146f62dd Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 7 Sep 2018 16:49:51 +0200 Subject: Improve user's guide on time-outs --- system/doc/design_principles/statem.xml | 161 +++++++++++++++++++++++++++----- 1 file changed, 136 insertions(+), 25 deletions(-) (limited to 'system') 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') If set postpone the current event, see section - Postponing Events + Postponing Events. @@ -557,41 +557,44 @@ State(S) x Event(E) -> Actions(A), State(S') If set hibernate the gen_statem, treated in section - Hibernation + Hibernation. - {state_timeout, Time} + {state_timeout, EventContent, Time}
- {state_timeout, Time, Opts} + {state_timeout, EventContent, Time, Opts} - Start a state time-out, read more in section - State Time-Outs + Start a state time-out, read more in sections + Time-Outs and + State Time-Outs. - {{timeout, Name}, Time} + {{timeout, Name}, EventContent, Time}
- {{timeout, Name}, Time, Opts} + {{timeout, Name}, EventContent, Time, Opts} - Start a generic time-out, read more in section - Generic Time-Outs + Start a generic time-out, read more in sections + Time-Outs and + Generic Time-Outs. - {timeout, Time} + {timeout, EventContent, Time}
- {timeout, Time, Opts}
+ {timeout, EventContent, Time, Opts}
Time - Start an event time-out, see more in section - Event Time-Outs + Start an event time-out, see more in sections + Time-Outs and + Event Time-Outs. @@ -600,7 +603,7 @@ State(S) x Event(E) -> Actions(A), State(S') Reply to a caller, mentioned at the end of section - All State Events + All State Events. @@ -609,7 +612,7 @@ State(S) x Event(E) -> Actions(A), State(S') Generate the next event to handle, see section - Inserted Events + Inserted Events.

@@ -678,10 +681,12 @@ State(S) x Event(E) -> Actions(A), State(S') Generated by transition action - + {state_timeout,Time,EventContent} - state timer timing out. + state timer timing out. Read more in sections + Time-Outs and + State Time-Outs. @@ -690,10 +695,12 @@ State(S) x Event(E) -> Actions(A), State(S') Generated by transition action - + {{timeout,Name},Time,EventContent} - generic timer timing out. + generic timer timing out. Read more in sections + Time-Outs and + Generic Time-Outs. @@ -702,11 +709,13 @@ State(S) x Event(E) -> Actions(A), State(S') Generated by transition action - + {timeout,Time,EventContent} (or its short form Time) - event timer timing out. + event timer timing out. Read more in sections + Time-Outs and + Event Time-Outs. @@ -714,10 +723,10 @@ State(S) x Event(E) -> Actions(A), State(S') - Generated by state transition - action - {next_event,internal,EventContent}. + Generated by transition action + {next_event,internal,EventContent}. All event types above can also be generated using + the next_event action: {next_event,EventType,EventContent}. @@ -780,6 +789,108 @@ StateName(EventType, EventContent, Data) ->

+ + +
+ + Time-outs +

+ Time-outs in gen_statem are started from a + + transition action + + during a state transition that is when exiting from the + state callback. +

+

+ There are 3 types of time-outs in gen_statem: +

+ + + + state_timeout + + + + There is one + State Time-Out + that is automatically cancelled by a state change. + + + + {timeout, Name} + + + + There are any number of + Generic Time-Outs + differing by their Name. + They have no automatic cancelling. + + + + timeout + + + + There is one + Event Time-Out + that is automatically cancelled by any event. + Note that + postponed + and + inserted + events cancel this timeout just as external events. + + +

+ When a time-out is started any running time-out with the same tag, + state_timeout, {timeout, Name} or timeout, + is cancelled, that is the time-out is restarted with the new time. +

+

+ All time-outs has got an EventContent that is part of the + + transition action + + that starts the time-out. + Different EventContents does not create different time-outs. + The EventContent is delivered to the + state callback + when the time-out expires. +

+
+ + Cancelling a Time-Out +

+ If a time-out is started with the time infinity 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 EventContent will in this case be ignored, + so why not set it to undefined. +

+
+
+ + Time-Out Zero +

+ If a time-out is started with the time 0 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 + postponing + an event in a state change with starting an + event time-out + with time 0 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. +

+
+
+ +
-- cgit v1.2.3