From e5875001247e6a6ac4f474157a51a8c54f94ae49 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 14 Mar 2013 16:01:25 +0100 Subject: Convert XML files to UTF-8 --- lib/stdlib/doc/src/sys.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src/sys.xml') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 0ffc5bc433..ab8b380f49 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -1,10 +1,10 @@ - +
- 19962011 + 19962013 Ericsson AB. All Rights Reserved. -- cgit v1.2.3 From 6c298a7bfa332e5b7d153648d741740abc3bcdf8 Mon Sep 17 00:00:00 2001 From: Steve Vinoski Date: Wed, 19 Mar 2014 11:45:11 -0400 Subject: fix sys:get_state/1,2 and sys:replace_state/2,3 when sys suspended Add two new system callbacks Module:system_get_state/1 and Module:system_replace_state/2 to allow sys:get_state/1,2 and sys:replace_state/2,3 to operate correctly even if a process is sys suspended. Modify gen_server, gen_fsm, and gen_event to support the new callbacks. If a callback module does not export these functions, then by default the Misc value (the same as that passed as the final argument to sys:handle_system_msg/6, and returned as part of the return value of sys:get_status/1,2) is treated as the callback module's state. The previous behaviour of intercepting the system message and passing a tuple of size 2 as the last argument to sys:handle_system_msg/6 is no longer supported. Add tests to verify the correctness of sys:get_state/1,2 and sys:replace_state/2,3 when processes are sys suspended. Add two tests for modules that implement special processes, one that exports system_get_state/1 and system_replace_state/2 and one that doesn't. Much of the credit for this patch goes to James Fish, who reported the initial problem and implemented much of the fix. --- lib/stdlib/doc/src/sys.xml | 73 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 3 deletions(-) (limited to 'lib/stdlib/doc/src/sys.xml') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index ab8b380f49..a46fa1289f 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -246,6 +246,22 @@ {Module, Id, HandlerState}, where Module is the event handler's module name, Id is the handler's ID (which is the value false if it was registered without an ID), and HandlerState is the handler's state.

+

If the callback module exports a system_get_state/1 function, it will be called in the + target process to get its state. Its argument is the same as the Misc value returned by + get_status/1,2, and the system_get_state/1 + function is expected to extract the callback module's state from it. The system_get_state/1 + function must return {ok, State} where State is the callback module's state.

+

If the callback module does not export a system_get_state/1 function, get_state/1,2 + assumes the Misc value is the callback module's state and returns it directly instead.

+

If the callback module's system_get_state/1 function crashes or throws an exception, the + caller exits with error {callback_failed, {Module, system_get_state}, {Class, Reason}} where + Module is the name of the callback module and Class and Reason indicate + details of the exception.

+

The system_get_state/1 function is primarily useful for user-defined + behaviours and modules that implement OTP special + processes. The gen_server, gen_fsm, and gen_event OTP + behaviour modules export this function, and so callback modules for those behaviours + need not supply their own.

To obtain more information about a process, including its state, see get_status/1 and get_status/2.

@@ -289,6 +305,28 @@ function means that only the state of the particular event handler it was working on when it failed or crashed is unchanged; it can still succeed in changing the states of other event handlers registered in the same gen_event process.

+

If the callback module exports a system_replace_state/2 function, it will be called in the + target process to replace its state using StateFun. Its two arguments are StateFun + and Misc, where Misc is the same as the Misc value returned by + get_status/1,2. A system_replace_state/2 function + is expected to return {ok, NewState, NewMisc} where NewState is the callback module's + new state obtained by calling StateFun, and NewMisc is a possibly new value used to + replace the original Misc (required since Misc often contains the callback + module's state within it).

+

If the callback module does not export a system_replace_state/2 function, + replace_state/2,3 assumes the Misc value is the callback module's state, passes it + to StateFun and uses the return value as both the new state and as the new value of + Misc.

+

If the callback module's system_replace_state/2 function crashes or throws an exception, + the caller exits with error {callback_failed, {Module, system_replace_state}, {Class, Reason}} + where Module is the name of the callback module and Class and Reason indicate details + of the exception. If the callback module does not provide a system_replace_state/2 function and + StateFun crashes or throws an exception, the caller exits with error + {callback_failed, StateFun, {Class, Reason}}.

+

The system_replace_state/2 function is primarily useful for user-defined behaviours and + modules that implement OTP special processes. The + gen_server, gen_fsm, and gen_event OTP behaviour modules export this function, + and so callback modules for those behaviours need not supply their own.

@@ -322,7 +360,7 @@
Process Implementation Functions -

The following functions are used when implementing a +

