A behaviour module for implementing the server of a client-server
relation. A generic server process (gen_server) 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
A gen_server 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:
gen_server module Callback module ----------------- --------------- gen_server:start_link -----> Module:init/1 gen_server:call gen_server:multi_call -----> Module:handle_call/3 gen_server:cast gen_server:abcast -----> Module:handle_cast/2 - -----> Module:handle_info/2 - -----> Module:terminate/2 - -----> Module:code_change/3
If a callback function fails or returns a bad value, the gen_server will terminate.
A gen_server handles system messages as documented in
Note that a gen_server does not trap exit signals automatically, this must be explicitly initiated in the callback module.
Unless otherwise stated, all functions in this module fail if the specified gen_server does not exist or if bad arguments are given.
The gen_server process can go into hibernation
(see
Creates a gen_server 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_server is linked to the supervisor.
The gen_server process calls
If
If the option
If the option
If the option
Using the spawn option
If the gen_server is successfully created and initialized
the function returns
If
Creates a stand-alone gen_server process, i.e. a gen_server which is not part of a supervision tree and thus has no supervisor.
See
Makes a synchronous call to the gen_server
The return value
The call may fail for several reasons, including timeout and the called gen_server dying before or during the call.
The ancient behaviour 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.
Makes a synchronous call to all gen_servers locally
registered as
The function returns a tuple
When a reply
If one of the nodes is not capable of process monitors,
for example C or Java nodes, and the gen_server is not started
when the requests are sent, but starts within 2 seconds,
this function waits the whole
This problem does not exist if all nodes are Erlang nodes.
To prevent late answers (after the timeout) from polluting the caller's message queue, a middleman process is used to do the actual calls. Late answers will then be discarded when they arrive to a terminated process.
Sends an asynchronous request to the gen_server
See
Sends an asynchronous request to the gen_servers locally
registered as
See
This function can be used by a gen_server to explicitly send
a reply to a client that called
The return value
Makes an existing process into a gen_server. Does not return,
instead the calling process will enter the gen_server receive
loop and become a gen_server 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_server behaviour provides.
Failure: If the calling process was not started by a
The following functions
should be exported from a
Whenever a gen_server is started using
If the initialization is successful, the function should
return
If an integer timeout value is provided, a timeout will occur
unless a request or a message is received within
If
If something goes wrong during the initialization
the function should return
Whenever a gen_server receives a request sent using
If the function returns
If the functions returns
If the function returns
Whenever a gen_server receives a request sent using
See
This function is called by a gen_server when a timeout occurs or when it receives any other message than a synchronous or asynchronous request (or a system message).
See
This function is called by a gen_server when it is about to
terminate. It should be the opposite of
If the gen_server is part of a supervision tree and is
ordered by its supervisor to terminate, this function will be
called with
Even if the gen_server is not part of a supervision tree,
this function will be called if it receives an
Otherwise, the gen_server will be immediately terminated.
Note that for any other reason than
This function is called by a gen_server when it should
update its internal state during a release upgrade/downgrade,
i.e. when the instruction
In the case of an upgrade,
If successful, the function shall return the updated internal state.
If the function returns
This callback is optional, so callback modules need not export it. The gen_server module provides a default implementation of this function that returns the callback module state.
This function is called by a gen_server process when:
This function is useful for customising the form and
appearance of the gen_server 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 representations to avoid having large state terms printed in logfiles.