← Back to branch summary

~clint-fewbar/ubuntu/precise/erlang/merge-15b

« back to all changes in this revision

Viewing changes to lib/kernel/doc/src/application.xml

  • Committer: Package Import Robot
  • Author(s): Sergei Golovan
  • Date: 2011-12-15 19:20:10 UTC
  • mfrom: (1.1.18) (3.5.15 sid)
  • mto: (3.5.16 sid)
  • mto: This revision was merged to the branch mainline in revision 33.
  • Revision ID: package-import@ubuntu.com-20111215192010-jnxcfe3tbrpp0big
Tags: 1:15.b-dfsg-1
* New upstream release.
* Upload to experimental because this release breaks external drivers
  API along with ABI, so several applications are to be fixed.
* Removed SSL patch because the old SSL implementation is removed from
  the upstream distribution.
* Removed never used patch which added native code to erlang beam files.
* Removed the erlang-docbuilder binary package because the docbuilder
  application was dropped by upstream.
* Documented dropping ${erlang-docbuilder:Depends} substvar in
  erlang-depends(1) manpage.
* Made erlang-base and erlang-base-hipe provide virtual package
  erlang-abi-15.b (the number means the first erlang version, which
  provides current ABI).

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/kernel/doc/src/application.xml
4
4
<erlref>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>1996</year><year>2010</year>
 
7
      <year>1996</year><year>2011</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
50
50
    <p>Refer to <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso> for more information about
51
51
      applications and behaviours.</p>
52
52
  </description>
 
53
  <datatypes>
 
54
    <datatype>
 
55
      <name name="start_type"/>
 
56
    </datatype>
 
57
    <datatype>
 
58
      <name name="restart_type"/>
 
59
    </datatype>
 
60
    <datatype>
 
61
      <!-- Parameterized opaque types are NYI: -->
 
62
      <name><marker id="type-tuple_of">tuple_of(T)</marker></name>
 
63
      <desc><p>A tuple where the elements are of type <c>T</c>.</p></desc>
 
64
    </datatype>
 
65
  </datatypes>
53
66
  <funcs>
54
67
    <func>
55
 
      <name>get_all_env() -> Env</name>
56
 
      <name>get_all_env(Application) -> Env</name>
 
68
      <name name="get_all_env" arity="0"/>
 
69
      <name name="get_all_env" arity="1"/>
57
70
      <fsummary>Get the configuration parameters for an application</fsummary>
58
 
      <type>
59
 
        <v>Application = atom()</v>
60
 
        <v>Env = [{Par,Val}]</v>
61
 
        <v>&nbsp;Par = atom()</v>
62
 
        <v>&nbsp;Val = term()</v>
63
 
      </type>
64
71
      <desc>
65
72
        <p>Returns the configuration parameters and their values for
66
 
          <c>Application</c>. If the argument is omitted, it defaults to
 
73
          <c><anno>Application</anno></c>. If the argument is omitted, it defaults to
67
74
          the application of the calling process.</p>
68
75
        <p>If the specified application is not loaded, or if the process
69
76
          executing the call does not belong to any application,
71
78
      </desc>
72
79
    </func>
73
80
    <func>
74
 
      <name>get_all_key() -> {ok, Keys} | []</name>
75
 
      <name>get_all_key(Application) -> {ok, Keys} | undefined </name>
 
81
      <name name="get_all_key" arity="0"/>
 
82
      <name name="get_all_key" arity="1"/>
76
83
      <fsummary>Get the application specification keys</fsummary>
77
 
      <type>
78
 
        <v>Application = atom()</v>
79
 
        <v>Keys = [{Key,Val}]</v>
80
 
        <v>&nbsp;Key = atom()</v>
81
 
        <v>&nbsp;Val = term()</v>
82
 
      </type>
83
84
      <desc>
84
85
        <p>Returns the application specification keys and their values
85
 
          for <c>Application</c>. If the argument is omitted, it
 
86
          for <c><anno>Application</anno></c>. If the argument is omitted, it
86
87
          defaults to the application of the calling process.</p>
87
88
        <p>If the specified application is not loaded, the function
88
89
          returns <c>undefined</c>. If the process executing the call
91
92
      </desc>
92
93
    </func>
93
94
    <func>
94
 
      <name>get_application() -> {ok, Application} | undefined</name>
95
 
      <name>get_application(Pid | Module) -> {ok, Application} | undefined</name>
 
95
      <name name="get_application" arity="0"/>
 
96
      <name name="get_application" arity="1"/>
96
97
      <fsummary>Get the name of an application containing a certain process or module</fsummary>
97
 
      <type>
98
 
        <v>Pid = pid()</v>
