From d30cae56d82763681b633cba25ad553eb672ec16 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 6 Apr 2017 16:09:38 +0200 Subject: Make Module:init/1 mandatory --- lib/stdlib/doc/src/gen_statem.xml | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 5eb13db1aa..f7baaad5d1 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -146,7 +146,7 @@ erlang:'!' -----> Module:StateName/3 This gathers all code for a specific state in one function as the gen_statem engine branches depending on state name. - Notice the fact that there is a mandatory callback function + Note the fact that the callback function Module:terminate/3 makes the state name terminate unusable in this mode.

@@ -1704,7 +1704,7 @@ handle_event(_, _, State, Data) -> Module:init(Args) -> Result(StateType) - Optional function for initializing process and internal state. + Initializing process and internal state. Args = term() @@ -1720,7 +1720,7 @@ handle_event(_, _, State, Data) -> start_link/3,4 or start/3,4, - 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.

@@ -1729,13 +1729,16 @@ handle_event(_, _, State, Data) ->

- This callback is optional, so a callback module does not need - to export it, but most do. If this function is not exported, - the gen_statem should be started through + Note that if the gen_statem is started trough proc_lib and - enter_loop/4-6. + enter_loop/4-6, + this callback will never be called. + Since this callback is not optional it can + in that case be implemented as:

+ 
+init(Args) -> erlang:error(not_implemented, [Args]).
 -- cgit v1.2.3 From bca4b5c87fd1aae2fdcb78b605181393a0caf9d9 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 7 Feb 2017 22:38:36 +0100 Subject: Implement erlang:start_timer opts --- lib/stdlib/doc/src/gen_statem.xml | 75 ++++++++++++++++++++++++++++----------- 1 file changed, 55 insertions(+), 20 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index f7baaad5d1..44ac1ad8ad 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -785,28 +785,38 @@ handle_event(_, _, State, Data) ->

- Generates an event of + Starts a timer set by + enter_action() + timeout. + When the timer expires an event of event_type() - timeout - after this time (in milliseconds) unless another - event arrives or has arrived - in which case this time-out is cancelled. + timeout will be generated. + See + erlang:start_timer/4 + for how Time and + Options + are interpreted. All Options of erlang:start_timer/4 + will not necessarily be supported in the future. +

+

+ 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.

- If the value is infinity, no timer is started, as - it never would trigger anyway. + If Time is infinity, + no timer is started, as it never would expire anyway.

- If the value is 0 no timer is actually started, + If Time is relative and 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, + Note that it is not possible nor needed to cancel this time-out, as it is cancelled automatically by any other event.

@@ -815,19 +825,26 @@ handle_event(_, _, State, Data) ->

- Generates an event of + Starts a timer set by + enter_action() + state_timeout. + When the timer expires 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. + state_timeout will be generated. + See + erlang:start_timer/4 + for how Time and + Options + are interpreted. All Options of erlang:start_timer/4 + will not necessarily be supported in the future.

- If the value is infinity, no timer is started, as - it never would trigger anyway. + If Time is infinity, + no timer is started, as it never would expire anyway.

- If the value is 0 no timer is actually started, + If Time is relative and 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. @@ -839,6 +856,20 @@ handle_event(_, _, State, Data) ->

+ + + +

+ If Abs is true an absolute timer is started, + and if it false a relative, which is the default. + See + erlang:start_timer/4 + for details. +

+

+

+ + @@ -954,7 +985,9 @@ handle_event(_, _, State, Data) -> Sets the transition_option() event_timeout() - to Time with EventContent. + to Time with EventContent + and options + Options.

state_timeout @@ -963,7 +996,9 @@ handle_event(_, _, State, Data) -> Sets the transition_option() state_timeout() - to Time with EventContent. + to Time with EventContent + and options + Options.

-- cgit v1.2.3 From 30cae2492d8d8e927d57c0dc656ee2dfbec0a70c Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Mon, 13 Feb 2017 08:20:16 +0100 Subject: Implement {timeout,Name} timeouts --- lib/stdlib/doc/src/gen_statem.xml | 100 +++++++++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 23 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 44ac1ad8ad..1b99b65e09 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -67,13 +67,16 @@ It has the same features and adds some really useful:

- State code is gathered. - The state can be any term. - Events can be postponed. - Events can be self-generated. - Automatic state enter code can be called. - A reply can be sent from a later state. - There can be multiple sys traceable replies. + Gathered state code. + Arbitrary term state. + Event postponing. + Self-generated events. + State time-out. + Multiple generic named time-outs. + Absolute time-out time. + Automatic state enter calls. + Reply from other state than the request. + Multiple sys traceable replies.

The callback model(s) for gen_statem differs from @@ -531,10 +534,12 @@ handle_event(_, _, State, Data) -> originate from the corresponding API functions. For calls, the event contains whom to reply to. Type info originates from regular process messages sent - to the gen_statem. Also, the state machine - implementation can generate events of types - timeout, state_timeout, - and internal to itself. + to the gen_statem. The state machine + implementation can, in addition to the above, + generate + events of types + timeout, {timeout,Name}, + state_timeout, and internal to itself.

@@ -701,13 +706,14 @@ handle_event(_, _, State, Data) ->

- Timeout timers - state_timeout() + Time-out timers + event_timeout(), + generic_timeout() and - event_timeout() + state_timeout() 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.

@@ -795,8 +801,8 @@ handle_event(_, _, State, Data) -> erlang:start_timer/4 for how Time and Options - are interpreted. All Options of erlang:start_timer/4 - will not necessarily be supported in the future. + are interpreted. Future erlang:start_timer/4 Options + will not necessarily be supported.

Any event that arrives cancels this time-out. @@ -821,6 +827,42 @@ handle_event(_, _, State, Data) ->

+ + + +

+ Starts a timer set by + enter_action() + {timeout,Name}. + When the timer expires an event of + event_type() + {timeout,Name} will be generated. + See + erlang:start_timer/4 + for how Time and + Options + are interpreted. Future erlang:start_timer/4 Options + will not necessarily be supported. +

+

+ If Time is infinity, + no timer is started, as it never would expire anyway. +

+

+ If Time is relative and 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 a timer with the same Name 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 infinity. +

+ + @@ -835,8 +877,8 @@ handle_event(_, _, State, Data) -> erlang:start_timer/4 for how Time and Options - are interpreted. All Options of erlang:start_timer/4 - will not necessarily be supported in the future. + are interpreted. Future erlang:start_timer/4 Options + will not necessarily be supported.

If Time is infinity, @@ -861,7 +903,7 @@ handle_event(_, _, State, Data) ->

If Abs is true an absolute timer is started, - and if it false a relative, which is the default. + and if it is false a relative, which is the default. See erlang:start_timer/4 for details. @@ -986,7 +1028,19 @@ handle_event(_, _, State, Data) -> transition_option() event_timeout() to Time with EventContent - and options + and time-out options + Options. +

+ + {timeout,Name} + +

+ Sets the + transition_option() + generic_timeout() + to Time for Name + with EventContent + and time-out options Options.

@@ -997,7 +1051,7 @@ handle_event(_, _, State, Data) -> transition_option() state_timeout() to Time with EventContent - and options + and time-out options Options.

@@ -1270,7 +1324,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?

-- cgit v1.2.3 From eff1ee5ebf1d767d610cd6bc059e5f4dea57d2af Mon Sep 17 00:00:00 2001 From: Zandra Norman Date: Mon, 23 Jan 2017 17:06:48 +0100 Subject: stdlib: Make gen_statem callbacks optional --- lib/stdlib/doc/src/gen_statem.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 1b99b65e09..bc86415d28 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -1733,6 +1733,16 @@ handle_event(_, _, State, Data) -> Reason = term() + +

+ This callback is optional, so callback modules need not export it. + If a release upgrade/downgrade with + Change={advanced,Extra} + specified in the .appup file is made + when code_change/4 is not implemented + the process will crash with exit reason undef. +

+

This function is called by a gen_statem when it is to update its internal state during a release upgrade/downgrade, -- cgit v1.2.3