-spec call(ServerRef :: server_ref(), Request :: term()) -> Reply :: term().

Equivalent to call(ServerRef, Request, infinity).

-spec call(ServerRef :: server_ref(),
           Request :: term(),
           Timeout :: timeout() | {clean_timeout, T :: timeout()} | {dirty_timeout, T :: timeout()}) ->
              Reply :: term().

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/0 {call,From} and event content Request.

A Reply is generated when a state callback returns with {reply,From,Reply} as one action/0, 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.

Previous issue with late replies that could occur when having network issues or using dirty_timeout is now prevented by use of process aliases. {clean_timeout, T} and {dirty_timeout, T} therefore no longer serves any purpose and will work the same as Timeout while all of them also being equally efficient.

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

When this call fails it exits the calling process. The exit term is on the form {Reason, Location} where Location = {gen_statem,call,ArgList}. See gen_server:call/3 that has a description of relevant values for the Reason in the exit term.

-spec cast(ServerRef :: server_ref(), Msg :: term()) -> ok.

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/0 cast and event content Msg.

-spec check_response(Msg, ReqId) -> Result
                        when
                            Msg :: term(),
                            ReqId :: request_id(),
                            Response ::
                                {reply, Reply :: term()} | {error, {Reason :: term(), server_ref()}},
                            Result :: Response | no_reply.

Check if Msg is a response corresponding to the request identifier ReqId.

The request must have been made by send_request/2. If Msg is a reply to the handle ReqId 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/0, 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.

-spec check_response(Msg, ReqIdCollection, Delete) -> Result
                        when
                            Msg :: term(),
                            ReqIdCollection :: request_id_collection(),
                            Delete :: boolean(),
                            Response ::
                                {reply, Reply :: term()} | {error, {Reason :: term(), server_ref()}},
                            Result ::
                                {Response,
                                 Label :: term(),
                                 NewReqIdCollection :: request_id_collection()} |
                                no_request | no_reply.

Check if Msg is a response corresponding to a request identifier saved in ReqIdCollection. All request identifiers of ReqIdCollection must correspond to requests that have been made using send_request/2 or send_request/4, and all requests must have been made by the process calling this function.

The Label in the response equals the Label associated with the request identifier that the response corresponds to. The Label of a request identifier is associated when saving the request id in a request identifier collection, or when sending the request using send_request/4.

Compared to check_response/2, the returned result associated with a specific request identifier or an exception associated with a specific request identifier will be wrapped in a 3-tuple. The first element of this tuple equals the value that would have been produced by check_response/2, the second element equals the Label associated with the specific request identifier, and the third element NewReqIdCollection is a possibly modified request identifier collection.

If ReqIdCollection is empty, the atom no_request will be returned. If Msg does not correspond to any of the request identifiers in ReqIdCollection, the atom no_reply is returned.

If Delete equals true, the association with Label will have been deleted from ReqIdCollection in the resulting NewReqIdCollection. If Delete equals false, NewReqIdCollection will equal ReqIdCollection. Note that deleting an association is not for free and that a collection containing already handled requests can still be used by subsequent calls to check_response/3, receive_response/3, and wait_response/3. However, without deleting handled associations, the above calls will not be able to detect when there are no more outstanding requests to handle, so you will have to keep track of this some other way than relying on a no_request return. Note that if you pass a collection only containing associations of already handled or abandoned requests to check_response/3, it will always return no_reply.

-spec enter_loop(Module :: module(), Opts :: [enter_loop_opt()], State :: state(), Data :: data()) ->
                    no_return().

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

-spec enter_loop(Module :: module(),
                 Opts :: [enter_loop_opt()],
                 State :: state(),
                 Data :: data(),
                 Server_or_Actions :: server_name() | pid() | [action()]) ->
                    no_return().

If Server_or_Actions is a list/0, the same as enter_loop/6 except that no server_name/0 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 = [].

-spec enter_loop(Module :: module(),
                 Opts :: [enter_loop_opt()],
                 State :: state(),
                 Data :: data(),
                 Server :: server_name() | pid(),
                 Actions :: [action()] | action()) ->
                    no_return().

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/0 an anonymous server is created just as when using start[_link|_monitor]/3. If Server is a server_name/0 a named server is created just as when using start[_link|_monitor]/4. However, the server_name/0 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/0.