The following functions are used when implementing a special process. This is an ordinary process which does not use a standard behaviour, but a process which understands the standard system messages.

@@ -375,8 +413,9 @@ process continues the execution, or Module:system_terminate(Reason, Parent, Debug, Misc) if the process should terminate. The Module must export - system_continue/3, system_terminate/4, and - system_code_change/4 (see below). + system_continue/3, system_terminate/4, + system_code_change/4, system_get_state/1 and + system_replace_state/2 (see below).

The Misc argument can be used to save internal data in a process, for example its state. It is sent to @@ -444,6 +483,34 @@ defined, the atom undefined is sent.

 + + Mod:system_get_state(Misc) -> {ok, State} + Called when the process should return its current state + + Misc = term() + State = term() + + +

This function is called from sys:handle_system_msg/6 when the process + should return a term that reflects its current state. State is the + value returned by sys:get_state/2.

+ + + + Mod:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc} + Called when the process should replace its current state + + StateFun = fun((State :: term()) -> NState) + Misc = term() + NState = term() + NMisc = term() + + +

This function is called from sys:handle_system_msg/6 when the process + should replace its current state. NState is the value returned by + sys:replace_state/3.

+ + -- cgit v1.2.3 From 6c3d24ccbc597e6d31db1f559470cc59585fdf52 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Wed, 7 May 2014 11:17:24 +0200 Subject: Add system message 'terminate' This is to be used when implementing synchronous stop of generic behaviours and other 'sys special processes'. --- lib/stdlib/doc/src/sys.xml | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src/sys.xml') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index a46fa1289f..7fb82e0e7e 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@
- 19962013 + 19962014 Ericsson AB. All Rights Reserved. @@ -356,6 +356,17 @@ installed.

+ + + + Terminate the process + +

This function orders the process to terminate with the + given Reason. The termination is done + asynchronously, so there is no guarantee that the process is + actually terminated when the function returns.

+ +
-- cgit v1.2.3 From bbf3e70e806b796611d14d4660372072dce8bffb Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Thu, 3 Jul 2014 09:48:37 +0200 Subject: Fix spec of format function in sys The argument FormFunc is sys:handle_debug/4war erronously specified as dbg_fun(), which is a debug function. This has now been corrected by adding a new type, format_fun(). --- lib/stdlib/doc/src/sys.xml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src/sys.xml') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index a46fa1289f..19605f325b 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@
- 19962013 + 19962014 Ericsson AB. All Rights Reserved. @@ -115,6 +115,9 @@ + + + -- cgit v1.2.3 From 738c34d4bb8f1a3811acd00af8c6c12107f8315b Mon Sep 17 00:00:00 2001 From: Bruce Yinhe Date: Thu, 18 Jun 2015 11:31:02 +0200 Subject: Change license text to APLv2 --- lib/stdlib/doc/src/sys.xml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'lib/stdlib/doc/src/sys.xml') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index cf7df54d1d..6ec515849e 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -8,16 +8,17 @@ Ericsson AB. All Rights Reserved. - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. -- cgit v1.2.3 From de432f4ea9a8c29c931f30dd504662be1a01464d Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Mon, 12 Oct 2015 14:28:39 +0200 Subject: [stdlib] Correct documentation Fix mistakes found by 'xmllint'. --- lib/stdlib/doc/src/sys.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc/src/sys.xml') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 6ec515849e..d400f72e1d 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -238,8 +238,8 @@

These functions are intended only to help with debugging. They are provided for convenience, allowing developers to avoid having to create their own state extraction functions and also avoid having to interactively extract state from the return values of - get_status/1 or - get_status/2 while debugging.

+ get_status/1 or + get_status/2 while debugging.

The value of State varies for different types of processes. For a gen_server process, the returned State -- cgit v1.2.3 From d840b24857a1d54419953661f70716c449c11864 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 3 Mar 2016 10:54:01 +0100 Subject: Fix most of the system docs and emacs mode --- lib/stdlib/doc/src/sys.xml | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) (limited to 'lib/stdlib/doc/src/sys.xml') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index d400f72e1d..2255395f46 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@

- 19962014 + 19962016 Ericsson AB. All Rights Reserved. @@ -217,14 +217,18 @@ processes. For example, a gen_server process returns the callback module's state, a gen_fsm process returns information such as its current state name and state data, - and a gen_event process returns information about each of its + a gen_statem process returns information about + its current state and data, and a gen_event process + returns information about each of its registered handlers. Callback modules for gen_server, - gen_fsm, and gen_event can also customise the value + gen_fsm, gen_statem and gen_event + can also customise the value of Misc by exporting a format_status/2 function that contributes module-specific information; - see gen_server:format_status/2, - gen_fsm:format_status/2, and - gen_event:format_status/2 + see gen_server format_status/2, + gen_fsm format_status/2, + gen_statem format_status/2, and + gen_event format_status/2 for more details.

