# gen_server

### MODULE

gen_server

### MODULE SUMMARY

Generic Server Behaviour

### DESCRIPTION

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 OTP Design Principles for more information.

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.

The `sys` module can be used for debugging a gen_server.

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.

### EXPORTS

`start_link(Module, Args, Options) -> Result`
`start_link(ServerName, Module, Args, Options) -> Result`

Types:

`ServerName = {local,Name} | {global,GlobalName}`
`Name = atom()`
`GlobalName = term()`
`Module = atom()`
`Args = term()`
`Options = [Option]`
`Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}`
`Dbgs = [Dbg]`
`Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}`
`SOpts = [term()]`
`Result = {ok,Pid} | ignore | {error,Error}`
`Pid = pid()`
`Error = {already_started,Pid} | term()`

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 `Module:init/1` to initialize. To ensure a synchronized start-up procedure, `start_link/3,4` does not return until `Module:init/1` has returned.

If `ServerName={local,Name}` the gen_server is registered locally as `Name` using `register/2`. If `ServerName={global,GlobalName}` the gen_server is registered globally as `GlobalName` using `global:register_name/2`. If no name is provided, the gen_server is not registered.

`Module` is the name of the callback module.

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

If the option `{timeout,Time}` is present, the gen_server is allowed to spend `Time` milliseconds initializing or it will be terminated and the start function will return `{error,timeout}`.

If the option `{debug,Dbgs}` is present, the corresponding `sys` function will be called for each item in `Dbgs`. Refer to `sys(3)` for more information.

If the option `{spawn_opt,SOpts}` is present, `SOpts` will be passed as option list to the `spawn_opt` BIF which is used to spawn the gen_server. Refer to `erlang(3)` for information about the `spawn_opt` options.

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

If `Module:init/1` fails with `Reason`, the function returns `{error,Reason}`. If `Module:init/1` returns `{stop,Reason}` or `ignore`, the process is terminated and the function returns `{error,Reason}` or `ignore`, respectively.

`start(Module, Args, Options) -> Result`
`start(ServerName, Module, Args, Options) -> Result`

Types:

`ServerName = {local,Name} | {global,GlobalName}`
`Name = atom()`
`GlobalName = term()`
`Module = atom()`
`Args = term()`
`Options = [Option]`
`Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}`
`Dbgs = [Dbg]`
`Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}`
`SOpts = [term()]`
`Result = {ok,Pid} | ignore | {error,Error}`
`Pid = pid()`
`Error = {already_started,Pid} | term()`

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 `start_link/3,4` for a description of arguments and return values.

`call(ServerRef, Request) -> Reply`
`call(ServerRef, Request, Timeout) -> Reply`

Types:

`ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()`
`Node = atom()`
`GlobalName = term()`
`Request = term()`
`Timeout = int()>0 | infinity`
`Reply = term()`

Makes a synchronous call to the gen_server `ServerRef` by sending a request and waiting until a reply arrives or a timout occurs. The gen_server will call `Module:handle_call/3` to handle the request.

`ServerRef` can be:

- the pid,
- `Name`, if the gen_server is locally registered,
- `{Name,Node}`, if the gen_server is locally registered at another node, or
- `{global,GlobalName}`, if the gen_server is globally registered.

`Request` is an arbitrary term which is passed as one of the arguments to `Module:handle_call/3`.

`Timeout` is an integer greater than zero which specifies how many milliseconds to wait for a reply, or the atom `infinity` to wait indefinitely. Default value is 5000. If no reply is received within the specified time, the function call fails.

The return value `Reply` is defined in the return value of `Module:handle_call/3`.

The call may fail for several reasons, including timeout and the called gen_server dying before or during the call.

There is a special case for backwards compatibility. If

- the client is linked to the gen server, and
- the client is trapping exits, and
- the gen_server terminates while handling the request

then the exit message is removed from the client's receive queue before the function call fails. This special-case behaviour may be removed in the future because it is inconsistent with the behaviour when a gen_server dies between calls and also because the exit message cannot be removed in some circumstances, for instance when `ServerRef = {Name, Node}` and `Node` goes down.

`multi_call(Name, Request) -> Result`
`multi_call(Nodes, Name, Request) -> Result`
`multi_call(Nodes, Name, Request, Timeout) -> Result`

Types:

`Nodes = [Node]`
`Node = atom()`
`Name = atom()`
`Request = term()`
`Timeout = int()>=0 | infinity`
`Result = {Replies,BadNodes}`
`Replies = [{Node,Reply}]`
`Reply = term()`
`BadNodes = [Node]`