-spec receive_response(ReqId) -> Result
                          when
                              ReqId :: request_id(),
                              Response ::
                                  {reply, Reply :: term()} | {error, {Reason :: term(), server_ref()}},
                              Result :: Response | timeout.

Equivalent to receive_response(ReqId, infinity).

-spec receive_response(ReqId, Timeout) -> Result
                          when
                              ReqId :: request_id(),
                              Timeout :: response_timeout(),
                              Response ::
                                  {reply, Reply :: term()} | {error, {Reason :: term(), server_ref()}},
                              Result :: Response | timeout.

Receive a response corresponding to the request identifier ReqId- The request must have been made by 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 specifies how long to wait for a response. If no response is received within the specified time, the function returns timeout. Assuming that the server executes on a node supporting aliases (introduced in OTP 24) the request will also be abandoned. That is, no response will be received after a timeout. Otherwise, a stray 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/0, 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/2 and receive_response/2 is that receive_response/2 abandons the request at timeout so that a potential future response is ignored, while wait_response/2 does not.

-spec receive_response(ReqIdCollection, Timeout, Delete) -> Result
                          when
                              ReqIdCollection :: request_id_collection(),
                              Timeout :: response_timeout(),
                              Delete :: boolean(),
                              Response ::
                                  {reply, Reply :: term()} | {error, {Reason :: term(), server_ref()}},
                              Result ::
                                  {Response,
                                   Label :: term(),
                                   NewReqIdCollection :: request_id_collection()} |
                                  no_request | timeout.

Receive a response corresponding to a request identifier saved in ReqIdCollection. All request identifiers of ReqIdCollection must correspond to requests that have been made using send_request/2 or send_request/4, and all requests must have been made by the process calling this function.

The Label in the response equals the Label associated with the request identifier that the response corresponds to. The Label of a request identifier is associated when adding the request id in a request identifier collection, or when sending the request using send_request/4.

Compared to receive_response/2, the returned result associated with a specific request identifier will be wrapped in a 3-tuple. The first element of this tuple equals the value that would have been produced by receive_response/2, the second element equals the Label associated with the specific request identifier, and the third element NewReqIdCollection is a possibly modified request identifier collection.

If ReqIdCollection is empty, the atom no_request will be returned.

Timeout specifies how long to wait for a response. If no response is received within the specified time, the function returns timeout. Assuming that the server executes on a node supporting aliases (introduced in OTP 24) all requests identified by ReqIdCollection will also be abandoned. That is, no responses will be received after a timeout. Otherwise, stray responses might be received at a later time.

The difference between receive_response/3 and wait_response/3 is that receive_response/3 abandons the requests at timeout so that potential future responses are ignored, while wait_response/3 does not.

If Delete equals true, the association with Label will have been deleted from ReqIdCollection in the resulting NewReqIdCollection. If Delete equals false, NewReqIdCollection will equal ReqIdCollection. Note that deleting an association is not for free and that a collection containing already handled requests can still be used by subsequent calls to receive_response/3, check_response/3, and wait_response/3. However, without deleting handled associations, the above calls will not be able to detect when there are no more outstanding requests to handle, so you will have to keep track of this some other way than relying on a no_request return. Note that if you pass a collection only containing associations of already handled or abandoned requests to receive_response/3, it will always block until a timeout determined by Timeout is triggered.

-spec reply(Replies :: [reply_action()] | reply_action()) -> ok.

Send a reply or multiple replies using one or several reply_action/0s from a state callback.

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.

Note

A reply sent with this function is not visible in sys debug output.

-spec reply(From :: from(), Reply :: term()) -> ok.

Send a Reply to From.

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.

Note

A reply sent with this function is not visible in sys debug output.

-spec reqids_add(ReqId :: request_id(), Label :: term(), ReqIdCollection :: request_id_collection()) ->
                    NewReqIdCollection :: request_id_collection().

Saves ReqId and associates a Label with the request identifier by adding this information to ReqIdCollection and returning the resulting request identifier collection.

-spec reqids_new() -> NewReqIdCollection :: request_id_collection().

Returns a new empty request identifier collection. A request identifier collection can be utilized in order the handle multiple outstanding requests.

Request identifiers of requests made by send_request/2 can be saved in a request identifier collection using reqids_add/3. Such a collection of request identifiers can later be used in order to get one response corresponding to a request in the collection by passing the collection as argument to receive_response/3, wait_response/3, or, check_response/3.

