1sys(3) Erlang Module Definition sys(3)
2
6 sys - A functional interface to system messages.
7
9 This module contains functions for sending system messages used by pro‐
10 grams, and messages used for debugging purposes.
11 Functions used for implementation of processes are also expected to
13 understand system messages, such as debug messages and code change.
14 These functions must be used to implement the use of system messages
15 for a process; either directly, or through standard behaviors, such as
16 gen_server.
17 The default time-out is 5000 ms, unless otherwise specified. timeout
19 defines the time to wait for the process to respond to a request. If
20 the process does not respond, the function evaluates exit({timeout, {M,
21 F, A}}).
22 The functions make references to a debug structure. The debug structure
24 is a list of dbg_opt(), which is an internal data type used by function
25 handle_system_msg/6. No debugging is performed if it is an empty list.
26
28 Processes that are not implemented as one of the standard behaviors
29 must still understand system messages. The following three messages
30 must be understood:
31 * Plain system messages. These are received as {system, From, Msg}.
33 The content and meaning of this message are not interpreted by the
34 receiving process module. When a system message is received, func‐
35 tion handle_system_msg/6 is called to handle the request.
36 * Shutdown messages. If the process traps exits, it must be able to
38 handle a shutdown request from its parent, the supervisor. The mes‐
39 sage {'EXIT', Parent, Reason} from the parent is an order to termi‐
40 nate. The process must terminate when this message is received,
41 normally with the same Reason as Parent.
42 * If the modules used to implement the process change dynamically
44 during runtime, the process must understand one more message. An
45 example is the gen_event processes. The message is {_Label, {From,
46 Ref}, get_modules}. The reply to this message is From ! {Ref, Mod‐
47 ules}, where Modules is a list of the currently active modules in
48 the process.
49 This message is used by the release handler to find which processes
51 that execute a certain module. The process can later be suspended
52 and ordered to perform a code change for one of its modules.
53
55 When debugging a process with the functions of this module, the process
56 generates system_events, which are then treated in the debug function.
57 For example, trace formats the system events to the terminal.
58 Three predefined system events are used when a process receives or
60 sends a message. The process can also define its own system events. It
61 is always up to the process itself to format these events.
62
64 name() =
65 pid() | atom() | {global, term()} | {via, module(), term()}
66 system_event() =
68 {in, Msg :: term()} |
69 {in, Msg :: term(), From :: term()} |
70 {out, Msg :: term(), To :: term()} |
71 term()
72 dbg_opt()
74 See the introduction of this manual page.
76 dbg_fun() =
78 fun((FuncState :: term(),
79 Event :: system_event(),
80 ProcState :: term()) ->
81 done | (NewFuncState :: term()))
82 format_fun() =
84 fun((Device :: io:device() | file:io_device(),
85 Event :: system_event(),
86 Extra :: term()) ->
87 any())
88
90 change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}
91 change_code(Name, Module, OldVsn, Extra, Timeout) ->
93 ok | {error, Reason}
94 Types:
96 Name = name()
98 Module = module()
99 OldVsn = undefined | term()
100 Extra = term()
101 Timeout = timeout()
102 Reason = term()
103 Tells the process to change code. The process must be suspended
105 to handle this message. Argument Extra is reserved for each
106 process to use as its own. Function Module:system_code_change/4
107 is called. OldVsn is the old version of the Module.
108 get_state(Name) -> State
110 get_state(Name, Timeout) -> State
112 Types:
114 Name = name()
116 Timeout = timeout()
117 State = term()
118 Gets the state of the process.
120 Note:
122 These functions are intended only to help with debugging. They
123 are provided for convenience, allowing developers to avoid hav‐
124 ing to create their own state extraction functions and also
125 avoid having to interactively extract the state from the return
126 values of get_status/1 or get_status/2 while debugging.
127 The value of State varies for different types of processes, as
130 follows:
131 * For a gen_server process, the returned State is the state of
133 the callback module.
134 * For a gen_statem process, State is the tuple {Cur‐
136 rentState,CurrentData}.
137 * For a gen_event process, State is a list of tuples, where
139 each tuple corresponds to an event handler registered in the
140 process and contains {Module, Id, HandlerState}, as follows:
141 Module:
143 The module name of the event handler.
144 Id:
146 The ID of the handler (which is false if it was registered
147 without an ID).
148 HandlerState:
150 The state of the handler.
151 If the callback module exports a function system_get_state/1, it
153 is called in the target process to get its state. Its argument
154 is the same as the Misc value returned by get_status/1,2, and
155 function Module:system_get_state/1 is expected to extract the
156 state of the callback module from it. Function sys‐
157 tem_get_state/1 must return {ok, State}, where State is the
158 state of the callback module.
159 If the callback module does not export a system_get_state/1
161 function, get_state/1,2 assumes that the Misc value is the state
162 of the callback module and returns it directly instead.
163 If the callback module's system_get_state/1 function crashes or
165 throws an exception, the caller exits with error {call‐
166 back_failed, {Module, system_get_state}, {Class, Reason}}, where
167 Module is the name of the callback module and Class and Reason
168 indicate details of the exception.
169 Function system_get_state/1 is primarily useful for user-defined
171 behaviors and modules that implement OTP special processes. The
172 gen_server, gen_statem, and gen_event OTP behavior modules
173 export this function, so callback modules for those behaviors
174 need not to supply their own.
175 For more information about a process, including its state, see
177 get_status/1 and get_status/2.
178 get_status(Name) -> Status
180 get_status(Name, Timeout) -> Status
182 Types:
184 Name = name()
186 Timeout = timeout()
187 Status =
188 {status, Pid :: pid(), {module, Module :: module()},
189 [SItem]}
190 SItem =
191 (PDict :: [{Key :: term(), Value :: term()}]) |
192 (SysState :: running | suspended) |
193 (Parent :: pid()) |
194 (Dbg :: [dbg_opt()]) |
195 (Misc :: term())
196 Gets the status of the process.
198 The value of Misc varies for different types of processes, for
200 example:
201 * A gen_server process returns the state of the callback mod‐
203 ule.
204 * A gen_statem process returns information, such as its cur‐
206 rent state name and state data.
207 * A gen_event process returns information about each of its
209 registered handlers.
210 Callback modules for gen_server, gen_statem, and gen_event can
212 also change the value of Misc by exporting a function for‐
213 mat_status/2, which contributes module-specific information. For
214 details, see gen_server:format_status/2, gen_statem:format_sta‐
215 tus/2, and gen_event:format_status/2.
216 install(Name, FuncSpec) -> ok
218 install(Name, FuncSpec, Timeout) -> ok
220 Types:
222 Name = name()
224 FuncSpec = {Func, FuncState}
225 Func = dbg_fun()
226 FuncState = term()
227 Timeout = timeout()
228 Enables installation of alternative debug functions. An example
230 of such a function is a trigger, a function that waits for some
231 special event and performs some action when the event is gener‐
232 ated. For example, turning on low-level tracing.
233 Func is called whenever a system event is generated. This func‐
235 tion is to return done, or a new Func state. In the first case,
236 the function is removed. It is also removed if the function
237 fails.
238 log(Name, Flag) -> ok | {ok, [system_event()]}
240 log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}
242 Types:
244 Name = name()
246 Flag = true | {true, N :: integer() >= 1} | false | get |
247 print
248 Timeout = timeout()
249 Turns the logging of system events on or off. If on, a maximum
251 of N events are kept in the debug structure (default is 10).
252 If Flag is get, a list of all logged events is returned.
254 If Flag is print, the logged events are printed to standard_io.
256 The events are formatted with a function that is defined by the
258 process that generated the event (with a call to han‐
259 dle_debug/4).
260 log_to_file(Name, Flag) -> ok | {error, open_file}
262 log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}
264 Types:
266 Name = name()
268 Flag = (FileName :: string()) | false
269 Timeout = timeout()
270 Enables or disables the logging of all system events in text
272 format to the file. The events are formatted with a function
273 that is defined by the process that generated the event (with a
274 call to handle_debug/4). The file is opened with encoding UTF-8.
275 no_debug(Name) -> ok
277 no_debug(Name, Timeout) -> ok
279 Types:
281 Name = name()
283 Timeout = timeout()
284 Turns off all debugging for the process. This includes functions
286 that are installed explicitly with function install/2,3, for
287 example, triggers.
288 remove(Name, Func) -> ok
290 remove(Name, Func, Timeout) -> ok
292 Types:
294 Name = name()
296 Func = dbg_fun()
297 Timeout = timeout()
298 Removes an installed debug function from the process. Func must
300 be the same as previously installed.
301 replace_state(Name, StateFun) -> NewState
303 replace_state(Name, StateFun, Timeout) -> NewState
305 Types:
307 Name = name()
309 StateFun = fun((State :: term()) -> NewState :: term())
310 Timeout = timeout()
311 NewState = term()
312 Replaces the state of the process, and returns the new state.
314 Note:
316 These functions are intended only to help with debugging, and
317 are not to be called from normal code. They are provided for
318 convenience, allowing developers to avoid having to create their
319 own custom state replacement functions.
320 Function StateFun provides a new state for the process. Argument
323 State and the NewState return value of StateFun vary for differ‐
324 ent types of processes as follows:
325 * For a gen_server process, State is the state of the callback
327 module and NewState is a new instance of that state.
328 * For a gen_statem process, State is the tuple {Cur‐
330 rentState,CurrentData}, and NewState is a similar tuple,
331 which can contain a new current state, new state data, or
332 both.
333 * For a gen_event process, State is the tuple {Module, Id,
335 HandlerState} as follows:
336 Module:
338 The module name of the event handler.
339 Id:
341 The ID of the handler (which is false if it was registered
342 without an ID).
343 HandlerState:
345 The state of the handler.
346 NewState is a similar tuple where Module and Id are to have
348 the same values as in State, but the value of HandlerState
349 can be different. Returning a NewState, whose Module or Id
350 values differ from those of State, leaves the state of the
351 event handler unchanged. For a gen_event process, StateFun
352 is called once for each event handler registered in the
353 gen_event process.
354 If a StateFun function decides not to effect any change in
356 process state, then regardless of process type, it can return
357 its State argument.
358 If a StateFun function crashes or throws an exception, the orig‐
360 inal state of the process is unchanged for gen_server, and
361 gen_statem processes. For gen_event processes, a crashing or
362 failing StateFun function means that only the state of the par‐
363 ticular event handler it was working on when it failed or
364 crashed is unchanged; it can still succeed in changing the
365 states of other event handlers registered in the same gen_event
366 process.
367 If the callback module exports a system_replace_state/2 func‐
369 tion, it is called in the target process to replace its state
370 using StateFun. Its two arguments are StateFun and Misc, where
371 Misc is the same as the Misc value returned by get_status/1,2. A
372 system_replace_state/2 function is expected to return {ok, New‐
373 State, NewMisc}, where NewState is the new state of the callback
374 module, obtained by calling StateFun, and NewMisc is a possibly
375 new value used to replace the original Misc (required as Misc
376 often contains the state of the callback module within it).
377 If the callback module does not export a system_replace_state/2
379 function, replace_state/2,3 assumes that Misc is the state of
380 the callback module, passes it to StateFun and uses the return
381 value as both the new state and as the new value of Misc.
382 If the callback module's function system_replace_state/2 crashes
384 or throws an exception, the caller exits with error {call‐
385 back_failed, {Module, system_replace_state}, {Class, Reason}},
386 where Module is the name of the callback module and Class and
387 Reason indicate details of the exception. If the callback module
388 does not provide a system_replace_state/2 function and StateFun
389 crashes or throws an exception, the caller exits with error
390 {callback_failed, StateFun, {Class, Reason}}.
391 Function system_replace_state/2 is primarily useful for user-
393 defined behaviors and modules that implement OTP special pro‐
394 cesses. The OTP behavior modules gen_server, gen_statem, and
395 gen_event export this function, so callback modules for those
396 behaviors need not to supply their own.
397 resume(Name) -> ok
399 resume(Name, Timeout) -> ok
401 Types:
403 Name = name()
405 Timeout = timeout()
406 Resumes a suspended process.
408 statistics(Name, Flag) -> ok | {ok, Statistics}
410 statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}
412 Types:
414 Name = name()
416 Flag = true | false | get
417 Statistics = [StatisticsTuple] | no_statistics
418 StatisticsTuple =
419 {start_time, DateTime1} |
420 {current_time, DateTime2} |
421 {reductions, integer() >= 0} |
422 {messages_in, integer() >= 0} |
423 {messages_out, integer() >= 0}
424 DateTime1 = DateTime2 = file:date_time()
425 Timeout = timeout()
426 Enables or disables the collection of statistics. If Flag is
428 get, the statistical collection is returned.
429 suspend(Name) -> ok
431 suspend(Name, Timeout) -> ok
433 Types:
435 Name = name()
437 Timeout = timeout()
438 Suspends the process. When the process is suspended, it only
440 responds to other system messages, but not other messages.
441 terminate(Name, Reason) -> ok
443 terminate(Name, Reason, Timeout) -> ok
445 Types:
447 Name = name()
449 Reason = term()
450 Timeout = timeout()
451 Orders the process to terminate with the specified Reason. The
453 termination is done asynchronously, so it is not guaranteed that
454 the process is terminated when the function returns.
455 trace(Name, Flag) -> ok
457 trace(Name, Flag, Timeout) -> ok
459 Types:
461 Name = name()
463 Flag = boolean()
464 Timeout = timeout()
465 Prints all system events on standard_io. The events are format‐
467 ted with a function that is defined by the process that gener‐
468 ated the event (with a call to handle_debug/4).
469
471 The following functions are used when implementing a special process.
472 This is an ordinary process, which does not use a standard behavior,
473 but a process that understands the standard system messages.
474
476 debug_options(Options) -> [dbg_opt()]
477 Types:
479 Options = [Opt]
481 Opt =
482 trace |
483 log |
484 {log, integer() >= 1} |
485 statistics |
486 {log_to_file, FileName} |
487 {install, FuncSpec}
488 FileName = file:name()
489 FuncSpec = {Func, FuncState}
490 Func = dbg_fun()
491 FuncState = term()
492 Can be used by a process that initiates a debug structure from a
494 list of options. The values of argument Opt are the same as for
495 the corresponding functions.
496 get_debug(Item, Debug, Default) -> term()
498 Types:
500 Item = log | statistics
502 Debug = [dbg_opt()]
503 Default = term()
504 Gets the data associated with a debug option. Default is
506 returned if Item is not found. Can be used by the process to
507 retrieve debug data for printing before it terminates.
508 handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]
510 Types:
512 Debug = [dbg_opt()]
514 FormFunc = format_fun()
515 Extra = term()
516 Event = system_event()
517 This function is called by a process when it generates a system
519 event. FormFunc is a formatting function, called as Form‐
520 Func(Device, Event, Extra) to print the events, which is neces‐
521 sary if tracing is activated. Extra is any extra information
522 that the process needs in the format function, for example, the
523 process name.
524 handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
526 no_return()
527 Types:
529 Msg = term()
531 From = {pid(), Tag :: term()}
532 Parent = pid()
533 Module = module()
534 Debug = [dbg_opt()]
535 Misc = term()
536 This function is used by a process module to take care of system
538 messages. The process receives a {system, From, Msg} message and
539 passes Msg and From to this function.
540 This function never returns. It calls either of the following
542 functions:
543 * Module:system_continue(Parent, NDebug, Misc), where the
545 process continues the execution.
546 * Module:system_terminate(Reason, Parent, Debug, Misc), if the
548 process is to terminate.
549 Module must export the following:
551 * system_continue/3
553 * system_terminate/4
555 * system_code_change/4
557 * system_get_state/1
559 * system_replace_state/2
561 Argument Misc can be used to save internal data in a process,
563 for example, its state. It is sent to Module:system_continue/3
564 or Module:system_terminate/4.
565 print_log(Debug) -> ok
567 Types:
569 Debug = [dbg_opt()]
571 Prints the logged system events in the debug structure, using
573 FormFunc as defined when the event was generated by a call to
574 handle_debug/4.
575 Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}
577 Types:
579 Misc = term()
581 OldVsn = undefined | term()
582 Module = atom()
583 Extra = term()
584 NMisc = term()
585 Called from handle_system_msg/6 when the process is to perform a
587 code change. The code change is used when the internal data
588 structure has changed. This function converts argument Misc to
589 the new data structure. OldVsn is attribute vsn of the old ver‐
590 sion of the Module. If no such attribute is defined, the atom
591 undefined is sent.
592 Module:system_continue(Parent, Debug, Misc) -> none()
594 Types:
596 Parent = pid()
598 Debug = [dbg_opt()]
599 Misc = term()
600 Called from handle_system_msg/6 when the process is to continue
602 its execution (for example, after it has been suspended). This
603 function never returns.
604 Module:system_get_state(Misc) -> {ok, State}
606 Types:
608 Misc = term()
610 State = term()
611 Called from handle_system_msg/6 when the process is to return a
613 term that reflects its current state. State is the value
614 returned by get_state/2.
615 Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}
617 Types:
619 StateFun = fun((State :: term()) -> NState)
621 Misc = term()
622 NState = term()
623 NMisc = term()
624 Called from handle_system_msg/6 when the process is to replace
626 its current state. NState is the value returned by
627 replace_state/3.
628 Module:system_terminate(Reason, Parent, Debug, Misc) -> none()
630 Types:
632 Reason = term()
634 Parent = pid()
635 Debug = [dbg_opt()]
636 Misc = term()
637 Called from handle_system_msg/6 when the process is to termi‐
639 nate. For example, this function is called when the process is
640 suspended and its parent orders shutdown. It gives the process a
641 chance to do a cleanup. This function never returns.
642Ericsson AB stdlib 3.4.5.1 sys(3)