@@ -245,6 +249,8 @@ processes. For a gen_server process, the returned State is simply the callback module's state. For a gen_fsm process, State is the tuple {CurrentStateName, CurrentStateData}. + For a gen_statem process State is + the tuple {CurrentState,CurrentData}. For a gen_event process, State a list of tuples, where each tuple corresponds to an event handler registered in the process and contains {Module, Id, HandlerState}, where Module is the event handler's module name, @@ -263,8 +269,9 @@ details of the exception.

The system_get_state/1 function is primarily useful for user-defined behaviours and modules that implement OTP special - processes. The gen_server, gen_fsm, and gen_event OTP - behaviour modules export this function, and so callback modules for those behaviours + processes. The gen_server, gen_fsm, + gen_statem and gen_event OTP + behaviour modules export this function, so callback modules for those behaviours need not supply their own.

To obtain more information about a process, including its state, see get_status/1 and @@ -290,6 +297,8 @@ gen_fsm process, State is the tuple {CurrentStateName, CurrentStateData}, and NewState is a similar tuple that may contain a new state name, new state data, or both. + The same applies for a gen_statem process but + it names the tuple fields {CurrentState,CurrentData}. For a gen_event process, State is the tuple {Module, Id, HandlerState} where Module is the event handler's module name, Id is the handler's ID (which is the value false if it was registered without @@ -304,7 +313,8 @@ state, then regardless of process type, it may simply return its State argument.

If a StateFun function crashes or throws an exception, then - for gen_server and gen_fsm processes, the original state of the process is + for gen_server, gen_fsm or gen_statem processes, + the original state of the process is unchanged. For gen_event processes, a crashing or failing StateFun function means that only the state of the particular event handler it was working on when it failed or crashed is unchanged; it can still succeed in changing the states of other event @@ -329,7 +339,8 @@ {callback_failed, StateFun, {Class, Reason}}.

The system_replace_state/2 function is primarily useful for user-defined behaviours and modules that implement OTP special processes. The - gen_server, gen_fsm, and gen_event OTP behaviour modules export this function, + gen_server, gen_fsm, gen_statem and + gen_event OTP behaviour modules export this function, and so callback modules for those behaviours need not supply their own.

-- cgit v1.2.3 From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/sys.xml | 831 +++++++++++++++++++++++++++------------------ 1 file changed, 505 insertions(+), 326 deletions(-) (limited to 'lib/stdlib/doc/src/sys.xml') diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 2255395f46..1120b926d5 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@
- 19962016 + 19962014 Ericsson AB. All Rights Reserved. @@ -30,62 +30,67 @@ 1996-06-06 - sys.sgml + sys.xml
sys - A Functional Interface to System Messages + A functional interface to system messages. -

This module contains functions for sending system messages used by programs, and messages used for debugging purposes. -

-

Functions used for implementation of processes - should also understand system messages such as debugging - messages and code change. These functions must be used to implement the use of system messages for a process; either directly, or through standard behaviours, such as gen_server.

-

The default timeout is 5000 ms, unless otherwise specified. The - timeout defines the time period to wait for the process to +

This module contains functions for sending system messages used by + programs, and messages used for debugging purposes.

+

Functions used for implementation of processes are also expected to + understand system messages, such as debug messages and code change. These + functions must be used to implement the use of system messages for a + process; either directly, or through standard behaviors, such as + gen_server.

+

The default time-out is 5000 ms, unless otherwise specified. + timeout defines the time to wait for the process to respond to a request. If the process does not respond, the function evaluates exit({timeout, {M, F, A}}).

-

The functions make reference to a debug structure. - The debug structure is a list of dbg_opt(). - dbg_opt() is an internal data type used by the - handle_system_msg/6 function. No debugging is performed if it is an empty list. -

+ +

The functions make references to a debug structure. + The debug structure is a list of dbg_opt(), which is an internal + data type used by function + handle_system_msg/6. No debugging is performed if it is + an empty list.
System Messages -

Processes which are not implemented as one of the standard - behaviours must still understand system - messages. There are three different messages which must be - understood: -

+

Processes that are not implemented as one of the standard + behaviors must still understand system messages. The following + three messages must be understood:

Plain system messages. These are received as {system, From, Msg}. The content and meaning of this message are not interpreted by the - receiving process module. When a system message has been - received, the function sys:handle_system_msg/6 - is called in order to handle the request. -

+ receiving process module. When a system message is received, function + + handle_system_msg/6 + is called to handle the request.

Shutdown messages. If the process traps exits, it must - be able to handle an shut-down request from its parent, the + be able to handle a shutdown request from its parent, the supervisor. The message {'EXIT', Parent, Reason} - from the parent is an order to terminate. The process must terminate when this message is received, normally with the + from the parent is an order to terminate. The process must + terminate when this message is received, normally with the same Reason as Parent.

-

There is one more message which the process must understand if the modules used to implement the process change dynamically during runtime. An example of such a process is the gen_event processes. This message is {get_modules, From}. The reply to this message is From ! {modules, Modules}, - where Modules is a list of the currently active modules in the process. -

+

If the modules used to implement the process change dynamically + during runtime, the process must understand one more message. An + example is the gen_event + processes. The message is {get_modules, From}. + The reply to this message is From ! {modules, Modules}, where + Modules is a list of the currently active modules in the + process.

This message is used by the release handler to find which - processes execute a certain module. The process may at a - later time be suspended and ordered to perform a code change - for one of its modules. -

+ processes that execute a certain module. The process can later be + suspended and ordered to perform a code change for one of its + modules.
@@ -93,15 +98,16 @@
System Events

When debugging a process with the functions of this - module, the process generates system_events which are + module, the process generates system_events, which are then treated in the debug function. For example, trace - formats the system events to the tty. + formats the system events to the terminal.

-

There are three predefined system events which are used when a +

Three predefined system events are used when a process receives or sends a message. The process can also define its own system events. It is always up to the process itself to format these events.

+ @@ -111,7 +117,7 @@ -

See above.

 +

See the introduction of this manual page.

 @@ -120,421 +126,594 @@ + - - - Log system events in memory - -

Turns the logging of system events On or Off. If On, a - maximum of N events are kept in the - debug structure (the default is 10). If Flag is get, a list of all - logged events is returned. If Flag is print, the - logged events are printed to standard_io. The events are - formatted with a function that is defined by the process that - generated the event (with a call to - sys:handle_debug/4).

- - - - - - Log system events to the specified file - -

Enables or disables the logging of all system events in textual - format to the file. The events are formatted with a function that is - defined by the process that generated the event (with a call - to sys:handle_debug/4).

- - - - - - Enable or disable the collections of statistics + + + Send the code change system message to the process. -

Enables or disables the collection of statistics. If Flag is - get, the statistical collection is returned.

+

Tells the process to change code. The process must be + suspended to handle this message. Argument Extra + is reserved for each process to use as its own. Function + Module:system_code_change/4 is called. + OldVsn is the old version of the + Module.

 + - - - Print all system events on standard_io + + + Get the state of the process. -

Prints all system events on standard_io. The events are - formatted with a function that is defined by the process that - generated the event (with a call to - sys:handle_debug/4).

+

Gets the state of the process.

+ +

These functions are intended only to help with debugging. They are + provided for convenience, allowing developers to avoid having to + create their own state extraction functions and also avoid having + to interactively extract the state from the return values of + get_status/1 or + get_status/2 + while debugging.

+ +

The value of State varies for different types of + processes, as follows:

+ + +

For a + gen_server + process, the returned State + is the state of the callback module.

+ + +

For a + gen_fsm + process, State is the tuple + {CurrentStateName, CurrentStateData}.

+ + +

For a + gen_statem + process, State is the tuple + {CurrentState,CurrentData}.

+ + +

For a + gen_event + process, State is a list of tuples, + where each tuple corresponds to an event handler registered + in the process and contains {Module, Id, HandlerState}, + as follows:

+ + Module + +

The module name of the event handler.

+ + Id + +

The ID of the handler (which is false if it was + registered without an ID).

+ + HandlerState + +

The state of the handler.

+ + + + +

If the callback module exports a function system_get_state/1, + it is called in the target process to get its state. Its argument is + the same as the Misc value returned by + get_status/1,2, and + function + Module:system_get_state/1 is expected to extract the + state of the callback module from it. Function + system_get_state/1 must return {ok, State}, where + State is the state of the callback module.

+

If the callback module does not export a system_get_state/1 + function, get_state/1,2 assumes that the Misc value is + the state of the callback module and returns it directly instead.

+

If the callback module's system_get_state/1 function crashes + or throws an exception, the caller exits with error + {callback_failed, {Module, system_get_state}, {Class, Reason}}, + where Module is the name of the callback module and + Class and Reason indicate details of the exception.

+

Function system_get_state/1 is primarily useful for + user-defined behaviors and modules that implement OTP + special processes. + The gen_server, gen_fsm, + gen_statem, and gen_event OTP + behavior modules export this function, so callback modules for those + behaviors need not to supply their own.

+

For more information about a process, including its state, see + get_status/1 and + get_status/2.

 + - - - Turn off debugging + + + Get the status of the process. -

Turns off all debugging for the process. This includes - functions that have been installed explicitly with the - install function, for example triggers.

+

Gets the status of the process.

+

The value of Misc varies for different types of + processes, for example:

+ + +

A gen_server + process returns the state of the callback module.

+ + +

A gen_fsm + process returns information, such as its current + state name and state data.

+ + +

A gen_statem + process returns information, such as its current + state name and state data.

+ + +

A gen_event + process returns information about each of its + registered handlers.

+ + +

Callback modules for gen_server, + gen_fsm, gen_statem, and gen_event + can also change the value of Misc + by exporting a function format_status/2, which contributes + module-specific information. For details, see + + gen_server:format_status/2, + + gen_fsm:format_status/2, + + gen_statem:format_status/2, and + + gen_event:format_status/2.

 + - - - Suspend the process + + + Install a debug function in the process. -

Suspends the process. When the process is suspended, it - will only respond to other system messages, but not other - messages.

+

Enables installation of alternative debug functions. An example of + such a function is a trigger, a function that waits for some + special event and performs some action when the event is + generated. For example, turning on low-level tracing.

+

Func is called whenever a system event is + generated. This function is to return done, or a new + Func state. In the first case, the function is removed. It is + also removed if the function fails.

 + - - - Resume a suspended process + + + Log system events in memory. -

Resumes a suspended process.

+

Turns the logging of system events on or off. If on, a + maximum of N events are kept in the + debug structure (default is 10).

+

If Flag is get, a list of all logged + events is returned.

+

If Flag is print, the logged events + are printed to standard_io.

+

The events are formatted with a function that is defined by the + process that generated the event (with a call to + + handle_debug/4).

 + - - - Send the code change system message to the process + + + Log system events to the specified file. -

Tells the process to change code. The process must be - suspended to handle this message. The Extra argument is - reserved for each process to use as its own. The function - Module:system_code_change/4 is called. OldVsn is - the old version of the Module.

+

Enables or disables the logging of all system events in text + format to the file. The events are formatted with a function that is + defined by the process that generated the event (with a call to + handle_debug/4). +

+ - - - Get the status of the process + + + Turn off debugging. -

Gets the status of the process.

-

The value of Misc varies for different types of - processes. For example, a gen_server process returns - the callback module's state, a gen_fsm process - returns information such as its current state name and state data, - a gen_statem process returns information about - its current state and data, and a gen_event process - returns information about each of its - registered handlers. Callback modules for gen_server, - gen_fsm, gen_statem and gen_event - can also customise the value - of Misc by exporting a format_status/2 - function that contributes module-specific information; - see gen_server format_status/2, - gen_fsm format_status/2, - gen_statem format_status/2, and - gen_event format_status/2 - for more details.

+

Turns off all debugging for the process. This includes + functions that are installed explicitly with function + install/2,3, + for example, triggers.

 + - - - Get the state of the process + + + Remove a debug function from the process. -

Gets the state of the process.

- -

These functions are intended only to help with debugging. They are provided for - convenience, allowing developers to avoid having to create their own state extraction - functions and also avoid having to interactively extract state from the return values of - get_status/1 or - get_status/2 while debugging.

- -

The value of State varies for different types of - processes. For a gen_server process, the returned State - is simply the callback module's state. For a gen_fsm process, - State is the tuple {CurrentStateName, CurrentStateData}. - For a gen_statem process State is - the tuple {CurrentState,CurrentData}. - For a gen_event process, State a list of tuples, - where each tuple corresponds to an event handler registered in the process and contains - {Module, Id, HandlerState}, where Module is the event handler's module name, - Id is the handler's ID (which is the value false if it was registered without - an ID), and HandlerState is the handler's state.

-

If the callback module exports a system_get_state/1 function, it will be called in the - target process to get its state. Its argument is the same as the Misc value returned by - get_status/1,2, and the system_get_state/1 - function is expected to extract the callback module's state from it. The system_get_state/1 - function must return {ok, State} where State is the callback module's state.

-

If the callback module does not export a system_get_state/1 function, get_state/1,2 - assumes the Misc value is the callback module's state and returns it directly instead.

-

If the callback module's system_get_state/1 function crashes or throws an exception, the - caller exits with error {callback_failed, {Module, system_get_state}, {Class, Reason}} where - Module is the name of the callback module and Class and Reason indicate - details of the exception.

-

The system_get_state/1 function is primarily useful for user-defined - behaviours and modules that implement OTP special - processes. The gen_server, gen_fsm, - gen_statem and gen_event OTP - behaviour modules export this function, so callback modules for those behaviours - need not supply their own.

-

To obtain more information about a process, including its state, see - get_status/1 and - get_status/2.

+

Removes an installed debug function from the + process. Func must be the same as previously + installed.

 + - Replace the state of the process + Replace the state of the process.

Replaces the state of the process, and returns the new state.

-

These functions are intended only to help with debugging, and they should not be - be called from normal code. They are provided for convenience, allowing developers - to avoid having to create their own custom state replacement functions.

+

These functions are intended only to help with debugging, and are + not to be called from normal code. They are provided for + convenience, allowing developers to avoid having to create their own + custom state replacement functions.

 -

The StateFun function provides a new state for the process. - The State argument and NewState return value - of StateFun vary for different types of processes. For a - gen_server process, State is simply the callback module's - state, and NewState is a new instance of that state. For a - gen_fsm process, State is the tuple - {CurrentStateName, CurrentStateData}, and NewState - is a similar tuple that may contain a new state name, new state data, or both. - The same applies for a gen_statem process but - it names the tuple fields {CurrentState,CurrentData}. - For a gen_event process, State is the tuple - {Module, Id, HandlerState} where Module is the event handler's module name, - Id is the handler's ID (which is the value false if it was registered without - an ID), and HandlerState is the handler's state. NewState is a - similar tuple where Module and Id shall have the same values as in - State but the value of HandlerState may be different. Returning - a NewState whose Module or Id values differ from those of - State will result in the event handler's state remaining unchanged. For a - gen_event process, StateFun is called once for each event handler - registered in the gen_event process.

-

If a StateFun function decides not to effect any change in process - state, then regardless of process type, it may simply return its State - argument.

-

If a StateFun function crashes or throws an exception, then - for gen_server, gen_fsm or gen_statem processes, - the original state of the process is - unchanged. For gen_event processes, a crashing or failing StateFun - function means that only the state of the particular event handler it was working on when it - failed or crashed is unchanged; it can still succeed in changing the states of other event +

Function StateFun provides a new state for the + process. Argument State and the + NewState return value of + StateFun vary for different types of + processes as follows:

+ + +

For a gen_server + process, State is the state of the callback + module and NewState + is a new instance of that state.

+ + +

For a gen_fsm process, + State is the tuple {CurrentStateName, + CurrentStateData}, and NewState is a + similar tuple, which can contain + a new state name, new state data, or both.

+ + +

For a gen_statem + process, State is the + tuple {CurrentState,CurrentData}, + and NewState is a + similar tuple, which can contain + a new current state, new state data, or both.

+ + +

For a gen_event + process, State is the + tuple {Module, Id, HandlerState} as follows:

+ + Module + +

The module name of the event handler.

+ + Id + +

The ID of the handler (which is false if it was + registered without an ID).

+ + HandlerState + +

The state of the handler.

+ + +

NewState is a similar tuple where + Module and Id are to have the same values as in + State, but the value of HandlerState + can be different. Returning a NewState, whose + Module or Id values differ from those of + State, leaves the state of the event handler + unchanged. For a gen_event process, + StateFun is called once for each event handler + registered in the gen_event process.

+ + +

If a StateFun function decides not to effect any + change in process state, then regardless of process type, it can + return its State argument.

+

If a StateFun function crashes or throws an + exception, the original state of the process is unchanged for + gen_server, gen_fsm, and gen_statem processes. + For gen_event processes, a crashing or + failing StateFun function + means that only the state of the particular event handler it was + working on when it failed or crashed is unchanged; it can still + succeed in changing the states of other event handlers registered in the same gen_event process.

-

If the callback module exports a system_replace_state/2 function, it will be called in the - target process to replace its state using StateFun. Its two arguments are StateFun - and Misc, where Misc is the same as the Misc value returned by - get_status/1,2. A system_replace_state/2 function - is expected to return {ok, NewState, NewMisc} where NewState is the callback module's - new state obtained by calling StateFun, and NewMisc is a possibly new value used to - replace the original Misc (required since Misc often contains the callback - module's state within it).