Makes a synchronous call to all gen_servers locally registered as `Name` at the specified nodes by first sending a request to every node and then waiting for the replies. The gen_servers will call `Module:handle_call/3` to handle the request.

The function returns a tuple `{Replies,BadNodes}` where `Replies` is a list of `{Node,Reply}` and `BadNodes` is a list of node that either did not exist, or where the gen_server `Name` did not exist or did not reply.

`Nodes` is a list of node names to which the request should be sent. Default value is the list of all known nodes `[node()|nodes()]`.

`Name` is the locally registered name of each gen_server.

`Request` is an arbitrary term which is passed as one of the arguments to `Module:handle_call/3`.

`Timeout` is an integer greater than zero which specifies how many milliseconds to wait for each reply, or the atom `infinity` to wait indefinitely. Default value is `infinity`. If no reply is received from a node within the specified time, the node is added to `BadNodes`.

When a reply `Reply` is received from the gen_server at a node `Node`, `{Node,Reply}` is added to `Replies`. `Reply` is defined in the return value of `Module:handle_call/3`.

| If one of the nodes is running Erlang/OTP R6B or older, and the gen_server is not started when the requests are sent, but starts within 2 seconds, this function waits the whole `Timeout`, which may be infinity. This problem does not exist if all nodes are running Erlang/OTP R7B or later.

This function does not read out any exit messages like `call/2,3` does.

The previously undocumented functions `safe_multi_call/2,3,4` were removed in OTP R7B/Erlang 5.0 since this function is now safe, except in the case mentioned above.

To avoid that late answers (after the timeout) pollutes 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.

`cast(ServerRef, Request) -> ok`

Types:

`ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()`
`Node = atom()`
`GlobalName = term()`
`Request = term()`

Sends an asynchronous request to the gen_server `ServerRef` and returns `ok` immediately, ignoring if the destination node or gen_server does not exist. The gen_server will call `Module:handle_cast/2` to handle the request.

See `call/2,3` for a description of `ServerRef`.

`Request` is an arbitrary term which is passed as one of the arguments to `Module:handle_cast/2`.

`abcast(Name, Request) -> abcast`
`abcast(Nodes, Name, Request) -> abcast`

Types:

`Nodes = [Node]`
`Node = atom()`
`Name = atom()`
`Request = term()`

Sends an asynchronous request to the gen_servers locally registered as `Name` at the specified nodes. The function returns immediately and ignores nodes that does not exist, or where the gen_server `Name` does not exist. The gen_servers will call `Module:handle_cast/2` to handle the request.

See `multi_call/2,3,4` for a description of the arguments.

`reply(Client, Reply) -> true`

Types:

`Client - see below`
`Reply = term()`

This function can be used by a gen_server to explicitly send a reply to a client that called `call` or `multi_call`, when the reply cannot be defined in the return value of `Module:handle_call/3`.

`Client` must be the `From` argument provided to the callback function. `Reply` is an arbitrary term, which will be given back to the client as the return value of `call` or `multi_call`.

`enter_loop(Module, Options, State)`
`enter_loop(Module, Options, State, ServerName)`
`enter_loop(Module, Options, State, Timeout)`
`enter_loop(Module, Options, State, ServerName, Timeout)`

Types:

`Module = atom()`
`Options = [Option]`
`Option = {debug,Dbgs}`
`Dbgs = [Dbg]`
`Dbg = trace | log | statistics`
`| {log_to_file,FileName} | {install,{Func,FuncState}}`
`State = term()`
`ServerName = {local,Name} | {global,GlobalName}`
`Name = atom()`
`GlobalName = term()`
`Timeout = int() | infinity`

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 `proc_lib`, see proc_lib(3). The user is responsible for any initialization of the process, including registering a name for it.

This function is useful when a more complex initalization procedure is needed than the gen_server behaviour provides.

`Module`, `Options` and `ServerName` have the same meanings as when calling gen_server:start[_link]/3,4. However, if `ServerName` is specified, the process must have been registered accordingly before this function is called.

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

Failure: If the calling process was not started by a `proc_lib` start function, or if it is not registered according to `ServerName`.

### CALLBACK FUNCTIONS

The following functions should be exported from a `gen_server` callback module.

### EXPORTS

`Module:init(Args) -> Result`

Types:

`Args = term()`
`Result = {ok,State} | {ok,State,Timeout}`
`| {stop,Reason} | ignore`
`State = term()`
`Timeout = int()>=0 | infinity`
`Reason = term()`

Whenever a gen_server is started using `gen_server:start/3,4` or `gen_server:start_link/3.4`, this function is called by the new process to initialize.

`Args` is the `Args` argument provided to the start function.

