From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/sys.xml | 212 ++++++++++++++++----------------------------- 1 file changed, 77 insertions(+), 135 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 efa8922a9d..073faf2df2 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -39,24 +39,12 @@

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 following types are used in the functions defined below:

- - -

Name = pid() | atom() | {global, atom()}

- - -

Timeout = int() >= 0 | infinity

- - -

system_event() = {in, Msg} | {in, Msg, From} | {out, Msg, To} | term()

- -

The default timeout is 5000 ms, unless otherwise specified. The timeout defines the time period 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 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. @@ -113,20 +101,31 @@ own system events. It is always up to the process itself to format these events.

+ + + + + + + + + +

See above.

 + + + + + - log(Name,Flag) - log(Name,Flag,Timeout) -> ok | {ok, [system_event()]} + + Log system events in memory - - Flag = true | {true, N} | false | get | print - N = integer() > 0 -

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 + 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 @@ -134,13 +133,9 @@ - log_to_file(Name,Flag) - log_to_file(Name,Flag,Timeout) -> ok | {error, open_file} + + Log system events to the specified file - - Flag = FileName | false - FileName = string() -

Enables or disables the logging of all system events in textual format to the file. The events are formatted with a function that is @@ -149,27 +144,18 @@ - statistics(Name,Flag) - statistics(Name,Flag,Timeout) -> ok | {ok, Statistics} + + Enable or disable the collections of statistics - - Flag = true | false | get - Statistics = [{start_time, {Date1, Time1}}, {current_time, {Date, Time2}}, {reductions, integer()}, {messages_in, integer()}, {messages_out, integer()}] - Date1 = Date2 = {Year, Month, Day} - Time1 = Time2 = {Hour, Min, Sec} - -

Enables or disables the collection of statistics. If Flag is +

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

 - trace(Name,Flag) - trace(Name,Flag,Timeout) -> void() + + Print all system events on standard_io - - Flag = boolean() -

Prints all system events on standard_io. The events are formatted with a function that is defined by the process that @@ -178,8 +164,8 @@ - no_debug(Name) - no_debug(Name,Timeout) -> void() + + Turn off debugging

Turns off all debugging for the process. This includes @@ -188,8 +174,8 @@ - suspend(Name) - suspend(Name,Timeout) -> void() + + Suspend the process

Suspends the process. When the process is suspended, it @@ -198,49 +184,37 @@ - resume(Name) - resume(Name,Timeout) -> void() + + Resume a suspended process

Resumes a suspended process.

 - change_code(Name, Module, OldVsn, Extra) - change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason} + + Send the code change system message to the process - - OldVsn = undefined | term() - Module = atom() - Extra = term() -

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

+ Module:system_code_change/4 is called. OldVsn is + the old version of the Module.

 - get_status(Name) - get_status(Name,Timeout) -> {status, Pid, {module, Mod}, [PDict, SysState, Parent, Dbg, Misc]} + + Get the status of the process - - PDict = [{Key, Value}] - 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 +

The value of Misc varies for different types of processes. For example, a gen_server process returns the callback module's state, and a gen_fsm process returns information such as its current state name. Callback modules for gen_server and gen_fsm can also - customise the value of Misc by exporting + customise the value of Misc by exporting a format_status/2 function that contributes module-specific information; see gen_server:format_status/2 @@ -249,17 +223,9 @@ - install(Name,{Func,FuncState}) - install(Name,{Func,FuncState},Timeout) + + Install a debug function in the process - - Func = dbg_fun() - dbg_fun() = fun(FuncState, Event, ProcState) -> done | NewFuncState - FuncState = term() - Event = system_event() - ProcState = term() - NewFuncState = term() -

This function makes it possible to install other debug functions than the ones defined above. An example of such a @@ -267,22 +233,19 @@ 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 +

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.

 - remove(Name,Func) - remove(Name,Func,Timeout) -> void() + + Remove a debug function from the process - - Func = dbg_fun() -

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

 @@ -296,86 +259,65 @@ - debug_options(Options) -> [dbg_opt()] + Convert a list of options to a debug structure - - Options = [Opt] - Opt = trace | log | statistics | {log_to_file, FileName} | {install, {Func, FuncState}} - Func = dbg_fun() - FuncState = term() -

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 + Opt argument are the same as the corresponding functions.

 - get_debug(Item,Debug,Default) -> term() + Get the data associated with a debug option - - Item = log | statistics - Debug = [dbg_opt()] - Default = term() - -

This function gets the data associated with a debug option. Default is returned if the - Item is not found. Can be +

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.

 - handle_debug([dbg_opt()],FormFunc,Extra,Event) -> [dbg_opt()] + Generate a system event - - FormFunc = dbg_fun() - Extra = term() - Event = 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.

+

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.

 - handle_system_msg(Msg,From,Parent,Module,Debug,Misc) + Take care of system messages - - Msg = term() - From = pid() - Parent = pid() - Module = atom() - Debug = [dbg_opt()] - Misc = term() -

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

-

The Misc argument can be used to save internal data +

The Misc argument 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_continue/3 or + Module:system_terminate/4

 - print_log(Debug) -> void() + Print the logged events in the debug structure - - Debug = [dbg_opt()] -

Prints the logged system events in the debug structure using FormFunc as defined when the event was @@ -383,11 +325,11 @@ - Mod:system_continue(Parent, Debug, Misc) + Mod:system_continue(Parent, Debug, Misc) -> none() Called when the process should continue its execution Parent = pid() - Debug = [dbg_opt()] + Debug = [dbg_opt()] Misc = term() @@ -397,12 +339,12 @@ - Mod:system_terminate(Reason, Parent, Debug, Misc) + Mod:system_terminate(Reason, Parent, Debug, Misc) -> none() Called when the process should terminate Reason = term() Parent = pid() - Debug = [dbg_opt()] + Debug = [dbg_opt()] Misc = term() -- cgit v1.2.3