-

If the callback module does not export a system_replace_state/2 function, - replace_state/2,3 assumes the Misc value is the callback module's state, passes it - to StateFun and uses the return value as both the new state and as the new value of - Misc.

-

If the callback module's system_replace_state/2 function crashes or throws an exception, - the caller exits with error {callback_failed, {Module, system_replace_state}, {Class, Reason}} - where Module is the name of the callback module and Class and Reason indicate details - of the exception. If the callback module does not provide a system_replace_state/2 function and - StateFun crashes or throws an exception, the caller exits with error +

If the callback module exports a + + system_replace_state/2 function, it is called in the + target process to replace its state using StateFun. Its two + arguments are StateFun and Misc, where + Misc is the same as the Misc value returned by + get_status/1,2. + A system_replace_state/2 function is expected to return + {ok, NewState, NewMisc}, where NewState is the new state + of the callback module, obtained by calling StateFun, and + NewMisc is + a possibly new value used to replace the original Misc + (required as Misc often contains the state of the callback + module within it).

+

If the callback module does not export a + system_replace_state/2 function, + replace_state/2,3 + assumes that Misc is the state of the callback module, + passes it to StateFun and uses the return value as + both the new state and as the new value of Misc.

+

If the callback module's function system_replace_state/2 + crashes or throws an exception, the caller exits with error + {callback_failed, {Module, system_replace_state}, {Class, + Reason}}, where Module is the name of the callback module + and Class and Reason indicate details of the exception. + If the callback module does not provide a + system_replace_state/2 function and StateFun crashes or + throws an exception, the caller exits with error {callback_failed, StateFun, {Class, Reason}}.

