Description
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.