reqids_size/1 can be used to determine the amount of request identifiers in a request identifier collection.

-spec reqids_size(ReqIdCollection :: request_id_collection()) -> non_neg_integer().

Returns the amount of request identifiers saved in ReqIdCollection.

-spec reqids_to_list(ReqIdCollection :: request_id_collection()) ->
                        [{ReqId :: request_id(), Label :: term()}].

Returns a list of {ReqId, Label} tuples which corresponds to all request identifiers with their associated labels present in the ReqIdCollection collection.

-spec send_request(ServerRef :: server_ref(), Request :: term()) -> ReqId :: request_id().

Sends an asynchronous call request Request to the gen_statem process identified by ServerRef and returns a request identifier ReqId.

The return value ReqId shall later be used with receive_response/2, wait_response/2, or check_response/2 to fetch the actual result of the request. Besides passing the request identifier directly to these functions, it can also be saved in a request identifier collection using reqids_add/3. Such a collection of request identifiers can later be used in order to get one response corresponding to a request in the collection by passing the collection as argument to receive_response/3, wait_response/3, or check_response/3. If you are about to save the request identifier in a request identifier collection, you may want to consider using send_request/4 instead.

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/0 {call,From} and event content Request.

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

-spec send_request(ServerRef :: server_ref(),
                   Request :: term(),
                   Label :: term(),
                   ReqIdCollection :: request_id_collection()) ->
                      NewReqIdCollection :: request_id_collection().

Sends an asynchronous call request Request to the gen_statem process identified by ServerRef. The Label will be associated with the request identifier of the operation and added to the returned request identifier collection NewReqIdCollection. The collection can later be used in order to get one response corresponding to a request in the collection by passing the collection as argument to receive_response/3, wait_response/3, or, check_response/3.

The same as calling gen_statem:reqids_add(statem:send_request(ServerRef, Request), Label, ReqIdCollection), but calling send_request/4 is slightly more efficient.

-spec start(Module :: module(), Args :: term(), Opts :: [start_opt()]) -> start_ret().

Equivalent to start/4 except that the gen_statem process is not registered with any name service.

-spec start(ServerName :: server_name(), Module :: module(), Args :: term(), Opts :: [start_opt()]) ->
               start_ret().

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/4.

-spec start_link(Module :: module(), Args :: term(), Opts :: [start_opt()]) -> start_ret().

Equivalent to start_link/4 except that the gen_statem process is not registered with any name service.

-spec start_link(ServerName :: server_name(), Module :: module(), Args :: term(), Opts :: [start_opt()]) ->
                    start_ret().

Creates a gen_statem process according to OTP design principles (using proc_lib primitives) that is spawned as 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 or failed.

ServerName specifies the server_name/0 to register for the gen_statem process. If the gen_statem process is started with start_link/3, no ServerName is provided and the gen_statem process 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 process is allowed to spend Time milliseconds initializing or it is terminated 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.

Note

Using spawn option monitor is not allowed, it causes this function to fail with reason badarg.

If the gen_statem process is successfully created and initialized, this function returns {ok,Pid}, where Pid is the pid/0 of the gen_statem process. If a process with the specified ServerName exists already, this function returns {error,{already_started,OtherPid}}, where OtherPid is the pid/0 of that process, and the gen_statem process exits with reason normal before calling Module:init/1.

If Module:init/1 does not return within the start timeout, the gen_statem process is killed with exit(_, kill), and this function returns {error,timeout}.

This function returns {error,Reason} if Module:init/1 returns {stop,Reason} or {error,Reason}, or fails with reason Reason. This function returns ignore if Module:init/1 returns ignore. In these cases the gen_statem process exits with reason Reason, except when Module:init/1 returns ignore or {error,_}; then the gen_statem process exits with reason normal.

If start_link/3,4 returns ignore or {error,_}, the started gen_statem process has terminated. If an 'EXIT' message was delivered to the calling process (due to the process link), that message has been consumed.

Warning

Before OTP 26.0, if the started gen_statem process returned e.g. {stop,Reason} from Module:init/1, this function could return {error,Reason} before the started gen_statem process had terminated so starting again might fail because VM resources such as the registered name was not yet unregistered, and an 'EXIT' message could arrive later to the process calling this function.

