From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= 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: This behavior module provides the server of a client-server
+ relation. A generic server process ( A 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. If a callback function fails or returns a bad value, the
+ A Notice that a 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
gen_server module Callback module
----------------- ---------------
@@ -59,175 +62,65 @@ gen_server:abcast -----> Module:handle_cast/2
- -----> Module:terminate/2
-- -----> Module:code_change/3
-
The
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
Orders a generic server to exit with the
- given
The function returns
If the process does not exist, a
Sends an asynchronous request to the
For a description of the arguments, see
+
Makes a synchronous call to the gen_server
Makes a synchronous call to the
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 +
The call can fail for many reasons, including time-out and the
+ called
The ancient behavior 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.
+ linked to the client was removed in Erlang 5.6/OTP R12B. +Sends an asynchronous request to the
For a description of
Makes an existing process into a
This function is useful when a more complex initialization procedure
+ is needed than the
The function fails if the calling process was not started by a
+
Makes a synchronous call to all gen_servers locally +
Makes a synchronous call to all
The function returns a tuple
The function returns a tuple
When a reply
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
If one of the nodes cannot process monitors, for example,
+ C or Java nodes, and the
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 +
To prevent late answers (after the time-out) from polluting + the message queue of the caller, a middleman process is used to + do the calls. Late answers are then discarded when they arrive to a terminated process.
Sends an asynchronous request to the gen_server
-
See
This function can be used by a
The return value
Sends an asynchronous request to the gen_servers locally
- registered as
See
-
Creates a standalone
For a description of arguments and return values, see
+
This function can be used by a gen_server to explicitly send
- a reply to a client that called
The return value
Creates a
The
If
If
If
If option
If option
If option
Using spawn option
If the
If
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
-
Orders a generic server to exit with the specified
The function returns
If the process does not exist, 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
This function is called by a
For an upgrade,
If successful, the function must return the updated + internal state.
+If the function returns
This callback is optional, so callback modules need not
+ export it. The
This function is called by a
One of
The
This function is useful for changing the form and
+ appearance of the
The function is to return
One use for this function is to return compact alternative + state representations to avoid that large state terms are + printed in log files.
+Whenever a gen_server receives a request sent using
-
Whenever a
If the function returns
If the functions returns
If the function returns
If
For a description of
If
If
If
Whenever a gen_server receives a request sent using
-
Whenever a
See
For a description of the arguments and possible return values, see
+
This function is called by a gen_server when a timeout - occurs or when it receives any other message than a +
This function is called by a
See
For a description of the other arguments and possible return values,
+ see
Whenever a
If the initialization is successful, the function is to
+ return
If an integer time-out value is provided, a time-out occurs
+ unless a request or a message is received within
+
If
If the initialization fails, the function is to return
+
This function is called by a gen_server when it is about to
- terminate. It should be the opposite of
This function is called by a
If the gen_server is part of a supervision tree and is - ordered by its supervisor to terminate, this function will be +
If the
The
The shutdown strategy as defined in the child specification
+ of the supervisor is an integer time-out value, not
+
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.
+Even if the
Otherwise, the
Notice that for any other reason than