From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?=
There is a new behaviour
A behaviour module for implementing a finite state machine.
- A generic finite state machine process (gen_fsm) implemented
- using this module will have a standard set of interface functions
- and include functionality for tracing and error reporting. It will
- also fit into an OTP supervision tree. Refer to
- This behavior module provides a finite state machine.
+ A generic finite state machine process ( A gen_fsm assumes all specific parts to be located in a callback
- module exporting a pre-defined set of functions. The relationship
- between the behaviour functions and the callback functions can be
- illustrated as follows: A If a callback function fails or returns a bad value, the gen_fsm
- will terminate. A gen_fsm handles system messages as documented in
- Note that a gen_fsm does not trap exit signals automatically,
- this must be explicitly initiated in the callback module. If a callback function fails or returns a bad value, the A Notice that a Unless otherwise stated, all functions in this module fail if
- the specified gen_fsm does not exist or if bad arguments are
- given. The gen_fsm process can go into hibernation
- (see
gen_fsm module Callback module
-------------- ---------------
@@ -73,34 +74,261 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
- -----> Module:terminate/3
- -----> Module:code_change/4
-
The
Cancels an internal timer referred by
If the timer has already timed out, but the event not yet + been delivered, it is cancelled as if it had not + timed out, so there is no false timer event after + returning from this function.
+Returns the remaining time in milliseconds until the timer would
+ have expired if
Makes an existing process into a
This function is useful when a more complex initialization
+ procedure is needed than the
The function fails if the calling process was not started by a
+
This function can be used by a
Return value
Sends an event asynchronously to the
For a description of the arguments, see
+
The difference between
Sends an event asynchronously to the
Sends a delayed event internally in the
The
Creates a standalone
For a description of arguments and return values, see
+
Creates a gen_fsm process as part of a supervision tree. - The function should be called, directly or indirectly, by - the supervisor. It will, among other things, ensure that - the gen_fsm is linked to the supervisor.
-The gen_fsm process calls
Creates a
The
If
If no name is provided, - the gen_fsm is not registered.
+If
If
If
If no name is provided, the
If the option
If option
If the option
If the option
If option
If option
Using the spawn option
Using spawn option
If the gen_fsm is successfully created and initialized
- the function returns
If the
If
Creates a stand-alone gen_fsm process, i.e. a gen_fsm which - is not part of a supervision tree and thus has no supervisor.
-See
Sends a time-out event internally in the
The
Orders a generic FSM to exit with the given
The function returns
Orders a generic finite state machine to exit with the specified
+
The function returns
If the process does not exist, a
Sends an event asynchronously to the gen_fsm
If the process does not exist, a
Sends an event asynchronously to the gen_fsm
See
The difference between
Sends an event to the
For a description of
For a discussion about the difference between
+
Sends an event to the gen_fsm
Sends an event to the
See
For a description of
The return value
Return value
The ancient behaviour of sometimes consuming the server
+ The ancient behavior of sometimes consuming the server
exit message if the server died during the call while
- linked to the client has been removed in OTP R12B/Erlang 5.6.
The following functions are to be exported from a
state name denotes a state of the state machine.
+ +state data denotes the internal state of the Erlang process + that implements the state machine.
+Sends an event to the gen_fsm
See
See
-
This function is called by a
For an upgrade,
The function is to return the new current state name and + updated internal data.
This function can be used by a gen_fsm to explicitly send a
- reply to a client process that called
-
The return value
This callback is optional, so callback modules need not
+ export it. The
This function is called by a
This function is useful for changing the form and
+ appearance of the
The function is to return
One use for this function is to return compact alternative + state data representations to avoid that large state terms + are printed in log files.
Sends a delayed event internally in the gen_fsm that calls
- this function after
The gen_fsm will call
Sends a timeout event internally in the gen_fsm that calls
- this function after
The gen_fsm will call
Whenever a
For a description of the other arguments and possible return values,
+ see
Cancels an internal timer referred by
If the timer has already timed out, but the event not yet - been delivered, it is cancelled as if it had not - timed out, so there will be no false timer event after - returning from this function.
-Returns the remaining time in ms until the timer would
- have expired if
This function is called by a
For a description of the other arguments and possible return values,
+ see
Makes an existing process into a gen_fsm. Does not return,
- instead the calling process will enter the gen_fsm receive
- loop and become a gen_fsm process. The process must
- have been started using one of the start functions in
-
This function is useful when a more complex initialization - procedure is needed than the gen_fsm behaviour provides.
-Failure: If the calling process was not started by a
-
Whenever a
For a description of the other arguments and possible return values,
+ see
The following functions should be exported from a
In the description, the expression state name is used to - denote a state of the state machine. state data is used - to denote the internal state of the Erlang process which - implements the state machine.
-Whenever a gen_fsm is started using
-
Whenever a
If initialization is successful, the function should return
-
If initialization is successful, the function is to return
+
If an integer timeout value is provided, a timeout will occur
+ state data of the
If an integer time-out value is provided, a time-out occurs
unless an event or a message is received within
If
If something goes wrong during the initialization
- the function should return
If
If the initialization fails, the function returns
+
There should be one instance of this function for each
- possible state name. Whenever a gen_fsm receives an event
- sent using
-
There is to be one instance of this function for each
+ possible state name. Whenever a
If the function returns
If the function returns
Whenever a gen_fsm receives an event sent using
-
See
There should be one instance of this function for each
- possible state name. Whenever a gen_fsm receives an event
- sent using
-
There is to be one instance of this function for each
+ possible state name. Whenever a
If the function returns
-
If the function returns
-
If the function returns
-
Whenever a gen_fsm receives an event sent using
-
See
This function is called by a gen_fsm when it receives any - other message than a synchronous or asynchronous event (or a - system message).
-See
If
If
If the function returns
+
This function is called by a gen_fsm when it is about to
- terminate. It should be the opposite of
This function is called by a
If the gen_fsm is part of a supervision tree and is ordered - by its supervisor to terminate, this function will be called +
If the
The
The shutdown strategy as defined in the child specification of
+ the supervisor is an integer time-out value, not
+
Even if the gen_fsm is not part of a supervision tree,
- this function will be called if it receives an
Otherwise, the gen_fsm will be immediately terminated.
-Note that for any other reason than
This function is called by a gen_fsm when it should update
- its internal state data during a release upgrade/downgrade,
- i.e. when the instruction
In the case of an upgrade,
The function should return the new current state name and - updated internal data.
-This callback is optional, so callback modules need not - export it. The gen_fsm module provides a default - implementation of this function that returns the callback - module state data.
-This function is called by a gen_fsm process when:
-This function is useful for customising the form and
- appearance of the gen_fsm status for these cases. A callback
- module wishing to customise the
The function should return
One use for this function is to return compact alternative - state data representations to avoid having large state terms - printed in logfiles.
+Even if the
Otherwise, the
Notice that for any other reason than