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 {max_heap_size, erlang:max_heap_size()} |
56 {min_heap_size, integer() >= 0} |
57 {min_bin_vheap_size, integer() >= 0} |
58 {fullsweep_after, integer() >= 0} |
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 be used by a process that has been started by
148 a start[_link]/3,4,5 function. It tells Parent that the process
149 has initialized itself, has started, or has failed to initialize
150 itself.
151 Function init_ack/1 uses the parent value previously stored by
153 the start function used.
154 If this function is not called, the start function returns an
156 error tuple (if a link and/or a time-out is used) or hang other‐
157 wise.
158 The following example illustrates how this function and
160 proc_lib:start_link/3 are used:
161 -module(my_proc).
163 -export([start_link/0]).
164 -export([init/1]).
165 start_link() ->
167 proc_lib:start_link(my_proc, init, [self()]).
168 init(Parent) ->
170 case do_initialization() of
171 ok ->
172 proc_lib:init_ack(Parent, {ok, self()});
173 {error, Reason} ->
174 exit(Reason)
175 end,
176 loop().
177 initial_call(Process) -> {Module, Function, Args} | false
180 Types:
182 Process = dict_or_pid()
184 Module = module()
185 Function = atom()
186 Args = [atom()]
187 Extracts the initial call of a process that was started using
189 one of the spawn or start functions in this module. Process can
190 either be a pid, an integer tuple (from which a pid can be cre‐
191 ated), or the process information of a process Pid fetched
192 through an erlang:process_info(Pid) function call.
193 Note:
195 The list Args no longer contains the arguments, but the same
196 number of atoms as the number of arguments; the first atom is
197 'Argument__1', the second 'Argument__2', and so on. The reason
198 is that the argument list could waste a significant amount of
199 memory, and if the argument list contained funs, it could be im‐
200 possible to upgrade the code for the module.
201 If the process was spawned using a fun, initial_call/1 no longer
203 returns the fun, but the module, function for the local function
204 implementing the fun, and the arity, for example, {some_mod‐
205 ule,-work/3-fun-0-,0} (meaning that the fun was created in func‐
206 tion some_module:work/3). The reason is that keeping the fun
207 would prevent code upgrade for the module, and that a signifi‐
208 cant amount of memory could be wasted.
209 spawn(Fun) -> pid()
212 spawn(Node, Fun) -> pid()
214 spawn(Module, Function, Args) -> pid()
216 spawn(Node, Module, Function, Args) -> pid()
218 Types:
220 Node = node()
222 Fun = function()
223 Module = module()
224 Function = atom()
225 Args = [term()]
226 Spawns a new process and initializes it as described in the be‐
228 ginning of this manual page. The process is spawned using the
229 spawn BIFs.
230 spawn_link(Fun) -> pid()
232 spawn_link(Node, Fun) -> pid()
234 spawn_link(Module, Function, Args) -> pid()
236 spawn_link(Node, Module, Function, Args) -> pid()
238 Types:
240 Node = node()
242 Fun = function()
243 Module = module()
244 Function = atom()
245 Args = [term()]
246 Spawns a new process and initializes it as described in the be‐
248 ginning of this manual page. The process is spawned using the
249 spawn_link BIFs.
250 spawn_opt(Fun, SpawnOpts) -> pid() | {pid(), reference()}
252 spawn_opt(Node, Function, SpawnOpts) ->
254 pid() | {pid(), reference()}
255 spawn_opt(Module, Function, Args, SpawnOpts) ->
257 pid() | {pid(), reference()}
258 spawn_opt(Node, Module, Function, Args, SpawnOpts) ->
260 pid() | {pid(), reference()}
261 Types:
263 Node = node()
265 Fun = function()
266 Module = module()
267 Function = atom()
268 Args = [term()]
269 SpawnOpts = [spawn_option()]
270 Spawns a new process and initializes it as described in the be‐
272 ginning of this manual page. The process is spawned using the
273 erlang:spawn_opt BIFs.
274 start(Module, Function, Args) -> Ret
276 start(Module, Function, Args, Time) -> Ret
278 start(Module, Function, Args, Time, SpawnOpts) -> Ret
280 Types:
282 Module = module()
284 Function = atom()
285 Args = [term()]
286 Time = timeout()
287 SpawnOpts = [start_spawn_option()]
288 Ret = term() | {error, Reason :: term()}
289 Starts a new process synchronously. Spawns the process and waits
291 for it to start. When the process has started, it must call
292 init_ack(Parent, Ret) or init_ack(Ret), where Parent is the
293 process that evaluates this function. At this time, Ret is re‐
294 turned.
295 If Time is specified as an integer, this function waits for Time
297 milliseconds for the new process to call init_ack, or Ret = {er‐
298 ror, timeout} will be returned, and the process is killed.
299 Argument SpawnOpts, if specified, is passed as the last argument
301 to the spawn_opt/2,3,4,5 BIF.
302 Note:
304 Using spawn option monitor is not allowed. It causes the func‐
305 tion to fail with reason badarg.
306 start_link(Module, Function, Args) -> Ret
309 start_link(Module, Function, Args, Time) -> Ret
311 start_link(Module, Function, Args, Time, SpawnOpts) -> Ret
313 Types:
315 Module = module()
317 Function = atom()
318 Args = [term()]
319 Time = timeout()
320 SpawnOpts = [start_spawn_option()]
321 Ret = term() | {error, Reason :: term()}
322 Starts a new process synchronously. Spawns the process and waits
324 for it to start. A link is atomically set on the newly spawned
325 process. When the process has started, it must call
326 init_ack(Parent, Ret) or init_ack(Ret), where Parent is the
327 process that evaluates this function. At this time, Ret is re‐
328 turned.
329 If Time is specified as an integer, this function waits for Time
331 milliseconds for the new process to call init_ack, or Ret = {er‐
332 ror, timeout} will be returned, and the process is killed.
333 If the process crashes before it has called init_ack/1,2, Ret =
335 {error, Reason} will be returned if the calling process traps
336 exits.
337 Argument SpawnOpts, if specified, is passed as the last argument
339 to the spawn_opt/2,3,4,5 BIF.
340 Note:
342 Using spawn option monitor is not allowed. It causes the func‐
343 tion to fail with reason badarg.
344 start_monitor(Module, Function, Args) -> {Ret, Mon}
347 start_monitor(Module, Function, Args, Time) -> {Ret, Mon}
349 start_monitor(Module, Function, Args, Time, SpawnOpts) ->
351 {Ret, Mon}
352 Types:
354 Module = module()
356 Function = atom()
357 Args = [term()]
358 Time = timeout()
359 SpawnOpts = [start_spawn_option()]
360 Mon = reference()
361 Ret = term() | {error, Reason :: term()}
362 Starts a new process synchronously. Spawns the process and waits
364 for it to start. A monitor is atomically set on the newly
365 spawned process. When the process has started, it must call
366 init_ack(Parent, Ret) or init_ack(Ret), where Parent is the
367 process that evaluates this function. At this time, Ret is re‐
368 turned.
369 If Time is specified as an integer, this function waits for Time
371 milliseconds for the new process to call init_ack, or Ret = {er‐
372 ror, timeout} will be returned, and the process is killed.
373 The return value is {Ret, Mon} where Ret corresponds to the Ret
375 argument in the call to init_ack(), and Mon is the monitor ref‐
376 erence of the monitor that has been set up.
377 A 'DOWN' message will be delivered to the caller if this func‐
379 tion returns, and the spawned process terminates. This is true
380 also in the case when the operation times out.
381 Argument SpawnOpts, if specified, is passed as the last argument
383 to the spawn_opt/2,3,4,5 BIF.
384 Note:
386 Using spawn option monitor is not allowed. It causes the func‐
387 tion to fail with reason badarg.
388 stop(Process) -> ok
391 Types:
393 Process = pid() | RegName | {RegName, node()}
395 Equivalent to stop(Process, normal, infinity).
397 stop(Process, Reason, Timeout) -> ok
399 Types:
401 Process = pid() | RegName | {RegName, node()}
403 Reason = term()
404 Timeout = timeout()
405 Orders the process to exit with the specified Reason and waits
407 for it to terminate.
408 Returns ok if the process exits with the specified Reason within
410 Timeout milliseconds.
411 If the call times out, a timeout exception is raised.
413 If the process does not exist, a noproc exception is raised.
415 The implementation of this function is based on the terminate
417 system message, and requires that the process handles system
418 messages correctly. For information about system messages, see
419 sys(3) and section sys and proc_lib in OTP Design Principles.
420 translate_initial_call(Process) -> {Module, Function, Arity}
422 Types:
424 Process = dict_or_pid()
426 Module = module()
427 Function = atom()
428 Arity = byte()
429 This function is used by functions c:i/0 and c:regs/0 to present
431 process information.
432 This function extracts the initial call of a process that was
434 started using one of the spawn or start functions in this mod‐
435 ule, and translates it to more useful information. Process can
436 either be a pid, an integer tuple (from which a pid can be cre‐
437 ated), or the process information of a process Pid fetched
438 through an erlang:process_info(Pid) function call.
439 If the initial call is to one of the system-defined behaviors
441 such as gen_server or gen_event, it is translated to more useful
442 information. If a gen_server is spawned, the returned Module is
443 the name of the callback module and Function is init (the func‐
444 tion that initiates the new server).
445 A supervisor and a supervisor_bridge are also gen_server pro‐
447 cesses. To return information that this process is a supervisor
448 and the name of the callback module, Module is supervisor and
449 Function is the name of the supervisor callback module. Arity is
450 1, as the init/1 function is called initially in the callback
451 module.
452 By default, {proc_lib,init_p,5} is returned if no information
454 about the initial call can be found. It is assumed that the
455 caller knows that the process has been spawned with the proc_lib
456 module.
457
459 error_logger(3)
460 logger(3)
462Ericsson AB stdlib 3.16.1 proc_lib(3)