99
 
        <v>Module = atom()</v>
100
 
        <v>Application = atom()</v>
101
 
      </type>
102
98
      <desc>
103
99
        <p>Returns the name of the application to which the process
104
 
          <c>Pid</c> or the module <c>Module</c> belongs. Providing no
 
100
          <c><anno>Pid</anno></c> or the module <c><anno>Module</anno></c> belongs. Providing no
105
101
          argument is the same as calling
106
102
          <c>get_application(self())</c>.</p>
107
103
        <p>If the specified process does not belong to any application,
110
106
      </desc>
111
107
    </func>
112
108
    <func>
113
 
      <name>get_env(Par) -> {ok, Val} | undefined</name>
114
 
      <name>get_env(Application, Par) -> {ok, Val} | undefined</name>
 
109
      <name name="get_env" arity="1"/>
 
110
      <name name="get_env" arity="2"/>
115
111
      <fsummary>Get the value of a configuration parameter</fsummary>
116
 
      <type>
117
 
        <v>Application = atom()</v>
118
 
        <v>Par = atom()</v>
119
 
        <v>Val = term()</v>
120
 
      </type>
121
112
      <desc>
122
 
        <p>Returns the value of the configuration parameter <c>Par</c>
123
 
          for <c>Application</c>. If the application argument is
 
113
        <p>Returns the value of the configuration parameter <c><anno>Par</anno></c>
 
114
          for <c><anno>Application</anno></c>. If the application argument is
124
115
          omitted, it defaults to the application of the calling
125
116
          process.</p>
126
117
        <p>If the specified application is not loaded, or
130
121
      </desc>
131
122
    </func>
132
123
    <func>
133
 
      <name>get_key(Key) -> {ok, Val} | undefined</name>
134
 
      <name>get_key(Application, Key) -> {ok, Val} | undefined</name>
 
124
      <name name="get_key" arity="1"/>
 
125
      <name name="get_key" arity="2"/>
135
126
      <fsummary>Get the value of an application specification key</fsummary>
136
 
      <type>
137
 
        <v>Application = atom()</v>
138
 
        <v>Key = atom()</v>
139
 
        <v>Val = term()</v>
140
 
      </type>
141
127
      <desc>
142
128
        <p>Returns the value of the application specification key
143
 
          <c>Key</c> for <c>Application</c>. If the application
 
129
          <c><anno>Key</anno></c> for <c><anno>Application</anno></c>. If the application
144
130
          argument is omitted, it defaults to the application of
145
131
          the calling process.</p>
146
132
        <p>If the specified application is not loaded, or
150
136
      </desc>
151
137
    </func>
152
138
    <func>
153
 
      <name>load(AppDescr) -> ok | {error, Reason}</name>
154
 
      <name>load(AppDescr, Distributed) -> ok | {error, Reason}</name>
 
139
      <name name="load" arity="1"/>
 
140
      <name name="load" arity="2"/>
155
141
      <fsummary>Load an application</fsummary>
156
 
      <type>
157
 
        <v>AppDescr = Application | AppSpec</v>
158
 
        <v>&nbsp;Application = atom()</v>
159
 
        <v>&nbsp;AppSpec = {application,Application,AppSpecKeys}</v>
160
 
        <v>&nbsp;&nbsp;AppSpec = [{Key,Val}]</v>
161
 
        <v>&nbsp;&nbsp;&nbsp;Key = atom()</v>
162
 
        <v>&nbsp;&nbsp;&nbsp;Val = term()</v>
163
 
        <v>Distributed = {Application,Nodes} | {Application,Time,Nodes} | default</v>
164
 
        <v>&nbsp;Nodes = [node() | {node(),..,node()}]</v>
165
 
        <v>&nbsp;Time = integer() > 0</v>
166
 
        <v>Reason = term()</v>
167
 
      </type>
 
142
      <type name="application_spec"/>
 
143
      <type name="application_opt"/>
168
144
      <desc>
169
145
        <p>Loads the application specification for an application into
170
146
          the application controller. It will also load the application
171
147
          specifications for any included applications. Note that
172
148
          the function does not load the actual Erlang object code.</p>
173
 
        <p>The application can be given by its name <c>Application</c>.
 
149
        <p>The application can be given by its name <c><anno>Application</anno></c>.
174
150
          In this case the application controller will search the code
175
 
          path for the application resource file <c>Application.app</c>
 
151
          path for the application resource file <c><anno>Application</anno>.app</c>
176
152
          and load the specification it contains.</p>
177
153
        <p>The application specification can also be given directly as a
178
 
          tuple <c>AppSpec</c>. This tuple should have the format and
 
