This behavior module provides the server of a client-server
relation. A generic server process (gen_server) implemented using
this module has a standard set of interface functions and
includes functionality for tracing and error reporting. It also
fits into an OTP supervision tree. For more information, see section
gen_server Behaviour in OTP Design Principles.
A gen_server process assumes all specific parts to be located in
a callback module exporting a predefined set of functions.
The relationship between the behavior functions and the callback
functions is as follows:
gen_server module Callback module
----------------- ---------------
gen_server:start
gen_server:start_monitor
gen_server:start_link -----> Module:init/1
gen_server:stop -----> Module:terminate/2
gen_server:call
gen_server:send_request
gen_server:multi_call -----> Module:handle_call/3
gen_server:cast
gen_server:abcast -----> Module:handle_cast/2
- -----> Module:handle_info/2
- -----> Module:handle_continue/2
- -----> Module:terminate/2
- -----> Module:code_change/3
If a callback function fails or returns a bad value, the
gen_server process terminates.
A gen_server process handles system messages as described in
sys(3). The sys module
can be used for debugging a gen_server process.
Notice that a gen_server process 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 process does not exist or if bad
arguments are specified.
The gen_server process can go into hibernation
(see
erlang:hibernate/3) if a callback
function specifies 'hibernate' instead of a time-out value. This
can be useful if the server is expected to be idle for a long
time. However, use this feature with care, as hibernation
implies at least two garbage collections (when hibernating and
shortly after waking up) and is not something you want to do
between each call to a busy server.
If the gen_server process needs to perform an action
immediately after initialization or to break the execution of a
callback into multiple steps, it can return {continue,Continue}
in place of the time-out or hibernation value, which will immediately
invoke the handle_continue/2 callback.
If the gen_server process terminates, e.g.
as a result of a function in the callback module returning
{stop,Reason,NewState}, an exit signal with this Reason
is sent to linked processes and ports. See
Processes in the Reference Manual for details
regarding error handling using exit signals.
Note
For some important information about distributed signals, see the
Blocking Signaling Over Distribution section in the
Processes chapter of the Erlang Reference Manual.
Blocking signaling can, for example, cause call timeouts in
gen_server to be significantly delayed.