aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/sys.xml
blob: 51fd5ee8d4406f36ce315ec720517f84185bbb45 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year>
      <year>2007</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
  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.

  The Initial Developer of the Original Code is Ericsson AB.
    </legalnotice>

    <title>sys</title>
    <prepared>Martin Bj&ouml;rklund</prepared>
    <responsible>Bjarne D&auml;cker</responsible>
    <docno></docno>
    <approved>Bjarne D&auml;cker</approved>
    <checked></checked>
    <date>1996-06-06</date>
    <rev></rev>
    <file>sys.sgml</file>
  </header>
  <module>sys</module>
  <modulesummary>A Functional Interface to System Messages</modulesummary>
  <description>
    <p>This module contains functions for sending system messages used by programs, and messaged used for debugging purposes.
      </p>
    <p>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 <c>gen_server</c>.</p>
    <p>The following types are used in the functions defined below:</p>
    <list type="bulleted">
      <item>
        <p><c>Name = pid() | atom() | {global, atom()}</c></p>
      </item>
      <item>
        <p><c>Timeout = int() >= 0 | infinity</c></p>
      </item>
      <item>
        <p><c>system_event() = {in, Msg} | {in, Msg, From} | {out, Msg, To} | term()</c></p>
      </item>
    </list>
    <p>The default timeout is 5000 ms, unless otherwise specified. The
      <c>timeout</c> defines the time period to wait for the process to
      respond to a request. If the process does not respond, the
      function evaluates <c>exit({timeout, {M, F, A}})</c>.
      </p>
    <p>The functions make reference to a debug structure.
      The debug structure is a list of <c>dbg_opt()</c>.
      <c>dbg_opt()</c> is an internal data type used by the
      <c>handle_system_msg/6</c> function. No debugging is performed if it is an empty list.
      </p>
  </description>

  <section>
    <title>System Messages</title>
    <p>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:
      </p>
    <list type="bulleted">
      <item>
        <p>Plain system messages. These are received as
          <c>{system, From, Msg}</c>. The content and meaning of
          this message are not interpreted by the
          receiving process module. When a system message has been
          received, the function <c>sys:handle_system_msg/6</c>
          is called in order to handle the request.
          </p>
      </item>
      <item>
        <p>Shutdown messages. If the process traps exits, it must
          be able to handle an shut-down request from its parent, the
          supervisor. The message <c>{'EXIT', Parent, Reason}</c>
          from the parent is an order to terminate.  The process must terminate when this message is received, normally with the
          same <c>Reason</c> as <c>Parent</c>.
          </p>
      </item>
      <item>
        <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>,
          where <c>Modules</c> is a list of the currently active modules in the process.
          </p>
        <p>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.
          </p>
      </item>
    </list>
  </section>

  <section>
    <title>System Events</title>
    <p>When debugging a process with the functions of this
      module, the process generates <em>system_events</em> which are
      then treated in the debug function. For example, <c>trace</c>
      formats the system events to the tty.
      </p>
    <p>There are three predefined system events which 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.</p>
  </section>
  <funcs>
    <func>
      <name>log(Name,Flag)</name>
      <name>log(Name,Flag,Timeout) -> ok | {ok, [system_event()]}</name>
      <fsummary>Log system events in memory</fsummary>
      <type>
        <v>Flag = true | {true, N} | false | get | print</v>
        <v>N = integer() > 0</v>
      </type>
      <desc>
        <p>Turns the logging of system events On or Off. If On, a
          maximum of <c>N</c>  events are kept in the
          debug structure (the default is 10). If <c>Flag</c> is <c>get</c>, a list of all
          logged events is returned. If <c>Flag</c> is <c>print</c>, the
          logged events are printed to <c>standard_io</c>. The events are
          formatted with a function that is defined by the process that
          generated the event (with a call to
          <c>sys:handle_debug/4</c>).</p>
      </desc>
    </func>
    <func>
      <name>log_to_file(Name,Flag)</name>
      <name>log_to_file(Name,Flag,Timeout) -> ok | {error, open_file}</name>
      <fsummary>Log system events to the specified file</fsummary>
      <type>
        <v>Flag = FileName | false</v>
        <v>FileName = string()</v>
      </type>
      <desc>
        <p>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 <c>sys:handle_debug/4</c>).</p>
      </desc>
    </func>
    <func>
      <name>statistics(Name,Flag)</name>
      <name>statistics(Name,Flag,Timeout) -> ok | {ok, Statistics} </name>
      <fsummary>Enable or disable the collections of statistics</fsummary>
      <type>
        <v>Flag = true | false | get</v>
        <v>Statistics = [{start_time, {Date1, Time1}}, {current_time, {Date, Time2}}, {reductions, integer()}, {messages_in, integer()}, {messages_out, integer()}]</v>
        <v>Date1 = Date2 = {Year, Month, Day}</v>
        <v>Time1 = Time2 = {Hour, Min, Sec}</v>
      </type>
      <desc>
        <p>Enables or disables the collection of statistics. If <c>Flag</c> is
          <c>get</c>, the statistical collection is returned.</p>
      </desc>
    </func>
    <func>
      <name>trace(Name,Flag)</name>
      <name>trace(Name,Flag,Timeout) -> void()</name>
      <fsummary>Print all system events on <c>standard_io</c></fsummary>
      <type>
        <v>Flag = boolean()</v>
      </type>
      <desc>
        <p>Prints all system events on <c>standard_io</c>. The events are
          formatted with a function that is defined by the process that
          generated the event (with a call to
          <c>sys:handle_debug/4</c>).</p>
      </desc>
    </func>
    <func>
      <name>no_debug(Name)</name>
      <name>no_debug(Name,Timeout) -> void()</name>
      <fsummary>Turn off debugging</fsummary>
      <desc>
        <p>Turns off all debugging for the process. This includes
          functions that have been installed explicitly with the
          <c>install</c> function, for example triggers.</p>
      </desc>
    </func>
    <func>
      <name>suspend(Name)</name>
      <name>suspend(Name,Timeout) -> void()</name>
      <fsummary>Suspend the process</fsummary>
      <desc>
        <p>Suspends the process. When the process is suspended, it
          will only respond to other system messages, but not other
          messages.</p>
      </desc>
    </func>
    <func>
      <name>resume(Name)</name>
      <name>resume(Name,Timeout) -> void()</name>
      <fsummary>Resume a suspended process</fsummary>
      <desc>
        <p>Resumes a suspended process.</p>
      </desc>
    </func>
    <func>
      <name>change_code(Name, Module, OldVsn, Extra)</name>
      <name>change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason}</name>
      <fsummary>Send the code change system message to the process</fsummary>
      <type>
        <v>OldVsn = undefined | term()</v>
        <v>Module = atom()</v>
        <v>Extra = term()</v>
      </type>
      <desc>
        <p>Tells the process to change code. The process must be
          suspended to handle this message. The <c>Extra</c> argument is
          reserved for each process to use as its own. The function
          <c>Mod:system_code_change/4</c> is called. <c>OldVsn</c> is
          the old version of the <c>Module</c>.</p>
      </desc>
    </func>
    <func>
      <name>get_status(Name)</name>
      <name>get_status(Name,Timeout) -> {status, Pid, {module, Mod}, [PDict, SysState, Parent, Dbg, Misc]}</name>
      <fsummary>Get the status of the process</fsummary>
      <type>
        <v>PDict = [{Key, Value}]</v>
        <v>SysState = running | suspended</v>
        <v>Parent = pid()</v>
        <v>Dbg = [dbg_opt()]</v>
        <v>Misc = term()</v>
      </type>
      <desc>
        <p>Gets the status of the process.</p>
        <p>The value of <c>Misc</c> varies for different types of
          processes. For example, a <c>gen_server</c> process returns
          the callback module's state, and a <c>gen_fsm</c> process
          returns information such as its current state name. Callback
          modules for <c>gen_server</c> and <c>gen_fsm</c> can also
          customise the value of <c>Misc</c> by exporting
          a <c>format_status/2</c> function that contributes
          module-specific information;
          see <seealso marker="gen_server#format_status/2">gen_server:format_status/2</seealso>
          and <seealso marker="gen_fsm#format_status/2">gen_fsm:format_status/2</seealso>
          for more details.</p>
      </desc>
    </func>
    <func>
      <name>install(Name,{Func,FuncState})</name>
      <name>install(Name,{Func,FuncState},Timeout)</name>
      <fsummary>Install a debug function in the process</fsummary>
      <type>
        <v>Func = dbg_fun()</v>
        <v>dbg_fun() = fun(FuncState, Event, ProcState) -> done | NewFuncState</v>
        <v>FuncState = term()</v>
        <v>Event = system_event()</v>
        <v>ProcState = term()</v>
        <v>NewFuncState = term()</v>
      </type>
      <desc>
        <p>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.
          </p>
        <p><c>Func</c> is called whenever a system event is
          generated. This function should return <c>done</c>, or a new
          func state. In the first case, the function is removed. It is removed 
          if the function fails.</p>
      </desc>
    </func>
    <func>
      <name>remove(Name,Func)</name>
      <name>remove(Name,Func,Timeout) -> void()</name>
      <fsummary>Remove a debug function from the process</fsummary>
      <type>
        <v>Func = dbg_fun()</v>
      </type>
      <desc>
        <p>Removes a previously installed debug function from the
          process. <c>Func</c> must be the same as previously
          installed.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Process Implementation Functions</title>
    <p>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.</p>
  </section>
  <funcs>
    <func>
      <name>debug_options(Options) -> [dbg_opt()]</name>
      <fsummary>Convert a list of options to a debug structure</fsummary>
      <type>
        <v>Options = [Opt]</v>
        <v>Opt = trace | log | statistics | {log_to_file, FileName} | {install, {Func, FuncState}}</v>
        <v>Func = dbg_fun()</v>
        <v>FuncState = term()</v>
      </type>
      <desc>
        <p>This function can be used by a process that initiates a debug
          structure from a list of options. The values of the
          <c>Opt</c> argument are the same as the corresponding
          functions.</p>
      </desc>
    </func>
    <func>
      <name>get_debug(Item,Debug,Default) -> term()</name>
      <fsummary>Get the data associated with a debug option</fsummary>
      <type>
        <v>Item = log | statistics</v>
        <v>Debug = [dbg_opt()]</v>
        <v>Default = term()</v>
      </type>
      <desc>
        <p>This function gets the data associated with a debug option. <c>Default</c> is returned if the
          <c>Item</c> is not found.  Can be
          used by the process to retrieve debug data for printing
          before it terminates.</p>
      </desc>
    </func>
    <func>
      <name>handle_debug([dbg_opt()],FormFunc,Extra,Event) -> [dbg_opt()]</name>
      <fsummary>Generate a system event</fsummary>
      <type>
        <v>FormFunc = dbg_fun()</v>
        <v>Extra = term()</v>
        <v>Event = system_event()</v>
      </type>
      <desc>
        <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
          extra information which the process needs in the format function, for example the name of the process.</p>
      </desc>
    </func>
    <func>
      <name>handle_system_msg(Msg,From,Parent,Module,Debug,Misc)</name>
      <fsummary>Take care of system messages</fsummary>
      <type>
        <v>Msg = term()</v>
        <v>From = pid()</v>
        <v>Parent = pid()</v>
        <v>Module = atom()</v>
        <v>Debug = [dbg_opt()]</v>
        <v>Misc = term()</v>
      </type>
      <desc>
        <p>This function is used by a process module that wishes to take care of system
          messages. The process receives a <c>{system, From, Msg}</c>
          message and passes the <c>Msg</c> and <c>From</c> to this
          function.
          </p>
        <p>This function <em>never</em> returns. It calls the function
          <c>Module:system_continue(Parent, NDebug, Misc)</c> where the
          process continues the execution, or
          <c>Module:system_terminate(Reason, Parent, Debug, Misc)</c> if
          the process should terminate. The <c>Module</c> must export
          <c>system_continue/3</c>, <c>system_terminate/4</c>, and
          <c>system_code_change/4</c> (see below).
          </p>
        <p>The <c>Misc</c> argument can be used to save internal data
          in a process, for example its state. It is sent to
          <c>Module:system_continue/3</c> or
          <c>Module:system_terminate/4</c></p>
      </desc>
    </func>
    <func>
      <name>print_log(Debug) -> void()</name>
      <fsummary>Print the logged events in the debug structure</fsummary>
      <type>
        <v>Debug = [dbg_opt()]</v>
      </type>
      <desc>
        <p>Prints the logged system events in the debug structure
          using <c>FormFunc</c> as defined when the event was
          generated by a call to <c>handle_debug/4</c>.</p>
      </desc>
    </func>
    <func>
      <name>Mod:system_continue(Parent, Debug, Misc)</name>
      <fsummary>Called when the process should continue its execution</fsummary>
      <type>
        <v>Parent = pid()</v>
        <v>Debug = [dbg_opt()]</v>
        <v>Misc = term()</v>
      </type>
      <desc>
        <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
          should continue its execution (for example after it has been
          suspended). This function never returns.</p>
      </desc>
    </func>
    <func>
      <name>Mod:system_terminate(Reason, Parent, Debug, Misc)</name>
      <fsummary>Called when the process should terminate</fsummary>
      <type>
        <v>Reason = term()</v>
        <v>Parent = pid()</v>
        <v>Debug = [dbg_opt()]</v>
        <v>Misc = term()</v>
      </type>
      <desc>
        <p>This function is called from <c>sys:handle_system_msg/6</c> 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.</p>
      </desc>
    </func>
    <func>
      <name>Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}</name>
      <fsummary>Called when the process should perform a code change</fsummary>
      <type>
        <v>Misc = term()</v>
        <v>OldVsn = undefined | term()</v>
        <v>Module = atom()</v>
        <v>Extra = term()</v>
        <v>NMisc = term()</v>
      </type>
      <desc>
        <p>Called from <c>sys:handle_system_msg/6</c> when the process
          should perform a code change. The code change is used when the
          internal data structure has changed. This function
          converts the <c>Misc</c> argument to the new data
          structure. <c>OldVsn</c> is the <em>vsn</em> attribute of the
          old version of the <c>Module</c>. If no such attribute was
          defined, the atom <c>undefined</c> is sent.</p>
      </desc>
    </func>
  </funcs>
</erlref>