diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 38e4922a072b..99333e284fbe 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -861,8 +861,8 @@ gen_event:stop -----> Module:terminate/2   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] - Result = {ok,Pid} | {error,{already_started,Pid}} -  Pid = pid() + Result = {ok,Pid} | {error,{already_started,OtherPid}} | {error,timeout} +  Pid = OtherPid = pid()

Creates a stand-alone event manager process, that is, an event @@ -888,14 +888,14 @@ gen_event:stop -----> Module:terminate/2   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] - Result = {ok,Pid} | {error,{already_started,Pid}} -  Pid = pid() + Result = {ok,Pid} | {error,{already_started,OtherPid}} | {error,timeout} +  Pid = OtherPid = pid()

Creates an event manager process as part of a supervision tree. The function is to be called, directly or indirectly, by the supervisor. For example, it ensures that - the event manager is linked to the supervisor.

+ the event manager is linked to the caller (supervisor).

If EventMgrName={local,Name}, the event manager is @@ -927,10 +927,50 @@ gen_event:stop -----> Module:terminate/2

If the event manager is successfully created, the function returns {ok,Pid}, where Pid is the pid of - the event manager. If a process with the specified + the event manager.

+

If a process with the specified EventMgrName exists already, the function returns - {error,{already_started,Pid}}, where Pid is - the pid of that process.

+ {error,{already_started,OtherPid}}, where OtherPid is + the pid of that process, and the event manager process + exits with reason normal.

+

+ If the event manager fails to start within the specified + start timeout {timeout,Time}, which is very unlikely + since the start does not interact with other processes, + the function returns {error,timeout} and the + failed event manager is killed with + exit(_, kill). +

+

+ If start_link/1,2 returns {error,_}, + the started event manager process has terminated. + If an 'EXIT' message was delivered to the calling process + (due to the process link), that message has been consumed. +

+ +

+ Before OTP 26.0, if the started event manager + failed to register its name, this founction could return + {error,{already_started,OtherPid}} + before the started event manager process + had terminated so starting again might fail + because the registered name was not yet unregistered, + and an 'EXIT' message could arrive later + to the process calling this function. +

+

+ But if the start timed out, this function killed + the started event manager process and returned + {error,timeout}, and then the process link + {'EXIT',Pid,killed} message was consumed. +

+

+ The start was made synchronous in OTP 26.0 + and the guarantee was implemented + that no process link 'EXIT' message from a failed start + will linger in the caller's inbox. +

+ @@ -948,8 +988,8 @@ gen_event:stop -----> Module:terminate/2   Dbgs = [Dbg]    Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}   SOpts = [term()] - Result = {ok,{Pid,Mon}} | {error,{already_started,Pid}} -  Pid = pid() + Result = {ok,{Pid,Mon}} | {error,{already_started,OtherPid}} | {error,timeout} +  Pid = OtherPid = pid()

Creates a stand-alone event manager process, that is, an event diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 65f8259464a1..788197ac46c0 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -345,30 +345,48 @@ gen_server:abcast -----> Module:handle_cast/2

A process with the specified ServerName exists already with the process identifier OtherPid. - This gen_server was not started. + This gen_server was not started, + or rather exited with reason normal before + calling + Module:init/1. +

+ + {error,timeout} + +

+ The gen_server process failed to initialize since + Module:init/1 + did not return within the + start timeout. + The gen_server process was killed with + exit(_, kill).

ignore

+ The gen_server process failed to initialize since Module:init/1 - returned ignore, the gen_server process - is terminated. An exit signal normal is sent - to linked processes and ports. + returned ignore.

{error,Reason}

+ The gen_server process failed to initialize since Module:init/1 - returned {stop,Reason} - or failed with Reason. - The gen_server process is terminated and - an exit signal with the same Reason - is sent to linked processes and ports. + returned {stop,Reason}, + {error,Reason}, + or it failed with reason Reason.

+

+ See + Module:init/1 + about the exit reason for the gen_server process + when it fails to initialize. +