154
          tuple <c><anno>AppSpec</anno></c>. This tuple should have the format and
179
155
          contents as described in <c>app(4)</c>.</p>
180
 
        <p>If <c>Distributed == {Application,[Time,]Nodes}</c>,
 
156
        <p>If <c><anno>Distributed</anno> == {<anno>Application</anno>,[<anno>Time</anno>,]<anno>Nodes</anno>}</c>,
181
157
          the application will be distributed. The argument overrides
182
158
          the value for the application in the Kernel configuration
183
 
          parameter <c>distributed</c>. <c>Application</c> must be
 
159
          parameter <c>distributed</c>. <c><anno>Application</anno></c> must be
184
160
          the name of the application (same as in the first argument).
185
 
          If a node crashes and <c>Time</c> has been specified, then
186
 
          the application controller will wait for <c>Time</c>
 
161
          If a node crashes and <c><anno>Time</anno></c> has been specified, then
 
162
          the application controller will wait for <c><anno>Time</anno></c>
187
163
          milliseconds before attempting to restart the application on
188
 
          another node. If <c>Time</c> is not specified, it will
 
164
          another node. If <c><anno>Time</anno></c> is not specified, it will
189
165
          default to 0 and the application will be restarted
190
166
          immediately.</p>
191
 
        <p><c>Nodes</c> is a list of node names where the application
 
167
        <p><c><anno>Nodes</anno></c> is a list of node names where the application
192
168
          may run, in priority from left to right. Node names can be
193
169
          grouped using tuples to indicate that they have the same
194
170
          priority. Example:</p>
204
180
      </desc>
205
181
    </func>
206
182
    <func>
207
 
      <name>loaded_applications() -> [{Application, Description, Vsn}]</name>
 
183
      <name name="loaded_applications" arity="0"/>
208
184
      <fsummary>Get the currently loaded applications</fsummary>
209
 
      <type>
210
 
        <v>Application = atom()</v>
211
 
        <v>Description = string()</v>
212
 
        <v>Vsn = string()</v>
213
 
      </type>
214
185
      <desc>
215
186
        <p>Returns a list with information about the applications which
216
187
          have been loaded using <c>load/1,2</c>, also included
217
 
          applications. <c>Application</c> is the application name.
218
 
          <c>Description</c> and <c>Vsn</c> are the values of its
 
188
          applications. <c><anno>Application</anno></c> is the application name.
 
189
          <c><anno>Description</anno></c> and <c><anno>Vsn</anno></c> are the values of its
219
190
          <c>description</c> and <c>vsn</c> application specification
220
191
          keys, respectively.</p>
221
192
      </desc>
222
193
    </func>
223
194
    <func>
224
 
      <name>permit(Application, Bool) -> ok | {error, Reason}</name>
 
195
      <name name="permit" arity="2"/>
225
196
      <fsummary>Change an application's permission to run on a node.</fsummary>
226
 
      <type>
227
 
        <v>Application = atom()</v>
228
 
        <v>Bool = bool()</v>
229
 
        <v>Reason = term()</v>
230
 
      </type>
231
197
      <desc>
232
 
        <p>Changes the permission for <c>Application</c> to run at
 
198
        <p>Changes the permission for <c><anno>Application</anno></c> to run at
233
199
          the current node. The application must have been loaded using
234
200
          <c>load/1,2</c> for the function to have effect.</p>
235
201
        <p>If the permission of a loaded, but not started, application
258
224
      </desc>
259
225
    </func>
260
226
    <func>
261
 
      <name>set_env(Application, Par, Val) -> ok</name>
262
 
      <name>set_env(Application, Par, Val, Timeout) -> ok</name>
 
227
      <name name="set_env" arity="3"/>
 
228
      <name name="set_env" arity="4"/>
263
229
      <fsummary>Set the value of a configuration parameter</fsummary>
264
 
      <type>
265
 
        <v>Application = atom()</v>
266
 
        <v>Par = atom()</v>
267
 
        <v>Val = term()</v>
268
 
        <v>Timeout = int() | infinity</v>
269
 
      </type>
270
230
      <desc>
271
 
        <p>Sets the value of the configuration parameter <c>Par</c> for
272
 
          <c>Application</c>.</p>
 
231
        <p>Sets the value of the configuration parameter <c><anno>Par</anno></c> for
 
232
          <c><anno>Application</anno></c>.</p>
273
233
        <p><c>set_env/3</c> uses the standard <c>gen_server</c> timeout
274
 
          value (5000 ms). A <c>Timeout</c> argument can be provided
 
234
          value (5000 ms). A <c><anno>Timeout</anno></c> argument can be provided
