Module gen_server

Description
Data Types
Function Index
Function Details

An implementation of the Erlang/OTP gen_server interface.

This module defines the gen_server behaviour.
Required callback functions: init/1, handle_call/3, handle_cast/2.

Description

This module implements a strict subset of the Erlang/OTP gen_server interface, supporting operations for local creation and management of gen_server instances.

This module is designed to be API-compatible with gen_server, with exceptions noted below.

Caveats:

Support only for locally named procs
No support for abcast
No support for enter_loop
No support for format_status
No support for multi_call

Data Types

from()


from() = any()

options()


options() = [{atom(), term()}]

server_ref()


server_ref() = atom() | pid()

Function Index

call/2	Send a request to a gen_server instance, and wait for a reply.
call/3	Send a request to a gen_server instance, and wait for a reply.
cast/2	Send a request to a gen_server instance.
init_it/4
init_it/5
reply/2	Send a reply to a calling client.
start/3	Start an un-named gen_server.
start/4	Start a named gen_server.
start_link/3	Start and link an un-named gen_server.
start_link/4	Start and link a named gen_server.
start_monitor/3	Start and monitor an un-named gen_server.
start_monitor/4	Start and monitor a named gen_server.
stop/1	Stop a previously started gen_server instance.
stop/3	Stop a previously started gen_server instance.

Function Details

call/2


call(ServerRef::server_ref(), Request::term()) -> Reply::term() | {error, Reason::term()}

Equivalent to call(ServerRef, Request, 5000).

Send a request to a gen_server instance, and wait for a reply.

call/3


call(ServerRef::server_ref(), Request::term(), TimeoutMs::timeout()) -> Reply::term() | {error, Reason::term()}

ServerRef: a reference to the gen_server acquired via start
Request: the request to send to the gen_server
TimeoutMs: the amount of time in milliseconds to wait for a reply

returns: the reply sent back from the gen_server; {error, Reason}, otherwise.

Send a request to a gen_server instance, and wait for a reply.

This function will send the specified request to the specified gen_server instance, and wait at least Timeout milliseconds for a reply from the gen_server.

cast/2


cast(ServerRef::server_ref(), Request::term()) -> ok | {error, Reason::term()}

ServerRef: a reference to the gen_server acquired via start
Request: the request to send to the gen_server

returns: ok | {error, Reason}

Send a request to a gen_server instance.

This function will send the specified request to the specified gen_server instance, but will not wait for a reply.

init_it/4

init_it(Starter, Module, Args, Options) -> any()

init_it/5

init_it(Starter, Name, Module, Args, Options) -> any()

reply/2


reply(From::from(), Reply::term()) -> term()

From: the client to whom to send the reply
Reply: the reply to send to the client

returns: an arbitrary term, that should be ignored

Send a reply to a calling client.

This function will send the specified reply back to the specified gen_server client (e.g, via call/3). The return value of this function can be safely ignored.

start/3


start(Module::module(), Args::term(), Options::options()) -> {ok, pid()} | {error, Reason::term()}

Module: the module in which the gen_server callbacks are defined
Args: the arguments to pass to the module’s init callback
Options: the options used to create the gen_server

returns: the gen_server pid, if successful; {error, Reason}, otherwise.

Start an un-named gen_server.

This function will start a gen_server instance.

Note. The Options argument is currently ignored.

start/4


start(ServerName::{local, Name::atom()}, Module::module(), Args::term(), Options::options()) -> {ok, pid()} | {error, Reason::term()}

ServerName: the name with which to register the gen_server
Module: the module in which the gen_server callbacks are defined
Args: the arguments to pass to the module’s init callback
Options: the options used to create the gen_server

returns: the gen_server pid, if successful; {error, Reason}, otherwise.

Start a named gen_server.

This function will start a gen_server instance and register the newly created process with the process registry. Subsequent calls may use the gen_server name, in lieu of the process id.

Note. The Options argument is currently ignored.

start_link/3


start_link(Module::module(), Args::term(), Options::options()) -> {ok, pid()} | {error, Reason::term()}

Module: the module in which the gen_server callbacks are defined
Args: the arguments to pass to the module’s init callback
Options: the options used to create the gen_server

returns: the gen_server pid, if successful; {error, Reason}, otherwise.

Start and link an un-named gen_server.

This function will start a gen_server instance.

Note. The Options argument is currently ignored.

start_link/4


start_link(ServerName::{local, Name::atom()}, Module::module(), Args::term(), Options::options()) -> {ok, pid()} | {error, Reason::term()}

ServerName: the name with which to register the gen_server
Module: the module in which the gen_server callbacks are defined
Args: the arguments to pass to the module’s init callback
Options: the options used to create the gen_server

returns: the gen_server pid, if successful; {error, Reason}, otherwise.

Start and link a named gen_server.

This function will start a gen_server instance and register the newly created process with the process registry. Subsequent calls may use the gen_server name, in lieu of the process id.

Note. The Options argument is currently ignored.

start_monitor/3


start_monitor(Module::module(), Args::term(), Options::options()) -> {ok, {Pid::pid(), MonRef::reference()}} | {error, Reason::term()}

Module: the module in which the gen_server callbacks are defined
Args: the arguments to pass to the module’s init callback
Options: the options used to create the gen_server

returns: the gen_server pid and monitor reference tuple if successful; {error, Reason}, otherwise.

Start and monitor an un-named gen_server.

This function will start a gen_server instance.

Note. The Options argument is currently ignored.

start_monitor/4


start_monitor(ServerName::{local, Name::atom()}, Module::module(), Args::term(), Options::options()) -> {ok, {Pid::pid(), MonRef::reference()}} | {error, Reason::term()}

ServerName: the name with which to register the gen_server
Module: the module in which the gen_server callbacks are defined
Args: the arguments to pass to the module’s init callback
Options: the options used to create the gen_server

returns: the gen_server pid and monitor reference tuple if successful; {error, Reason}, otherwise.

Start and monitor a named gen_server.

This function will start a gen_server instance and register the newly created process with the process registry. Subsequent calls may use the gen_server name, in lieu of the process id.

Note. The Options argument is currently ignored.

stop/1


stop(ServerRef::server_ref()) -> ok | {error, Reason::term()}

Equivalent to stop(ServerRef, normal, infinity).

Stop a previously started gen_server instance.

stop/3


stop(ServerRef::server_ref(), Reason::term(), Timeout::non_neg_integer() | infinity) -> ok | {error, Reason::term()}

ServerRef: a reference to the gen_server acquired via start
Reason: reason to be supplied to callback function
Timeout: ms to wait for successful stop

returns: ok, if the gen_server stopped; {error, Reason}, otherwise.

Stop a previously started gen_server instance.

This function will stop a gen_server instance, providing the supplied Reason to the gen_server’s terminate/2 callback function. If the gen_server is named, then the gen_server name may be used to stop the gen_server.