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() =
49 link | monitor |
50 {priority, priority_level()} |
51 {max_heap_size, max_heap_size()} |
52 {min_heap_size, integer() >= 0} |
53 {min_bin_vheap_size, integer() >= 0} |
54 {fullsweep_after, integer() >= 0} |
55 {message_queue_data, off_heap | on_heap | mixed}
56 See erlang:spawn_opt/2,3,4,5.
58 priority_level() = high | low | max | normal
60 max_heap_size() =
62 integer() >= 0 |
63 #{size => integer() >= 0,
64 kill => true,
65 error_logger => true}
66 See erlang:process_flag(max_heap_size, MaxHeapSize).
68 dict_or_pid() =
70 pid() |
71 (ProcInfo :: [term()]) |
72 {X :: integer(), Y :: integer(), Z :: integer()}
73
75 format(CrashReport) -> string()
76 Types:
78 CrashReport = [term()]
80 Equivalent to format(CrashReport, latin1).
82 format(CrashReport, Encoding) -> string()
84 Types:
86 CrashReport = [term()]
88 Encoding = latin1 | unicode | utf8
89 Note:
91 This function is deprecated in the sense that the error_logger
92 is no longer the preferred interface for logging in Erlang/OTP.
93 A new logging API was added in Erlang/OTP 21.0, but legacy
94 error_logger handlers can still be used. New Logger handlers do
95 not need to use this function, since the formatting callback
96 (report_cb) is included as metadata in the log event.
97 This function can be used by a user-defined legacy error_logger
100 event handler to format a crash report. The crash report is sent
101 using logger(3), and the event to be handled is of the format
102 {error_report, GL, {Pid, crash_report, CrashReport}}, where GL
103 is the group leader pid of process Pid that sent the crash
104 report.
105 format(CrashReport, Encoding, Depth) -> string()
107 Types:
109 CrashReport = [term()]
111 Encoding = latin1 | unicode | utf8
112 Depth = unlimited | integer() >= 1
113 Note:
115 This function is deprecated in the sense that the error_logger
116 is no longer the preferred interface for logging in Erlang/OTP.
117 A new logging API was added in Erlang/OTP 21.0, but legacy
118 error_logger handlers can still be used. New Logger handlers do
119 not need to used this function, since the formatting callback
120 (report_cb) is included as metadata in the log event.
121 This function can be used by a user-defined legacy error_logger
124 event handler to format a crash report. When Depth is specified
125 as a positive integer, it is used in the format string to limit
126 the output as follows: io_lib:format("~P", [Term,Depth]).
127 hibernate(Module, Function, Args) -> no_return()
129 Types:
131 Module = module()
133 Function = atom()
134 Args = [term()]
135 This function does the same as (and does call) the hibernate/3
137 BIF, but ensures that exception handling and logging continues
138 to work as expected when the process wakes up.
139 Always use this function instead of the BIF for processes
141 started using proc_lib functions.
142 init_ack(Ret) -> ok
144 init_ack(Parent, Ret) -> ok
146 Types:
148 Parent = pid()
150 Ret = term()
151 This function must be used by a process that has been started by
153 a start[_link]/3,4,5 function. It tells Parent that the process
154 has initialized itself, has started, or has failed to initialize
155 itself.
156 Function init_ack/1 uses the parent value previously stored by
158 the start function used.
159 If this function is not called, the start function returns an
161 error tuple (if a link and/or a time-out is used) or hang other‐
162 wise.
163 The following example illustrates how this function and
165 proc_lib:start_link/3 are used:
166 -module(my_proc).
168 -export([start_link/0]).
169 -export([init/1]).
170 start_link() ->
172 proc_lib:start_link(my_proc, init, [self()]).
173 init(Parent) ->
175 case do_initialization() of
176 ok ->
177 proc_lib:init_ack(Parent, {ok, self()});
178 {error, Reason} ->
179 exit(Reason)
180 end,
181 loop().
182 initial_call(Process) -> {Module, Function, Args} | false
185 Types:
187 Process = dict_or_pid()
189 Module = module()
190 Function = atom()
191 Args = [atom()]
192 Extracts the initial call of a process that was started using
194 one of the spawn or start functions in this module. Process can
195 either be a pid, an integer tuple (from which a pid can be cre‐
196 ated), or the process information of a process Pid fetched
197 through an erlang:process_info(Pid) function call.
198 Note:
200 The list Args no longer contains the arguments, but the same
201 number of atoms as the number of arguments; the first atom is
202 'Argument__1', the second 'Argument__2', and so on. The reason
203 is that the argument list could waste a significant amount of
204 memory, and if the argument list contained funs, it could be
205 impossible to upgrade the code for the module.
206 If the process was spawned using a fun, initial_call/1 no longer
208 returns the fun, but the module, function for the local function
209 implementing the fun, and the arity, for example, {some_mod‐
210 ule,-work/3-fun-0-,0} (meaning that the fun was created in func‐
211 tion some_module:work/3). The reason is that keeping the fun
212 would prevent code upgrade for the module, and that a signifi‐
213 cant amount of memory could be wasted.
214 spawn(Fun) -> pid()
217 spawn(Node, Fun) -> pid()
219 spawn(Module, Function, Args) -> pid()
221 spawn(Node, Module, Function, Args) -> pid()
223 Types:
225 Node = node()
227 Fun = function()
228 Module = module()
229 Function = atom()
230 Args = [term()]
231 Spawns a new process and initializes it as described in the
233 beginning of this manual page. The process is spawned using the
234 spawn BIFs.
235 spawn_link(Fun) -> pid()
237 spawn_link(Node, Fun) -> pid()
239 spawn_link(Module, Function, Args) -> pid()
241 spawn_link(Node, Module, Function, Args) -> pid()
243 Types:
245 Node = node()
247 Fun = function()
248 Module = module()
249 Function = atom()
250 Args = [term()]
251 Spawns a new process and initializes it as described in the
253 beginning of this manual page. The process is spawned using the
254 spawn_link BIFs.
255 spawn_opt(Fun, SpawnOpts) -> pid()
257 spawn_opt(Node, Function, SpawnOpts) -> pid()
259 spawn_opt(Module, Function, Args, SpawnOpts) -> pid()
261 spawn_opt(Node, Module, Function, Args, SpawnOpts) -> pid()
263 Types:
265 Node = node()
267 Fun = function()
268 Module = module()
269 Function = atom()
270 Args = [term()]
271 SpawnOpts = [spawn_option()]
272 Spawns a new process and initializes it as described in the
274 beginning of this manual page. The process is spawned using the
275 spawn_opt BIFs.
276 Note:
278 Using spawn option monitor is not allowed. It causes the func‐
279 tion to fail with reason badarg.
280 start(Module, Function, Args) -> Ret
283 start(Module, Function, Args, Time) -> Ret
285 start(Module, Function, Args, Time, SpawnOpts) -> Ret
287 start_link(Module, Function, Args) -> Ret
289 start_link(Module, Function, Args, Time) -> Ret
291 start_link(Module, Function, Args, Time, SpawnOpts) -> Ret
293 Types:
295 Module = module()
297 Function = atom()
298 Args = [term()]
299 Time = timeout()
300 SpawnOpts = [spawn_option()]
301 Ret = term() | {error, Reason :: term()}
302 Starts a new process synchronously. Spawns the process and waits
304 for it to start. When the process has started, it must call
305 init_ack(Parent, Ret) or init_ack(Ret), where Parent is the
306 process that evaluates this function. At this time, Ret is
307 returned.
308 If function start_link/3,4,5 is used and the process crashes
310 before it has called init_ack/1,2, {error, Reason} is returned
311 if the calling process traps exits.
312 If Time is specified as an integer, this function waits for Time
314 milliseconds for the new process to call init_ack, or {error,
315 timeout} is returned, and the process is killed.
316 Argument SpawnOpts, if specified, is passed as the last argument
318 to the spawn_opt/2,3,4,5 BIF.
319 Note:
321 Using spawn option monitor is not allowed. It causes the func‐
322 tion to fail with reason badarg.
323 stop(Process) -> ok
326 Types:
328 Process = pid() | RegName | {RegName, node()}
330 Equivalent to stop(Process, normal, infinity).
332 stop(Process, Reason, Timeout) -> ok
334 Types:
336 Process = pid() | RegName | {RegName, node()}
338 Reason = term()
339 Timeout = timeout()
340 Orders the process to exit with the specified Reason and waits
342 for it to terminate.
343 Returns ok if the process exits with the specified Reason within
345 Timeout milliseconds.
346 If the call times out, a timeout exception is raised.
348 If the process does not exist, a noproc exception is raised.
350 The implementation of this function is based on the terminate
352 system message, and requires that the process handles system
353 messages correctly. For information about system messages, see
354 sys(3) and section sys and proc_lib in OTP Design Principles.
355 translate_initial_call(Process) -> {Module, Function, Arity}
357 Types:
359 Process = dict_or_pid()
361 Module = module()
362 Function = atom()
363 Arity = byte()
364 This function is used by functions c:i/0 and c:regs/0 to present
366 process information.
367 This function extracts the initial call of a process that was
369 started using one of the spawn or start functions in this mod‐
370 ule, and translates it to more useful information. Process can
371 either be a pid, an integer tuple (from which a pid can be cre‐
372 ated), or the process information of a process Pid fetched
373 through an erlang:process_info(Pid) function call.
374 If the initial call is to one of the system-defined behaviors
376 such as gen_server or gen_event, it is translated to more useful
377 information. If a gen_server is spawned, the returned Module is
378 the name of the callback module and Function is init (the func‐
379 tion that initiates the new server).
380 A supervisor and a supervisor_bridge are also gen_server pro‐
382 cesses. To return information that this process is a supervisor
383 and the name of the callback module, Module is supervisor and
384 Function is the name of the supervisor callback module. Arity is
385 1, as the init/1 function is called initially in the callback
386 module.
387 By default, {proc_lib,init_p,5} is returned if no information
389 about the initial call can be found. It is assumed that the
390 caller knows that the process has been spawned with the proc_lib
391 module.
392
394 error_logger(3)
395 logger(3)
397Ericsson AB stdlib 3.12.1 proc_lib(3)