gen_statem

Makes a synchronous call to the gen_statem ServerRef by sending a request and waiting until its reply arrives. The gen_statem calls the state callback with event_type() {call,From} and event content Request.

A Reply is generated when a state callback returns with {reply,From,Reply} as one action(), and that Reply becomes the return value of this function.

Timeout is an integer > 0, which specifies how many milliseconds to wait for a reply, or the atom infinity to wait indefinitely, which is the default. If no reply is received within the specified time, the function call fails.

Timeout can also be a tuple {clean_timeout,T} or {dirty_timeout,T}, where T is the time-out time. {clean_timeout,T} works like just T described in the note above and uses a proxy process while {dirty_timeout,T} bypasses the proxy process which is more lightweight.

The call can also fail, for example, if the gen_statem dies before or during this function call.

Sends an asynchronous event to the gen_statem ServerRef and returns ok immediately, ignoring if the destination node or gen_statem does not exist. The gen_statem calls the state callback with event_type() cast and event content Msg.

This function is used to check if a previously received message, for example by receive or handle_info/2, is a result of a request made with send_request/2. If Msg is a reply to the handle RequestId the result of the request is returned in Reply. Otherwise returns no_reply and no cleanup is done, and thus the function shall be invoked repeatedly until a reply is returned.

The return value Reply is generated when a state callback returns with {reply,From,Reply} as one action(), and that Reply becomes the return value of this function.

The function returns an error if the gen_statem dies before or during this request.

The same as enter_loop/6 with Actions = [] except that no server_name() must have been registered. This creates an anonymous server.

If Server_or_Actions is a list(), the same as enter_loop/6 except that no server_name() must have been registered and Actions = Server_or_Actions. This creates an anonymous server.

Otherwise the same as enter_loop/6 with Server = Server_or_Actions and Actions = [].

Makes the calling process become a gen_statem. Does not return, instead the calling process enters the gen_statem receive loop and becomes a gen_statem server. The process must have been started using one of the start functions in proc_lib. The user is responsible for any initialization of the process, including registering a name for it.

This function is useful when a more complex initialization procedure is needed than the gen_statem behavior provides.

Module, Opts have the same meaning as when calling start[_link|_monitor]/3,4.

If Server is self() an anonymous server is created just as when using start[_link|_monitor]/3. If Server is a server_name() a named server is created just as when using start[_link|_monitor]/4. However, the server_name() name must have been registered accordingly before this function is called.

State, Data, and Actions have the same meanings as in the return value of Module:init/1. Also, the callback module does not need to export a Module:init/1 function.

The function fails if the calling process was not started by a proc_lib start function, or if it is not registered according to server_name().

This function is used to receive for a reply of a request made with send_request/2 to the gen_statem process. This function must be called from the same process from which send_request/2 was made.

Timeout is an integer greater then or equal to zero that specifies how many milliseconds to wait for an reply, or the atom infinity to wait indefinitely. Defaults to infinity. If no reply is received within the specified time, the function returns timeout. Assuming that the server executes on a node supporting aliases (introduced in OTP 24) no response will be received after a timeout. Otherwise, a garbage response might be received at a later time.

The return value Reply is generated when a state callback returns with {reply,From,Reply} as one action(), and that Reply becomes the return value of this function.

The function returns an error if the gen_statem dies before or during this function call.

The difference between wait_response() and receive_response() is that receive_response() abandons the request at timeout so that a potential future response is ignored, while wait_response() does not.

This function can be used by a gen_statem to explicitly send a reply to a process that waits in call/2 when the reply cannot be defined in the return value of a state callback.

From must be the term from argument {call,From} to the state callback. A reply or multiple replies canalso be sent using one or several reply_action()s from a state callback.

Sends a request to the gen_statem ServerRef and returns a handle RequestId.

The return value RequestId shall later be used with receive_response/1,2, wait_response/1,2, or check_response/2 to fetch the actual result of the request.

