1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
27
<prepared>Martin Björklund</prepared>
28
<responsible>Bjarne Däcker</responsible>
30
<approved>Bjarne Däcker</approved>
32
<date>1996-06-06</date>
37
<modulesummary>A Functional Interface to System Messages</modulesummary>
39
<p>This module contains functions for sending system messages used by programs, and messaged used for debugging purposes.
41
<p>Functions used for implementation of processes
42
should also understand system messages such as debugging
43
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 <c>gen_server</c>.</p>
44
<p>The following types are used in the functions defined below:</p>
45
<list type="bulleted">
47
<p><c>Name = pid() | atom() | {global, atom()}</c></p>
50
<p><c>Timeout = int() >= 0 | infinity</c></p>
53
<p><c>system_event() = {in, Msg} | {in, Msg, From} | {out, Msg, To} | term()</c></p>
56
<p>The default timeout is 5000 ms, unless otherwise specified. The
57
<c>timeout</c> defines the time period to wait for the process to
58
respond to a request. If the process does not respond, the
59
function evaluates <c>exit({timeout, {M, F, A}})</c>.
61
<p>The functions make reference to a debug structure.
62
The debug structure is a list of <c>dbg_opt()</c>.
63
<c>dbg_opt()</c> is an internal data type used by the
64
<c>handle_system_msg/6</c> function. No debugging is performed if it is an empty list.
69
<title>System Messages</title>
70
<p>Processes which are not implemented as one of the standard
71
behaviours must still understand system
72
messages. There are three different messages which must be
75
<list type="bulleted">
77
<p>Plain system messages. These are received as
78
<c>{system, From, Msg}</c>. The content and meaning of
79
this message are not interpreted by the
80
receiving process module. When a system message has been
81
received, the function <c>sys:handle_system_msg/6</c>
82
is called in order to handle the request.
86
<p>Shutdown messages. If the process traps exits, it must
87
be able to handle an shut-down request from its parent, the
88
supervisor. The message <c>{'EXIT', Parent, Reason}</c>
89
from the parent is an order to terminate. The process must terminate when this message is received, normally with the
90
same <c>Reason</c> as <c>Parent</c>.
94
<p>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 <c>gen_event</c> processes. This message is <c>{get_modules, From}</c>. The reply to this message is <c>From ! {modules, Modules}</c>,
95
where <c>Modules</c> is a list of the currently active modules in the process.
97
<p>This message is used by the release handler to find which
98
processes execute a certain module. The process may at a
99
later time be suspended and ordered to perform a code change
100
for one of its modules.
107
<title>System Events</title>
108
<p>When debugging a process with the functions of this
109
module, the process generates <em>system_events</em> which are
110
then treated in the debug function. For example, <c>trace</c>
111
formats the system events to the tty.
113
<p>There are three predefined system events which are used when a
114
process receives or sends a message. The process can also define its
115
own system events. It is always up to the process itself
116
to format these events.</p>
120
<name>log(Name,Flag)</name>
121
<name>log(Name,Flag,Timeout) -> ok | {ok, [system_event()]}</name>
122
<fsummary>Log system events in memory</fsummary>
124
<v>Flag = true | {true, N} | false | get | print</v>
125
<v>N = integer() > 0</v>
128
<p>Turns the logging of system events On or Off. If On, a
129
maximum of <c>N</c> events are kept in the
130
debug structure (the default is 10). If <c>Flag</c> is <c>get</c>, a list of all
131
logged events is returned. If <c>Flag</c> is <c>print</c>, the
132
logged events are printed to <c>standard_io</c>. The events are
133
formatted with a function that is defined by the process that
134
generated the event (with a call to
135
<c>sys:handle_debug/4</c>).</p>
139
<name>log_to_file(Name,Flag)</name>
140
<name>log_to_file(Name,Flag,Timeout) -> ok | {error, open_file}</name>
141
<fsummary>Log system events to the specified file</fsummary>
143
<v>Flag = FileName | false</v>
144
<v>FileName = string()</v>
147
<p>Enables or disables the logging of all system events in textual
148
format to the file. The events are formatted with a function that is
149
defined by the process that generated the event (with a call
150
to <c>sys:handle_debug/4</c>).</p>
154
<name>statistics(Name,Flag)</name>
155
<name>statistics(Name,Flag,Timeout) -> ok | {ok, Statistics} </name>
156
<fsummary>Enable or disable the collections of statistics</fsummary>
158
<v>Flag = true | false | get</v>
159
<v>Statistics = [{start_time, {Date1, Time1}}, {current_time, {Date, Time2}}, {reductions, integer()}, {messages_in, integer()}, {messages_out, integer()}]</v>
160
<v>Date1 = Date2 = {Year, Month, Day}</v>
161
<v>Time1 = Time2 = {Hour, Min, Sec}</v>
164
<p>Enables or disables the collection of statistics. If <c>Flag</c> is
165
<c>get</c>, the statistical collection is returned.</p>
169
<name>trace(Name,Flag)</name>
170
<name>trace(Name,Flag,Timeout) -> void()</name>
171
<fsummary>Print all system events on <c>standard_io</c></fsummary>
173
<v>Flag = boolean()</v>
176
<p>Prints all system events on <c>standard_io</c>. The events are
177
formatted with a function that is defined by the process that
178
generated the event (with a call to
179
<c>sys:handle_debug/4</c>).</p>
183
<name>no_debug(Name)</name>
184
<name>no_debug(Name,Timeout) -> void()</name>
185
<fsummary>Turn off debugging</fsummary>
187
<p>Turns off all debugging for the process. This includes
188
functions that have been installed explicitly with the
189
<c>install</c> function, for example triggers.</p>
193
<name>suspend(Name)</name>
194
<name>suspend(Name,Timeout) -> void()</name>
195
<fsummary>Suspend the process</fsummary>
197
<p>Suspends the process. When the process is suspended, it
198
will only respond to other system messages, but not other
203
<name>resume(Name)</name>
204
<name>resume(Name,Timeout) -> void()</name>
205
<fsummary>Resume a suspended process</fsummary>
207
<p>Resumes a suspended process.</p>
211
<name>change_code(Name, Module, OldVsn, Extra)</name>
212
<name>change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason}</name>
213
<fsummary>Send the code change system message to the process</fsummary>
215
<v>OldVsn = undefined | term()</v>
216
<v>Module = atom()</v>
217
<v>Extra = term()</v>
220
<p>Tells the process to change code. The process must be
221
suspended to handle this message. The <c>Extra</c> argument is
222
reserved for each process to use as its own. The function
223
<c>Mod:system_code_change/4</c> is called. <c>OldVsn</c> is
224
the old version of the <c>Module</c>.</p>
228
<name>get_status(Name)</name>
229
<name>get_status(Name,Timeout) -> {status, Pid, {module, Mod}, [PDict, SysState, Parent, Dbg, Misc]}</name>
230
<fsummary>Get the status of the process</fsummary>
232
<v>PDict = [{Key, Value}]</v>
233
<v>SysState = running | suspended</v>
234
<v>Parent = pid()</v>
235
<v>Dbg = [dbg_opt()]</v>
239
<p>Gets the status of the process.</p>
243
<name>install(Name,{Func,FuncState})</name>
244
<name>install(Name,{Func,FuncState},Timeout)</name>
245
<fsummary>Install a debug function in the process</fsummary>
247
<v>Func = dbg_fun()</v>
248
<v>dbg_fun() = fun(FuncState, Event, ProcState) -> done | NewFuncState</v>
249
<v>FuncState = term()</v>
250
<v>Event = system_event()</v>
251
<v>ProcState = term()</v>
252
<v>NewFuncState = term()</v>
255
<p>This function makes it possible to install other debug
256
functions than the ones defined above. An example of such a
257
function is a trigger, a function that waits for some
258
special event and performs some action when the event is
259
generated. This could, for example, be turning on low level tracing.
261
<p><c>Func</c> is called whenever a system event is
262
generated. This function should return <c>done</c>, or a new
263
func state. In the first case, the function is removed. It is removed
264
if the function fails.</p>
268
<name>remove(Name,Func)</name>
269
<name>remove(Name,Func,Timeout) -> void()</name>
270
<fsummary>Remove a debug function from the process</fsummary>
272
<v>Func = dbg_fun()</v>
275
<p>Removes a previously installed debug function from the
276
process. <c>Func</c> must be the same as previously
283
<title>Process Implementation Functions</title>
284
<p>The following functions are used when implementing a
285
special process. This is an ordinary process which does not use a
286
standard behaviour, but a process which understands the standard system messages.</p>
290
<name>debug_options(Options) -> [dbg_opt()]</name>
291
<fsummary>Convert a list of options to a debug structure</fsummary>
293
<v>Options = [Opt]</v>
294
<v>Opt = trace | log | statistics | {log_to_file, FileName} | {install, {Func, FuncState}}</v>
295
<v>Func = dbg_fun()</v>
296
<v>FuncState = term()</v>
299
<p>This function can be used by a process that initiates a debug
300
structure from a list of options. The values of the
301
<c>Opt</c> argument are the same as the corresponding
306
<name>get_debug(Item,Debug,Default) -> term()</name>
307
<fsummary>Get the data associated with a debug option</fsummary>
309
<v>Item = log | statistics</v>
310
<v>Debug = [dbg_opt()]</v>
311
<v>Default = term()</v>
314
<p>This function gets the data associated with a debug option. <c>Default</c> is returned if the
315
<c>Item</c> is not found. Can be
316
used by the process to retrieve debug data for printing
317
before it terminates.</p>
321
<name>handle_debug([dbg_opt()],FormFunc,Extra,Event) -> [dbg_opt()]</name>
322
<fsummary>Generate a system event</fsummary>
324
<v>FormFunc = dbg_fun()</v>
325
<v>Extra = term()</v>
326
<v>Event = system_event()</v>
329
<p>This function is called by a process when it generates a system event. <c>FormFunc</c> is a formatting function which is called as <c>FormFunc(Device, Event, Extra)</c> in order to print the events, which is necessary if tracing is activated. <c>Extra</c> is any
330
extra information which the process needs in the format function, for example the name of the process.</p>
334
<name>handle_system_msg(Msg,From,Parent,Module,Debug,Misc)</name>
335
<fsummary>Take care of system messages</fsummary>
339
<v>Parent = pid()</v>
340
<v>Module = atom()</v>
341
<v>Debug = [dbg_opt()]</v>
345
<p>This function is used by a process module that wishes to take care of system
346
messages. The process receives a <c>{system, From, Msg}</c>
347
message and passes the <c>Msg</c> and <c>From</c> to this
350
<p>This function <em>never</em> returns. It calls the function
351
<c>Module:system_continue(Parent, NDebug, Misc)</c> where the
352
process continues the execution, or
353
<c>Module:system_terminate(Reason, Parent, Debug, Misc)</c> if
354
the process should terminate. The <c>Module</c> must export
355
<c>system_continue/3</c>, <c>system_terminate/4</c>, and
356
<c>system_code_change/4</c> (see below).
358
<p>The <c>Misc</c> argument can be used to save internal data
359
in a process, for example its state. It is sent to
360
<c>Module:system_continue/3</c> or
361
<c>Module:system_terminate/4</c></p>
365
<name>print_log(Debug) -> void()</name>
366
<fsummary>Print the logged events in the debug structure</fsummary>
368
<v>Debug = [dbg_opt()]</v>
371
<p>Prints the logged system events in the debug structure
372
using <c>FormFunc</c> as defined when the event was
373
generated by a call to <c>handle_debug/4</c>.</p>
377
<name>Mod:system_continue(Parent, Debug, Misc)</name>
378
<fsummary>Called when the process should continue its execution</fsummary>
380
<v>Parent = pid()</v>
381
<v>Debug = [dbg_opt()]</v>
385
<p>This function is called from <c>sys:handle_system_msg/6</c> when the process
386
should continue its execution (for example after it has been
387
suspended). This function never returns.</p>
391
<name>Mod:system_terminate(Reason, Parent, Debug, Misc)</name>
392
<fsummary>Called when the process should terminate</fsummary>
394
<v>Reason = term()</v>
395
<v>Parent = pid()</v>
396
<v>Debug = [dbg_opt()]</v>
400
<p>This function is called from <c>sys:handle_system_msg/6</c> when the process
401
should terminate. For example, this function is called when
402
the process is suspended and its parent orders shut-down.
403
It gives the process a chance to do a clean-up. This function never
408
<name>Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}</name>
409
<fsummary>Called when the process should perform a code change</fsummary>
412
<v>OldVsn = undefined | term()</v>
413
<v>Module = atom()</v>
414
<v>Extra = term()</v>
415
<v>NMisc = term()</v>
418
<p>Called from <c>sys:handle_system_msg/6</c> when the process
419
should perform a code change. The code change is used when the
420
internal data structure has changed. This function
421
converts the <c>Misc</c> argument to the new data
422
structure. <c>OldVsn</c> is the <em>vsn</em> attribute of the
423
old version of the <c>Module</c>. If no such attribute was
424
defined, the atom <c>undefined</c> is sent.</p>
added
removed
lib/stdlib/doc/src/sys.xml
