aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/proc_lib.xml
blob: 5bf57446221e08c9360e4397099c405f38933545 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
    
    </legalnotice>

    <title>proc_lib</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module>proc_lib</module>
  <modulesummary>Functions for asynchronous and synchronous start of processes adhering to the OTP design principles.</modulesummary>
  <description>
    <p>This module is used to start processes adhering to
      the <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso>. Specifically, the functions in this
      module are used by the OTP standard behaviors (<c>gen_server</c>,
      <c>gen_fsm</c>, ...) when starting new processes. The functions
      can also be used to start <em>special processes</em>, user
      defined processes which comply to the OTP design principles. See
      <seealso marker="doc/design_principles:spec_proc">Sys and Proc_Lib</seealso> in OTP Design Principles for an example.</p>
    <p>Some useful information is initialized when a process starts.
      The registered names, or the process identifiers, of the parent
      process, and the parent ancestors, are stored together with
      information about the function initially called in the process.</p>
    <p>While in "plain Erlang" a process is said to terminate normally
      only for the exit reason <c>normal</c>, a process started
      using <c>proc_lib</c> is also said to terminate normally if it
      exits with reason <c>shutdown</c> or <c>{shutdown,Term}</c>.
      <c>shutdown</c> is the reason used when
      an application (supervision tree) is stopped.</p>
    <p>When a process started using <c>proc_lib</c> terminates
      abnormally -- that is, with another exit reason than <c>normal</c>,
      <c>shutdown</c>, or <c>{shutdown,Term}</c> -- a <em>crash report</em>
      is generated, which is written to terminal by the default SASL
      event handler. That is, the crash report is normally only visible
      if the SASL application is started. See
      <seealso marker="sasl:sasl_app">sasl(6)</seealso> and
      <seealso marker="sasl:error_logging">SASL User's Guide</seealso>.</p>
    <p>The crash report contains the previously stored information such
      as ancestors and initial function, the termination reason, and
      information regarding other processes which terminate as a result
      of this process terminating.</p>
  </description>
  <datatypes>
    <datatype>
      <name name="spawn_option"/>
      <desc>
        <p>See <seealso marker="erts:erlang#spawn_opt/4">
          erlang:spawn_opt/2,3,4,5</seealso>.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="priority_level"/>
    </datatype>
    <datatype>
      <name name="dict_or_pid"/>
    </datatype>
  </datatypes>
  <funcs>
    <func>
      <name name="spawn" arity="1"/>
      <name name="spawn" arity="2"/>
      <name name="spawn" arity="3"/>
      <name name="spawn" arity="4"/>
      <fsummary>Spawn a new process.</fsummary>
      <type variable="Node"/>
      <type variable="Fun" name_i="1"/>
      <type variable="Module"/>
      <type variable="Function"/>
      <type variable="Args"/>
      <desc>
        <p>Spawns a new process and initializes it as described above.
          The process is spawned using the
          <seealso marker="erts:erlang#spawn/1">spawn</seealso> BIFs.</p>
      </desc>
    </func>
    <func>
      <name name="spawn_link" arity="1"/>
      <name name="spawn_link" arity="2"/>
      <name name="spawn_link" arity="3"/>
      <name name="spawn_link" arity="4"/>
      <fsummary>Spawn and link to a new process.</fsummary>
      <type variable="Node"/>
      <type variable="Fun" name_i="1"/>
      <type variable="Module"/>
      <type variable="Function"/>
      <type variable="Args"/>
      <desc>
        <p>Spawns a new process and initializes it as described above.
          The process is spawned using the
          <seealso marker="erts:erlang#spawn_link/1">spawn_link</seealso>
          BIFs.</p>
      </desc>
    </func>
    <func>
      <name name="spawn_opt" arity="2"/>
      <name name="spawn_opt" arity="3"/>
      <name name="spawn_opt" arity="4"/>
      <name name="spawn_opt" arity="5"/>
      <fsummary>Spawn a new process with given options.</fsummary>
      <type variable="Node"/>
      <type variable="Fun" name_i="1"/>
      <type variable="Module"/>
      <type variable="Function"/>
      <type variable="Args"/>
      <type variable="SpawnOpts"/>
      <desc>
        <p>Spawns a new process and initializes it as described above.
          The process is spawned using the
          <seealso marker="erts:erlang#spawn_opt/2">spawn_opt</seealso>
          BIFs.</p>
        <note>
          <p>Using the spawn option <c>monitor</c> is currently not
            allowed, but will cause the function to fail with reason
            <c>badarg</c>.</p>
        </note>
      </desc>
    </func>
    <func>
      <name name="start" arity="3"/>
      <name name="start" arity="4"/>
      <name name="start" arity="5"/>
      <name name="start_link" arity="3"/>
      <name name="start_link" arity="4"/>
      <name name="start_link" arity="5"/>
      <fsummary>Start a new process synchronously.</fsummary>
      <desc>
        <p>Starts a new process synchronously. Spawns the process and
          waits for it to start.  When the process has started, it
          <em>must</em> call
          <seealso marker="#init_ack/2">init_ack(Parent,Ret)</seealso>
          or <seealso marker="#init_ack/1">init_ack(Ret)</seealso>,
          where <c>Parent</c> is the process that evaluates this
          function.  At this time, <c>Ret</c> is returned.</p>
        <p>If the <c>start_link/3,4,5</c> function is used and
          the process crashes before it has called <c>init_ack/1,2</c>,
          <c>{error, <anno>Reason</anno>}</c> is returned if the calling process
          traps exits.</p>
        <p>If <c><anno>Time</anno></c> is specified as an integer, this function
          waits for <c><anno>Time</anno></c> milliseconds for the new process to call
          <c>init_ack</c>, or <c>{error, timeout}</c> is returned, and
          the process is killed.</p>
        <p>The <c><anno>SpawnOpts</anno></c> argument, if given, will be passed
          as the last argument to the <c>spawn_opt/2,3,4,5</c> BIF.</p>
        <note>
          <p>Using the spawn option <c>monitor</c> is currently not
            allowed, but will cause the function to fail with reason
            <c>badarg</c>.</p>
        </note>
      </desc>
    </func>
    <func>
      <name name="init_ack" arity="1"/>
      <name name="init_ack" arity="2"/>
      <fsummary>Used by a process when it has started.</fsummary>
      <desc>
        <p>This function must used by a process that has been started by
          a <seealso marker="#start/3">start[_link]/3,4,5</seealso>
          function. It tells <c><anno>Parent</anno></c> that the process has
          initialized itself, has started, or has failed to initialize
          itself.</p>
        <p>The <c>init_ack/1</c> function uses the parent value
          previously stored by the start function used.</p>
        <p>If this function is not called, the start function will
          return an error tuple (if a link and/or a timeout is used) or
          hang otherwise.</p>
        <p>The following example illustrates how this function and
          <c>proc_lib:start_link/3</c> are used.</p>
        <code type="none">
