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 un‐
13 derstand system messages, such as debug messages and code change. These
14 functions must be used to implement the use of system messages for a
15 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 al‐
61 ways 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(), State :: term()} |
70 {out, Msg :: term(), To :: term()} |
71 {out, Msg :: term(), To :: term(), State :: term()} |
72 {noreply, State :: term()} |
73 {continue, Continuation :: term()} |
74 {code_change, Event :: term(), State :: term()} |
75 {postpone,
76 Event :: term(),
77 State :: term(),
78 NextState :: term()} |
79 {consume,
80 Event :: term(),
81 State :: term(),
82 NextState :: term()} |
83 {start_timer, Action :: term(), State :: term()} |
84 {insert_timeout, Event :: term(), State :: term()} |
85 {enter, State :: term()} |
86 {terminate, Reason :: term(), State :: term()} |
87 term()
88 {in,Msg}:
90 Is produced by gen_server and gen_event when the message Msg
91 arrives.
92 {in,Msg,State}:
94 Is produced by gen_statem when the message Msg arrives in
95 state State.
96 For gen_statem the Msg term is an {EventType,EventContent}
98 tuple.
99 {out,Msg,To}:
101 Is produced by gen_statem when the reply Msg is sent back to
102 To by returning a {reply,To,Msg} action from the callback
103 module.
104 To is of the same type as the first argument to
106 gen_statem:reply/2.
107 {out,Msg,To,State}:
109 Is produced by gen_server when the reply Msg is sent back to
110 To by returning a {reply,...} tuple from the callback mod‐
111 ule.
112 To is of the same type as the first argument to
114 gen_server:reply/2.
115 State is the new server state.
117 {noreply,State}:
119 Is produced by gen_server when a {noreply,...} tuple is re‐
120 turned from the callback module.
121 State is the new server state.
123 {continue,Continuation}:
125 Is produced by gen_server when a {continue,Continuation} tu‐
126 ple is returned from the callback module.
127 {code_change,Event,State}:
129 Is produced by gen_statem when the message Event arrives in
130 state State as the first event after a code change.
131 Event is an {EventType,EventContent} tuple.
133 {postpone,Event,State,NextState} :
135 Is produced by gen_statem when the message Event is post‐
136 poned in state State. NextState is the new state.
137 Event is an {EventType,EventContent} tuple.
139 {consume,Event,State,NextState} :
141 Is produced by gen_statem when the message Event is consumed
142 in state State. NextState is the new state.
143 Event is an {EventType,EventContent} tuple.
145 {start_timer,Action,State} :
147 Is produced by gen_statem when the action Action starts a
148 timer in state State.
149 {insert_timeout,Event,State} :
151 Is produced by gen_statem when a timeout zero action inserts
152 event Event in state State.
153 Event is an {EventType,EventContent} tuple.
155 {enter,State} :
157 Is produced by gen_statem when the first state State is en‐
158 tered.
159 {terminate,Reason,State} :
161 Is produced by gen_statem when it terminates with reason
162 Reason in state State.
163 dbg_opt()
165 See the introduction of this manual page.
167 dbg_fun() =
169 fun((FuncState :: term(),
170 Event :: system_event(),
171 ProcState :: term()) ->
172 done | (NewFuncState :: term()))
173 debug_option() =
175 trace | log |
176 {log, N :: integer() >= 1} |
177 statistics |
178 {log_to_file, FileName :: file:name()} |
179 {install,
180 {Func :: dbg_fun(), FuncState :: term()} |
181 {FuncId :: term(), Func :: dbg_fun(), FuncState :: term()}}
182 format_fun() =
184 fun((Device :: io:device() | file:io_device(),
185 Event :: system_event(),
186 Extra :: term()) ->
187 any())
188
190 change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}
191 change_code(Name, Module, OldVsn, Extra, Timeout) ->
193 ok | {error, Reason}
194 Types:
196 Name = name()
198 Module = module()
199 OldVsn = undefined | term()
200 Extra = term()
201 Timeout = timeout()
202 Reason = term()
203 Tells the process to change code. The process must be suspended
205 to handle this message. Argument Extra is reserved for each
206 process to use as its own. Function Module:system_code_change/4
207 is called. OldVsn is the old version of the Module.
208 get_state(Name) -> State
210 get_state(Name, Timeout) -> State
212 Types:
214 Name = name()
216 Timeout = timeout()
217 State = term()
218 Gets the state of the process.
220 Note:
222 These functions are intended only to help with debugging. They
223 are provided for convenience, allowing developers to avoid hav‐
224 ing to create their own state extraction functions and also
225 avoid having to interactively extract the state from the return
226 values of get_status/1 or get_status/2 while debugging.
227 The value of State varies for different types of processes, as
230 follows:
231 * For a gen_server process, the returned State is the state of
233 the callback module.
234 * For a gen_statem process, State is the tuple {Cur‐
236 rentState,CurrentData}.
237 * For a gen_event process, State is a list of tuples, where
239 each tuple corresponds to an event handler registered in the
240 process and contains {Module, Id, HandlerState}, as follows:
241 Module:
243 The module name of the event handler.
244 Id:
246 The ID of the handler (which is false if it was registered
247 without an ID).
248 HandlerState:
250 The state of the handler.
251 If the callback module exports a function system_get_state/1, it
253 is called in the target process to get its state. Its argument
254 is the same as the Misc value returned by get_status/1,2, and
255 function Module:system_get_state/1 is expected to extract the
256 state of the callback module from it. Function sys‐
257 tem_get_state/1 must return {ok, State}, where State is the
258 state of the callback module.
259 If the callback module does not export a system_get_state/1
261 function, get_state/1,2 assumes that the Misc value is the state
262 of the callback module and returns it directly instead.
263 If the callback module's system_get_state/1 function crashes or
265 throws an exception, the caller exits with error {call‐
266 back_failed, {Module, system_get_state}, {Class, Reason}}, where
267 Module is the name of the callback module and Class and Reason
268 indicate details of the exception.
269 Function system_get_state/1 is primarily useful for user-defined
271 behaviors and modules that implement OTP special processes. The
272 gen_server, gen_statem, and gen_event OTP behavior modules ex‐
273 port this function, so callback modules for those behaviors need
274 not to supply their own.
275 For more information about a process, including its state, see
277 get_status/1 and get_status/2.
278 get_status(Name) -> Status
280 get_status(Name, Timeout) -> Status
282 Types:
284 Name = name()
286 Timeout = timeout()
287 Status =
288 {status, Pid :: pid(), {module, Module :: module()},
289 [SItem]}
290 SItem =
291 (PDict :: [{Key :: term(), Value :: term()}]) |
292 (SysState :: running | suspended) |
293 (Parent :: pid()) |
294 (Dbg :: [dbg_opt()]) |
295 (Misc :: term())
296 Gets the status of the process.
298 The value of Misc varies for different types of processes, for
300 example:
301 * A gen_server process returns the state of the callback mod‐
303 ule.
304 * A gen_statem process returns information, such as its cur‐
306 rent state name and state data.
307 * A gen_event process returns information about each of its
309 registered handlers.
310 Callback modules for gen_server, gen_statem, and gen_event can
312 also change the value of Misc by exporting a function for‐
313 mat_status/2, which contributes module-specific information. For
314 details, see gen_server:format_status/2, gen_statem:format_sta‐
315 tus/2, and gen_event:format_status/2.
316 install(Name, FuncSpec) -> ok
318 install(Name, FuncSpec, Timeout) -> ok
320 Types:
322 Name = name()
324 FuncSpec = {Func, FuncState} | {FuncId, Func, FuncState}
325 FuncId = term()
326 Func = dbg_fun()
327 FuncState = term()
328 Timeout = timeout()
329 Enables installation of alternative debug functions. An example
331 of such a function is a trigger, a function that waits for some
332 special event and performs some action when the event is gener‐
333 ated. For example, turning on low-level tracing.
334 Func is called whenever a system event is generated. This func‐
336 tion is to return done, or a new Func state. In the first case,
337 the function is removed. It is also removed if the function
338 fails. If one debug function should be installed more times, a
339 unique FuncId must be specified for each installation.
340 log(Name, Flag) -> ok | {ok, [system_event()]}
342 log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}
344 Types:
346 Name = name()
348 Flag = true | {true, N :: integer() >= 1} | false | get |
349 print
350 Timeout = timeout()
351 Turns the logging of system events on or off. If on, a maximum
353 of N events are kept in the debug structure (default is 10).
354 If Flag is get, a list of all logged events is returned.
356 If Flag is print, the logged events are printed to standard_io.
358 The events are formatted with a function that is defined by the
360 process that generated the event (with a call to handle_de‐
361 bug/4).
362 log_to_file(Name, Flag) -> ok | {error, open_file}
364 log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}
366 Types:
368 Name = name()
370 Flag = (FileName :: string()) | false
371 Timeout = timeout()
372 Enables or disables the logging of all system events in text
374 format to the file. The events are formatted with a function
375 that is defined by the process that generated the event (with a
376 call to handle_debug/4). The file is opened with encoding UTF-8.
377 no_debug(Name) -> ok
379 no_debug(Name, Timeout) -> ok
381 Types:
383 Name = name()
385 Timeout = timeout()
386 Turns off all debugging for the process. This includes functions
388 that are installed explicitly with function install/2,3, for ex‐
389 ample, triggers.
390 remove(Name, FuncOrFuncId :: Func | FuncId) -> ok
392 remove(Name, FuncOrFuncId :: Func | FuncId, Timeout) -> ok
394 Types:
396 Name = name()
398 Func = dbg_fun()
399 FuncId = term()
400 Timeout = timeout()
401 Removes an installed debug function from the process. Func or
403 FuncId must be the same as previously installed.
404 replace_state(Name, StateFun) -> NewState
406 replace_state(Name, StateFun, Timeout) -> NewState
408 Types:
410 Name = name()
412 StateFun = fun((State :: term()) -> NewState :: term())
413 Timeout = timeout()
414 NewState = term()
415 Replaces the state of the process, and returns the new state.
417 Note:
419 These functions are intended only to help with debugging, and
420 are not to be called from normal code. They are provided for
421 convenience, allowing developers to avoid having to create their
422 own custom state replacement functions.
423 Function StateFun provides a new state for the process. Argument
426 State and the NewState return value of StateFun vary for differ‐
427 ent types of processes as follows:
428 * For a gen_server process, State is the state of the callback
430 module and NewState is a new instance of that state.
431 * For a gen_statem process, State is the tuple {Cur‐
433 rentState,CurrentData}, and NewState is a similar tuple,
434 which can contain a new current state, new state data, or
435 both.
436 * For a gen_event process, State is the tuple {Module, Id,
438 HandlerState} as follows:
439 Module:
441 The module name of the event handler.
442 Id:
444 The ID of the handler (which is false if it was registered
445 without an ID).
446 HandlerState:
448 The state of the handler.
449 NewState is a similar tuple where Module and Id are to have
451 the same values as in State, but the value of HandlerState
452 can be different. Returning a NewState, whose Module or Id
453 values differ from those of State, leaves the state of the
454 event handler unchanged. For a gen_event process, StateFun
455 is called once for each event handler registered in the
456 gen_event process.
457 If a StateFun function decides not to effect any change in
459 process state, then regardless of process type, it can return
460 its State argument.
461 If a StateFun function crashes or throws an exception, the orig‐
463 inal state of the process is unchanged for gen_server, and
464 gen_statem processes. For gen_event processes, a crashing or
465 failing StateFun function means that only the state of the par‐
466 ticular event handler it was working on when it failed or
467 crashed is unchanged; it can still succeed in changing the
468 states of other event handlers registered in the same gen_event
469 process.
470 If the callback module exports a system_replace_state/2 func‐
472 tion, it is called in the target process to replace its state
473 using StateFun. Its two arguments are StateFun and Misc, where
474 Misc is the same as the Misc value returned by get_status/1,2. A
475 system_replace_state/2 function is expected to return {ok, New‐
476 State, NewMisc}, where NewState is the new state of the callback
477 module, obtained by calling StateFun, and NewMisc is a possibly
478 new value used to replace the original Misc (required as Misc
479 often contains the state of the callback module within it).
480 If the callback module does not export a system_replace_state/2
482 function, replace_state/2,3 assumes that Misc is the state of
483 the callback module, passes it to StateFun and uses the return
484 value as both the new state and as the new value of Misc.
485 If the callback module's function system_replace_state/2 crashes
487 or throws an exception, the caller exits with error {call‐
488 back_failed, {Module, system_replace_state}, {Class, Reason}},
489 where Module is the name of the callback module and Class and
490 Reason indicate details of the exception. If the callback module
491 does not provide a system_replace_state/2 function and StateFun
492 crashes or throws an exception, the caller exits with error
493 {callback_failed, StateFun, {Class, Reason}}.
494 Function system_replace_state/2 is primarily useful for user-de‐
496 fined behaviors and modules that implement OTP special pro‐
497 cesses. The OTP behavior modules gen_server, gen_statem, and
498 gen_event export this function, so callback modules for those
499 behaviors need not to supply their own.
500 resume(Name) -> ok
502 resume(Name, Timeout) -> ok
504 Types:
506 Name = name()
508 Timeout = timeout()
509 Resumes a suspended process.
511 statistics(Name, Flag) -> ok | {ok, Statistics}
513 statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}
515 Types:
517 Name = name()
519 Flag = true | false | get
520 Statistics = [StatisticsTuple] | no_statistics
521 StatisticsTuple =
522 {start_time, DateTime1} |
523 {current_time, DateTime2} |
524 {reductions, integer() >= 0} |
525 {messages_in, integer() >= 0} |
526 {messages_out, integer() >= 0}
527 DateTime1 = DateTime2 = file:date_time()
528 Timeout = timeout()
529 Enables or disables the collection of statistics. If Flag is
531 get, the statistical collection is returned.
532 suspend(Name) -> ok
534 suspend(Name, Timeout) -> ok
536 Types:
538 Name = name()
540 Timeout = timeout()
541 Suspends the process. When the process is suspended, it only re‐
543 sponds to other system messages, but not other messages.
544 terminate(Name, Reason) -> ok
546 terminate(Name, Reason, Timeout) -> ok
548 Types:
550 Name = name()
552 Reason = term()
553 Timeout = timeout()
554 Orders the process to terminate with the specified Reason. The
556 termination is done asynchronously, so it is not guaranteed that
557 the process is terminated when the function returns.
558 trace(Name, Flag) -> ok
560 trace(Name, Flag, Timeout) -> ok
562 Types:
564 Name = name()
566 Flag = boolean()
567 Timeout = timeout()
568 Prints all system events on standard_io. The events are format‐
570 ted with a function that is defined by the process that gener‐
571 ated the event (with a call to handle_debug/4).
572
574 The following functions are used when implementing a special process.
575 This is an ordinary process, which does not use a standard behavior,
576 but a process that understands the standard system messages.
577
579 debug_options(Options :: [Opt :: debug_option()]) -> [dbg_opt()]
580 Can be used by a process that initiates a debug structure from a
582 list of options. The values of argument Opt are the same as for
583 the corresponding functions.
584 get_debug(Item, Debug, Default) -> term()
586 Types:
588 Item = log | statistics
590 Debug = [dbg_opt()]
591 Default = term()
592 Warning:
594 get_debug/3 is deprecated since it returns data of an internal
595 type only useful for debugging.
596 Gets the data associated with a debug option. Default is re‐
599 turned if Item is not found. Can be used by the process to re‐
600 trieve debug data for printing before it terminates.
601 handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]
603 Types:
605 Debug = [dbg_opt()]
607 FormFunc = format_fun()
608 Extra = term()
609 Event = system_event()
610 This function is called by a process when it generates a system
612 event. FormFunc is a formatting function, called as FormFunc(De‐
613 vice, Event, Extra) to print the events, which is necessary if
614 tracing is activated. Extra is any extra information that the
615 process needs in the format function, for example, the process
616 name.
617 handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
619 no_return()
620 Types:
622 Msg = term()
624 From = {pid(), Tag :: term()}
625 Parent = pid()
626 Module = module()
627 Debug = [dbg_opt()]
628 Misc = term()
629 This function is used by a process module to take care of system
631 messages. The process receives a {system, From, Msg} message and
632 passes Msg and From to this function.
633 This function never returns. It calls either of the following
635 functions:
636 * Module:system_continue(Parent, NDebug, Misc), where the
638 process continues the execution.
639 * Module:system_terminate(Reason, Parent, Debug, Misc), if the
641 process is to terminate.
642 Module must export the following:
644 * system_continue/3
646 * system_terminate/4
648 * system_code_change/4
650 * system_get_state/1
652 * system_replace_state/2
654 Argument Misc can be used to save internal data in a process,
656 for example, its state. It is sent to Module:system_continue/3
657 or Module:system_terminate/4.
658 print_log(Debug) -> ok
660 Types:
662 Debug = [dbg_opt()]
664 Prints the logged system events in the debug structure, using
666 FormFunc as defined when the event was generated by a call to
667 handle_debug/4.
668 get_log(Debug) -> [system_event()]
670 Types:
672 Debug = [dbg_opt()]
674 Returns the logged system events in the debug structure, that is
676 the last argument to handle_debug/4.
677 Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}
679 Types:
681 Misc = term()
683 OldVsn = undefined | term()
684 Module = atom()
685 Extra = term()
686 NMisc = term()
687 Called from handle_system_msg/6 when the process is to perform a
689 code change. The code change is used when the internal data
690 structure has changed. This function converts argument Misc to
691 the new data structure. OldVsn is attribute vsn of the old ver‐
692 sion of the Module. If no such attribute is defined, the atom
693 undefined is sent.
694 Module:system_continue(Parent, Debug, Misc) -> none()
696 Types:
698 Parent = pid()
700 Debug = [dbg_opt()]
701 Misc = term()
702 Called from handle_system_msg/6 when the process is to continue
704 its execution (for example, after it has been suspended). This
705 function never returns.
706 Module:system_get_state(Misc) -> {ok, State}
708 Types:
710 Misc = term()
712 State = term()
713 Called from handle_system_msg/6 when the process is to return a
715 term that reflects its current state. State is the value re‐
716 turned by get_state/2.
717 Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}
719 Types:
721 StateFun = fun((State :: term()) -> NState)
723 Misc = term()
724 NState = term()
725 NMisc = term()
726 Called from handle_system_msg/6 when the process is to replace
728 its current state. NState is the value returned by re‐
729 place_state/3.
730 Module:system_terminate(Reason, Parent, Debug, Misc) -> none()
732 Types:
734 Reason = term()
736 Parent = pid()
737 Debug = [dbg_opt()]
738 Misc = term()
739 Called from handle_system_msg/6 when the process is to termi‐
741 nate. For example, this function is called when the process is
742 suspended and its parent orders shutdown. It gives the process a
743 chance to do a cleanup. This function never returns.
744Ericsson AB stdlib 3.14.2.1 sys(3)