275
235
          if another timeout value is useful, for example, in situations
276
236
          where the application controller is heavily loaded.</p>
277
237
        <warning>
285
245
      </desc>
286
246
    </func>
287
247
    <func>
288
 
      <name>start(Application) -> ok | {error, Reason}</name>
289
 
      <name>start(Application, Type) -> ok | {error, Reason}</name>
 
248
      <name name="start" arity="1"/>
 
249
      <name name="start" arity="2"/>
290
250
      <fsummary>Load and start an application</fsummary>
291
 
      <type>
292
 
        <v>Application = atom()</v>
293
 
        <v>Type = permanent | transient | temporary</v>
294
 
        <v>Reason = term()</v>
295
 
      </type>
296
251
      <desc>
297
 
        <p>Starts <c>Application</c>. If it is not loaded,
 
252
        <p>Starts <c><anno>Application</anno></c>. If it is not loaded,
298
253
          the application controller will first load it using
299
254
          <c>load/1</c>. It will make sure any included applications
300
255
          are loaded, but will not start them. That is assumed to be
301
 
          taken care of in the code for <c>Application</c>.</p>
 
256
          taken care of in the code for <c><anno>Application</anno></c>.</p>
302
257
        <p>The application controller checks the value of
303
258
          the application specification key <c>applications</c>, to
304
259
          ensure that all applications that should be started before
310
265
          The application master starts the application by calling
311
266
          the application callback function <c>Module:start/2</c> as
312
267
          defined by the application specification key <c>mod</c>.</p>
313
 
        <p>The <c>Type</c> argument specifies the type of
 
268
        <p>The <c><anno>Type</anno></c> argument specifies the type of
314
269
          the application. If omitted, it defaults to <c>temporary</c>.</p>
315
270
        <list type="bulleted">
316
271
          <item>If a permanent application terminates, all other
331
286
      </desc>
332
287
    </func>
333
288
    <func>
334
 
      <name>start_type() -> StartType | local | undefined</name>
 
289
      <name name="start_type" arity="0"/>
335
290
      <fsummary>Get the start type of an ongoing application startup.</fsummary>
336
 
      <type>
337
 
        <v>StartType = normal | {takeover,Node} | {failover,Node}</v>
338
 
        <v>&nbsp;Node = node()</v>
339
 
      </type>
340
291
      <desc>
341
292
        <p>This function is intended to be called by a process belonging
342
293
          to an application, when the application is being started, to
343
 
          determine the start type which is either <c>StartType</c> or
 
294
          determine the start type which is either <c><anno>StartType</anno></c> or
344
295
          <c>local</c>.</p>
345
 
        <p>See <c>Module:start/2</c> for a description of
346
 
          <c>StartType</c>.</p>
 
296
        <p>See <seealso marker="#start_type"><c>Module:start/2</c></seealso> for a description of
 
297
          <c><anno>StartType</anno></c>.</p>
347
298
        <p><c>local</c> is returned if only parts of the application is
348
299
          being restarted (by a supervisor), or if the function is
349
300
          called outside a startup.</p>
352
303
      </desc>
353
304
    </func>
354
305
    <func>
355
 
      <name>stop(Application) -> ok | {error, Reason}</name>
 
306
      <name name="stop" arity="1"/>
356
307
      <fsummary>Stop an application</fsummary>
357
 
      <type>
358
 
        <v>Application = atom()</v>
359
 
        <v>Reason = term()</v>
360
 
      </type>
361
308
      <desc>
362
 
        <p>Stops <c>Application</c>. The application master calls
 
309
        <p>Stops <c><anno>Application</anno></c>. The application master calls
363
310
          <c>Module:prep_stop/1</c>, if such a function is defined, and
364
311
          then tells the top supervisor of the application to shutdown
365
312
          (see <c>supervisor(3)</c>). This means that the entire
384
331
      </desc>
385
332
    </func>
386
333
    <func>
387
 
      <name>takeover(Application, Type) -> ok | {error, Reason}</name>
 
334
      <name name="takeover" arity="2"/>
388
335
      <fsummary>Take over a distributed application</fsummary>
389
 
      <type>
390
 
        <v>Application = atom()</v>
391
 
        <v>Type = permanent | transient | temporary</v>
392
 
        <v>Reason = term()</v>
393
 
      </type>
394
336
      <desc>
395
337
        <p>Performs a takeover of the distributed application
396
 
          <c>Application</c>, which executes at another node
 
338
          <c><anno>Application</anno></c>, which executes at another node
397
339
          <c>Node</c>. At the current node, the application is
398
340
          restarted by calling