-

The system_replace_state/2 function is primarily useful for user-defined behaviours and - modules that implement OTP special processes. The - gen_server, gen_fsm, gen_statem and - gen_event OTP behaviour modules export this function, - and so callback modules for those behaviours need not supply their own.

+

Function system_replace_state/2 is primarily useful for + user-defined behaviors and modules that implement OTP + special processes. The + OTP behavior modules gen_server, + gen_fsm, gen_statem, and gen_event + export this function, so callback modules for those + behaviors need not to supply their own.

 + - - - Install a debug function in the process + + + Resume a suspended process. -

This function makes it possible to install other debug - functions than the ones defined above. An example of such a - function is a trigger, a function that waits for some - special event and performs some action when the event is - generated. This could, for example, be turning on low level tracing. -

-

Func is called whenever a system event is - generated. This function should return done, or a new - func state. In the first case, the function is removed. It is removed - if the function fails.

+

Resumes a suspended process.

 + - - - Remove a debug function from the process + + + Enable or disable the collections of statistics. -

Removes a previously installed debug function from the - process. Func must be the same as previously - installed.

+

Enables or disables the collection of statistics. If + Flag is get, + the statistical collection is returned.

 + + + + + Suspend the process. + +

Suspends the process. When the process is suspended, it + only responds to other system messages, but not other + messages.

