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 {postpone,
75 Event :: term(),
76 State :: term(),
77 NextState :: term()} |
78 {consume,
79 Event :: term(),
80 State :: term(),
81 NextState :: term()} |
82 {start_timer, Action :: term(), State :: term()} |
83 {insert_timeout, Event :: term(), State :: term()} |
84 {enter, Module :: module(), State :: term()} |
85 {module, Module :: module(), 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 {postpone,Event,State,NextState} :
129 Is produced by gen_statem when the message Event is post‐
130 poned in state State. NextState is the new state.
131 Event is an {EventType,EventContent} tuple.
133 {consume,Event,State,NextState} :
135 Is produced by gen_statem when the message Event is consumed
136 in state State. NextState is the new state.
137 Event is an {EventType,EventContent} tuple.
139 {start_timer,Action,State} :
141 Is produced by gen_statem when the action Action starts a
142 timer in state State.
143 {insert_timeout,Event,State} :
145 Is produced by gen_statem when a timeout zero action inserts
146 event Event in state State.
147 Event is an {EventType,EventContent} tuple.
149 {enter,Module,State} :
151 Is produced by gen_statem when module Module enters the
152 first state State.
153 {module,Module,State} :
155 Is produced by gen_statem when setting module Module in
156 state State.
157 {terminate,Reason,State} :
159 Is produced by gen_statem when it terminates with reason
160 Reason in state State.
161 dbg_opt()
163 See the introduction of this manual page.
165 dbg_fun() =
167 fun((FuncState :: term(),
168 Event :: system_event(),
169 ProcState :: term()) ->
170 done | (NewFuncState :: term()))
171 debug_option() =
173 trace | log |
174 {log, N :: integer() >= 1} |
175 statistics |
176 {log_to_file, FileName :: file:name()} |
177 {install,
178 {Func :: dbg_fun(), FuncState :: term()} |
179 {FuncId :: term(), Func :: dbg_fun(), FuncState :: term()}}
180 format_fun() =
182 fun((Device :: io:device() | file:io_device(),
183 Event :: system_event(),
184 Extra :: term()) ->
185 any())
186
188 change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}
189 change_code(Name, Module, OldVsn, Extra, Timeout) ->
191 ok | {error, Reason}
192 Types:
194 Name = name()
196 Module = module()
197 OldVsn = undefined | term()
198 Extra = term()
199 Timeout = timeout()
200 Reason = term()
201 Tells the process to change code. The process must be suspended
203 to handle this message. Argument Extra is reserved for each
204 process to use as its own. Function Module:system_code_change/4
205 is called. OldVsn is the old version of the Module.
206 get_state(Name) -> State
208 get_state(Name, Timeout) -> State
210 Types:
212 Name = name()
214 Timeout = timeout()
215 State = term()
216 Gets the state of the process.
218 Note:
220 These functions are intended only to help with debugging. They
221 are provided for convenience, allowing developers to avoid hav‐
222 ing to create their own state extraction functions and also
223 avoid having to interactively extract the state from the return
224 values of get_status/1 or get_status/2 while debugging.
225 The value of State varies for different types of processes, as
228 follows:
229 * For a gen_server process, the returned State is the state of
231 the callback module.
232 * For a gen_statem process, State is the tuple {Cur‐
234 rentState,CurrentData}.
235 * For a gen_event process, State is a list of tuples, where
237 each tuple corresponds to an event handler registered in the
238 process and contains {Module, Id, HandlerState}, as follows:
239 Module:
241 The module name of the event handler.
242 Id:
244 The ID of the handler (which is false if it was registered
245 without an ID).
246 HandlerState:
248 The state of the handler.
249 If the callback module exports a function system_get_state/1, it
251 is called in the target process to get its state. Its argument
252 is the same as the Misc value returned by get_status/1,2, and
253 function Module:system_get_state/1 is expected to extract the
254 state of the callback module from it. Function sys‐
255 tem_get_state/1 must return {ok, State}, where State is the
256 state of the callback module.
257 If the callback module does not export a system_get_state/1
259 function, get_state/1,2 assumes that the Misc value is the state
260 of the callback module and returns it directly instead.
261 If the callback module's system_get_state/1 function crashes or
263 throws an exception, the caller exits with error {call‐
264 back_failed, {Module, system_get_state}, {Class, Reason}}, where
265 Module is the name of the callback module and Class and Reason
266 indicate details of the exception.
267 Function system_get_state/1 is primarily useful for user-defined
269 behaviors and modules that implement OTP special processes. The
270 gen_server, gen_statem, and gen_event OTP behavior modules ex‐
271 port this function, so callback modules for those behaviors need
272 not to supply their own.
273 For more information about a process, including its state, see
275 get_status/1 and get_status/2.
276 get_status(Name) -> Status
278 get_status(Name, Timeout) -> Status
280 Types:
282 Name = name()
284 Timeout = timeout()
285 Status =
286 {status, Pid :: pid(), {module, Module :: module()},
287 [SItem]}
288 SItem =
289 (PDict :: [{Key :: term(), Value :: term()}]) |
290 (SysState :: running | suspended) |
291 (Parent :: pid()) |
292 (Dbg :: [dbg_opt()]) |
293 (Misc :: term())
294 Gets the status of the process.
296 The value of Misc varies for different types of processes, for
298 example:
299 * A gen_server process returns the state of the callback mod‐
301 ule.
302 * A gen_statem process returns information, such as its cur‐
304 rent state name and state data.
305 * A gen_event process returns information about each of its
307 registered handlers.
308 Callback modules for gen_server, gen_statem, and gen_event can
310 also change the value of Misc by exporting a function for‐
311 mat_status/2, which contributes module-specific information. For
312 details, see gen_server:format_status/2, gen_statem:format_sta‐
313 tus/2, and gen_event:format_status/2.
314 install(Name, FuncSpec) -> ok
316 install(Name, FuncSpec, Timeout) -> ok
318 Types:
320 Name = name()
322 FuncSpec = {Func, FuncState} | {FuncId, Func, FuncState}
323 FuncId = term()
324 Func = dbg_fun()
325 FuncState = term()
326 Timeout = timeout()
327 Enables installation of alternative debug functions. An example
329 of such a function is a trigger, a function that waits for some
330 special event and performs some action when the event is gener‐
331 ated. For example, turning on low-level tracing.
332 Func is called whenever a system event is generated. This func‐
334 tion is to return done, or a new Func state. In the first case,
335 the function is removed. It is also removed if the function
336 fails. If one debug function should be installed more times, a
337 unique FuncId must be specified for each installation.
338 log(Name, Flag) -> ok | {ok, [system_event()]}
340 log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}
342 Types:
344 Name = name()
346 Flag = true | {true, N :: integer() >= 1} | false | get |
347 print
348 Timeout = timeout()
349 Turns the logging of system events on or off. If on, a maximum
351 of N events are kept in the debug structure (default is 10).
352 If Flag is get, a list of all logged events is returned.
354 If Flag is print, the logged events are printed to standard_io.
356 The events are formatted with a function that is defined by the
358 process that generated the event (with a call to handle_de‐
359 bug/4).
360 log_to_file(Name, Flag) -> ok | {error, open_file}
362 log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}
364 Types:
366 Name = name()
368 Flag = (FileName :: string()) | false
369 Timeout = timeout()
370 Enables or disables the logging of all system events in text
372 format to the file. The events are formatted with a function
373 that is defined by the process that generated the event (with a
374 call to handle_debug/4). The file is opened with encoding UTF-8.
375 no_debug(Name) -> ok
377 no_debug(Name, Timeout) -> ok
379 Types:
381 Name = name()
383 Timeout = timeout()
384 Turns off all debugging for the process. This includes functions
386 that are installed explicitly with function install/2,3, for ex‐
387 ample, triggers.
388 remove(Name, FuncOrFuncId :: Func | FuncId) -> ok
390 remove(Name, FuncOrFuncId :: Func | FuncId, Timeout) -> ok
392 Types:
394 Name = name()
396 Func = dbg_fun()
397 FuncId = term()
398 Timeout = timeout()
399 Removes an installed debug function from the process. Func or
401 FuncId must be the same as previously installed.
402 replace_state(Name, StateFun) -> NewState
404 replace_state(Name, StateFun, Timeout) -> NewState
406 Types:
408 Name = name()
410 StateFun = fun((State :: term()) -> NewState :: term())
411 Timeout = timeout()
412 NewState = term()
413 Replaces the state of the process, and returns the new state.
415 Note:
417 These functions are intended only to help with debugging, and
418 are not to be called from normal code. They are provided for
419 convenience, allowing developers to avoid having to create their
420 own custom state replacement functions.
421 Function StateFun provides a new state for the process. Argument
424 State and the NewState return value of StateFun vary for differ‐
425 ent types of processes as follows:
426 * For a gen_server process, State is the state of the callback
428 module and NewState is a new instance of that state.
429 * For a gen_statem process, State is the tuple {Cur‐
431 rentState,CurrentData}, and NewState is a similar tuple,
432 which can contain a new current state, new state data, or
433 both.
434 * For a gen_event process, State is the tuple {Module, Id,
436 HandlerState} as follows:
437 Module:
439 The module name of the event handler.
440 Id:
442 The ID of the handler (which is false if it was registered
443 without an ID).
444 HandlerState:
446 The state of the handler.
447 NewState is a similar tuple where Module and Id are to have
449 the same values as in State, but the value of HandlerState
450 can be different. Returning a NewState, whose Module or Id
451 values differ from those of State, leaves the state of the
452 event handler unchanged. For a gen_event process, StateFun
453 is called once for each event handler registered in the
454 gen_event process.
455 If a StateFun function decides not to effect any change in
457 process state, then regardless of process type, it can return
458 its State argument.
459 If a StateFun function crashes or throws an exception, the orig‐
461 inal state of the process is unchanged for gen_server, and
462 gen_statem processes. For gen_event processes, a crashing or
463 failing StateFun function means that only the state of the par‐
464 ticular event handler it was working on when it failed or
465 crashed is unchanged; it can still succeed in changing the
466 states of other event handlers registered in the same gen_event
467 process.
468 If the callback module exports a system_replace_state/2 func‐
470 tion, it is called in the target process to replace its state
471 using StateFun. Its two arguments are StateFun and Misc, where
472 Misc is the same as the Misc value returned by get_status/1,2. A
473 system_replace_state/2 function is expected to return {ok, New‐
474 State, NewMisc}, where NewState is the new state of the callback
475 module, obtained by calling StateFun, and NewMisc is a possibly
476 new value used to replace the original Misc (required as Misc
477 often contains the state of the callback module within it).
478 If the callback module does not export a system_replace_state/2
480 function, replace_state/2,3 assumes that Misc is the state of
481 the callback module, passes it to StateFun and uses the return
482 value as both the new state and as the new value of Misc.
483 If the callback module's function system_replace_state/2 crashes
485 or throws an exception, the caller exits with error {call‐
486 back_failed, {Module, system_replace_state}, {Class, Reason}},
487 where Module is the name of the callback module and Class and
488 Reason indicate details of the exception. If the callback module
489 does not provide a system_replace_state/2 function and StateFun
490 crashes or throws an exception, the caller exits with error
491 {callback_failed, StateFun, {Class, Reason}}.
492 Function system_replace_state/2 is primarily useful for user-de‐
494 fined behaviors and modules that implement OTP special pro‐
495 cesses. The OTP behavior modules gen_server, gen_statem, and
496 gen_event export this function, so callback modules for those
497 behaviors need not to supply their own.
498 resume(Name) -> ok
500 resume(Name, Timeout) -> ok
502 Types:
504 Name = name()
506 Timeout = timeout()
507 Resumes a suspended process.
509 statistics(Name, Flag) -> ok | {ok, Statistics}
511 statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}
513 Types:
515 Name = name()
517 Flag = true | false | get
518 Statistics = [StatisticsTuple] | no_statistics
519 StatisticsTuple =
520 {start_time, DateTime1} |
521 {current_time, DateTime2} |
522 {reductions, integer() >= 0} |
523 {messages_in, integer() >= 0} |
524 {messages_out, integer() >= 0}
525 DateTime1 = DateTime2 = file:date_time()
526 Timeout = timeout()
527 Enables or disables the collection of statistics. If Flag is
529 get, the statistical collection is returned.
530 suspend(Name) -> ok
532 suspend(Name, Timeout) -> ok
534 Types:
536 Name = name()
538 Timeout = timeout()
539 Suspends the process. When the process is suspended, it only re‐
541 sponds to other system messages, but not other messages.
542 terminate(Name, Reason) -> ok
544 terminate(Name, Reason, Timeout) -> ok
546 Types:
548 Name = name()
550 Reason = term()
551 Timeout = timeout()
552 Orders the process to terminate with the specified Reason. The
554 termination is done asynchronously, so it is not guaranteed that
555 the process is terminated when the function returns.
556 trace(Name, Flag) -> ok
558 trace(Name, Flag, Timeout) -> ok
560 Types:
562 Name = name()
564 Flag = boolean()
565 Timeout = timeout()
566 Prints all system events on standard_io. The events are format‐
568 ted with a function that is defined by the process that gener‐
569 ated the event (with a call to handle_debug/4).
570
572 The following functions are used when implementing a special process.
573 This is an ordinary process, which does not use a standard behavior,
574 but a process that understands the standard system messages.
575
577 debug_options(Options :: [Opt :: debug_option()]) -> [dbg_opt()]
578 Can be used by a process that initiates a debug structure from a
580 list of options. The values of argument Opt are the same as for
581 the corresponding functions.
582 get_debug(Item, Debug, Default) -> term()
584 Types:
586 Item = log | statistics
588 Debug = [dbg_opt()]
589 Default = term()
590 Warning:
592 get_debug/3 is deprecated since it returns data of an internal
593 type only useful for debugging.
594 Gets the data associated with a debug option. Default is re‐
597 turned if Item is not found. Can be used by the process to re‐
598 trieve debug data for printing before it terminates.
599 handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]
601 Types:
603 Debug = [dbg_opt()]
605 FormFunc = format_fun()
606 Extra = term()
607 Event = system_event()
608 This function is called by a process when it generates a system
610 event. FormFunc is a formatting function, called as FormFunc(De‐
611 vice, Event, Extra) to print the events, which is necessary if
612 tracing is activated. Extra is any extra information that the
613 process needs in the format function, for example, the process
614 name.
615 handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
617 no_return()
618 Types:
620 Msg = term()
622 From = {pid(), Tag :: term()}
623 Parent = pid()
624 Module = module()
625 Debug = [dbg_opt()]
626 Misc = term()
627 This function is used by a process module to take care of system
629 messages. The process receives a {system, From, Msg} message and
630 passes Msg and From to this function.
631 This function never returns. It calls either of the following
633 functions:
634 * Module:system_continue(Parent, NDebug, Misc), where the
636 process continues the execution.
637 * Module:system_terminate(Reason, Parent, Debug, Misc), if the
639 process is to terminate.
640 Module must export the following:
642 * system_continue/3
644 * system_terminate/4
646 * system_code_change/4
648 * system_get_state/1
650 * system_replace_state/2
652 Argument Misc can be used to save internal data in a process,
654 for example, its state. It is sent to Module:system_continue/3
655 or Module:system_terminate/4.
656 print_log(Debug) -> ok
658 Types:
660 Debug = [dbg_opt()]
662 Prints the logged system events in the debug structure, using
664 FormFunc as defined when the event was generated by a call to
665 handle_debug/4.
666 get_log(Debug) -> [system_event()]
668 Types:
670 Debug = [dbg_opt()]
672 Returns the logged system events in the debug structure, that is
674 the last argument to handle_debug/4.
675 Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}
677 Types:
679 Misc = term()
681 OldVsn = undefined | term()
682 Module = atom()
683 Extra = term()
684 NMisc = term()
685 Called from handle_system_msg/6 when the process is to perform a
687 code change. The code change is used when the internal data
688 structure has changed. This function converts argument Misc to
689 the new data structure. OldVsn is attribute vsn of the old ver‐
690 sion of the Module. If no such attribute is defined, the atom
691 undefined is sent.
692 Module:system_continue(Parent, Debug, Misc) -> none()
694 Types:
696 Parent = pid()
698 Debug = [dbg_opt()]
699 Misc = term()
700 Called from handle_system_msg/6 when the process is to continue
702 its execution (for example, after it has been suspended). This
703 function never returns.
704 Module:system_get_state(Misc) -> {ok, State}
706 Types:
708 Misc = term()
710 State = term()
711 Called from handle_system_msg/6 when the process is to return a
713 term that reflects its current state. State is the value re‐
714 turned by get_state/2.
715 Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}
717 Types:
719 StateFun = fun((State :: term()) -> NState)
721 Misc = term()
722 NState = term()
723 NMisc = term()
724 Called from handle_system_msg/6 when the process is to replace
726 its current state. NState is the value returned by re‐
727 place_state/3.
728 Module:system_terminate(Reason, Parent, Debug, Misc) -> none()
730 Types:
732 Reason = term()
734 Parent = pid()
735 Debug = [dbg_opt()]
736 Misc = term()
737 Called from handle_system_msg/6 when the process is to termi‐
739 nate. For example, this function is called when the process is
740 suspended and its parent orders shutdown. It gives the process a
741 chance to do a cleanup. This function never returns.
742Ericsson AB stdlib 4.2 sys(3)