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 SASL event handler. That is, the crash report is nor‐
34 mally only visible if the SASL application is started; see sasl(6) and
35 section SASL 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 and do not
39 require SASL to be started. All exceptions are converted to exits which
40 are ignored by the default error_logger 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 This function can be used by a user-defined event handler to
92 format a crash report. The crash report is sent using error_log‐
93 ger:error_report(crash_report, CrashReport). That is, the event
94 to be handled is of the format {error_report, GL, {Pid,
95 crash_report, CrashReport}}, where GL is the group leader pid of
96 process Pid that sent the crash report.
97 format(CrashReport, Encoding, Depth) -> string()
99 Types:
101 CrashReport = [term()]
103 Encoding = latin1 | unicode | utf8
104 Depth = unlimited | integer() >= 1
105 This function can be used by a user-defined event handler to
107 format a crash report. When Depth is specified as a positive
108 integer, it is used in the format string to limit the output as
109 follows: io_lib:format("~P", [Term,Depth]).
110 hibernate(Module, Function, Args) -> no_return()
112 Types:
114 Module = module()
116 Function = atom()
117 Args = [term()]
118 This function does the same as (and does call) the hibernate/3
120 BIF, but ensures that exception handling and logging continues
121 to work as expected when the process wakes up.
122 Always use this function instead of the BIF for processes
124 started using proc_lib functions.
125 init_ack(Ret) -> ok
127 init_ack(Parent, Ret) -> ok
129 Types:
131 Parent = pid()
133 Ret = term()
134 This function must be used by a process that has been started by
136 a start[_link]/3,4,5 function. It tells Parent that the process
137 has initialized itself, has started, or has failed to initialize
138 itself.
139 Function init_ack/1 uses the parent value previously stored by
141 the start function used.
142 If this function is not called, the start function returns an
144 error tuple (if a link and/or a time-out is used) or hang other‐
145 wise.
146 The following example illustrates how this function and
148 proc_lib:start_link/3 are used:
149 -module(my_proc).
151 -export([start_link/0]).
152 -export([init/1]).
153 start_link() ->
155 proc_lib:start_link(my_proc, init, [self()]).
156 init(Parent) ->
158 case do_initialization() of
159 ok ->
160 proc_lib:init_ack(Parent, {ok, self()});
161 {error, Reason} ->
162 exit(Reason)
163 end,
164 loop().
165 initial_call(Process) -> {Module, Function, Args} | false
168 Types:
170 Process = dict_or_pid()
172 Module = module()
173 Function = atom()
174 Args = [atom()]
175 Extracts the initial call of a process that was started using
177 one of the spawn or start functions in this module. Process can
178 either be a pid, an integer tuple (from which a pid can be cre‐
179 ated), or the process information of a process Pid fetched
180 through an erlang:process_info(Pid) function call.
181 Note:
183 The list Args no longer contains the arguments, but the same
184 number of atoms as the number of arguments; the first atom is
185 'Argument__1', the second 'Argument__2', and so on. The reason
186 is that the argument list could waste a significant amount of
187 memory, and if the argument list contained funs, it could be
188 impossible to upgrade the code for the module.
189 If the process was spawned using a fun, initial_call/1 no longer
191 returns the fun, but the module, function for the local function
192 implementing the fun, and the arity, for example, {some_mod‐
193 ule,-work/3-fun-0-,0} (meaning that the fun was created in func‐
194 tion some_module:work/3). The reason is that keeping the fun
195 would prevent code upgrade for the module, and that a signifi‐
196 cant amount of memory could be wasted.
197 spawn(Fun) -> pid()
200 spawn(Node, Fun) -> pid()
202 spawn(Module, Function, Args) -> pid()
204 spawn(Node, Module, Function, Args) -> pid()
206 Types:
208 Node = node()
210 Fun = function()
211 Module = module()
212 Function = atom()
213 Args = [term()]
214 Spawns a new process and initializes it as described in the
216 beginning of this manual page. The process is spawned using the
217 spawn BIFs.
218 spawn_link(Fun) -> pid()
220 spawn_link(Node, Fun) -> pid()
222 spawn_link(Module, Function, Args) -> pid()
224 spawn_link(Node, Module, Function, Args) -> pid()
226 Types:
228 Node = node()
230 Fun = function()
231 Module = module()
232 Function = atom()
233 Args = [term()]
234 Spawns a new process and initializes it as described in the
236 beginning of this manual page. The process is spawned using the
237 spawn_link BIFs.
238 spawn_opt(Fun, SpawnOpts) -> pid()
240 spawn_opt(Node, Function, SpawnOpts) -> pid()
242 spawn_opt(Module, Function, Args, SpawnOpts) -> pid()
244 spawn_opt(Node, Module, Function, Args, SpawnOpts) -> pid()
246 Types:
248 Node = node()
250 Fun = function()
251 Module = module()
252 Function = atom()
253 Args = [term()]
254 SpawnOpts = [spawn_option()]
255 Spawns a new process and initializes it as described in the
257 beginning of this manual page. The process is spawned using the
258 spawn_opt BIFs.
259 Note:
261 Using spawn option monitor is not allowed. It causes the func‐
262 tion to fail with reason badarg.
263 start(Module, Function, Args) -> Ret
266 start(Module, Function, Args, Time) -> Ret
268 start(Module, Function, Args, Time, SpawnOpts) -> Ret
270 start_link(Module, Function, Args) -> Ret
272 start_link(Module, Function, Args, Time) -> Ret
274 start_link(Module, Function, Args, Time, SpawnOpts) -> Ret
276 Types:
278 Module = module()
280 Function = atom()
281 Args = [term()]
282 Time = timeout()
283 SpawnOpts = [spawn_option()]
284 Ret = term() | {error, Reason :: term()}
285 Starts a new process synchronously. Spawns the process and waits
287 for it to start. When the process has started, it must call
288 init_ack(Parent, Ret) or init_ack(Ret), where Parent is the
289 process that evaluates this function. At this time, Ret is
290 returned.
291 If function start_link/3,4,5 is used and the process crashes
293 before it has called init_ack/1,2, {error, Reason} is returned
294 if the calling process traps exits.
295 If Time is specified as an integer, this function waits for Time
297 milliseconds for the new process to call init_ack, or {error,
298 timeout} is 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 stop(Process) -> ok
309 Types:
311 Process = pid() | RegName | {RegName, node()}
313 Equivalent to stop(Process, normal, infinity).
315 stop(Process, Reason, Timeout) -> ok
317 Types:
319 Process = pid() | RegName | {RegName, node()}
321 Reason = term()
322 Timeout = timeout()
323 Orders the process to exit with the specified Reason and waits
325 for it to terminate.
326 Returns ok if the process exits with the specified Reason within
328 Timeout milliseconds.
329 If the call times out, a timeout exception is raised.
331 If the process does not exist, a noproc exception is raised.
333 The implementation of this function is based on the terminate
335 system message, and requires that the process handles system
336 messages correctly. For information about system messages, see
337 sys(3) and section sys and proc_lib in OTP Design Principles.
338 translate_initial_call(Process) -> {Module, Function, Arity}
340 Types:
342 Process = dict_or_pid()
344 Module = module()
345 Function = atom()
346 Arity = byte()
347 This function is used by functions c:i/0 and c:regs/0 to present
349 process information.
350 This function extracts the initial call of a process that was
352 started using one of the spawn or start functions in this mod‐
353 ule, and translates it to more useful information. Process can
354 either be a pid, an integer tuple (from which a pid can be cre‐
355 ated), or the process information of a process Pid fetched
356 through an erlang:process_info(Pid) function call.
357 If the initial call is to one of the system-defined behaviors
359 such as gen_server or gen_event, it is translated to more useful
360 information. If a gen_server is spawned, the returned Module is
361 the name of the callback module and Function is init (the func‐
362 tion that initiates the new server).
363 A supervisor and a supervisor_bridge are also gen_server pro‐
365 cesses. To return information that this process is a supervisor
366 and the name of the callback module, Module is supervisor and
367 Function is the name of the supervisor callback module. Arity is
368 1, as the init/1 function is called initially in the callback
369 module.
370 By default, {proc_lib,init_p,5} is returned if no information
372 about the initial call can be found. It is assumed that the
373 caller knows that the process has been spawned with the proc_lib
374 module.
375
377 error_logger(3)
378Ericsson AB stdlib 3.4.5.1 proc_lib(3)