1proc_lib(3)                Erlang Module Definition                proc_lib(3)
2
3
4

NAME

6       proc_lib  -  Functions  for  asynchronous and synchronous start of pro‐
7       cesses
8           adhering to the OTP design principles.
9

DESCRIPTION

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
19       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
24       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
30       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
37       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
42       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

DATA TYPES

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
57              See erlang:spawn_opt/2,3,4,5.
58
59       priority_level() = high | low | max | normal
60
61       max_heap_size() =
62           integer() >= 0 |
63           #{size => integer() >= 0,
64             kill => true,
65             error_logger => true}
66
67              See  erlang:process_flag(max_heap_size, MaxHeapSize).
68
69       dict_or_pid() =
70           pid() |
71           (ProcInfo :: [term()]) |
72           {X :: integer(), Y :: integer(), Z :: integer()}
73

EXPORTS

75       format(CrashReport) -> string()
76
77              Types:
78
79                 CrashReport = [term()]
80
81              Equivalent to format(CrashReport, latin1).
82
83       format(CrashReport, Encoding) -> string()
84
85              Types:
86
87                 CrashReport = [term()]
88                 Encoding = latin1 | unicode | utf8
89
90          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
98
99              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
106       format(CrashReport, Encoding, Depth) -> string()
107
108              Types:
109
110                 CrashReport = [term()]
111                 Encoding = latin1 | unicode | utf8
112                 Depth = unlimited | integer() >= 1
113
114          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
122
123              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
128       hibernate(Module, Function, Args) -> no_return()
129
130              Types:
131
132                 Module = module()
133                 Function = atom()
134                 Args = [term()]
135
136              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
140              Always use this  function  instead  of  the  BIF  for  processes
141              started using proc_lib functions.
142
143       init_ack(Ret) -> ok
144
145       init_ack(Parent, Ret) -> ok
146
147              Types:
148
149                 Parent = pid()
150                 Ret = term()
151
152              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
157              Function init_ack/1 uses the parent value previously  stored  by
158              the start function used.
159
160              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
164              The   following   example  illustrates  how  this  function  and
165              proc_lib:start_link/3 are used:
166
167              -module(my_proc).
168              -export([start_link/0]).
169              -export([init/1]).
170
171              start_link() ->
172                  proc_lib:start_link(my_proc, init, [self()]).
173
174              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
183
184       initial_call(Process) -> {Module, Function, Args} | false
185
186              Types:
187
188                 Process = dict_or_pid()
189                 Module = module()
190                 Function = atom()
191                 Args = [atom()]
192
193              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
199          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
207              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
215
216       spawn(Fun) -> pid()
217
218       spawn(Node, Fun) -> pid()
219
220       spawn(Module, Function, Args) -> pid()
221
222       spawn(Node, Module, Function, Args) -> pid()
223
224              Types:
225
226                 Node = node()
227                 Fun = function()
228                 Module = module()
229                 Function = atom()
230                 Args = [term()]
231
232              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
236       spawn_link(Fun) -> pid()
237
238       spawn_link(Node, Fun) -> pid()
239
240       spawn_link(Module, Function, Args) -> pid()
241
242       spawn_link(Node, Module, Function, Args) -> pid()
243
244              Types:
245
246                 Node = node()
247                 Fun = function()
248                 Module = module()
249                 Function = atom()
250                 Args = [term()]
251
252              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
256       spawn_opt(Fun, SpawnOpts) -> pid()
257
258       spawn_opt(Node, Function, SpawnOpts) -> pid()
259
260       spawn_opt(Module, Function, Args, SpawnOpts) -> pid()
261
262       spawn_opt(Node, Module, Function, Args, SpawnOpts) -> pid()
263
264              Types:
265
266                 Node = node()
267                 Fun = function()
268                 Module = module()
269                 Function = atom()
270                 Args = [term()]
271                 SpawnOpts = [spawn_option()]
272
273              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
277          Note:
278              Using  spawn  option monitor is not allowed. It causes the func‐
279              tion to fail with reason badarg.
280
281
282       start(Module, Function, Args) -> Ret
283
284       start(Module, Function, Args, Time) -> Ret
285
286       start(Module, Function, Args, Time, SpawnOpts) -> Ret
287
288       start_link(Module, Function, Args) -> Ret
289
290       start_link(Module, Function, Args, Time) -> Ret
291
292       start_link(Module, Function, Args, Time, SpawnOpts) -> Ret
293
294              Types:
295
296                 Module = module()
297                 Function = atom()
298                 Args = [term()]
299                 Time = timeout()
300                 SpawnOpts = [spawn_option()]
301                 Ret = term() | {error, Reason :: term()}
302
303              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
309              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
313              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
317              Argument SpawnOpts, if specified, is passed as the last argument
318              to the spawn_opt/2,3,4,5 BIF.
319
320          Note:
321              Using  spawn  option monitor is not allowed. It causes the func‐
322              tion to fail with reason badarg.
323
324
325       stop(Process) -> ok
326
327              Types:
328
329                 Process = pid() | RegName | {RegName, node()}
330
331              Equivalent to stop(Process, normal, infinity).
332
333       stop(Process, Reason, Timeout) -> ok
334
335              Types:
336
337                 Process = pid() | RegName | {RegName, node()}
338                 Reason = term()
339                 Timeout = timeout()
340
341              Orders the process to exit with the specified Reason  and  waits
342              for it to terminate.
343
344              Returns ok if the process exits with the specified Reason within
345              Timeout milliseconds.
346
347              If the call times out, a timeout exception is raised.
348
349              If the process does not exist, a noproc exception is raised.
350
351              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
356       translate_initial_call(Process) -> {Module, Function, Arity}
357
358              Types:
359
360                 Process = dict_or_pid()
361                 Module = module()
362                 Function = atom()
363                 Arity = byte()
364
365              This function is used by functions c:i/0 and c:regs/0 to present
366              process information.
367
368              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
375              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
381              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
388              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

SEE ALSO

394       error_logger(3)
395
396       logger(3)
397
398
399
400Ericsson AB                       stdlib 3.10                      proc_lib(3)
Impressum