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() = erlang:spawn_opt_option()
49
50              See erlang:spawn_opt/2,3,4,5.
51
52       start_spawn_option() =
53           link |
54           {priority, erlang:priority_level()} |
55           {fullsweep_after, integer() >= 0} |
56           {min_heap_size, integer() >= 0} |
57           {min_bin_vheap_size, integer() >= 0} |
58           {max_heap_size, erlang:max_heap_size()} |
59           {message_queue_data, erlang:message_queue_data()}
60
61              A restricted set of spawn options. Most notably monitor  is  not
62              part of these options.
63
64       dict_or_pid() =
65           pid() |
66           (ProcInfo :: [term()]) |
67           {X :: integer(), Y :: integer(), Z :: integer()}
68

EXPORTS

70       format(CrashReport) -> string()
71
72              Types:
73
74                 CrashReport = [term()]
75
76              Equivalent to format(CrashReport, latin1).
77
78       format(CrashReport, Encoding) -> string()
79
80              Types:
81
82                 CrashReport = [term()]
83                 Encoding = latin1 | unicode | utf8
84
85          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
93
94              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
101       format(CrashReport, Encoding, Depth) -> string()
102
103              Types:
104
105                 CrashReport = [term()]
106                 Encoding = latin1 | unicode | utf8
107                 Depth = unlimited | integer() >= 1
108
109          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
117
118              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
123       hibernate(Module, Function, Args) -> no_return()
124
125              Types:
126
127                 Module = module()
128                 Function = atom()
129                 Args = [term()]
130
131              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
135              Always  use  this  function  instead  of  the  BIF for processes
136              started using proc_lib functions.
137
138       init_ack(Ret) -> ok
139
140       init_ack(Parent, Ret) -> ok
141
142              Types:
143
144                 Parent = pid()
145                 Ret = term()
146
147              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
152              Function  init_ack/1  uses the parent value previously stored by
153              the start function used.
154
155              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
159              The  following  example  illustrates  how  this   function   and
160              proc_lib:start_link/3 are used:
161
162              -module(my_proc).
163              -export([start_link/0]).
164              -export([init/1]).
165
166              start_link() ->
167                  proc_lib:start_link(my_proc, init, [self()]).
168
169              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
178
179       initial_call(Process) -> {Module, Function, Args} | false
180
181              Types:
182
183                 Process = dict_or_pid()
184                 Module = module()
185                 Function = atom()
186                 Args = [atom()]
187
188              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
194          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
202              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
210
211       spawn(Fun) -> pid()
212
213       spawn(Node, Fun) -> pid()
214
215       spawn(Module, Function, Args) -> pid()
216
217       spawn(Node, Module, Function, Args) -> pid()
218
219              Types:
220
221                 Node = node()
222                 Fun = function()
223                 Module = module()
224                 Function = atom()
225                 Args = [term()]
226
227              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
231       spawn_link(Fun) -> pid()
232
233       spawn_link(Node, Fun) -> pid()
234
235       spawn_link(Module, Function, Args) -> pid()
236
237       spawn_link(Node, Module, Function, Args) -> pid()
238
239              Types:
240
241                 Node = node()
242                 Fun = function()
243                 Module = module()
244                 Function = atom()
245                 Args = [term()]
246
247              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
251       spawn_opt(Fun, SpawnOpts) -> pid() | {pid(), reference()}
252
253       spawn_opt(Node, Function, SpawnOpts) ->
254                    pid() | {pid(), reference()}
255
256       spawn_opt(Module, Function, Args, SpawnOpts) ->
257                    pid() | {pid(), reference()}
258
259       spawn_opt(Node, Module, Function, Args, SpawnOpts) ->
260                    pid() | {pid(), reference()}
261
262              Types:
263
264                 Node = node()
265                 Fun = function()
266                 Module = module()
267                 Function = atom()
268                 Args = [term()]
269                 SpawnOpts = [spawn_option()]
270
271              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
275       start(Module, Function, Args) -> Ret
276
277       start(Module, Function, Args, Time) -> Ret
278
279       start(Module, Function, Args, Time, SpawnOpts) -> Ret
280
281              Types:
282
283                 Module = module()
284                 Function = atom()
285                 Args = [term()]
286                 Time = timeout()
287                 SpawnOpts = [start_spawn_option()]
288                 Ret = term() | {error, Reason :: term()}
289
290              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
296              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
300              Argument SpawnOpts, if specified, is passed as the last argument
301              to the spawn_opt/2,3,4,5 BIF.
302
303          Note:
304              Using  spawn  option monitor is not allowed. It causes the func‐
305              tion to fail with reason badarg.
306
307
308       start_link(Module, Function, Args) -> Ret
309
310       start_link(Module, Function, Args, Time) -> Ret
311
312       start_link(Module, Function, Args, Time, SpawnOpts) -> Ret
313
314              Types:
315
316                 Module = module()
317                 Function = atom()
318                 Args = [term()]
319                 Time = timeout()
320                 SpawnOpts = [start_spawn_option()]
321                 Ret = term() | {error, Reason :: term()}
322
323              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
330              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
334              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
338              Argument SpawnOpts, if specified, is passed as the last argument
339              to the spawn_opt/2,3,4,5 BIF.
340
341          Note:
342              Using spawn option monitor is not allowed. It causes  the  func‐
343              tion to fail with reason badarg.
344
345
346       start_monitor(Module, Function, Args) -> {Ret, Mon}
347
348       start_monitor(Module, Function, Args, Time) -> {Ret, Mon}
349
350       start_monitor(Module, Function, Args, Time, SpawnOpts) ->
351                        {Ret, Mon}
352
353              Types:
354
355                 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
363              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
370              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
374              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
378              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
382              Argument SpawnOpts, if specified, is passed as the last argument
383              to the spawn_opt/2,3,4,5 BIF.
384
385          Note:
386              Using  spawn  option monitor is not allowed. It causes the func‐
387              tion to fail with reason badarg.
388
389
390       stop(Process) -> ok
391
392              Types:
393
394                 Process = pid() | RegName | {RegName, node()}
395
396              Equivalent to stop(Process, normal, infinity).
397
398       stop(Process, Reason, Timeout) -> ok
399
400              Types:
401
402                 Process = pid() | RegName | {RegName, node()}
403                 Reason = term()
404                 Timeout = timeout()
405
406              Orders the process to exit with the specified Reason  and  waits
407              for it to terminate.
408
409              Returns ok if the process exits with the specified Reason within
410              Timeout milliseconds.
411
412              If the call times out, a timeout exception is raised.
413
414              If the process does not exist, a noproc exception is raised.
415
416              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
421       translate_initial_call(Process) -> {Module, Function, Arity}
422
423              Types:
424
425                 Process = dict_or_pid()
426                 Module = module()
427                 Function = atom()
428                 Arity = byte()
429
430              This function is used by functions c:i/0 and c:regs/0 to present
431              process information.
432
433              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
440              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
446              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
453              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

SEE ALSO

459       error_logger(3)
460
461       logger(3)
462
463
464
465Ericsson AB                       stdlib 4.2                       proc_lib(3)
Impressum