The call gen_statem:wait_response(gen_statem:send_request(ServerRef,Request), Timeout) can be seen as equivalent to gen_statem:call(Server,Request,Timeout), ignoring the error handling.

The gen_statem calls the state callback with event_type() {call,From} and event content Request.

A Reply is generated when a state callback returns with {reply,From,Reply} as one action(), and that Reply becomes the return value of receive_response/1,2, wait_response/1,2, or check_response/2 function.

Creates a standalone gen_statem process according to OTP design principles (using proc_lib primitives). As it does not get linked to the calling process, this start function cannot be used by a supervisor to start a child.

For a description of arguments and return values, see start_link/3,4.

Creates a gen_statem process according to OTP design principles (using proc_lib primitives) that is linked to the calling process. This is essential when the gen_statem must be part of a supervision tree so it gets linked to its supervisor.

The gen_statem process calls Module:init/1 to initialize the server. To ensure a synchronized startup procedure, start_link/3,4 does not return until Module:init/1 has returned.

ServerName specifies the server_name() to register for the gen_statem. If the gen_statem is started with start_link/3, no ServerName is provided and the gen_statem is not registered.

Module is the name of the callback module.

Args is an arbitrary term that is passed as the argument to Module:init/1.

• If option {timeout,Time} is present in Opts, the gen_statem is allowed to spend Time milliseconds initializing or it terminates and the start function returns {error,timeout}.

• If option {hibernate_after,HibernateAfterTimeout} is present, the gen_statem process awaits any message for HibernateAfterTimeout milliseconds and if no message is received, the process goes into hibernation automatically (by calling proc_lib:hibernate/3).

• If option {debug,Dbgs} is present in Opts, debugging through sys is activated.

• If option {spawn_opt,SpawnOpts} is present in Opts, SpawnOpts is passed as option list to erlang:spawn_opt/2, which is used to spawn the gen_statem process.

If the gen_statem is successfully created and initialized, this function returns {ok,Pid}, where Pid is the pid() of the gen_statem. If a process with the specified ServerName exists already, this function returns {error,{already_started,Pid}}, where Pid is the pid() of that process.

If Module:init/1 fails with Reason, this function returns {error,Reason}. If Module:init/1 returns {stop,Reason} or ignore, the process is terminated and this function returns {error,Reason} or ignore, respectively. An exit signal with the same Reason (or normal if Module:init/1 returns ignore) is set to linked processes and ports, including the process calling start_link/3,4.

Creates a standalone gen_statem process according to OTP design principles (using proc_lib primitives) and atomically sets up a monitor to the newly created process. As it does not get linked to the calling process, this start function cannot be used by a supervisor to start a child.

For a description of arguments and return values, see start_link/3,4. Note that the return value on successful start differs from start_link/3,4. start_monitor/3,4 will return {ok,{Pid,Mon}} where Pid is the process identifier of the process, and Mon is a reference to the monitor set up to monitor the process. If the start is not successful, the caller will be blocked until the DOWN message has been received and removed from the message queue.

The same as stop(ServerRef, normal, infinity).

Orders the gen_statem ServerRef to exit with the specified Reason and waits for it to terminate. The gen_statem calls Module:terminate/3 before exiting.

This function returns ok if the server terminates with the expected reason. Any other reason than normal, shutdown, or {shutdown,Term} causes an error report to be issued through logger(3). An exit signal with the same reason is sent to linked processes and ports. The default Reason is normal.

Timeout is an integer > 0, which specifies how many milliseconds to wait for the server to terminate, or the atom infinity to wait indefinitely. Defaults to infinity. If the server does not terminate within the specified time, a timeout exception is raised.

If the process does not exist, a noproc exception is raised.

This function is used to wait for a reply of a request made with send_request/2 to the gen_statem process. This function must be called from the same process from which send_request/2 was made.