399
341
          <c>Module:start({takeover,Node},StartArgs)</c>. <c>Module</c>
413
355
      </desc>
414
356
    </func>
415
357
    <func>
416
 
      <name>unload(Application) -> ok | {error, Reason}</name>
 
358
      <name name="unload" arity="1"/>
417
359
      <fsummary>Unload an application</fsummary>
418
 
      <type>
419
 
        <v>Application = atom()</v>
420
 
        <v>Reason = term()</v>
421
 
      </type>
422
360
      <desc>
423
 
        <p>Unloads the application specification for <c>Application</c>
 
361
        <p>Unloads the application specification for <c><anno>Application</anno></c>
424
362
          from the application controller. It will also unload
425
363
          the application specifications for any included applications.
426
364
          Note that the function does not purge the actual Erlang
428
366
      </desc>
429
367
    </func>
430
368
    <func>
431
 
      <name>unset_env(Application, Par) -> ok</name>
432
 
      <name>unset_env(Application, Par, Timeout) -> ok</name>
 
369
      <name name="unset_env" arity="2"/>
 
370
      <name name="unset_env" arity="3"/>
433
371
      <fsummary>Unset the value of a configuration parameter</fsummary>
434
 
      <type>
435
 
        <v>Application = atom()</v>
436
 
        <v>Par = atom()</v>
437
 
        <v>Timeout = int() | infinity</v>
438
 
      </type>
439
372
      <desc>
440
 
        <p>Removes the configuration parameter <c>Par</c> and its value
441
 
          for <c>Application</c>.</p>
 
373
        <p>Removes the configuration parameter <c><anno>Par</anno></c> and its value
 
374
          for <c><anno>Application</anno></c>.</p>
442
375
        <p><c>unset_env/2</c> uses the standard <c>gen_server</c>
443
 
          timeout value (5000 ms). A <c>Timeout</c> argument can be
 
376
          timeout value (5000 ms). A <c><anno>Timeout</anno></c> argument can be
444
377
          provided if another timeout value is useful, for example, in
445
378
          situations where the application controller is heavily loaded.</p>
446
379
        <warning>
454
387
      </desc>
455
388
    </func>
456
389
    <func>
457
 
      <name>which_applications() -> [{Application, Description, Vsn}]</name>
458
 
      <name>which_applications(Timeout) -> [{Application, Description, Vsn}]</name>
 
390
      <name name="which_applications" arity="0"/>
 
391
      <name name="which_applications" arity="1"/>
459
392
      <fsummary>Get the currently running applications</fsummary>
460
 
      <type>
461
 
        <v>Application = atom()</v>
462
 
        <v>Description = string()</v>
463
 
        <v>Vsn = string()</v>
464
 
        <v>Timeout = int() | infinity</v>
465
 
      </type>
466
393
      <desc>
467
394
        <p>Returns a list with information about the applications which
468
 
          are currently running. <c>Application</c> is the application
469
 
          name. <c>Description</c> and <c>Vsn</c> are the values of its
 
395
          are currently running. <c><anno>Application</anno></c> is the application
 
396
          name. <c><anno>Description</anno></c> and <c><anno>Vsn</anno></c> are the values of its
470
397
          <c>description</c> and <c>vsn</c> application specification
471
398
          keys, respectively.</p>
472
399
        <p><c>which_applications/0</c> uses the standard
473
 
          <c>gen_server</c> timeout value (5000 ms). A <c>Timeout</c>
 
400
          <c>gen_server</c> timeout value (5000 ms). A <c><anno>Timeout</anno></c>
474
401
          argument can be provided if another timeout value is useful,
475
402
          for example, in situations where the application controller
476
403
          is heavily loaded.</p>
501
428
          structured according to the OTP design principles as a
502
429
          supervision tree, this means starting the top supervisor of
503
430
          the tree.</p>
504
 
        <p><c>StartType</c> defines the type of start:</p>
 
431
        <p><marker id="start_type"/><c>StartType</c> defines the type of start:</p>
505
432
        <list type="bulleted">
506
433
          <item><c>normal</c> if it's a normal startup.</item>
507
434
          <item><c>normal</c> also if the application is distributed and
532
459
      <fsummary>Extended start of an application</fsummary>
533
460
      <type>
534
461
        <v>Phase = atom()</v>
535
 
        <v>StartType = normal | {takeover,Node} | {failover,Node}</v>
536
 
        <v>&nbsp;Node = node()</v>
 
462
        <v>StartType = <seealso marker="#type-start_type">start_type()</seealso></v>
537
463
        <v>PhaseArgs = term()</v>
538
464
        <v>Pid = pid()</v>
539
465
        <v>State = state()</v>