+ + + - Terminate the process + Terminate the process. -

This function orders the process to terminate with the - given Reason. The termination is done - asynchronously, so there is no guarantee that the process is - actually terminated when the function returns.

+

Orders the process to terminate with the + specified Reason. The termination is done + asynchronously, so it is not guaranteed that the process is + terminated when the function returns.

+ + + + + + + Print all system events on standard_io. + +

Prints all system events on standard_io. The events are + formatted with a function that is defined by the process that + generated the event (with a call to + handle_debug/4). +

Process Implementation Functions -

The following functions are used when implementing a - special process. This is an ordinary process which does not use a - standard behaviour, but a process which understands the standard system messages.

+ +

The following functions are used when implementing a + special process. This is an ordinary process, which does not use a + standard behavior, but a process that understands the standard system + messages.

+ - Convert a list of options to a debug structure + Convert a list of options to a debug structure. -

This function can be used by a process that initiates a debug - structure from a list of options. The values of the - Opt argument are the same as the corresponding +

Can be used by a process that initiates a debug + structure from a list of options. The values of argument + Opt are the same as for the corresponding functions.

 + - Get the data associated with a debug option + Get the data associated with a debug option. -

This function gets the data associated with a debug option. Default is returned if the - Item is not found. Can be - used by the process to retrieve debug data for printing - before it terminates.