@@ -1260,7 +1278,8 @@ gen_server:abcast -----> Module:handle_cast/2 Creates a gen_server process as part of a supervision tree. This function is to be called, directly or indirectly, by the supervisor. For example, it ensures that - the gen_server process is linked to the supervisor. + the gen_server process is spawned as linked + to the caller (supervisor).

The gen_server process calls @@ -1268,7 +1287,7 @@ gen_server:abcast -----> Module:handle_cast/2 to initialize. To ensure a synchronized startup procedure, start_link/3,4 does not return until - Module:init/1 has returned. + Module:init/1 has returned or failed.

Using the argument ServerName @@ -1298,6 +1317,48 @@ gen_server:abcast -----> Module:handle_cast/2 start_ret() for a description this function's return values.

+

+ If start_link/3,4 returns ignore or {error,_}, + the started gen_server process has terminated. + If an 'EXIT' message was delivered to the calling process + (due to the process link), that message has been consumed. +

+ +

+ Before OTP 26.0, if the started gen_server process + returned e.g. {stop,Reason} from + Module:init/1, + this function could return {error,Reason} + before the started gen_statem process + had terminated so starting again might fail + because VM resources such as the registered name + was not yet unregistered. An 'EXIT' message + could arrive later to the process calling this function. +

+

+ But if the started gen_server process instead + failed during + Module:init/1, + a process link {'EXIT',Pid,Reason} message + caused this function to return {error,Reason} + so the 'EXIT' message had been consumed + and the started gen_statem process had terminated. +

+

+ Since it was impossible to tell the difference + between these two cases from + start_link/3,4's return value, + this inconsistency was cleaned up in OTP 26.0. +

+ +

+ The difference between returning + {stop,_} and {error,_} from + Module:init/1, + is that {error,_} results in a graceful ("silent") + termination since the gen_server process + exits with reason normal. +

@@ -1964,30 +2025,34 @@ format_status(Status) -> {stop,Reason}
+ + +

+ Initialization failed. The gen_server process + exits with reason Reason. +

+ + {error,Reason}
ignore

- Initialization failed. - An exit signal with reason

- - stop: - Reason - error: - normal - ignore: - normal - -

is sent to linked processes and ports, - notably to the process starting the gen_server when - - start_link/3,4 - - is used. + Initialization failed. The gen_server process + exits with reason normal. +

+

+ {error,Reason} was introduced in OTP 26.0.

+

+ See function + start_link/3,4's + return value + start_ret() + in these different cases. +

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 042c16e3c82a..92c5bc5f8062 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -588,8 +588,10 @@ handle_event(_, _, State, Data) ->

- Return value from the start() and start_link() functions, - for example, start_link/3. + Return value from the + start/3,4 and + start_link/3,4 + functions.

@@ -598,7 +600,7 @@ handle_event(_, _, State, Data) ->

Return value from the - start_monitor() + start_monitor/3,4 functions.

@@ -1502,11 +1504,14 @@ handle_event(_, _, State, Data) ->

For an unsuccesful initialization, - {stop, Reason}, - {error, Reason} + {stop,Reason}, + {error,Reason} or ignore should be used; see start_link/3,4.

+

+ {error,Reason} was introduced in OTP 26.0. +

@@ -2382,7 +2387,7 @@ handle_event(_, _, State, Data) -> (using proc_lib primitives) - that is linked to the calling process. + that is spawned as linked to the calling process. This is essential when the gen_statem must be part of a supervision tree so it gets linked to its supervisor.

@@ -2392,15 +2397,15 @@ handle_event(_, _, State, Data) -> to initialize the server. To ensure a synchronized startup procedure, start_link/3,4 does not return until Module:init/1 - has returned. + has returned or failed.

ServerName specifies the server_name() - to register for the gen_statem. - If the gen_statem is started with start_link/3, - no ServerName is provided and - the gen_statem is not registered. + to register for the gen_statem process. + If the gen_statem process is started with start_link/3, + no ServerName is provided and + the gen_statem process is not registered.