Timeout is an integer greater then or equal to zero that specifies how many milliseconds to wait for an reply, or the atom infinity to wait indefinitely. Defaults to infinity. If no reply is received within the specified time, the function returns timeout and no cleanup is done, and thus the function can be invoked repeatedly until a reply is returned.

The return value Reply is generated when a state callback returns with {reply,From,Reply} as one action(), and that Reply becomes the return value of this function.

The function returns an error if the gen_statem dies before or during this function call.

The difference between receive_response() and wait_response() is that receive_response() abandons the request at timeout so that a potential future response is ignored, while wait_response() does not.

Types

This function is called by a gen_statem when it needs to find out the callback mode of the callback module. The value is cached by gen_statem for efficiency reasons, so this function is only called once after server start, after code change, and after changing the callback module, but before the first state callback in the current callback module's code version is called. More occasions may be added in future versions of gen_statem.

Server start happens either when Module:init/1 returns or when enter_loop/4-6 is called. Code change happens when Module:code_change/4 returns. A change of the callback module happens when a state callback returns any of the actions change_callback_module, push_callback_module or pop_callback_module.

The CallbackMode is either just callback_mode() or a list containing callback_mode() and possibly the atom state_enter.

Types

This function is called by a gen_statem when it is to update its internal state during a release upgrade/downgrade, that is, when the instruction {update,Module,Change,...}, where Change = {advanced,Extra}, is specified in the appup file. For more information, see OTP Design Principles.

For an upgrade, OldVsn is Vsn, and for a downgrade, OldVsn is {down,Vsn}. Vsn is defined by the vsn attribute(s) of the old version of the callback module Module. If no such attribute is defined, the version is the checksum of the Beam file.

OldState and OldData is the internal state of the gen_statem.

Extra is passed "as is" from the {advanced,Extra} part of the update instruction.

If successful, the function must return the updated internal state in an {ok,NewState,NewData} tuple.

If the function returns a failure Reason, the ongoing upgrade fails and rolls back to the old release. Note that Reason cannot be an {ok,_,_} tuple since that will be regarded as a {ok,NewState,NewData} tuple, and that a tuple matching {ok,_} is an also invalid failure Reason. It is recommended to use an atom as Reason since it will be wrapped in an {error,Reason} tuple.

Also note when upgrading a gen_statem, this function and hence the Change = {advanced,Extra} parameter in the appup file is not only needed to update the internal state or to act on the Extra argument. It is also needed if an upgrade or downgrade should change callback mode, or else the callback mode after the code change will not be honoured, most probably causing a server crash.

If the server changes callback module using any of the actions change_callback_module, push_callback_module or pop_callback_module, be aware that it is always the current callback module that will get this callback call. That the current callback module handles the current state and data update should be no surprise, but it must be able to handle even parts of the state and data that it is not familiar with, somehow.

In the supervisor child specification there is a list of modules which is recommended to contain only the callback module. For a gen_statem with multiple callback modules there is no real need to list all of them, it may not even be possible since the list could change after code upgrade. If this list would contain only the start callback module, as recommended, what is important is to upgrade that module whenever a synchronized code replacement is done. Then the release handler concludes that an upgrade that upgrades that module needs to suspend, code change, and resume any server whose child specification declares that it is using that module. And again; the current callback module will get the Module:code_change/4 call.

Types

Whenever a gen_statem is started using start_link/3,4, start_monitor/3,4, or start/3,4, this function is called by the new process to initialize the implementation state and server data.

Args is the Args argument provided to that start function.

init(Args) -> erlang:error(not_implemented, [Args]).

Types

This function is called by a gen_statem process when any of the following apply:

• One of sys:get_status/1,2 is invoked to get the gen_statem status. Opt is set to the atom normal for this case.
• The gen_statem terminates abnormally and logs an error. Opt is set to the atom terminate for this case.

