Merge branch 'raimo/gen_statem-dev'

OTP-14531 Generic time-outs in gen_statem

Conflicts:
	lib/stdlib/test/erl_internal_SUITE.erl

6 files changed, 562 insertions, 137 deletions

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 18089a8191..17a3a3c83c 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2016-2017</year>
+      <year>2016</year><year>2017</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -67,13 +67,16 @@
       It has the same features and adds some really useful:
     </p>
     <list type="bulleted">
-      <item>State code is gathered.</item>
-      <item>The state can be any term.</item>
-      <item>Events can be postponed.</item>
-      <item>Events can be self-generated.</item>
-      <item>Automatic state enter code can be called.</item>
-      <item>A reply can be sent from a later state.</item>
-      <item>There can be multiple <c>sys</c> traceable replies.</item>
+      <item>Gathered state code.</item>
+      <item>Arbitrary term state.</item>
+      <item>Event postponing.</item>
+      <item>Self-generated events.</item>
+      <item>State time-out.</item>
+      <item>Multiple generic named time-outs.</item>
+      <item>Absolute time-out time.</item>
+      <item>Automatic state enter calls.</item>
+      <item>Reply from other state than the request.</item>
+      <item>Multiple <c>sys</c> traceable replies.</item>
     </list>
     <p>
       The callback model(s) for <c>gen_statem</c> differs from
@@ -148,7 +151,7 @@ erlang:'!'            -----> Module:StateName/3
       This gathers all code for a specific state
       in one function as the <c>gen_statem</c> engine
       branches depending on state name.
-      Notice the fact that there is a mandatory callback function
+      Note the fact that the callback function
       <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
       makes the state name <c>terminate</c> unusable in this mode.
     </p>
@@ -533,10 +536,12 @@ handle_event(_, _, State, Data) ->
 	  originate from the corresponding API functions.
 	  For calls, the event contains whom to reply to.
 	  Type <c>info</c> originates from regular process messages sent
-	  to the <c>gen_statem</c>. Also, the state machine
-	  implementation can generate events of types
-	  <c>timeout</c>, <c>state_timeout</c>,
-	  and <c>internal</c> to itself.
+	  to the <c>gen_statem</c>. The state machine
+	  implementation can, in addition to the above,
+	  generate
+	  <seealso marker="#type-event_type"><c>events of types</c></seealso>
+	  <c>timeout</c>, <c>{timeout,<anno>Name</anno>}</c>,
+	  <c>state_timeout</c>, and <c>internal</c> to itself.
 	</p>
       </desc>
     </datatype>
@@ -703,13 +708,14 @@ handle_event(_, _, State, Data) ->
 	  </item>
 	  <item>
 	    <p>
-	      Timeout timers 
-              <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
+	      Time-out timers
+              <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>,
+              <seealso marker="#type-generic_timeout"><c>generic_timeout()</c></seealso>
 	      and 
-              <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>
+              <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
 	      are handled.  Time-outs with zero time are guaranteed to be
 	      delivered to the state machine before any external
-	      not yet received event so if there is such a timeout requested,
+	      not yet received event so if there is such a time-out requested,
 	      the corresponding time-out zero event is enqueued as
 	      the newest event.
 	    </p>
@@ -787,49 +793,102 @@ handle_event(_, _, State, Data) ->
       <name name="event_timeout"/>
       <desc>
 	<p>
-	  Generates an event of
+	  Starts a timer set by
+	  <seealso marker="#type-enter_action"><c>enter_action()</c></seealso>
+	  <c>timeout</c>.
+	  When the timer expires an event of
 	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
-	  <c>timeout</c>
-	  after this time (in milliseconds) unless another
-	  event arrives or has arrived
-	  in which case this time-out is cancelled.
+	  <c>timeout</c> will be generated.
+	  See
+	  <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso>
+	  for how <c>Time</c> and
+	  <seealso marker="#type-timeout_option"><c>Options</c></seealso>
+	  are interpreted.  Future <c>erlang:start_timer/4</c> <c>Options</c>
+	  will not necessarily be supported.
+	</p>
+	<p>
+	  Any event that arrives cancels this time-out.
 	  Note that a retried or inserted event counts as arrived.
 	  So does a state time-out zero event, if it was generated
-	  before this timer is requested.
+	  before this time-out is requested.
 	</p>
 	<p>
-	  If the value is <c>infinity</c>, no timer is started, as
-	  it never would trigger anyway.
+	  If <c>Time</c> is <c>infinity</c>,
+	  no timer is started, as it never would expire anyway.
 	</p>
 	<p>
-	  If the value is <c>0</c> no timer is actually started,
+	  If <c>Time</c> is relative and <c>0</c>
+	  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.
 	</p>
 	<p>
-	  Note that it is not possible or needed to cancel this time-out,
+	  Note that it is not possible nor needed to cancel this time-out,
 	  as it is cancelled automatically by any other event.
 	</p>
       </desc>
     </datatype>
     <datatype>