If the initialization is successful, the function should return `{ok,State}` or `{ok,State,Timout}`, where `State` is the internal state of the gen_server.

If an integer timout value is provided, a timout will occur unless a request or a message is received within `Timeout` milliseconds. A timout is represented by the atom `timeout` which should be handled by the `handle_info/2` callback function. The atom `inifinity` can be used to wait indefinitely, this is the default value.

If something goes wrong during the initialization the function should return `{stop,Reason}` where `Reason` is any term, or `ignore`.

`Module:handle_call(Request, From, State) -> Result`

Types:

`Request = term()`
`From = {pid(),Tag}`
`State = term()`
`Result = {reply,Reply,NewState} | {reply,Reply,NewState,Timeout}`
`| {noreply,NewState} | {noreply,NewState,Timeout}`
`| {stop,Reason,Reply,NewState} | {stop,Reason,NewState}`
`Reply = term()`
`NewState = term()`
`Timeout = int()>=0 | infinity`
`Reason = term()`

Whenever a gen_server receives a request sent using `gen_server:call/2,3` or `gen_server:multi_call/2,3,4`, this function is called to handle the request.

`Request` is the `Request` argument provided to `call` or `multi_call`.

`From` is a tuple `{Pid,Tag}` where `Pid` is the pid of the client and `Tag` is a unique tag.

`State` is the internal state of the gen_server.

If the function returns `{reply,Reply,NewState}` or `{reply,Reply,NewState,Timout}`, `Reply` will be given back to `From` as the return value of `call` or included in the return value of `multi_call`. The gen_server then continues executing with the possibly updated internal state `NewState`. See `Module:init/1` for a description of `Timeout`.

If the functions returns `{noreply,NewState}` or `{noreply,NewState,Timeout}`, the gen_server will continue executing with `NewState`. Any reply to `From` must be given explicitly using `gen_server:reply/2`.

If the function returns `{stop,Reason,Reply,NewState}`, `Reply` will be given back to `From`. If the function returns `{stop,Reason,NewState}`, any reply to `From` must be given explicitly using `gen_server:reply/2`. The gen_server will then call `Module:terminate(Reason,NewState)` and terminate.

`Module:handle_cast(Request, State) -> Result`

Types:

`Request = term()`
`State = term()`
`Result = {noreply,NewState} | {noreply,NewState,Timeout}`
`| {stop,Reason,NewState}`
`NewState = term()`
`Timeout = int()>=0 | infinity`
`Reason = term()`

Whenever a gen_server receives a request sent using `gen_server:cast/2` or `gen_server:abcast/2,3`, this function is called to handle the request.

See `Module:handle_call/3` for a description of the arguments and possible return values.

`Module:handle_info(Info, State) -> Result`

Types:

`Info = timeout | term()`
`State = term()`
`Result = {noreply,NewState} | {noreply,NewState,Timeout}`
`| {stop,Reason,NewState}`
`NewState = term()`
`Timeout = int()>=0 | infinity`
`Reason = normal | term()`

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

`Info` is either the atom `timeout`, if a timeout has occured, or the received message.

See `Module:handle_call/3` for a description of the other arguments and possible return values.

`Module:terminate(Reason, State)`

Types:

`Reason = normal | shutdown | term()`
`State = term()`

This function is called by a gen_server when it is about to terminate. It should be the opposite of `Module:init/1` and do any necessary cleaning up. When it returns, the gen_server 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_server.

`Reason` depends on why the gen_server is terminating. If it is because another callback function has returned a stop tuple `{stop,..}`, `Reason` will have the value specified in that tuple. If it is due to a failure, `Reason` is the error reason.

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

- the gen_server has been set to trap exit signals, and
- the shutdown strategy as defined in the supervisor's child specification is an integer timeout value, not `brutal_kill`.

Otherwise, the gen_server will be immediately terminated.

Note that for any other reason than `normal` or `shutdown`, the gen_server is assumed to terminate due to an error and an error report is issued using `error_logger:format/2`.

`Module:code_change(OldVsn, State, Extra) -> {ok, NewState}`

Types:

`OldVsn = Vsn | {down, Vsn}`
`Vsn = term()`
`State = NewState = term()`
`Extra = term()`

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 `{update,Module,Change,...}` where `Change={advanced,Extra}` is given in the `appup` file. See OTP Design Principles for more information.

In the case of an upgrade, `OldVsn` is `Vsn`, and in the case of 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.

`State` is the internal state of the gen_server.

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

The function should return the updated internal state.

### SEE ALSO

supervisor(3), sys(3)

### AUTHORS

Gunilla Arendt - support@erlang.ericsson.se

stdlib 1.14.1
Copyright © 1991-2006 Ericsson AB