File 3113-stdlib-doc-Document-the-new-init-return-va... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 3113-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>&nbsp;&nbsp;| {ok,State,hibernate}</v>
 <v>&nbsp;&nbsp;| {ok,State,{continue,Continue}}</v>
 <v>&nbsp;&nbsp;| {stop,Reason}</v>
+ <v>&nbsp;&nbsp;| {error,Reason}</v>
 <v>&nbsp;&nbsp;| ignore</v>
 <v>&nbsp;State = term()</v>
 <v>
@@ -1960,14 +1961,22 @@ format_status(Status) ->
 </item>
 <tag>
 <c>{stop,Reason}</c> 
+ <c>{error,Reason}</c> 
 <c>ignore</c>
 </tag>
 <item>
 
 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
+	 <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>
+ 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) ->
 	
 	
 	 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>.
 	
@@ -2495,9 +2496,10 @@ handle_event(_, _, State, Data) ->
 	
 	 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>.
 	
+	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. 
 </desc>
 </func>
 
-- 
2.35.3

Places

File 3113-stdlib-doc-Document-the-new-init-return-value.patch of Package erlang

Places