This function is useful for changing the form and appearance of the gen_statem status for these cases. A callback module wishing to change the sys:get_status/1,2 return value and how its status appears in termination error logs exports an instance of format_status/2, which returns a term describing the current status of the gen_statem.

PDict is the current value of the process dictionary of the gen_statem.

State is the internal state of the gen_statem.

Data is the internal server data of the gen_statem.

The function is to return Status, a term that contains the appropriate details of the current state and status of the gen_statem. There are no restrictions on the form Status can take, but for the sys:get_status/1,2 case (when Opt is normal), the recommended form for the Status value is [{data, [{"State", Term}]}], where Term provides relevant details of the gen_statem state. Following this recommendation is not required, but it makes the callback module status consistent with the rest of the sys:get_status/1,2 return value.

One use for this function is to return compact alternative state representations to avoid having large state terms printed in log files. Another use is to hide sensitive data from being written to the error log.

Types

Whenever a gen_statem receives an event from call/2, cast/2, or as a normal process message, one of these functions is called. If callback mode is state_functions, Module:StateName/3 is called, and if it is handle_event_function, Module:handle_event/4 is called.

If EventType is {call,From}, the caller waits for a reply. The reply can be sent from this or from any other state callback by returning with {reply,From,Reply} in Actions, in Replies, or by calling reply(From, Reply).

If this function returns with a next state that does not match equal (=/=) to the current state, all postponed events are retried in the next state.

The only difference between StateFunctionResult and HandleEventResult is that for StateFunctionResult the next state must be an atom, but for HandleEventResult there is no restriction on the next state.

For options that can be set and actions that can be done by gen_statem after returning from this function, see action().

When the gen_statem runs with state enter calls, these functions are also called with arguments (enter, OldState, ...) during every state change. In this case there are some restrictions on the actions that may be returned: postpone() is not allowed since a state enter call is not an event so there is no event to postpone, and {next_event,_,_} is not allowed since using state enter calls should not affect how events are consumed and produced. You may also not change states from this call. Should you return {next_state,NextState, ...} with NextState =/= State the gen_statem crashes. Note that it is actually allowed to use {repeat_state, NewData, ...} although it makes little sense since you immediately will be called again with a new state enter call making this just a weird way of looping, and there are better ways to loop in Erlang. If you do not update NewData and have some loop termination condition, or if you use {repeat_state_and_data, _} or repeat_state_and_data you have an infinite loop! You are advised to use {keep_state,...}, {keep_state_and_data,_} or keep_state_and_data since changing states from a state enter call is not possible anyway.

Note the fact that you can use throw to return the result, which can be useful. For example to bail out with throw(keep_state_and_data) from deep within complex code that cannot return {next_state,State,Data} because State or Data is no longer in scope.

Types

This function is called by a gen_statem when it is about to terminate. It is to be the opposite of Module:init/1 and do any necessary cleaning up. When it returns, the gen_statem terminates with Reason. The return value is ignored.

Reason is a term denoting the stop reason and State is the internal state of the gen_statem.

Reason depends on why the gen_statem is terminating. If it is because another callback function has returned, a stop tuple {stop,Reason} in Actions, Reason has the value specified in that tuple. If it is because of a failure, Reason is the error reason.

If the gen_statem is part of a supervision tree and is ordered by its supervisor to terminate, this function is called with Reason = shutdown if both the following conditions apply:

• The gen_statem has been set to trap exit signals.

• The shutdown strategy as defined in the supervisor's child specification is an integer time-out value, not brutal_kill.

Even if the gen_statem is not part of a supervision tree, this function is called if it receives an 'EXIT' message from its parent. Reason is the same as in the 'EXIT' message.

Otherwise, the gen_statem is immediately terminated.

Notice that for any other reason than normal, shutdown, or {shutdown,Term}, the gen_statem is assumed to terminate because of an error and an error report is issued using logger(3).

When the gen_statem process exits, an exit signal with the same reason is sent to linked processes and ports.