File 4113-stdlib-doc-Document-the-new-init-return-value.patch of Package erlang
From 92a7f223b54be8b9a5bceb66755c54d70452e15d Mon Sep 17 00:00:00 2001
From: Micael Karlberg <bmk@erlang.org>
Date: Tue, 31 Jan 2023 10:18:38 +0100
Subject: [PATCH 3/3] [stdlib|doc] Document the new init return value
Document the new valid return value for Module:init/1
for both gen_server and gen_statem.
OTP-18423
---
lib/stdlib/doc/src/gen_server.xml | 17 +++++++++++++----
lib/stdlib/doc/src/gen_statem.xml | 13 +++++++++----
2 files changed, 22 insertions(+), 8 deletions(-)
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 4948418b3d..0bbaee2fd8 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2022</year>
+ <year>1996</year><year>2023</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -1916,6 +1916,7 @@ format_status(Status) ->
<v> | {ok,State,hibernate}</v>
<v> | {ok,State,{continue,Continue}}</v>
<v> | {stop,Reason}</v>
+ <v> | {error,Reason}</v>
<v> | ignore</v>
<v> State = term()</v>
<v>
@@ -1960,14 +1961,22 @@ format_status(Status) ->
</item>
<tag>
<c>{stop,Reason}</c><br/>
+ <c>{error,Reason}</c><br/>
<c>ignore</c>
</tag>
<item>
<p>
Initialization failed.
- An exit signal with this <c>Reason</c>
- (or with reason <c>normal</c> if <c>ignore</c> is returned)
- is sent to linked processes and ports,
+ An exit signal with reason</p>
+ <taglist>
+ <tag>stop:</tag>
+ <item><c>Reason</c></item>
+ <tag>error:</tag>
+ <item><c>normal</c></item>
+ <tag>ignore:</tag>
+ <item><c>normal</c></item>
+ </taglist>
+ <p>is sent to linked processes and ports,
notably to the process starting the gen_server when
<seemfa marker="#start_link/3">
<c>start_link/3,4</c>
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 9dd1c6f270..1eae53d9e4 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>2016</year><year>2022</year>
+ <year>2016</year><year>2023</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -1494,7 +1494,8 @@ handle_event(_, _, State, Data) ->
</p>
<p>
For an unsuccesful initialization,
- <c>{stop,<anno>Reason</anno>}</c>
+ <c>{stop, <anno>Reason</anno>}</c>,
+ <c>{error, <anno>Reason</anno>}</c>
or <c>ignore</c> should be used; see
<seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.
</p>
@@ -2495,9 +2496,10 @@ handle_event(_, _, State, Data) ->
<p>
If <c>Module:init/1</c> fails with <c>Reason</c>,
this function returns
- <seetype marker="#start_ret"><c>{error,Reason}</c></seetype>.
+ <seetype marker="#start_ret"><c>{error, Reason}</c></seetype>.
If <c>Module:init/1</c> returns
- <seetype marker="#start_ret"><c>{stop,Reason}</c></seetype>
+ <seetype marker="#start_ret"><c>{stop, Reason}</c></seetype>,
+ <seetype marker="#start_ret"><c>{shutdown, Reason}</c></seetype>
or
<seetype marker="#start_ret"><c>ignore</c></seetype>,
the process is terminated and this function
@@ -2510,6 +2512,9 @@ handle_event(_, _, State, Data) ->
<c>Module:init/1</c> returns <c>ignore</c>) is set to linked processes
and ports, including the process calling <c>start_link/3,4</c>.
</p>
+ <p>The difference between returning <c>{stop, Reason}</c> and
+ <c>{error, Reason}</c> (from <c>Module:init/1</c>) is that
+ <c>error</c> results in a graceful ("silent") termination. </p>
</desc>
</func>
--
2.35.3