+      <name name="generic_timeout"/>
+      <desc>
+	<p>
+	  Starts a timer set by
+	  <seealso marker="#type-enter_action"><c>enter_action()</c></seealso>
+	  <c>{timeout,Name}</c>.
+	  When the timer expires an event of
+	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
+	  <c>{timeout,Name}</c> will be generated.
+	  See
+	  <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso>
+	  for how <c>Time</c> and
+	  <seealso marker="#type-timeout_option"><c>Options</c></seealso>
+	  are interpreted.  Future <c>erlang:start_timer/4</c> <c>Options</c>
+	  will not necessarily be supported.
+	</p>
+	<p>
+	  If <c>Time</c> is <c>infinity</c>,
+	  no timer is started, as it never would expire anyway.
+	</p>
+	<p>
+	  If <c>Time</c> is relative and <c>0</c>
+	  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.
+	</p>
+	<p>
+	  Setting a timer with the same <c>Name</c> while it is running
+	  will restart it with the new time-out value.
+	  Therefore it is possible to cancel
+	  a specific time-out by setting it to <c>infinity</c>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="state_timeout"/>
       <desc>
 	<p>
-	  Generates an event of
+	  Starts a timer set by
+	  <seealso marker="#type-enter_action"><c>enter_action()</c></seealso>
+	  <c>state_timeout</c>.
+	  When the timer expires an event of
 	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
-	  <c>state_timeout</c>
-	  after this time (in milliseconds) unless the <c>gen_statem</c>
-	  changes states (<c>NewState =/= OldState</c>)
-	  which case this time-out is cancelled.
+	  <c>state_timeout</c> will be generated.
+	  See
+	  <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso>
+	  for how <c>Time</c> and
+	  <seealso marker="#type-timeout_option"><c>Options</c></seealso>
+	  are interpreted.  Future <c>erlang:start_timer/4</c> <c>Options</c>
+	  will not necessarily be supported.
 	</p>
 	<p>
-	  If the value is <c>infinity</c>, no timer is started, as
-	  it never would trigger anyway.
+	  If <c>Time</c> is <c>infinity</c>,
+	  no timer is started, as it never would expire anyway.
 	</p>
 	<p>
-	  If the value is <c>0</c> no timer is actually started,
+	  If <c>Time</c> is relative and <c>0</c>
+	  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.
@@ -842,6 +901,20 @@ handle_event(_, _, State, Data) ->
       </desc>
     </datatype>
     <datatype>
+      <name name="timeout_option"/>
+      <desc>
+	<p>
+	  If <c>Abs</c> is <c>true</c> an absolute timer is started,
+	  and if it is <c>false</c> a relative, which is the default.
+	  See
+	  <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso>
+	  for details.
+	</p>
+	<p>
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="action"/>
       <desc>
 	<p>
@@ -955,7 +1028,21 @@ handle_event(_, _, State, Data) ->
 	      Sets the
 	      <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>
 	      <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>
-	      to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>.
+	      to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>
+	      and time-out options
+	      <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>.
+	    </p>
+	  </item>
+	  <tag><c>{timeout,<anno>Name</anno>}</c></tag>
+	  <item>
+	    <p>
+	      Sets the
+	      <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>
+	      <seealso marker="#type-generic_timeout"><c>generic_timeout()</c></seealso>
+	      to <c><anno>Time</anno></c> for <c><anno>Name</anno></c>
+	      with <c><anno>EventContent</anno></c>
+	      and time-out options
+	      <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>.
 	    </p>
 	  </item>
 	  <tag><c>state_timeout</c></tag>
@@ -964,7 +1051,9 @@ handle_event(_, _, State, Data) ->
 	      Sets the
 	      <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>
 	      <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
-	      to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>.
+	      to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>
+	      and time-out options
+	      <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>.
 	    </p>
 	  </item>
 	</taglist>
@@ -1236,7 +1325,7 @@ handle_event(_, _, State, Data) ->
 	    to avoid that the calling process dies when the call
 	    times out, you will have to be prepared to handle
 	    a late reply.
-	    So why not just allow the calling process to die?
+	    So why not just let the calling process die?
 	  </p>
 	</note>
 	<p>
@@ -1645,6 +1734,16 @@ handle_event(_, _, State, Data) ->
 	<v>Reason = term()</v>
       </type>
       <desc>
+        <note>
+          <p>
+	    This callback is optional, so callback modules need not export it.
+            If a release upgrade/downgrade with
+	    <c>Change={advanced,Extra}</c>
+	    specified in the <c>.appup</c> file is made
+	    when <c>code_change/4</c> is not implemented
+	    the process will crash with exit reason <c>undef</c>.
+	  </p>
+        </note>
         <p>
 	  This function is called by a <c>gen_statem</c> when it is to
 	  update its internal state during a release upgrade/downgrade,
@@ -1705,7 +1804,7 @@ handle_event(_, _, State, Data) ->
     <func>
       <name>Module:init(Args) -> Result(StateType)</name>
       <fsummary>
-	Optional function for initializing process and internal state.
+	Initializing process and internal state.
       </fsummary>
       <type>
         <v>Args = term()</v>
@@ -1721,7 +1820,7 @@ handle_event(_, _, State, Data) ->
 	  <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>
 	  or
 	  <seealso marker="#start/3"><c>start/3,4</c></seealso>,
-	  this optional function is called by the new process to initialize
+	  this function is called by the new process to initialize
 	  the implementation state and server data.
 	</p>
 	<p>
@@ -1730,13 +1829,16 @@ handle_event(_, _, State, Data) ->
 	</p>
         <note>
 	  <p>
-	    This callback is optional, so a callback module does not need
-	    to export it, but most do.  If this function is not exported,
-	    the <c>gen_statem</c> should be started through
+	    Note that if the <c>gen_statem</c> is started trough
 	    <seealso marker="proc_lib"><c>proc_lib</c></seealso>
 	    and