Module is the name of the callback module.

@@ -2416,9 +2421,9 @@ handle_event(_, _, State, Data) -> {timeout,Time} is present in - Opts, the gen_statem + Opts, the gen_statem process is allowed to spend Time milliseconds initializing - or it terminates and the start function returns + or it is terminated and the start function returns {error,timeout}.

@@ -2428,9 +2433,11 @@ handle_event(_, _, State, Data) -> {hibernate_after,HibernateAfterTimeout} is present, the gen_statem - process awaits any message for HibernateAfterTimeout milliseconds and - if no message is received, the process goes into hibernation automatically - (by calling proc_lib:hibernate/3). + process awaits any message for HibernateAfterTimeout + milliseconds and if no message is received, + the process goes into hibernation automatically + (by calling + proc_lib:hibernate/3).

@@ -2465,38 +2472,88 @@ handle_event(_, _, State, Data) ->

- If the gen_statem is successfully created + If the gen_statem process is successfully created and initialized, this function returns {ok,Pid}, where Pid is the pid() - of the gen_statem. + of the gen_statem process. If a process with the specified ServerName exists already, this function returns - {error,{already_started,Pid}}, - where Pid is the pid() of that process. + {error,{already_started,OtherPid}}, + where OtherPid is the pid() of that process, + and the gen_statem process exits with reason normal + before calling + Module:init/1.

+

+ If Module:init/1 + does not return within the + start timeout, + the gen_statem process is killed with + exit(_, kill), + and this function returns + {error,timeout}. +

- If Module:init/1 fails with Reason, - this function returns - {error, Reason}. - If Module:init/1 returns - {stop, Reason}, - {shutdown, Reason} - or - ignore, - the process is terminated and this function - returns - {error,Reason} - or - ignore, - respectively. - An exit signal with the same Reason (or normal if - Module:init/1 returns ignore) is set to linked processes - and ports, including the process calling start_link/3,4. + This function returns + {error,Reason} if + Module:init/1 + returns + {stop,Reason} or + {error,Reason}, + or fails with reason Reason. + This function returns + ignore if + Module:init/1 + returns + ignore. + In these cases the gen_statem process exits + with reason Reason, except when Module:init/1 + returns ignore or {error,_}; + then the gen_statem process exits with reason normal. +

+

+ If start_link/3,4 returns ignore or {error,_}, + the started gen_statem process has terminated. + If an 'EXIT' message was delivered to the calling process + (due to the process link), that message has been consumed.

-

The difference between returning {stop, Reason} and - {error, Reason} (from Module:init/1) is that - error results in a graceful ("silent") termination.

+ +

+ Before OTP 26.0, if the started gen_statem process + returned e.g. {stop,Reason} from + Module:init/1, + this function could return {error,Reason} + before the started gen_statem process + had terminated so starting again might fail + because VM resources such as the registered name + was not yet unregistered, and an 'EXIT' message + could arrive later to the process calling this function. +

+

+ But if the started gen_statem process instead + failed during + Module:init/1, + a process link {'EXIT',Pid,Reason} message + caused this function to return {error,Reason} + so the 'EXIT' message had been consumed + and the started gen_statem process had terminated. +

+

+ Since it was impossible to tell the difference + between these two cases from + start_link/3,4's return value, + this inconsistency was cleaned up in OTP 26.0. +

+ +

+ The difference between returning + {stop,_} and {error,_} from + Module:init/1, + is that {error,_} results in a graceful ("silent") + termination since the gen_statem process + exits with reason normal. +

@@ -2531,7 +2588,7 @@ handle_event(_, _, State, Data) -> - Synchronously stop a generic server. + Synchronously stop a gen_statem process.

The same as @@ -2542,7 +2599,7 @@ handle_event(_, _, State, Data) -> - Synchronously stop a generic server. + Synchronously stop a gen_statem process.

Orders the gen_statem