Specs

change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}
               when
                   Name :: name(),
                   Module :: module(),
                   OldVsn :: undefined | term(),
                   Extra :: term(),
                   Reason :: term().

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.

Specs

change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason}
               when
                   Name :: name(),
                   Module :: module(),
                   OldVsn :: undefined | term(),
                   Extra :: term(),
                   Timeout :: timeout(),
                   Reason :: term().

Specs

debug_options([Opt :: debug_option()]) -> [dbg_opt()].

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.

Specs

get_debug(Item, Debug, Default) -> term()
             when Item :: log | statistics, Debug :: [dbg_opt()], Default :: term().

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.

Specs

get_log(Debug) -> [system_event()] when Debug :: [dbg_opt()].

Returns the logged system events in the debug structure, that is the last argument to handle_debug/4.

Specs

get_state(Name) -> State when Name :: name(), State :: term().

Gets the state of the process.

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_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_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.

Specs

get_state(Name, Timeout) -> State when Name :: name(), Timeout :: timeout(), State :: term().

Specs

get_status(Name) -> Status
              when
                  Name :: name(),
                  Status :: {status, Pid :: pid(), {module, Module :: module()}, [SItem]},
                  SItem ::
                      (PDict :: [{Key :: term(), Value :: term()}]) |
                      (SysState :: running | suspended) |
                      (Parent :: pid()) |
                      (Dbg :: [dbg_opt()]) |
                      (Misc :: term()).

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_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_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_statem:format_status/2, and gen_event:format_status/2.

Specs

get_status(Name, Timeout) -> Status
              when
                  Name :: name(),
                  Timeout :: timeout(),
                  Status :: {status, Pid :: pid(), {module, Module :: module()}, [SItem]},
                  SItem ::
                      (PDict :: [{Key :: term(), Value :: term()}]) |
                      (SysState :: running | suspended) |
                      (Parent :: pid()) |
                      (Dbg :: [dbg_opt()]) |
                      (Misc :: term()).

Specs

handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]
                when
                    Debug :: [dbg_opt()],
                    FormFunc :: format_fun(),
                    Extra :: term(),
                    Event :: system_event().

This function is called by a process when it generates a 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.

Specs

handle_system_msg(Msg, From, Parent, Module, Debug, Misc) -> no_return()
                     when
                         Msg :: term(),
                         From :: {pid(), Tag :: _},
                         Parent :: pid(),
                         Module :: module(),
                         Debug :: [dbg_opt()],
                         Misc :: term().

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.

Specs

install(Name, FuncSpec) -> ok
           when
               Name :: name(),
               FuncSpec :: {Func, FuncState} | {FuncId, Func, FuncState},
               FuncId :: term(),
               Func :: dbg_fun(),
               FuncState :: term().

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. If one debug function should be installed more times, a unique FuncId must be specified for each installation.

Specs

install(Name, FuncSpec, Timeout) -> ok
           when
               Name :: name(),
               FuncSpec :: {Func, FuncState} | {FuncId, Func, FuncState},
               FuncId :: term(),
               Func :: dbg_fun(),
               FuncState :: term(),
               Timeout :: timeout().

Specs

log(Name, Flag) -> ok | {ok, [system_event()]}
       when Name :: name(), Flag :: true | {true, N :: pos_integer()} | false | get | print.

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).

Specs

log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}
       when
           Name :: name(),
           Flag :: true | {true, N :: pos_integer()} | false | get | print,
           Timeout :: timeout().

Specs

log_to_file(Name, Flag) -> ok | {error, open_file}
               when Name :: name(), Flag :: (FileName :: string()) | false.

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). The file is opened with encoding UTF-8.

Specs

log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}
               when Name :: name(), Flag :: (FileName :: string()) | false, Timeout :: timeout().

Specs

no_debug(Name) -> ok when Name :: name().

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

Specs

no_debug(Name, Timeout) -> ok when Name :: name(), Timeout :: timeout().

Specs

print_log(Debug) -> ok when Debug :: [dbg_opt()].

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.

Specs

remove(Name, Func | FuncId) -> ok when Name :: name(), Func :: dbg_fun(), FuncId :: term().

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

Specs

remove(Name, Func | FuncId, Timeout) -> ok
          when Name :: name(), Func :: dbg_fun(), FuncId :: term(), Timeout :: timeout().

Specs

replace_state(Name, StateFun) -> NewState
                 when
                     Name :: name(),
                     StateFun :: fun((State :: term()) -> NewState :: term()),
                     NewState :: term().

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

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_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, 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 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}}.

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_statem, and gen_event export this function, so callback modules for those behaviors need not to supply their own.

Specs

replace_state(Name, StateFun, Timeout) -> NewState
                 when
                     Name :: name(),
                     StateFun :: fun((State :: term()) -> NewState :: term()),
                     Timeout :: timeout(),
                     NewState :: term().

Specs

resume(Name) -> ok when Name :: name().

Resumes a suspended process.

Specs

resume(Name, Timeout) -> ok when Name :: name(), Timeout :: timeout().

Specs

statistics(Name, Flag) -> ok | {ok, Statistics}
              when
                  Name :: name(),
                  Flag :: true | false | get,
                  Statistics :: [StatisticsTuple] | no_statistics,
                  StatisticsTuple ::
                      {start_time, DateTime1} |
                      {current_time, DateTime2} |
                      {reductions, non_neg_integer()} |
                      {messages_in, non_neg_integer()} |
                      {messages_out, non_neg_integer()},
                  DateTime1 :: file:date_time(),
                  DateTime2 :: file:date_time().

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

Specs

statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}
              when
                  Name :: name(),
                  Flag :: true | false | get,
                  Statistics :: [StatisticsTuple] | no_statistics,
                  StatisticsTuple ::
                      {start_time, DateTime1} |
                      {current_time, DateTime2} |
                      {reductions, non_neg_integer()} |
                      {messages_in, non_neg_integer()} |
                      {messages_out, non_neg_integer()},
                  DateTime1 :: file:date_time(),
                  DateTime2 :: file:date_time(),
                  Timeout :: timeout().

Specs

suspend(Name) -> ok when Name :: name().

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

Specs

suspend(Name, Timeout) -> ok when Name :: name(), Timeout :: timeout().

Specs

terminate(Name, Reason) -> ok when Name :: name(), Reason :: term().

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.

Specs

terminate(Name, Reason, Timeout) -> ok when Name :: name(), Reason :: term(), Timeout :: timeout().

Specs

trace(Name, Flag) -> ok when Name :: name(), Flag :: boolean().

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).

Specs

trace(Name, Flag, Timeout) -> ok when Name :: name(), Flag :: boolean(), Timeout :: timeout().