-	    <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>.
+	    <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>,
+	    this callback will never be called.
+	    Since this callback is not optional it can
+	    in that case be implemented as:
 	  </p>
+	  <pre>
+init(Args) -> erlang:error(not_implemented, [Args]).</pre>
         </note>
       </desc>
     </func>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index cacc932ec4..6f566b8beb 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -78,8 +78,9 @@
 -type data() :: term().
 
 -type event_type() ::
-	{'call',From :: from()} | 'cast' |
-	'info' | 'timeout' | 'state_timeout' | 'internal'.
+	{'call',From :: from()} | 'cast' | 'info' |
+	'timeout' | {'timeout', Name :: term()} | 'state_timeout' |
+	'internal'.
 
 -type callback_mode_result() ::
 	callback_mode() | [callback_mode() | state_enter()].
@@ -88,7 +89,7 @@
 
 -type transition_option() ::
 	postpone() | hibernate() |
-	event_timeout() | state_timeout().
+	event_timeout() | generic_timeout() | state_timeout().
 -type postpone() ::
 	%% If 'true' postpone the current event
 	%% and retry it when the state changes (=/=)
@@ -97,13 +98,17 @@
 	%% If 'true' hibernate the server instead of going into receive
 	boolean().
 -type event_timeout() ::
-	%% Generate a ('timeout', EventContent, ...) event after Time
+	%% Generate a ('timeout', EventContent, ...) event
 	%% unless some other event is delivered
-	Time :: timeout().
+	Time :: timeout() | integer().
+-type generic_timeout() ::
+	%% Generate a ({'timeout',Name}, EventContent, ...) event
+	Time :: timeout() | integer().
 -type state_timeout() ::
-	%% Generate a ('state_timeout', EventContent, ...) event after Time
+	%% Generate a ('state_timeout', EventContent, ...) event
 	%% unless the state is changed
-	Time :: timeout().
+	Time :: timeout() | integer().
+-type timeout_option() :: {abs,Abs :: boolean()}.
 
 -type action() ::
 	%% During a state change:
@@ -137,8 +142,24 @@
 	(Timeout :: event_timeout()) | % {timeout,Timeout}
 	{'timeout', % Set the event_timeout option
 	 Time :: event_timeout(), EventContent :: term()} |
+	{'timeout', % Set the event_timeout option
+	 Time :: event_timeout(),
+	 EventContent :: term(),
+	 Options :: (timeout_option() | [timeout_option()])} |
+	%%
+	{{'timeout', Name :: term()}, % Set the generic_timeout option
+	 Time :: generic_timeout(), EventContent :: term()} |
+	{{'timeout', Name :: term()}, % Set the generic_timeout option
+	 Time :: generic_timeout(),
+	 EventContent :: term(),
+	 Options :: (timeout_option() | [timeout_option()])} |
+	%%
 	{'state_timeout', % Set the state_timeout option
 	 Time :: state_timeout(), EventContent :: term()} |
+	{'state_timeout', % Set the state_timeout option
+	 Time :: state_timeout(),
+	 EventContent :: term(),
+	 Options :: (timeout_option() | [timeout_option()])} |
 	%%
 	reply_action().
 -type reply_action() ::