But if the started gen_statem process instead failed during Module:init/1, a process link {'EXIT',Pid,Reason} message caused this function to return {error,Reason} so the 'EXIT' message had been consumed and the started gen_statem process had terminated.

Since it was impossible to tell the difference between these two cases from start_link/3,4's return value, this inconsistency was cleaned up in OTP 26.0.

The difference between returning {stop,_} and {error,_} from Module:init/1, is that {error,_} results in a graceful ("silent") termination since the gen_statem process exits with reason normal.

-spec start_monitor(Module :: module(), Args :: term(), Opts :: [start_opt()]) -> start_mon_ret().

Equivalent to start_monitor/4 except that the gen_statem process is not registered with any name service.

-spec start_monitor(ServerName :: server_name(),
                    Module :: module(),
                    Args :: term(),
                    Opts :: [start_opt()]) ->
                       start_mon_ret().

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.

-spec stop(ServerRef :: server_ref()) -> ok.

Equivalent to stop(ServerRef, normal, infinity).

-spec stop(ServerRef :: server_ref(), Reason :: term(), Timeout :: timeout()) -> ok.

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. 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, the call exits the calling process with reason timeout.

If the process does not exist, the call exits the calling process with reason noproc, and with reason {nodedown,Node} if the connection fails to the remote Node where the server runs.

-spec wait_response(ReqId) -> Result
                       when
                           ReqId :: request_id(),
                           Response ::
                               {reply, Reply :: term()} | {error, {Reason :: term(), server_ref()}},
                           Result :: Response | timeout.

Equivalent to receive_response(ReqId, infinity).

-spec wait_response(ReqId, WaitTime) -> Result
                       when
                           ReqId :: request_id(),
                           WaitTime :: response_timeout(),
                           Response ::
                               {reply, Reply :: term()} | {error, {Reason :: term(), server_ref()}},
                           Result :: Response | timeout.

Wait for a response corresponding to the request identifier ReqId. The request must have been made by send_request/2 to the gen_statem process. This function must be called from the same process from which send_request/2 was made.

WaitTime specifies how long to wait for a reply. 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/0, 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/2 and wait_response/2 is that receive_response/2 abandons the request at timeout so that a potential future response is ignored, while wait_response/2 does not.

-spec wait_response(ReqIdCollection, WaitTime, Delete) -> Result
                       when
                           ReqIdCollection :: request_id_collection(),
                           WaitTime :: response_timeout(),
                           Delete :: boolean(),
                           Response ::
                               {reply, Reply :: term()} | {error, {Reason :: term(), server_ref()}},
                           Result ::
                               {Response,
                                Label :: term(),
                                NewReqIdCollection :: request_id_collection()} |
                               no_request | timeout.

Wait for a response corresponding to a request identifier saved in ReqIdCollection. All request identifiers of ReqIdCollection must correspond to requests that have been made using send_request/2 or send_request/4, and all requests must have been made by the process calling this function.

The Label in the response equals the Label associated with the request identifier that the response corresponds to. The Label of a request identifier is associated when saving the request id in a request identifier collection, or when sending the request using send_request/4.

Compared to wait_response/2, the returned result associated with a specific request identifier or an exception associated with a specific request identifier will be wrapped in a 3-tuple. The first element of this tuple equals the value that would have been produced by wait_response/2, the second element equals the Label associated with the specific request identifier, and the third element NewReqIdCollection is a possibly modified request identifier collection.

If ReqIdCollection is empty, no_request will be returned. If no response is received before the WaitTime timeout has triggered, the atom timeout is returned. It is valid to continue waiting for a response as many times as needed up until a response has been received and completed by check_response(), receive_response(), or wait_response().

The difference between receive_response/3 and wait_response/3 is that receive_response/3 abandons requests at timeout so that potential future responses are ignored, while wait_response/3 does not.

If Delete equals true, the association with Label will have been deleted from ReqIdCollection in the resulting NewReqIdCollection. If Delete equals false, NewReqIdCollection will equal ReqIdCollection. Note that deleting an association is not for free and that a collection containing already handled requests can still be used by subsequent calls to wait_response/3, check_response/3, and receive_response/3. However, without deleting handled associations, the above calls will not be able to detect when there are no more outstanding requests to handle, so you will have to keep track of this some other way than relying on a no_request return. Note that if you pass a collection only containing associations of already handled or abandoned requests to wait_response/3, it will always block until a timeout determined by WaitTime is triggered and then return no_reply.