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 |
50 monitor |
51 {priority, priority_level()} |
52 {max_heap_size, max_heap_size()} |
53 {min_heap_size, integer() >= 0} |
54 {min_bin_vheap_size, integer() >= 0} |
55 {fullsweep_after, integer() >= 0} |
56 {message_queue_data, off_heap | on_heap | mixed}
57 See erlang:spawn_opt/2,3,4,5.
59 priority_level() = high | low | max | normal
61 max_heap_size() =
63 integer() >= 0 |
64 #{size => integer() >= 0,
65 kill => true,
66 error_logger => true}
67 See erlang:process_flag(max_heap_size, MaxHeapSize).
69 dict_or_pid() =
71 pid() |
72 (ProcInfo :: [term()]) |
73 {X :: integer(), Y :: integer(), Z :: integer()}
74
76 format(CrashReport) -> string()
77 Types:
79 CrashReport = [term()]
81 Equivalent to format(CrashReport, latin1).
83 format(CrashReport, Encoding) -> string()
85 Types:
87 CrashReport = [term()]
89 Encoding = latin1 | unicode | utf8
90 Note:
92 This function is deprecated in the sense that the error_logger
93 is no longer the preferred interface for logging in Erlang/OTP.
94 A new logging API was added in Erlang/OTP 21.0, but legacy
95 error_logger handlers can still be used. New Logger handlers do
96 not need to use this function, since the formatting callback
97 (report_cb) is included as metadata in the log event.
98 This function can be used by a user-defined legacy error_logger
101 event handler to format a crash report. The crash report is sent
102 using logger(3), and the event to be handled is of the format
103 {error_report, GL, {Pid, crash_report, CrashReport}}, where GL
104 is the group leader pid of process Pid that sent the crash
105 report.
106 format(CrashReport, Encoding, Depth) -> string()
108 Types:
110 CrashReport = [term()]
112 Encoding = latin1 | unicode | utf8
113 Depth = unlimited | integer() >= 1
114 Note:
116 This function is deprecated in the sense that the error_logger
117 is no longer the preferred interface for logging in Erlang/OTP.
118 A new logging API was added in Erlang/OTP 21.0, but legacy
119 error_logger handlers can still be used. New Logger handlers do
120 not need to used this function, since the formatting callback
121 (report_cb) is included as metadata in the log event.
122 This function can be used by a user-defined legacy error_logger
125 event handler to format a crash report. When Depth is specified
126 as a positive integer, it is used in the format string to limit
127 the output as follows: io_lib:format("~P", [Term,Depth]).
128 hibernate(Module, Function, Args) -> no_return()
130 Types:
132 Module = module()
134 Function = atom()
135 Args = [term()]
136 This function does the same as (and does call) the hibernate/3
138 BIF, but ensures that exception handling and logging continues
139 to work as expected when the process wakes up.
140 Always use this function instead of the BIF for processes
142 started using proc_lib functions.
143 init_ack(Ret) -> ok
145 init_ack(Parent, Ret) -> ok
147 Types:
149 Parent = pid()
151 Ret = term()
152 This function must be used by a process that has been started by
154 a start[_link]/3,4,5 function. It tells Parent that the process
155 has initialized itself, has started, or has failed to initialize
156 itself.
157 Function init_ack/1 uses the parent value previously stored by
159 the start function used.
160 If this function is not called, the start function returns an
162 error tuple (if a link and/or a time-out is used) or hang other‐
163 wise.
164 The following example illustrates how this function and
166 proc_lib:start_link/3 are used:
167 -module(my_proc).
169 -export([start_link/0]).
170 -export([init/1]).
171 start_link() ->
173 proc_lib:start_link(my_proc, init, [self()]).
174 init(Parent) ->
176 case do_initialization() of
177 ok ->
178 proc_lib:init_ack(Parent, {ok, self()});
179 {error, Reason} ->
180 exit(Reason)
181 end,
182 loop().
183 initial_call(Process) -> {Module, Function, Args} | false
186 Types:
188 Process = dict_or_pid()
190 Module = module()
191 Function = atom()
192 Args = [atom()]
193 Extracts the initial call of a process that was started using
195 one of the spawn or start functions in this module. Process can
196 either be a pid, an integer tuple (from which a pid can be cre‐
197 ated), or the process information of a process Pid fetched
198 through an erlang:process_info(Pid) function call.
199 Note:
201 The list Args no longer contains the arguments, but the same
202 number of atoms as the number of arguments; the first atom is
203 'Argument__1', the second 'Argument__2', and so on. The reason
204 is that the argument list could waste a significant amount of
205 memory, and if the argument list contained funs, it could be
206 impossible to upgrade the code for the module.
207 If the process was spawned using a fun, initial_call/1 no longer
209 returns the fun, but the module, function for the local function
210 implementing the fun, and the arity, for example, {some_mod‐
211 ule,-work/3-fun-0-,0} (meaning that the fun was created in func‐
212 tion some_module:work/3). The reason is that keeping the fun
213 would prevent code upgrade for the module, and that a signifi‐
214 cant amount of memory could be wasted.
215 spawn(Fun) -> pid()
218 spawn(Node, Fun) -> pid()
220 spawn(Module, Function, Args) -> pid()
222 spawn(Node, Module, Function, Args) -> pid()
224 Types:
226 Node = node()
228 Fun = function()
229 Module = module()
230 Function = atom()
231 Args = [term()]
232 Spawns a new process and initializes it as described in the
234 beginning of this manual page. The process is spawned using the
235 spawn BIFs.
236 spawn_link(Fun) -> pid()
238 spawn_link(Node, Fun) -> pid()
240 spawn_link(Module, Function, Args) -> pid()
242 spawn_link(Node, Module, Function, Args) -> pid()
244 Types:
246 Node = node()
248 Fun = function()
249 Module = module()
250 Function = atom()
251 Args = [term()]
252 Spawns a new process and initializes it as described in the
254 beginning of this manual page. The process is spawned using the
255 spawn_link BIFs.
256 spawn_opt(Fun, SpawnOpts) -> pid()
258 spawn_opt(Node, Function, SpawnOpts) -> pid()
260 spawn_opt(Module, Function, Args, SpawnOpts) -> pid()
262 spawn_opt(Node, Module, Function, Args, SpawnOpts) -> pid()
264 Types:
266 Node = node()
268 Fun = function()
269 Module = module()
270 Function = atom()
271 Args = [term()]
272 SpawnOpts = [spawn_option()]
273 Spawns a new process and initializes it as described in the
275 beginning of this manual page. The process is spawned using the
276 spawn_opt BIFs.
277 Note:
279 Using spawn option monitor is not allowed. It causes the func‐
280 tion to fail with reason badarg.
281 start(Module, Function, Args) -> Ret
284 start(Module, Function, Args, Time) -> Ret
286 start(Module, Function, Args, Time, SpawnOpts) -> Ret
288 start_link(Module, Function, Args) -> Ret
290 start_link(Module, Function, Args, Time) -> Ret
292 start_link(Module, Function, Args, Time, SpawnOpts) -> Ret
294 Types:
296 Module = module()
298 Function = atom()
299 Args = [term()]
300 Time = timeout()
301 SpawnOpts = [spawn_option()]
302 Ret = term() | {error, Reason :: term()}
303 Starts a new process synchronously. Spawns the process and waits
305 for it to start. When the process has started, it must call
306 init_ack(Parent, Ret) or init_ack(Ret), where Parent is the
307 process that evaluates this function. At this time, Ret is
308 returned.
309 If function start_link/3,4,5 is used and the process crashes
311 before it has called init_ack/1,2, {error, Reason} is returned
312 if the calling process traps exits.
313 If Time is specified as an integer, this function waits for Time
315 milliseconds for the new process to call init_ack, or {error,
316 timeout} is returned, and the process is killed.
317 Argument SpawnOpts, if specified, is passed as the last argument
319 to the spawn_opt/2,3,4,5 BIF.
320 Note:
322 Using spawn option monitor is not allowed. It causes the func‐
323 tion to fail with reason badarg.
324 stop(Process) -> ok
327 Types:
329 Process = pid() | RegName | {RegName, node()}
331 Equivalent to stop(Process, normal, infinity).
333 stop(Process, Reason, Timeout) -> ok
335 Types:
337 Process = pid() | RegName | {RegName, node()}
339 Reason = term()
340 Timeout = timeout()
341 Orders the process to exit with the specified Reason and waits
343 for it to terminate.
344 Returns ok if the process exits with the specified Reason within
346 Timeout milliseconds.
347 If the call times out, a timeout exception is raised.
349 If the process does not exist, a noproc exception is raised.
351 The implementation of this function is based on the terminate
353 system message, and requires that the process handles system
354 messages correctly. For information about system messages, see
355 sys(3) and section sys and proc_lib in OTP Design Principles.
356 translate_initial_call(Process) -> {Module, Function, Arity}
358 Types:
360 Process = dict_or_pid()
362 Module = module()
363 Function = atom()
364 Arity = byte()
365 This function is used by functions c:i/0 and c:regs/0 to present
367 process information.
368 This function extracts the initial call of a process that was
370 started using one of the spawn or start functions in this mod‐
371 ule, and translates it to more useful information. Process can
372 either be a pid, an integer tuple (from which a pid can be cre‐
373 ated), or the process information of a process Pid fetched
374 through an erlang:process_info(Pid) function call.
375 If the initial call is to one of the system-defined behaviors
377 such as gen_server or gen_event, it is translated to more useful
378 information. If a gen_server is spawned, the returned Module is
379 the name of the callback module and Function is init (the func‐
380 tion that initiates the new server).
381 A supervisor and a supervisor_bridge are also gen_server pro‐
383 cesses. To return information that this process is a supervisor
384 and the name of the callback module, Module is supervisor and
385 Function is the name of the supervisor callback module. Arity is
386 1, as the init/1 function is called initially in the callback
387 module.
388 By default, {proc_lib,init_p,5} is returned if no information
390 about the initial call can be found. It is assumed that the
391 caller knows that the process has been spawned with the proc_lib
392 module.
393
395 error_logger(3)
396 logger(3)
398Ericsson AB stdlib 3.8.2.1 proc_lib(3)