-module(my_proc).
-export([start_link/0]).
-export([init/1]).

start_link() ->
    proc_lib:start_link(my_proc, init, [self()]).

init(Parent) ->
    case do_initialization() of
        ok ->
            proc_lib:init_ack(Parent, {ok, self()});
        {error, Reason} ->
            exit(Reason)
    end,
    loop().

...</code>
      </desc>
    </func>
    <func>
      <name name="format" arity="1"/>
      <fsummary>Format a crash report.</fsummary>
      <desc>
        <p>Equivalent to <c>format(<anno>CrashReport</anno>, latin1)</c>.</p>
      </desc>
    </func>
    <func>
      <name name="format" arity="2"/>
      <fsummary>Format a crash report.</fsummary>
      <desc>
        <p>This function can be used by a user defined event handler to
          format a crash report. The crash report is sent using
          <c>error_logger:error_report(crash_report, <anno>CrashReport</anno>)</c>.
          That is, the event to be handled is of the format
          <c>{error_report, GL, {Pid, crash_report, <anno>CrashReport</anno>}}</c>
          where <c>GL</c> is the group leader pid of the process
          <c>Pid</c> which sent the crash report.</p>
      </desc>
    </func>
    <func>
      <name name="initial_call" arity="1"/>
      <fsummary>Extract the initial call of a <c>proc_lib</c>spawned process.</fsummary>
      <desc>
        <p>Extracts the initial call of a process that was started
          using one of the spawn or start functions described above.
          <c><anno>Process</anno></c> can either be a pid, an integer tuple (from
          which a pid can be created), or the process information of a
          process <c>Pid</c> fetched through an
          <c>erlang:process_info(Pid)</c> function call.</p>

	<note><p>The list <c><anno>Args</anno></c> no longer contains the actual arguments,
	but the same number of atoms as the number of arguments; the first atom
	is always <c>'Argument__1'</c>, the second <c>'Argument__2'</c>, and
	so on. The reason is that the argument list could waste a significant
	amount of memory, and if the argument list contained funs, it could
	be impossible to upgrade the code for the module.</p>

	<p>If the process was spawned using a fun, <c>initial_call/1</c> no
	longer returns the actual fun, but the module, function for the local
	function implementing the fun, and the arity, for instance
	<c>{some_module,-work/3-fun-0-,0}</c> (meaning that the fun was
	created in the function <c>some_module:work/3</c>).
	The reason is that keeping the fun would prevent code upgrade for the
	module, and that a significant amount of memory could be wasted.</p>
	</note>
      </desc>
    </func>
    <func>
      <name name="translate_initial_call" arity="1"/>
      <fsummary>Extract and translate the initial call of a <c>proc_lib</c>spawned process.</fsummary>
      <desc>
        <p>This function is used by the <c>c:i/0</c> and
          <c>c:regs/0</c> functions in order to present process
          information.</p>
        <p>Extracts the initial call of a process that was started
          using one of the spawn or start functions described above,
          and translates it to more useful information. <c><anno>Process</anno></c>
          can either be a pid, an integer tuple (from which a pid can
          be created), or the process information of a process
          <c>Pid</c> fetched through an <c>erlang:process_info(Pid)</c>
          function call.</p>
        <p>If the initial call is to one of the system defined behaviors
          such as <c>gen_server</c> or <c>gen_event</c>, it is
          translated to more useful information. If a <c>gen_server</c>
          is spawned, the returned <c><anno>Module</anno></c> is the name of
          the callback module and <c><anno>Function</anno></c> is <c>init</c>
          (the function that initiates the new server).</p>
        <p>A <c>supervisor</c> and a <c>supervisor_bridge</c> are also
          <c>gen_server</c> processes. In order to return information
          that this process is a supervisor and the name of the
          call-back module, <c><anno>Module</anno></c> is <c>supervisor</c> and
          <c><anno>Function</anno></c> is the name of the supervisor callback
          module. <c><anno>Arity</anno></c> is <c>1</c> since the <c>init/1</c>
          function is called initially in the callback module.</p>
        <p>By default, <c>{proc_lib,init_p,5}</c> is returned if no
          information about the initial call can be found. It is
          assumed that the caller knows that the process has been
          spawned with the <c>proc_lib</c> module.</p>
      </desc>
    </func>
    <func>
      <name name="hibernate" arity="3"/>
      <fsummary>Hibernate a process until a message is sent to it</fsummary>
      <desc>
        <p>This function does the same as (and does call) the BIF
          <seealso marker="erts:erlang#erlang:hibernate/3">hibernate/3</seealso>,
          but ensures that exception handling and logging continues to
          work as expected when the process wakes up. Always use this
          function instead of the BIF for processes started using
          <c>proc_lib</c> functions.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>SEE ALSO</title>
    <p><seealso marker="kernel:error_logger">error_logger(3)</seealso></p>
  </section>
</erlref>