@@ -287,8 +308,7 @@
       StatusOption :: 'normal' | 'terminate'.
 
 -optional_callbacks(
-   [init/1, % One may use enter_loop/5,6,7 instead
-    format_status/2, % Has got a default implementation
+   [format_status/2, % Has got a default implementation
     terminate/3, % Has got a default implementation
     code_change/4, % Only needed by advanced soft upgrade
     %%
@@ -303,37 +323,26 @@
 %% Type validation functions
 callback_mode(CallbackMode) ->
     case CallbackMode of
-	state_functions ->
-	    true;
-	handle_event_function ->
-	    true;
-	_ ->
-	    false
+	state_functions -> true;
+	handle_event_function -> true;
+	_ -> false
     end.
 %%
-from({Pid,_}) when is_pid(Pid) ->
-    true;
-from(_) ->
-    false.
+from({Pid,_}) when is_pid(Pid) -> true;
+from(_) -> false.
 %%
 event_type({call,From}) ->
     from(From);
 event_type(Type) ->
     case Type of
-	{call,From} ->
-	    from(From);
-	cast ->
-	    true;
-	info ->
-	    true;
-	timeout ->
-	    true;
-	state_timeout ->
-	    true;
-	internal ->
-	    true;
-	_ ->
-	    false
+	{call,From} -> from(From);
+	cast -> true;
+	info -> true;
+	timeout -> true;
+	state_timeout -> true;
+	internal -> true;
+	{timeout,_} -> true;
+	_ -> false
     end.
 
 
@@ -1313,7 +1322,7 @@ parse_enter_actions(Debug, S, State, Actions, Hibernate, TimeoutsR) ->
 
 parse_actions(Debug, S, State, Actions) ->
     Hibernate = false,
-    TimeoutsR = [{timeout,infinity,infinity}], %% Will cancel event timer
+    TimeoutsR = [infinity], %% Will cancel event timer
     Postpone = false,
     NextEventsR = [],
     parse_actions(
@@ -1379,7 +1388,11 @@ parse_actions(
 		     ?STACKTRACE()}
 	    end;
 	%%
-	{state_timeout,_,_} = Timeout ->
+	{{timeout,_},_,_} = Timeout ->
+	    parse_actions_timeout(
+	      Debug, S, State, Actions,
+	      Hibernate, TimeoutsR, Postpone, NextEventsR, Timeout);
+	{{timeout,_},_,_,_} = Timeout ->
 	    parse_actions_timeout(
 	      Debug, S, State, Actions,
 	      Hibernate, TimeoutsR, Postpone, NextEventsR, Timeout);
@@ -1387,6 +1400,18 @@ parse_actions(
 	    parse_actions_timeout(
 	      Debug, S, State, Actions,
 	      Hibernate, TimeoutsR, Postpone, NextEventsR, Timeout);
+	{timeout,_,_,_} = Timeout ->
+	    parse_actions_timeout(
+	      Debug, S, State, Actions,
+	      Hibernate, TimeoutsR, Postpone, NextEventsR, Timeout);
+	{state_timeout,_,_} = Timeout ->
+	    parse_actions_timeout(
+	      Debug, S, State, Actions,
+	      Hibernate, TimeoutsR, Postpone, NextEventsR, Timeout);
+	{state_timeout,_,_,_} = Timeout ->
+	    parse_actions_timeout(
+	      Debug, S, State, Actions,
+	      Hibernate, TimeoutsR, Postpone, NextEventsR, Timeout);
 	Time ->
 	    parse_actions_timeout(
 	      Debug, S, State, Actions,
@@ -1396,26 +1421,64 @@ parse_actions(
 parse_actions_timeout(
   Debug, S, State, Actions,
   Hibernate, TimeoutsR, Postpone, NextEventsR, Timeout) ->
-    Time =
-	case Timeout of
-	    {_,T,_} -> T;
-	    T -> T
-	end,
-    case validate_time(Time) of
-	true ->
-	    parse_actions(
-	      Debug, S, State, Actions,
-	      Hibernate, [Timeout|TimeoutsR],
-	      Postpone, NextEventsR);
-	false ->
-	    {error,
-	     {bad_action_from_state_function,Timeout},
-	     ?STACKTRACE()}
+    case Timeout of
+	{TimerType,Time,TimerMsg,TimerOpts} ->
+	    case validate_timer_args(Time, listify(TimerOpts)) of
+		true ->
+		    parse_actions(
+		      Debug, S, State, Actions,
+		      Hibernate, [Timeout|TimeoutsR],
+		      Postpone, NextEventsR);
+		false ->
+		    NewTimeout = {TimerType,Time,TimerMsg},
+		    parse_actions(
+		      Debug, S, State, Actions,
+		      Hibernate, [NewTimeout|TimeoutsR],
+		      Postpone, NextEventsR);
+		error ->
+		    {error,
+		     {bad_action_from_state_function,Timeout},
+		     ?STACKTRACE()}
+	    end;
+	{_,Time,_} ->
+	    case validate_timer_args(Time, []) of
+		false ->
+		    parse_actions(
+		      Debug, S, State, Actions,
+		      Hibernate, [Timeout|TimeoutsR],
+		      Postpone, NextEventsR);
+		error ->
+		    {error,
+		     {bad_action_from_state_function,Timeout},
+		     ?STACKTRACE()}
+	    end;
+	Time ->
+	    case validate_timer_args(Time, []) of
+		false ->
+		    parse_actions(
+		      Debug, S, State, Actions,
+		      Hibernate, [Timeout|TimeoutsR],
+		      Postpone, NextEventsR);
+		error ->
+		    {error,
+		     {bad_action_from_state_function,Timeout},
+		     ?STACKTRACE()}
+	    end
     end.
 
-validate_time(Time) when is_integer(Time), Time >= 0 -> true;
-validate_time(infinity) -> true;
-validate_time(_) -> false.
+validate_timer_args(Time, Opts) ->
+    validate_timer_args(Time, Opts, false).
+%%
+validate_timer_args(Time, [], true) when is_integer(Time) ->
+    true;
+validate_timer_args(Time, [], false) when is_integer(Time), Time >= 0 ->
+    false;
+validate_timer_args(infinity, [], Abs) ->
+    Abs;
+validate_timer_args(Time, [{abs,Abs}|Opts], _) when is_boolean(Abs) ->
+    validate_timer_args(Time, Opts, Abs);
+validate_timer_args(_, [_|_], _) ->
+    error.
 
 %% Stop and start timers as well as create timeout zero events
 %% and pending event timer
@@ -1431,22 +1494,39 @@ parse_timers(
   TimerRefs, TimerTypes, CancelTimers, [Timeout|TimeoutsR],
   Seen, TimeoutEvents) ->
     case Timeout of
+	{TimerType,Time,TimerMsg,TimerOpts} ->
+	    %% Absolute timer
+	    parse_timers(
+	      TimerRefs, TimerTypes, CancelTimers, TimeoutsR,
+	      Seen, TimeoutEvents,
+	      TimerType, Time, TimerMsg, listify(TimerOpts));
+	%% Relative timers below
+	{TimerType,0,TimerMsg} ->
+	    parse_timers(
+	      TimerRefs, TimerTypes, CancelTimers, TimeoutsR,
+	      Seen, TimeoutEvents,
+	      TimerType, zero, TimerMsg, []);
 	{TimerType,Time,TimerMsg} ->
 	    parse_timers(
-              TimerRefs, TimerTypes, CancelTimers, TimeoutsR,
-              Seen, TimeoutEvents,
-              TimerType, Time, TimerMsg);
+	      TimerRefs, TimerTypes, CancelTimers, TimeoutsR,
+	      Seen, TimeoutEvents,
+	      TimerType, Time, TimerMsg, []);
+	0 ->
+	    parse_timers(
+	      TimerRefs, TimerTypes, CancelTimers, TimeoutsR,
+	      Seen, TimeoutEvents,
+	      timeout, zero, 0, []);
 	Time ->
 	    parse_timers(
-              TimerRefs, TimerTypes, CancelTimers, TimeoutsR,
-              Seen, TimeoutEvents,
-              timeout, Time, Time)
+	      TimerRefs, TimerTypes, CancelTimers, TimeoutsR,
+	      Seen, TimeoutEvents,
+	      timeout, Time, Time, [])
     end.
 
 parse_timers(
   TimerRefs, TimerTypes, CancelTimers, TimeoutsR,
   Seen, TimeoutEvents,
-  TimerType, Time, TimerMsg) ->
+  TimerType, Time, TimerMsg, TimerOpts) ->
     case Seen of
 	#{TimerType := _} ->
 	    %% Type seen before - ignore
@@ -1465,7 +1545,7 @@ parse_timers(
 		    parse_timers(
 		      TimerRefs, NewTimerTypes, NewCancelTimers, TimeoutsR,
 		      NewSeen, TimeoutEvents);
-		0 ->
+		zero ->
 		    %% Cancel any running timer
 		    {NewTimerTypes,NewCancelTimers} =
 			cancel_timer_by_type(
@@ -1478,7 +1558,8 @@ parse_timers(
 		_ ->
 		    %% (Re)start the timer
 		    TimerRef =
-			erlang:start_timer(Time, self(), TimerMsg),
+			erlang:start_timer(
+			  Time, self(), TimerMsg, TimerOpts),
 		    case TimerTypes of
 			#{TimerType := OldTimerRef} ->
 			    %% Cancel the running timer
@@ -1492,6 +1573,8 @@ parse_timers(
 			      NewCancelTimers, TimeoutsR,
 			      NewSeen, TimeoutEvents);
 			#{} ->
+			    %% Insert the new timer into
+			    %% both TimerRefs and TimerTypes
 			    parse_timers(
 			      TimerRefs#{TimerRef => TimerType},
 			      TimerTypes#{TimerType => TimerRef},
diff --git a/lib/stdlib/test/erl_internal_SUITE.erl b/lib/stdlib/test/erl_internal_SUITE.erl
index 099f21f905..789a9d4363 100644
--- a/lib/stdlib/test/erl_internal_SUITE.erl
+++ b/lib/stdlib/test/erl_internal_SUITE.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %% 
-%% Copyright Ericsson AB 1999-2016. All Rights Reserved.
+%% Copyright Ericsson AB 1999-2017. All Rights Reserved.
 %% 
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -60,7 +60,7 @@ end_per_testcase(_Case, _Config) ->
 %% Check that the behaviour callbacks are correctly defined.
 behav(_) ->
     Modules = [application, gen_server, gen_fsm, gen_event,
-               supervisor_bridge, supervisor],
+               gen_statem, supervisor_bridge, supervisor],
     lists:foreach(fun check_behav/1, Modules).
 
 check_behav(Module) ->
@@ -89,6 +89,10 @@ callbacks(gen_event) ->
     [{init,1}, {handle_event,2}, {handle_call,2},
      {handle_info,2}, {terminate,2}, {code_change,3},
      {format_status,2}];
+callbacks(gen_statem) ->
+    [{init, 1}, {callback_mode, 0}, {state_name, 3},
+     {handle_event, 4}, {terminate, 3}, {code_change, 4},
+     {format_status, 2}];
 callbacks(supervisor_bridge) ->
     [{init,1}, {terminate,2}];
 callbacks(supervisor) ->
@@ -102,6 +106,9 @@ optional_callbacks(gen_fsm) ->
     [{handle_info, 3}, {terminate, 3}, {code_change, 4}, {format_status, 2}];
 optional_callbacks(gen_event) ->
     [{handle_info, 2}, {terminate, 2}, {code_change, 3}, {format_status, 2}];
+optional_callbacks(gen_statem) ->
+    [{state_name, 3}, {handle_event, 4},
+     {terminate, 3}, {code_change, 4}, {format_status, 2}];
 optional_callbacks(supervisor_bridge) ->
     [];
 optional_callbacks(supervisor) ->
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index ac27c9fc79..05934b3953 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 2016. All Rights Reserved.
+%% Copyright Ericsson AB 2016-2017. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -38,9 +38,10 @@ all() ->
      {group, abnormal},
      {group, abnormal_handle_event},
      shutdown, stop_and_reply, state_enter, event_order,
-     state_timeout, event_types, code_change,
+     state_timeout, event_types, generic_timers, code_change,
      {group, sys},
-     hibernate, enter_loop].
+     hibernate, enter_loop, {group, undef_callbacks},
+     undef_in_terminate].
 
 groups() ->
     [{start, [], tcs(start)},
@@ -50,7 +51,8 @@ groups() ->
      {abnormal, [], tcs(abnormal)},
      {abnormal_handle_event, [], tcs(abnormal)},
      {sys, [], tcs(sys)},
-     {sys_handle_event, [], tcs(sys)}].
+     {sys_handle_event, [], tcs(sys)},
+     {undef_callbacks, [], tcs(undef_callbacks)}].
 
 tcs(start) ->
     [start1, start2, start3, start4, start5, start6, start7,
@@ -62,8 +64,9 @@ tcs(abnormal) ->
 tcs(sys) ->
     [sys1, call_format_status,
      error_format_status, terminate_crash_format,
-     get_state, replace_state].
-
+     get_state, replace_state];
+tcs(undef_callbacks) ->
+    [undef_code_change, undef_terminate1, undef_terminate2].
 
 init_per_suite(Config) ->
     Config.
@@ -77,6 +80,11 @@ init_per_group(GroupName, Config)
        GroupName =:= abnormal_handle_event;
        GroupName =:= sys_handle_event ->
     [{callback_mode,handle_event_function}|Config];
+init_per_group(undef_callbacks, Config) ->
+    DataDir = ?config(data_dir, Config),
+    StatemPath = filename:join(DataDir, "oc_statem.erl"),
+    {ok, oc_statem} = compile:file(StatemPath),
+    Config;
 init_per_group(_GroupName, Config) ->
     Config.
 
@@ -834,6 +842,7 @@ event_types(_Config) ->
 			{next_event,timeout,3},
 			{next_event,info,4},
 			{next_event,cast,5},
+			{next_event,{timeout,6}, 6},
 			{next_event,Call,Req}]}
 	      end,
 	  state1 =>
@@ -857,6 +866,10 @@ event_types(_Config) ->
 		      {next_state, state6, undefined}
 	      end,
 	  state6 =>
+	      fun ({timeout,6}, 6, undefined) ->
+		      {next_state, state7, undefined}
+	      end,
+	  state7 =>
 	      fun ({call,From}, stop, undefined) ->
 		      {stop_and_reply, shutdown,
 		       [{reply,From,stopped}]}
@@ -884,6 +897,69 @@ event_types(_Config) ->
 
 
 
+generic_timers(_Config) ->
+    process_flag(trap_exit, true),
+
+    Machine =
+	%% Abusing the internal format of From...
+	#{init =>
+	      fun () ->
+		      {ok, start, undefined}
+	      end,
+	  start =>
+	      fun ({call,_} = Call, Req, undefined) ->
+		      {next_state, state1, undefined,
+		       [{{timeout,a},1500,1},
+			{state_timeout,1500,1},
+			{{timeout,b},1000,1},
+			{next_event,Call,Req}]}
+	      end,
+	  state1 =>
+	      fun ({call,_} = Call, Req, undefined) ->
+		      T = erlang:monotonic_time(millisecond) + 500,
+		      {next_state, state2, undefined,
+		       [{{timeout,c},T,2,{abs,true}},
+			{{timeout,d},0,2,[{abs,false}]},
+			{timeout,0,2},
+			{{timeout,b},infinity,2},
+			{{timeout,a},1000,{Call,Req}}]}
+	      end,
+	  state2 =>
+	      fun ({timeout,d}, 2, undefined) ->
+		      {next_state, state3, undefined}
+	      end,
+	  state3 =>
+	      fun ({timeout,c}, 2, undefined) ->
+		      {next_state, state4, undefined}
+	      end,
+	  state4 =>
+	      fun ({timeout,a}, {{call,From},stop}, undefined) ->
+		      {stop_and_reply, shutdown,
+		       [{reply,From,stopped}]}
+	      end},
+    {ok,STM} =
+	gen_statem:start_link(
+	  ?MODULE, {map_statem,Machine,[]}, [{debug,[trace]}]),
+
+    stopped = gen_statem:call(STM, stop),
+    receive
+	{'EXIT',STM,shutdown} ->
+	    ok
+    after 500 ->
+	    ct:fail(did_not_stop)
+    end,
+
+    {noproc,_} =
+	?EXPECT_FAILURE(gen_statem:call(STM, hej), Reason),
+    case flush() of
+	[] ->
+	    ok;
+	Other2 ->
+	    ct:fail({unexpected,Other2})
+    end.
+
+
+
 sys1(Config) ->
     {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     {status, Pid, {module,gen_statem}, _} = sys:get_status(Pid),
@@ -1393,6 +1469,51 @@ enter_loop(Reg1, Reg2) ->
 	    gen_statem:enter_loop(?MODULE, [], state0, [])
     end.
 
+undef_code_change(_Config) ->
+    {ok, Statem} = gen_statem:start(oc_statem, [], []),
+    {error, {'EXIT',
+             {undef, [{oc_statem, code_change, [_, _, _, _], _}|_]}}}
+        = fake_upgrade(Statem, oc_statem).
+
+fake_upgrade(Pid, Mod) ->
+    sys:suspend(Pid),
+    sys:replace_state(Pid, fun(State) -> {new, State} end),
+    Ret = sys:change_code(Pid, Mod, old_vsn, []),
+    ok = sys:resume(Pid),
+    Ret.
+
+undef_terminate1(_Config) ->
+    {ok, Statem} = gen_statem:start(oc_statem, [], []),
+    MRef = monitor(process, Statem),
+    ok = gen_statem:stop(Statem),
+    verify_down(Statem, MRef, normal),
+    ok.
+
+undef_terminate2(_Config) ->
+    Reason = {error, test},
+    {ok, Statem} = oc_statem:start(),
+    MRef = monitor(process, Statem),
+    ok = gen_statem:stop(Statem, Reason, infinity),
+    verify_down(Statem, MRef, Reason).
+
+undef_in_terminate(_Config) ->
+    Data =  {undef_in_terminate, {?MODULE, terminate}},
+    {ok, Statem} = gen_statem:start(?MODULE, {data, Data}, []),
+    try
+        gen_statem:stop(Statem),
+        ct:fail(should_crash)
+    catch
+        exit:{undef, [{?MODULE, terminate, _, _}|_]} ->
+            ok
+    end.
+
+verify_down(Statem, MRef, Reason) ->
+    receive
+        {'DOWN', MRef, process, Statem, Reason} ->
+            ok
+    after 5000 ->
+        ct:fail(default_terminate_failed)
+    end.
 
 %% Test the order for multiple {next_event,T,C}
 next_events(Config) ->
@@ -1571,6 +1692,9 @@ callback_mode() ->
 
 terminate(_, _State, crash_terminate) ->
     exit({crash,terminate});
+terminate(_, _State, {undef_in_terminate, {Mod, Fun}}) ->
+    Mod:Fun(),
+    ok;
 terminate({From,stopped}, State, _Data) ->
     From ! {self(),{stopped,State}},
     ok;
@@ -1597,8 +1721,9 @@ idle({call,From}, {delayed_answer,T}, Data) ->
 	    throw({keep_state,Data})
     end;
 idle({call,From}, {timeout,Time}, _Data) ->
+    AbsTime = erlang:monotonic_time(millisecond) + Time,
     {next_state,timeout,{From,Time},
-     {timeout,Time,idle}};
+     {timeout,AbsTime,idle,[{abs,true}]}};
 idle(cast, next_event, _Data) ->
     {next_state,next_events,[a,b,c],
      [{next_event,internal,a},
diff --git a/lib/stdlib/test/gen_statem_SUITE_data/oc_statem.erl b/lib/stdlib/test/gen_statem_SUITE_data/oc_statem.erl
new file mode 100644
index 0000000000..27c9e0718d
--- /dev/null
+++ b/lib/stdlib/test/gen_statem_SUITE_data/oc_statem.erl
@@ -0,0 +1,37 @@
+%%
+%% %CopyrightBegin%
+%%
+%% Copyright Ericsson AB 2017. All Rights Reserved.
+%%
+%% Licensed under the Apache License, Version 2.0 (the "License");
+%% you may not use this file except in compliance with the License.
+%% You may obtain a copy of the License at
+%%
+%%     http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing, software
+%% distributed under the License is distributed on an "AS IS" BASIS,
+%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%% See the License for the specific language governing permissions and
+%% limitations under the License.
+%%
+%% %CopyrightEnd%
+%%
+-module(oc_statem).
+
+-behaviour(gen_statem).
+
+%% API
+-export([start/0]).
+
+%% gen_statem callbacks
+-export([init/1, callback_mode/0]).
+
+start() ->
+    gen_statem:start({local, ?MODULE}, ?MODULE, [], []).
+
+init([]) ->
+    {ok, state_name, #{}}.
+
+callback_mode() ->
+    handle_event_function.
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index f4d84ab163..0667af7868 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2016</year>
+      <year>2016</year><year>2017</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -293,6 +293,13 @@ StateName(EventType, EventContent, Data) ->
 	<seealso marker="#State Time-Outs">State Time-Outs</seealso>
       </item>
       <item>
+	Start a
+	<seealso marker="stdlib:gen_statem#type-generic_timeout">
+	  generic time-out</seealso>,
+	  read more in section
+	<seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>
+      </item>
+      <item>
 	Start an
 	<seealso marker="stdlib:gen_statem#type-event_timeout">event time-out</seealso>,
 	see more in section
@@ -320,8 +327,9 @@ StateName(EventType, EventContent, Data) ->
 	<c>gen_statem(3)</c>
       </seealso>
       manual page.
-      You can, for example, reply to many callers
-      and generate multiple next events to handle.
+      You can, for example, reply to many callers,
+      generate multiple next events,
+      and set time-outs to relative or absolute times.
     </p>
   </section>
 
@@ -369,6 +377,14 @@ StateName(EventType, EventContent, Data) ->
 	</seealso>
 	state timer timing out.
       </item>
+      <tag><c>{timeout,Name}</c></tag>
+      <item>
+	Generated by state transition action
+	<seealso marker="stdlib:gen_statem#type-generic_timeout">
+	  <c>{{timeout,Name},Time,EventContent}</c>
+	</seealso>
+	generic timer timing out.
+      </item>
       <tag><c>timeout</c></tag>
       <item>
 	Generated by state transition action
@@ -450,7 +466,7 @@ locked(
         [Digit] ->
 	    do_unlock(),
             {next_state, open, Data#{remaining := Code},
-             [{state_timeout,10000,lock}];
+             [{state_timeout,10000,lock}]};
         [Digit|Rest] -> % Incomplete
             {next_state, locked, Data#{remaining := Rest}};
         _Wrong ->
@@ -779,7 +795,7 @@ handle_event(cast, {button,Digit}, State, #{code := Code} = Data) ->
 		[Digit] -> % Complete
 		    do_unlock(),
 		    {next_state, open, Data#{remaining := Code},
-                     [{state_timeout,10000,lock}};
+                     [{state_timeout,10000,lock}]};
 		[Digit|Rest] -> % Incomplete
 		    {keep_state, Data#{remaining := Rest}};
 		[_|_] -> % Wrong
@@ -873,7 +889,7 @@ stop() ->
     <marker id="Event Time-Outs" />
     <title>Event Time-Outs</title>
     <p>
-      A timeout feature inherited from <c>gen_statem</c>'s predecessor
+      A time-out feature inherited from <c>gen_statem</c>'s predecessor
       <seealso marker="stdlib:gen_fsm"><c>gen_fsm</c></seealso>,
       is an event time-out, that is,
       if an event arrives the timer is cancelled.
@@ -906,24 +922,24 @@ locked(
 ...
      ]]></code>
     <p>
-      Whenever we receive a button event we start an event timeout
+      Whenever we receive a button event we start an event time-out
       of 30 seconds, and if we get an event type <c>timeout</c>
       we reset the remaining code sequence.
     </p>
     <p>
-      An event timeout is cancelled by any other event so you either
-      get some other event or the timeout event.  It is therefore
-      not possible nor needed to cancel or restart an event timeout.
+      An event time-out is cancelled by any other event so you either
+      get some other event or the time-out event.  It is therefore
+      not possible nor needed to cancel or restart an event time-out.
       Whatever event you act on has already cancelled
-      the event timeout...
+      the event time-out...
     </p>
   </section>
 
 <!-- =================================================================== -->
 
   <section>
-    <marker id="Erlang Timers" />
-    <title>Erlang Timers</title>
+    <marker id="Generic Time-Outs" />
+    <title>Generic Time-Outs</title>
     <p>
       The previous example of state time-outs only work if
       the state machine stays in the same state during the
@@ -934,13 +950,68 @@ locked(
       You may want to start a timer in one state and respond
       to the time-out in another, maybe cancel the time-out
       without changing states, or perhaps run multiple
-      time-outs in parallel. All this can be accomplished
-      with Erlang Timers:
+      time-outs in parallel. All this can be accomplished with
+      <seealso marker="stdlib:gen_statem#type-generic_timeout">generic time-outs</seealso>.
+      They may look a little bit like
+      <seealso marker="stdlib:gen_statem#type-event_timeout">event time-outs</seealso>
+      but contain a name to allow for any number of them simultaneously
+      and they are not automatically cancelled.
+    </p>
+    <p>
+      Here is how to accomplish the state time-out
+      in the previous example by instead using a generic time-out
+      named <c>open_tm</c>:
+    </p>
+    <code type="erl"><![CDATA[
+...
+locked(
+  cast, {button,Digit},
+  #{code := Code, remaining := Remaining} = Data) ->
+    case Remaining of
+        [Digit] ->
+	    do_unlock(),
+            {next_state, open, Data#{remaining := Code},
+	     [{{timeout,open_tm},10000,lock}]};
+...
+
+open({timeout,open_tm}, lock, Data) ->
+    do_lock(),
+    {next_state,locked,Data};
+open(cast, {button,_}, Data) ->
+    {keep_state,Data};
+...
+    ]]></code>
+    <p>
+      Just as
+      <seealso marker="#State Time-Outs">state time-outs</seealso>
+      you can restart or cancel a specific generic time-out
+      by setting it to a new time or <c>infinity</c>.
+    </p>
+    <p>
+      Another way to handle a late time-out can be to not cancel it,
+      but to ignore it if it arrives in a state
+      where it is known to be late.
+    </p>
+  </section>
+
+<!-- =================================================================== -->
+
+  <section>
+    <marker id="Erlang Timers" />
+    <title>Erlang Timers</title>
+    <p>
+      The most versatile way to handle time-outs is to use
+      Erlang Timers; see
       <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer3,4</c></seealso>.
+      Most time-out tasks can be performed with the
+      time-out features in <c>gen_statem</c>,
+      but an example of one that can not is if you should need
+      the return value from
+      <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>, that is; the remaining time of the timer.
     </p>
     <p>
       Here is how to accomplish the state time-out
-      in the previous example by insted using an Erlang Timer:
+      in the previous example by instead using an Erlang Timer:
     </p>
     <code type="erl"><![CDATA[
 ...
@@ -1596,7 +1667,7 @@ handle_event(
   {call,From}, code_length,
   {_StateName,_LockButton}, #{code := Code}) ->
     {keep_state_and_data,
-    [{reply,From,length(Code)}]};
+     [{reply,From,length(Code)}]};
 %%
 %% State: locked
 handle_event(
@@ -1636,7 +1707,7 @@ handle_event(
 	    if
 		Digit =:= LockButton ->
 		    {next_state, {locked,LockButton}, Data,
-		     [{reply,From,locked}]);
+		     [{reply,From,locked}]};
 		true ->
 		    {keep_state_and_data,
 		     [postpone]}
@@ -1710,10 +1781,10 @@ handle_event(
   EventType, EventContent,
   {open,LockButton}, Data) ->
     case {EventType, EventContent} of
-	{enter, _OldState} ->
-	    do_unlock(),
-	    {keep_state_and_data,
-	    [{state_timeout,10000,lock},hibernate]};
+        {enter, _OldState} ->
+            do_unlock(),
+            {keep_state_and_data,
+             [{state_timeout,10000,lock},hibernate]};
 ...
     ]]></code>
     <p>