1proc_lib(3) Erlang Module Definition proc_lib(3)
2
6 proc_lib - Functions for asynchronous and synchronous start of pro‐
7 cesses
8 adhering to the OTP design principles.
9
11 This module is used to start processes adhering to the OTP Design
12 Principles. Specifically, the functions in this module are used by the
13 OTP standard behaviors (for example, gen_server and gen_statem) when
14 starting new processes. The functions can also be used to start special
15 processes, user-defined processes that comply to the OTP design princi‐
16 ples. For an example, see section sys and proc_lib in OTP Design Prin‐
17 ciples.
18 Some useful information is initialized when a process starts. The reg‐
20 istered names, or the process identifiers, of the parent process, and
21 the parent ancestors, are stored together with information about the
22 function initially called in the process.
23 While in "plain Erlang", a process is said to terminate normally only
25 for exit reason normal, a process started using proc_lib is also said
26 to terminate normally if it exits with reason shutdown or {shut‐
27 down,Term}. shutdown is the reason used when an application (supervi‐
28 sion tree) is stopped.
29 When a process that is started using proc_lib terminates abnormally
31 (that is, with another exit reason than normal, shutdown, or {shut‐
32 down,Term}), a crash report is generated, which is written to terminal
33 by the default logger handler setup by Kernel. For more information
34 about how crash reports were logged prior to Erlang/OTP 21.0, see SASL
35 Error Logging in the SASL User's Guide.
36 Unlike in "plain Erlang", proc_lib processes will not generate error
38 reports, which are written to the terminal by the emulator. All excep‐
39 tions are converted to exits which are ignored by the default logger
40 handler.
41 The crash report contains the previously stored information, such as
43 ancestors and initial function, the termination reason, and information
44 about other processes that terminate as a result of this process termi‐
45 nating.
46
48 spawn_option() = erlang:spawn_opt_option()
49 See erlang:spawn_opt/2,3,4,5.
51 start_spawn_option() =
53 link |
54 {priority, erlang:priority_level()} |
55 {fullsweep_after, integer() >= 0} |
56 {min_heap_size, integer() >= 0} |
57 {min_bin_vheap_size, integer() >= 0} |
58 {max_heap_size, erlang:max_heap_size()} |
59 {message_queue_data, erlang:message_queue_data()}
60 A restricted set of spawn options. Most notably monitor is not
62 part of these options.
63 dict_or_pid() =
65 pid() |
66 (ProcInfo :: [term()]) |
67 {X :: integer(), Y :: integer(), Z :: integer()}
68
70 format(CrashReport) -> string()
71 Types:
73 CrashReport = [term()]
75 Equivalent to format(CrashReport, latin1).
77 format(CrashReport, Encoding) -> string()
79 Types:
81 CrashReport = [term()]
83 Encoding = latin1 | unicode | utf8
84 Note:
86 This function is deprecated in the sense that the error_logger
87 is no longer the preferred interface for logging in Erlang/OTP.
88 A new logging API was added in Erlang/OTP 21.0, but legacy er‐
89 ror_logger handlers can still be used. New Logger handlers do
90 not need to use this function, since the formatting callback
91 (report_cb) is included as metadata in the log event.
92 This function can be used by a user-defined legacy error_logger
95 event handler to format a crash report. The crash report is sent
96 using logger(3), and the event to be handled is of the format
97 {error_report, GL, {Pid, crash_report, CrashReport}}, where GL
98 is the group leader pid of process Pid that sent the crash re‐
99 port.
100 format(CrashReport, Encoding, Depth) -> string()
102 Types:
104 CrashReport = [term()]
106 Encoding = latin1 | unicode | utf8
107 Depth = unlimited | integer() >= 1
108 Note:
110 This function is deprecated in the sense that the error_logger
111 is no longer the preferred interface for logging in Erlang/OTP.
112 A new logging API was added in Erlang/OTP 21.0, but legacy er‐
113 ror_logger handlers can still be used. New Logger handlers do
114 not need to used this function, since the formatting callback
115 (report_cb) is included as metadata in the log event.
116 This function can be used by a user-defined legacy error_logger
119 event handler to format a crash report. When Depth is specified
120 as a positive integer, it is used in the format string to limit
121 the output as follows: io_lib:format("~P", [Term,Depth]).
122 hibernate(Module, Function, Args) -> no_return()
124 Types:
126 Module = module()
128 Function = atom()
129 Args = [term()]
130 This function does the same as (and does call) the hibernate/3
132 BIF, but ensures that exception handling and logging continues
133 to work as expected when the process wakes up.
134 Always use this function instead of the BIF for processes
136 started using proc_lib functions.
137 init_ack(Ret) -> ok
139 init_ack(Parent, Ret) -> ok
141 Types:
143 Parent = pid()
145 Ret = term()
146 This function must only be used by a process that has been
148 started by a start[_link|_monitor]/3,4,5 function. It tells Par‐
149 ent that the process has initialized itself and started.
150 Function init_ack/1 uses the parent value previously stored by
152 the start function used.
153 If neither this function nor init_fail/2,3 is called by the
155 started process, the start function returns an error tuple when
156 the started process exits, or when the start function time-out
157 (if used) has passed, see start/3,4,5.
158 Warning:
160 Do not use this function to return an error indicating that the
161 process start failed. When doing so the start function can re‐
162 turn before the failing process has exited, which may block VM
163 resources required for a new start attempt to succeed. Use
164 init_fail/2,3 for that purpose.
165 The following example illustrates how this function and
168 proc_lib:start_link/3 are used:
169 -module(my_proc).
171 -export([start_link/0]).
172 -export([init/1]).
173 start_link() ->
175 proc_lib:start_link(my_proc, init, [self()]).
176 init(Parent) ->
178 case do_initialization() of
179 ok ->
180 proc_lib:init_ack(Parent, {ok, self()});
181 {error, Reason} ->
182 exit(Reason)
183 end,
184 loop().
185 init_fail(Ret, Exception) -> no_return()
188 init_fail(Parent, Ret, Exception) -> no_return()
189 Types:
191 Parent = pid()
193 Ret = term()
194 Exception = {Class, Reason} | {Class, Reason, Stacktrace}
195 This function must only be used by a process that has been
197 started by a start[_link|_monitor]/3,4,5 function. It tells Par‐
198 ent that the process has failed to initialize, and immediately
199 raises an exception according to Exception. The start function
200 then returns Ret.
201 See erlang:raise/3 for a description of Class, Reason and Stack‐
203 trace.
204 Function init_fail/2 uses the parent value previously stored by
206 the start function used.
207 Warning:
209 Do not consider catching the exception from this function. That
210 would defeat its purpose. A process started by a
211 start[_link|_monitor]/3,4,5 function should end in a value (that
212 will be ignored) or an exception that will be handled by this
213 module. See Description.
214 If neither this function nor init_ack/1,2 is called by the
217 started process, the start function returns an error tuple when
218 the started process exits, or when the start function time-out
219 (if used) has passed, see start/3,4,5.
220 The following example illustrates how this function and
222 proc_lib:start_link/3 can be used:
223 -module(my_proc).
225 -export([start_link/0]).
226 -export([init/1]).
227 start_link() ->
229 proc_lib:start_link(my_proc, init, [self()]).
230 init(Parent) ->
232 case do_initialization() of
233 ok ->
234 proc_lib:init_ack(Parent, {ok, self()});
235 {error, Reason} = Error ->
236 proc_lib:init_fail(Parent, Error, {exit, normal})
237 end,
238 loop().
239 initial_call(Process) -> {Module, Function, Args} | false
242 Types:
244 Process = dict_or_pid()
246 Module = module()
247 Function = atom()
248 Args = [atom()]
249 Extracts the initial call of a process that was started using
251 one of the spawn or start functions in this module. Process can
252 either be a pid, an integer tuple (from which a pid can be cre‐
253 ated), or the process information of a process Pid fetched
254 through an erlang:process_info(Pid) function call.
255 Note:
257 The list Args no longer contains the arguments, but the same
258 number of atoms as the number of arguments; the first atom is
259 'Argument__1', the second 'Argument__2', and so on. The reason
260 is that the argument list could waste a significant amount of
261 memory, and if the argument list contained funs, it could be im‐
262 possible to upgrade the code for the module.
263 If the process was spawned using a fun, initial_call/1 no longer
265 returns the fun, but the module, function for the local function
266 implementing the fun, and the arity, for example, {some_mod‐
267 ule,-work/3-fun-0-,0} (meaning that the fun was created in func‐
268 tion some_module:work/3). The reason is that keeping the fun
269 would prevent code upgrade for the module, and that a signifi‐
270 cant amount of memory could be wasted.
271 spawn(Fun) -> pid()
274 spawn(Node, Fun) -> pid()
276 spawn(Module, Function, Args) -> pid()
278 spawn(Node, Module, Function, Args) -> pid()
280 Types:
282 Node = node()
284 Fun = function()
285 Module = module()
286 Function = atom()
287 Args = [term()]
288 Spawns a new process and initializes it as described in the be‐
290 ginning of this manual page. The process is spawned using the
291 spawn BIFs.
292 spawn_link(Fun) -> pid()
294 spawn_link(Node, Fun) -> pid()
296 spawn_link(Module, Function, Args) -> pid()
298 spawn_link(Node, Module, Function, Args) -> pid()
300 Types:
302 Node = node()
304 Fun = function()
305 Module = module()
306 Function = atom()
307 Args = [term()]
308 Spawns a new process and initializes it as described in the be‐
310 ginning of this manual page. The process is spawned using the
311 spawn_link BIFs.
312 spawn_opt(Fun, SpawnOpts) -> pid() | {pid(), reference()}
314 spawn_opt(Node, Function, SpawnOpts) ->
316 pid() | {pid(), reference()}
317 spawn_opt(Module, Function, Args, SpawnOpts) ->
319 pid() | {pid(), reference()}
320 spawn_opt(Node, Module, Function, Args, SpawnOpts) ->
322 pid() | {pid(), reference()}
323 Types:
325 Node = node()
327 Fun = function()
328 Module = module()
329 Function = atom()
330 Args = [term()]
331 SpawnOpts = [spawn_option()]
332 Spawns a new process and initializes it as described in the be‐
334 ginning of this manual page. The process is spawned using the
335 erlang:spawn_opt BIFs.
336 start(Module, Function, Args) -> Ret
338 start(Module, Function, Args, Time) -> Ret
340 start(Module, Function, Args, Time, SpawnOpts) -> Ret
342 Types:
344 Module = module()
346 Function = atom()
347 Args = [term()]
348 Time = timeout()
349 SpawnOpts = [start_spawn_option()]
350 Ret = term() | {error, Reason :: term()}
351 Starts a new process synchronously. Spawns the process and waits
353 for it to start.
354 To indicate a succesful start, the started process must call
356 init_ack(Parent, Ret) where Parent is the process that evaluates
357 this function, or init_ack(Ret). Ret is then returned by this
358 function.
359 If the process fails to start, it must fail; preferably by call‐
361 ing init_fail(Parent, Ret, Exception) where Parent is the
362 process that evaluates this function, or init_fail(Ret, Excep‐
363 tion). Ret is then returned by this function, and the started
364 process fails with Exception.
365 If the process instead fails before calling init_ack/1,2 or
367 init_fail/2,3, this function returns {error, Reason} where Rea‐
368 son depends a bit on the exception just like for a process link
369 {'EXIT',Pid,Reason} message.
370 If Time is specified as an integer, this function waits for Time
372 milliseconds for the new process to call init_ack/1,2 or
373 init_fail/2,3, otherwise the process gets killed and Ret = {er‐
374 ror, timeout} is returned.
375 Argument SpawnOpts, if specified, is passed as the last argument
377 to the spawn_opt/2,3,4,5 BIF.
378 Note:
380 Using spawn option monitor is not allowed. It causes the func‐
381 tion to fail with reason badarg.
382 Using spawn option link will set a link to the spawned process,
384 just like start_link/3,4,5.
385 start_link(Module, Function, Args) -> Ret
388 start_link(Module, Function, Args, Time) -> Ret
390 start_link(Module, Function, Args, Time, SpawnOpts) -> Ret
392 Types:
394 Module = module()
396 Function = atom()
397 Args = [term()]
398 Time = timeout()
399 SpawnOpts = [start_spawn_option()]
400 Ret = term() | {error, Reason :: term()}
401 Starts a new process synchronously. Spawns the process and waits
403 for it to start. A link is atomically set on the newly spawned
404 process.
405 Note:
407 If the started process gets killed or crashes with a reason that
408 is not `normal`, the process link will kill the calling process
409 so this function does not return, unless the calling process
410 traps exits. For example, if this function times out it will
411 kill the spawned process, and then the link might kill the call‐
412 ing process.
413 Besides setting a link on the spawned process this function be‐
416 haves like start/3,4,5.
417 When the calling process traps exits; if this function returns
419 due to the spawned process exiting (any error return), this
420 function receives (consumes) the 'EXIT' message, also when this
421 function times out and kills the spawned process.
422 Note:
424 Using spawn option monitor is not allowed. It causes the func‐
425 tion to fail with reason badarg.
426 start_monitor(Module, Function, Args) -> {Ret, Mon}
429 start_monitor(Module, Function, Args, Time) -> {Ret, Mon}
431 start_monitor(Module, Function, Args, Time, SpawnOpts) ->
433 {Ret, Mon}
434 Types:
436 Module = module()
438 Function = atom()
439 Args = [term()]
440 Time = timeout()
441 SpawnOpts = [start_spawn_option()]
442 Mon = reference()
443 Ret = term() | {error, Reason :: term()}
444 Starts a new process synchronously. Spawns the process and waits
446 for it to start. A monitor is atomically set on the newly
447 spawned process.
448 Besides setting a monitor on the spawned process this function
450 behaves like start/3,4,5.
451 The return value is {Ret, Mon} where Ret corresponds to the Ret
453 argument in the call to init_ack/1,2 or init_fail/2,3, and Mon
454 is the monitor reference of the monitor that has been set up.
455 If this function returns due to the spawned process exiting,
457 that is returns any error value, a 'DOWN' message will be deliv‐
458 ered to the calling process, also when this function times out
459 and kills the spawned process.
460 Note:
462 Using spawn option monitor is not allowed. It causes the func‐
463 tion to fail with reason badarg.
464 Using spawn option link will set a link to the spawned process,
466 just like start_link/3,4,5.
467 stop(Process) -> ok
470 Types:
472 Process = pid() | RegName | {RegName, node()}
474 Equivalent to stop(Process, normal, infinity).
476 stop(Process, Reason, Timeout) -> ok
478 Types:
480 Process = pid() | RegName | {RegName, node()}
482 Reason = term()
483 Timeout = timeout()
484 Orders the process to exit with the specified Reason and waits
486 for it to terminate.
487 Returns ok if the process exits with the specified Reason within
489 Timeout milliseconds.
490 If the call times out, a timeout exception is raised.
492 If the process does not exist, a noproc exception is raised.
494 The implementation of this function is based on the terminate
496 system message, and requires that the process handles system
497 messages correctly. For information about system messages, see
498 sys(3) and section sys and proc_lib in OTP Design Principles.
499 translate_initial_call(Process) -> {Module, Function, Arity}
501 Types:
503 Process = dict_or_pid()
505 Module = module()
506 Function = atom()
507 Arity = byte()
508 This function is used by functions c:i/0 and c:regs/0 to present
510 process information.
511 This function extracts the initial call of a process that was
513 started using one of the spawn or start functions in this mod‐
514 ule, and translates it to more useful information. Process can
515 either be a pid, an integer tuple (from which a pid can be cre‐
516 ated), or the process information of a process Pid fetched
517 through an erlang:process_info(Pid) function call.
518 If the initial call is to one of the system-defined behaviors
520 such as gen_server or gen_event, it is translated to more useful
521 information. If a gen_server is spawned, the returned Module is
522 the name of the callback module and Function is init (the func‐
523 tion that initiates the new server).
524 A supervisor and a supervisor_bridge are also gen_server pro‐
526 cesses. To return information that this process is a supervisor
527 and the name of the callback module, Module is supervisor and
528 Function is the name of the supervisor callback module. Arity is
529 1, as the init/1 function is called initially in the callback
530 module.
531 By default, {proc_lib,init_p,5} is returned if no information
533 about the initial call can be found. It is assumed that the
534 caller knows that the process has been spawned with the proc_lib
535 module.
536
538 error_logger(3)
539 logger(3)
541Ericsson AB stdlib 5.1.1 proc_lib(3)