+

Gets the data associated with a debug option. + Default + is returned if Item is not found. Can be + used by the process to retrieve debug data for printing before it + terminates.

 + - Generate a system event + Generate a system event.

This function is called by a process when it generates a - system event. FormFunc is a formatting - function which is called as FormFunc(Device, - Event, Extra) in order to print - the events, which is necessary if tracing is activated. - Extra is any extra information which the - process needs in the format function, for example the name - of the process.

+ system event. FormFunc is a formatting + function, called as FormFunc(Device, + Event, Extra) to print the events, + which is necessary if tracing is activated. + Extra is any extra information that the + process needs in the format function, for example, the process + name.

 + - Take care of system messages + Take care of system messages. -

This function is used by a process module that wishes to take care of system - messages. The process receives a {system, From, Msg} - message and passes the Msg and From to this - function. -

-

This function never returns. It calls the function - Module:system_continue(Parent, NDebug, Misc) where the - process continues the execution, or - Module:system_terminate(Reason, Parent, Debug, Misc) if - the process should terminate. The Module must export - system_continue/3, system_terminate/4, - system_code_change/4, system_get_state/1 and - system_replace_state/2 (see below). -

-

The Misc argument can be used to save internal data - in a process, for example its state. It is sent to +

This function is used by a process module to take care of system + messages. The process receives a + {system, From, Msg} message and + passes Msg and From to this + function.

