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 Four predefined system events are used when a process receives or sends
60 a message. The process can also define its own system events. It is
61 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 {out, Msg :: term(), To :: term(), State :: term()} |
72 term()
73 dbg_opt()
75 See the introduction of this manual page.
77 dbg_fun() =
79 fun((FuncState :: term(),
80 Event :: system_event(),
81 ProcState :: term()) ->
82 done | (NewFuncState :: term()))
83 format_fun() =
85 fun((Device :: io:device() | file:io_device(),
86 Event :: system_event(),
87 Extra :: term()) ->
88 any())
89
91 change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}
92 change_code(Name, Module, OldVsn, Extra, Timeout) ->
94 ok | {error, Reason}
95 Types:
97 Name = name()
99 Module = module()
100 OldVsn = undefined | term()
101 Extra = term()
102 Timeout = timeout()
103 Reason = term()
104 Tells the process to change code. The process must be suspended
106 to handle this message. Argument Extra is reserved for each
107 process to use as its own. Function Module:system_code_change/4
108 is called. OldVsn is the old version of the Module.
109 get_state(Name) -> State
111 get_state(Name, Timeout) -> State
113 Types:
115 Name = name()
117 Timeout = timeout()
118 State = term()
119 Gets the state of the process.
121 Note:
123 These functions are intended only to help with debugging. They
124 are provided for convenience, allowing developers to avoid hav‐
125 ing to create their own state extraction functions and also
126 avoid having to interactively extract the state from the return
127 values of get_status/1 or get_status/2 while debugging.
128 The value of State varies for different types of processes, as
131 follows:
132 * For a gen_server process, the returned State is the state of
134 the callback module.
135 * For a gen_statem process, State is the tuple {Cur‐
137 rentState,CurrentData}.
138 * For a gen_event process, State is a list of tuples, where
140 each tuple corresponds to an event handler registered in the
141 process and contains {Module, Id, HandlerState}, as follows:
142 Module:
144 The module name of the event handler.
145 Id:
147 The ID of the handler (which is false if it was registered
148 without an ID).
149 HandlerState:
151 The state of the handler.
152 If the callback module exports a function system_get_state/1, it
154 is called in the target process to get its state. Its argument
155 is the same as the Misc value returned by get_status/1,2, and
156 function Module:system_get_state/1 is expected to extract the
157 state of the callback module from it. Function sys‐
158 tem_get_state/1 must return {ok, State}, where State is the
159 state of the callback module.
160 If the callback module does not export a system_get_state/1
162 function, get_state/1,2 assumes that the Misc value is the state
163 of the callback module and returns it directly instead.
164 If the callback module's system_get_state/1 function crashes or
166 throws an exception, the caller exits with error {call‐
167 back_failed, {Module, system_get_state}, {Class, Reason}}, where
168 Module is the name of the callback module and Class and Reason
169 indicate details of the exception.
170 Function system_get_state/1 is primarily useful for user-defined
172 behaviors and modules that implement OTP special processes. The
173 gen_server, gen_statem, and gen_event OTP behavior modules
174 export this function, so callback modules for those behaviors
175 need not to supply their own.
176 For more information about a process, including its state, see
178 get_status/1 and get_status/2.
179 get_status(Name) -> Status
181 get_status(Name, Timeout) -> Status
183 Types:
185 Name = name()
187 Timeout = timeout()
188 Status =
189 {status, Pid :: pid(), {module, Module :: module()},
190 [SItem]}
191 SItem =
192 (PDict :: [{Key :: term(), Value :: term()}]) |
193 (SysState :: running | suspended) |
194 (Parent :: pid()) |
195 (Dbg :: [dbg_opt()]) |
196 (Misc :: term())
197 Gets the status of the process.
199 The value of Misc varies for different types of processes, for
201 example:
202 * A gen_server process returns the state of the callback mod‐
204 ule.
205 * A gen_statem process returns information, such as its cur‐
207 rent state name and state data.
208 * A gen_event process returns information about each of its
210 registered handlers.
211 Callback modules for gen_server, gen_statem, and gen_event can
213 also change the value of Misc by exporting a function for‐
214 mat_status/2, which contributes module-specific information. For
215 details, see gen_server:format_status/2, gen_statem:format_sta‐
216 tus/2, and gen_event:format_status/2.
217 install(Name, FuncSpec) -> ok
219 install(Name, FuncSpec, Timeout) -> ok
221 Types:
223 Name = name()
225 FuncSpec = {Func, FuncState} | {FuncId, Func, FuncState}
226 FuncId = term()
227 Func = dbg_fun()
228 FuncState = term()
229 Timeout = timeout()
230 Enables installation of alternative debug functions. An example
232 of such a function is a trigger, a function that waits for some
233 special event and performs some action when the event is gener‐
234 ated. For example, turning on low-level tracing.
235 Func is called whenever a system event is generated. This func‐
237 tion is to return done, or a new Func state. In the first case,
238 the function is removed. It is also removed if the function
239 fails. If one debug function should be installed more times, a
240 unique FuncId must be specified for each installation.
241 log(Name, Flag) -> ok | {ok, [system_event()]}
243 log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}
245 Types:
247 Name = name()
249 Flag = true | {true, N :: integer() >= 1} | false | get |
250 print
251 Timeout = timeout()
252 Turns the logging of system events on or off. If on, a maximum
254 of N events are kept in the debug structure (default is 10).
255 If Flag is get, a list of all logged events is returned.
257 If Flag is print, the logged events are printed to standard_io.
259 The events are formatted with a function that is defined by the
261 process that generated the event (with a call to han‐
262 dle_debug/4).
263 log_to_file(Name, Flag) -> ok | {error, open_file}
265 log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}
267 Types:
269 Name = name()
271 Flag = (FileName :: string()) | false
272 Timeout = timeout()
273 Enables or disables the logging of all system events in text
275 format to the file. The events are formatted with a function
276 that is defined by the process that generated the event (with a
277 call to handle_debug/4). The file is opened with encoding UTF-8.
278 no_debug(Name) -> ok
280 no_debug(Name, Timeout) -> ok
282 Types:
284 Name = name()
286 Timeout = timeout()
287 Turns off all debugging for the process. This includes functions
289 that are installed explicitly with function install/2,3, for
290 example, triggers.
291 remove(Name, FuncOrFuncId :: Func | FuncId) -> ok
293 remove(Name, FuncOrFuncId :: Func | FuncId, Timeout) -> ok
295 Types:
297 Name = name()
299 Func = dbg_fun()
300 FuncId = term()
301 Timeout = timeout()
302 Removes an installed debug function from the process. Func or
304 FuncId must be the same as previously installed.
305 replace_state(Name, StateFun) -> NewState
307 replace_state(Name, StateFun, Timeout) -> NewState
309 Types:
311 Name = name()
313 StateFun = fun((State :: term()) -> NewState :: term())
314 Timeout = timeout()
315 NewState = term()
316 Replaces the state of the process, and returns the new state.
318 Note:
320 These functions are intended only to help with debugging, and
321 are not to be called from normal code. They are provided for
322 convenience, allowing developers to avoid having to create their
323 own custom state replacement functions.
324 Function StateFun provides a new state for the process. Argument
327 State and the NewState return value of StateFun vary for differ‐
328 ent types of processes as follows:
329 * For a gen_server process, State is the state of the callback
331 module and NewState is a new instance of that state.
332 * For a gen_statem process, State is the tuple {Cur‐
334 rentState,CurrentData}, and NewState is a similar tuple,
335 which can contain a new current state, new state data, or
336 both.
337 * For a gen_event process, State is the tuple {Module, Id,
339 HandlerState} as follows:
340 Module:
342 The module name of the event handler.
343 Id:
345 The ID of the handler (which is false if it was registered
346 without an ID).
347 HandlerState:
349 The state of the handler.
350 NewState is a similar tuple where Module and Id are to have
352 the same values as in State, but the value of HandlerState
353 can be different. Returning a NewState, whose Module or Id
354 values differ from those of State, leaves the state of the
355 event handler unchanged. For a gen_event process, StateFun
356 is called once for each event handler registered in the
357 gen_event process.
358 If a StateFun function decides not to effect any change in
360 process state, then regardless of process type, it can return
361 its State argument.
362 If a StateFun function crashes or throws an exception, the orig‐
364 inal state of the process is unchanged for gen_server, and
365 gen_statem processes. For gen_event processes, a crashing or
366 failing StateFun function means that only the state of the par‐
367 ticular event handler it was working on when it failed or
368 crashed is unchanged; it can still succeed in changing the
369 states of other event handlers registered in the same gen_event
370 process.
371 If the callback module exports a system_replace_state/2 func‐
373 tion, it is called in the target process to replace its state
374 using StateFun. Its two arguments are StateFun and Misc, where
375 Misc is the same as the Misc value returned by get_status/1,2. A
376 system_replace_state/2 function is expected to return {ok, New‐
377 State, NewMisc}, where NewState is the new state of the callback
378 module, obtained by calling StateFun, and NewMisc is a possibly
379 new value used to replace the original Misc (required as Misc
380 often contains the state of the callback module within it).
381 If the callback module does not export a system_replace_state/2
383 function, replace_state/2,3 assumes that Misc is the state of
384 the callback module, passes it to StateFun and uses the return
385 value as both the new state and as the new value of Misc.
386 If the callback module's function system_replace_state/2 crashes
388 or throws an exception, the caller exits with error {call‐
389 back_failed, {Module, system_replace_state}, {Class, Reason}},
390 where Module is the name of the callback module and Class and
391 Reason indicate details of the exception. If the callback module
392 does not provide a system_replace_state/2 function and StateFun
393 crashes or throws an exception, the caller exits with error
394 {callback_failed, StateFun, {Class, Reason}}.
395 Function system_replace_state/2 is primarily useful for user-
397 defined behaviors and modules that implement OTP special pro‐
398 cesses. The OTP behavior modules gen_server, gen_statem, and
399 gen_event export this function, so callback modules for those
400 behaviors need not to supply their own.
401 resume(Name) -> ok
403 resume(Name, Timeout) -> ok
405 Types:
407 Name = name()
409 Timeout = timeout()
410 Resumes a suspended process.
412 statistics(Name, Flag) -> ok | {ok, Statistics}
414 statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}
416 Types:
418 Name = name()
420 Flag = true | false | get
421 Statistics = [StatisticsTuple] | no_statistics
422 StatisticsTuple =
423 {start_time, DateTime1} |
424 {current_time, DateTime2} |
425 {reductions, integer() >= 0} |
426 {messages_in, integer() >= 0} |
427 {messages_out, integer() >= 0}
428 DateTime1 = DateTime2 = file:date_time()
429 Timeout = timeout()
430 Enables or disables the collection of statistics. If Flag is
432 get, the statistical collection is returned.
433 suspend(Name) -> ok
435 suspend(Name, Timeout) -> ok
437 Types:
439 Name = name()
441 Timeout = timeout()
442 Suspends the process. When the process is suspended, it only
444 responds to other system messages, but not other messages.
445 terminate(Name, Reason) -> ok
447 terminate(Name, Reason, Timeout) -> ok
449 Types:
451 Name = name()
453 Reason = term()
454 Timeout = timeout()
455 Orders the process to terminate with the specified Reason. The
457 termination is done asynchronously, so it is not guaranteed that
458 the process is terminated when the function returns.
459 trace(Name, Flag) -> ok
461 trace(Name, Flag, Timeout) -> ok
463 Types:
465 Name = name()
467 Flag = boolean()
468 Timeout = timeout()
469 Prints all system events on standard_io. The events are format‐
471 ted with a function that is defined by the process that gener‐
472 ated the event (with a call to handle_debug/4).
473
475 The following functions are used when implementing a special process.
476 This is an ordinary process, which does not use a standard behavior,
477 but a process that understands the standard system messages.
478
480 debug_options(Options) -> [dbg_opt()]
481 Types:
483 Options = [Opt]
485 Opt =
486 trace |
487 log |
488 {log, integer() >= 1} |
489 statistics |
490 {log_to_file, FileName} |
491 {install, FuncSpec}
492 FileName = file:name()
493 FuncSpec = {Func, FuncState} | {FuncId, Func, FuncState}
494 FuncId = term()
495 Func = dbg_fun()
496 FuncState = term()
497 Can be used by a process that initiates a debug structure from a
499 list of options. The values of argument Opt are the same as for
500 the corresponding functions.
501 get_debug(Item, Debug, Default) -> term()
503 Types:
505 Item = log | statistics
507 Debug = [dbg_opt()]
508 Default = term()
509 Gets the data associated with a debug option. Default is
511 returned if Item is not found. Can be used by the process to
512 retrieve debug data for printing before it terminates.
513 handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]
515 Types:
517 Debug = [dbg_opt()]
519 FormFunc = format_fun()
520 Extra = term()
521 Event = system_event()
522 This function is called by a process when it generates a system
524 event. FormFunc is a formatting function, called as Form‐
525 Func(Device, Event, Extra) to print the events, which is neces‐
526 sary if tracing is activated. Extra is any extra information
527 that the process needs in the format function, for example, the
528 process name.
529 handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
531 no_return()
532 Types:
534 Msg = term()
536 From = {pid(), Tag :: term()}
537 Parent = pid()
538 Module = module()
539 Debug = [dbg_opt()]
540 Misc = term()
541 This function is used by a process module to take care of system
543 messages. The process receives a {system, From, Msg} message and
544 passes Msg and From to this function.
545 This function never returns. It calls either of the following
547 functions:
548 * Module:system_continue(Parent, NDebug, Misc), where the
550 process continues the execution.
551 * Module:system_terminate(Reason, Parent, Debug, Misc), if the
553 process is to terminate.
554 Module must export the following:
556 * system_continue/3
558 * system_terminate/4
560 * system_code_change/4
562 * system_get_state/1
564 * system_replace_state/2
566 Argument Misc can be used to save internal data in a process,
568 for example, its state. It is sent to Module:system_continue/3
569 or Module:system_terminate/4.
570 print_log(Debug) -> ok
572 Types:
574 Debug = [dbg_opt()]
576 Prints the logged system events in the debug structure, using
578 FormFunc as defined when the event was generated by a call to
579 handle_debug/4.
580 Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}
582 Types:
584 Misc = term()
586 OldVsn = undefined | term()
587 Module = atom()
588 Extra = term()
589 NMisc = term()
590 Called from handle_system_msg/6 when the process is to perform a
592 code change. The code change is used when the internal data
593 structure has changed. This function converts argument Misc to
594 the new data structure. OldVsn is attribute vsn of the old ver‐
595 sion of the Module. If no such attribute is defined, the atom
596 undefined is sent.
597 Module:system_continue(Parent, Debug, Misc) -> none()
599 Types:
601 Parent = pid()
603 Debug = [dbg_opt()]
604 Misc = term()
605 Called from handle_system_msg/6 when the process is to continue
607 its execution (for example, after it has been suspended). This
608 function never returns.
609 Module:system_get_state(Misc) -> {ok, State}
611 Types:
613 Misc = term()
615 State = term()
616 Called from handle_system_msg/6 when the process is to return a
618 term that reflects its current state. State is the value
619 returned by get_state/2.
620 Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}
622 Types:
624 StateFun = fun((State :: term()) -> NState)
626 Misc = term()
627 NState = term()
628 NMisc = term()
629 Called from handle_system_msg/6 when the process is to replace
631 its current state. NState is the value returned by
632 replace_state/3.
633 Module:system_terminate(Reason, Parent, Debug, Misc) -> none()
635 Types:
637 Reason = term()
639 Parent = pid()
640 Debug = [dbg_opt()]
641 Misc = term()
642 Called from handle_system_msg/6 when the process is to termi‐
644 nate. For example, this function is called when the process is
645 suspended and its parent orders shutdown. It gives the process a
646 chance to do a cleanup. This function never returns.
647Ericsson AB stdlib 3.8.2.1 sys(3)