+

This function never returns. It calls either of the + following functions:

+ + +

Module:system_continue(Parent, + NDebug, Misc), + where the process continues the execution.

+ + +

Module:system_terminate(Reason, + Parent, Debug, Misc), + if the process is to terminate.

+ + +

Module must export the following:

+ + system_continue/3 + system_terminate/4 + system_code_change/4 + system_get_state/1 + system_replace_state/2 + +

Argument Misc can be used to save internal data + in a process, for example, its state. It is sent to Module:system_continue/3 or - Module:system_terminate/4

+ Module:system_terminate/4.

 + - Print the logged events in the debug structure + Print the logged events in the debug structure. -

Prints the logged system events in the debug structure +

Prints the logged system events in the debug structure, using FormFunc as defined when the event was - generated by a call to handle_debug/4.

+ generated by a call to + handle_debug/4.

 + - Mod:system_continue(Parent, Debug, Misc) -> none() - Called when the process should continue its execution + Module:system_code_change(Misc, Module, OldVsn, Extra) -> + {ok, NMisc} + Called when the process is to perform a code change. - Parent = pid() - Debug = [dbg_opt()] Misc = term() + OldVsn = undefined | term() + Module = atom() + Extra = term() + NMisc = term() -

This function is called from sys:handle_system_msg/6 when the process - should continue its execution (for example after it has been - suspended). This function never returns.

+

Called from + handle_system_msg/6 when the process is to perform a + code change. The code change is used when the + internal data structure has changed. This function + converts argument Misc to the new data + structure. OldVsn is attribute vsn of the + old version of the Module. If no such attribute is + defined, the atom undefined is sent.

 + - Mod:system_terminate(Reason, Parent, Debug, Misc) -> none() - Called when the process should terminate + Module:system_continue(Parent, Debug, Misc) -> none() + Called when the process is to continue its execution. - Reason = term() Parent = pid() Debug = [dbg_opt()] Misc = term() -

This function is called from sys:handle_system_msg/6 when the process - should terminate. For example, this function is called when - the process is suspended and its parent orders shut-down. - It gives the process a chance to do a clean-up. This function never - returns.

+

Called from + handle_system_msg/6 when the process is to continue + its execution (for example, after it has been + suspended). This function never returns.

 + - Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc} - Called when the process should perform a code change + Module:system_get_state(Misc) -> {ok, State} + Called when the process is to return its current state. + Misc = term() - OldVsn = undefined | term() - Module = atom() - Extra = term() - NMisc = term() + State = term() -

Called from sys:handle_system_msg/6 when the process - should perform a code change. The code change is used when the - internal data structure has changed. This function - converts the Misc argument to the new data - structure. OldVsn is the vsn attribute of the - old version of the Module. If no such attribute was - defined, the atom undefined is sent.

+

Called from + handle_system_msg/6 + when the process is to return a term that reflects its current state. + State is the value returned by + get_state/2.

 + - Mod:system_get_state(Misc) -> {ok, State} - Called when the process should return its current state + Module:system_replace_state(StateFun, Misc) -> + {ok, NState, NMisc} + Called when the process is to replace its current state. + + StateFun = fun((State :: term()) -> NState) Misc = term() - State = term() - + NState = term() + NMisc = term() + -

This function is called from sys:handle_system_msg/6 when the process - should return a term that reflects its current state. State is the - value returned by sys:get_state/2.

+

Called from + handle_system_msg/6 when the process is to replace + its current state. NState is the value returned by + replace_state/3. +

+ - Mod:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc} - Called when the process should replace its current state + Module:system_terminate(Reason, Parent, Debug, Misc) -> none() + Called when the process is to terminate. - StateFun = fun((State :: term()) -> NState) + Reason = term() + Parent = pid() + Debug = [dbg_opt()] Misc = term() - NState = term() - NMisc = term() - + -

This function is called from sys:handle_system_msg/6 when the process - should replace its current state. NState is the value returned by - sys:replace_state/3.

+

Called from + handle_system_msg/6 when the process is to terminate. + For example, this function is called when + the process is suspended and its parent orders shutdown. + It gives the process a chance to do a cleanup. This function never + returns.

 -- cgit v1.2.3