1application(3) Erlang Module Definition application(3)
2
6 application - Generic OTP application functions
7
9 In OTP, application denotes a component implementing some specific
10 functionality, that can be started and stopped as a unit, and that can
11 be reused in other systems. This module interacts with application con‐
12 troller, a process started at every Erlang runtime system. This module
13 contains functions for controlling applications (for example, starting
14 and stopping applications), and functions to access information about
15 applications (for example, configuration parameters).
16 An application is defined by an application specification. The specifi‐
18 cation is normally located in an application resource file named Appli‐
19 cation.app, where Application is the application name. For details
20 about the application specification, see app(4).
21 This module can also be viewed as a behaviour for an application imple‐
23 mented according to the OTP design principles as a supervision tree.
24 The definition of how to start and stop the tree is to be located in an
25 application callback module, exporting a predefined set of functions.
26 For details about applications and behaviours, see OTP Design Princi‐
28 ples.
29
31 start_type() =
32 normal |
33 {takeover, Node :: node()} |
34 {failover, Node :: node()}
35 restart_type() = permanent | transient | temporary
37 tuple_of(T)
39 A tuple where the elements are of type T.
41
43 ensure_all_started(Application) -> {ok, Started} | {error, Reason}
44 ensure_all_started(Application, Type) ->
46 {ok, Started} | {error, Reason}
47 Types:
49 Application = atom()
51 Type = restart_type()
52 Started = [atom()]
53 Reason = term()
54 Equivalent to calling start/1,2 repeatedly on all dependencies
56 that are not yet started for an application that is not yet
57 started.
58 Returns {ok, AppNames}, where AppNames is a list of the applica‐
60 tion names that was actually started by this call. The list
61 might be empty, or not contain all dependencies if the applica‐
62 tion or some of its dependencies are already started.
63 The function reports {error, {AppName,Reason}} for errors, where
65 Reason is any possible reason returned by start/1,2 when start‐
66 ing a specific dependency.
67 If an error occurs, the applications started by the function are
69 stopped to bring the set of running applications back to its
70 initial state.
71 ensure_started(Application) -> ok | {error, Reason}
73 ensure_started(Application, Type) -> ok | {error, Reason}
75 Types:
77 Application = atom()
79 Type = restart_type()
80 Reason = term()
81 Equivalent to start/1,2 except it returns ok for already started
83 applications.
84 get_all_env() -> Env
86 get_all_env(Application) -> Env
88 Types:
90 Application = atom()
92 Env = [{Par :: atom(), Val :: term()}]
93 Returns the configuration parameters and their values for Appli‐
95 cation. If the argument is omitted, it defaults to the applica‐
96 tion of the calling process.
97 If the specified application is not loaded, or if the process
99 executing the call does not belong to any application, the func‐
100 tion returns [].
101 get_all_key() -> [] | {ok, Keys}
103 get_all_key(Application) -> undefined | Keys
105 Types:
107 Application = atom()
109 Keys = {ok, [{Key :: atom(), Val :: term()}, ...]}
110 Returns the application specification keys and their values for
112 Application. If the argument is omitted, it defaults to the
113 application of the calling process.
114 If the specified application is not loaded, the function returns
116 undefined. If the process executing the call does not belong to
117 any application, the function returns [].
118 get_application() -> undefined | {ok, Application}
120 get_application(PidOrModule) -> undefined | {ok, Application}
122 Types:
124 PidOrModule = (Pid :: pid()) | (Module :: module())
126 Application = atom()
127 Returns the name of the application to which the process Pid or
129 the module Module belongs. Providing no argument is the same as
130 calling get_application(self()).
131 If the specified process does not belong to any application, or
133 if the specified process or module does not exist, the function
134 returns undefined.
135 get_env(Par) -> undefined | {ok, Val}
137 get_env(Application, Par) -> undefined | {ok, Val}
139 Types:
141 Application = Par = atom()
143 Val = term()
144 Returns the value of configuration parameter Par for Applica‐
146 tion. If the application argument is omitted, it defaults to the
147 application of the calling process.
148 Returns undefined if any of the following applies:
150 * The specified application is not loaded.
152 * The configuration parameter does not exist.
154 * The process executing the call does not belong to any appli‐
156 cation.
157 get_env(Application, Par, Def) -> Val
159 Types:
161 Application = Par = atom()
163 Def = Val = term()
164 Works like get_env/2 but returns value Def when configuration
166 parameter Par does not exist.
167 get_key(Key) -> undefined | {ok, Val}
169 get_key(Application, Key) -> undefined | {ok, Val}
171 Types:
173 Application = Key = atom()
175 Val = term()
176 Returns the value of the application specification key Key for
178 Application. If the application argument is omitted, it defaults
179 to the application of the calling process.
180 Returns undefined if any of the following applies:
182 * The specified application is not loaded.
184 * The specification key does not exist.
186 * The process executing the call does not belong to any appli‐
188 cation.
189 load(AppDescr) -> ok | {error, Reason}
191 load(AppDescr, Distributed) -> ok | {error, Reason}
193 Types:
195 AppDescr = Application | (AppSpec :: application_spec())
197 Application = atom()
198 Distributed =
199 {Application, Nodes} | {Application, Time, Nodes} |
200 default
201 Nodes = [node() | tuple_of(node())]
202 Time = integer() >= 1
203 Reason = term()
204 application_spec() =
205 {application,
206 Application :: atom(),
207 AppSpecKeys :: [application_opt()]}
208 application_opt() =
209 {description, Description :: string()} |
210 {vsn, Vsn :: string()} |
211 {id, Id :: string()} |
212 {modules, [Module :: module()]} |
213 {registered, Names :: [Name :: atom()]} |
214 {applications, [Application :: atom()]} |
215 {included_applications, [Application :: atom()]} |
216 {env, [{Par :: atom(), Val :: term()}]} |
217 {start_phases,
218 [{Phase :: atom(), PhaseArgs :: term()}] | undefined} |
219 {maxT, MaxT :: timeout()} |
220 {maxP, MaxP :: integer() >= 1 | infinity} |
221 {mod, Start :: {Module :: module(), StartArgs :: term()}}
222 Loads the application specification for an application into the
224 application controller. It also loads the application specifica‐
225 tions for any included applications. Notice that the function
226 does not load the Erlang object code.
227 The application can be specified by its name Application. In
229 this case, the application controller searches the code path for
230 the application resource file Application.app and loads the
231 specification it contains.
232 The application specification can also be specified directly as
234 a tuple AppSpec, having the format and contents as described in
235 app(4).
236 If Distributed == {Application,[Time,]Nodes}, the application
238 becomes distributed. The argument overrides the value for the
239 application in the Kernel configuration parameter distributed.
240 Application must be the application name (same as in the first
241 argument). If a node crashes and Time is specified, the applica‐
242 tion controller waits for Time milliseconds before attempting to
243 restart the application on another node. If Time is not speci‐
244 fied, it defaults to 0 and the application is restarted immedi‐
245 ately.
246 Nodes is a list of node names where the application can run, in
248 priority from left to right. Node names can be grouped using
249 tuples to indicate that they have the same priority.
250 Example:
252 Nodes = [cp1@cave, {cp2@cave, cp3@cave}]
254 This means that the application is preferably to be started at
256 cp1@cave. If cp1@cave is down, the application is to be started
257 at cp2@cave or cp3@cave.
258 If Distributed == default, the value for the application in the
260 Kernel configuration parameter distributed is used.
261 loaded_applications() -> [{Application, Description, Vsn}]
263 Types:
265 Application = atom()
267 Description = Vsn = string()
268 Returns a list with information about the applications, and
270 included applications, which are loaded using load/1,2. Applica‐
271 tion is the application name. Description and Vsn are the values
272 of their description and vsn application specification keys,
273 respectively.
274 set_env(Config) -> ok
276 set_env(Config, Opts) -> ok
278 Types:
280 Config = [{Application, Env}]
282 Application = atom()
283 Env = [{Par :: atom(), Val :: term()}]
284 Opts = [{timeout, timeout()} | {persistent, boolean()}]
285 Sets the configuration Config for multiple applications. It is
287 equivalent to calling set_env/4 on each application individu‐
288 ally, except it is more efficient. The given Config is validated
289 before the configuration is set.
290 set_env/2 uses the standard gen_server time-out value (5000 ms).
292 Option timeout can be specified if another time-out value is
293 useful, for example, in situations where the application con‐
294 troller is heavily loaded.
295 Option persistent can be set to true to guarantee that parame‐
297 ters set with set_env/2 are not overridden by those defined in
298 the application resource file on load. This means that persis‐
299 tent values will stick after the application is loaded and also
300 on application reload.
301 If an application is given more than once or if an application
303 has the same key given more than once, the behaviour is unde‐
304 fined and a warning message will be logged. In future releases,
305 an error will be raised.
306 set_env/1 is equivalent to set_env(Config, []).
308 Warning:
310 Use this function only if you know what you are doing, that is,
311 on your own applications. It is very application-dependent and
312 configuration parameter-dependent when and how often the value
313 is read by the application. Careless use of this function can
314 put the application in a weird, inconsistent, and malfunctioning
315 state.
316 permit(Application, Permission) -> ok | {error, Reason}
319 Types:
321 Application = atom()
323 Permission = boolean()
324 Reason = term()
325 Changes the permission for Application to run at the current
327 node. The application must be loaded using load/1,2 for the
328 function to have effect.
329 If the permission of a loaded, but not started, application is
331 set to false, start returns ok but the application is not
332 started until the permission is set to true.
333 If the permission of a running application is set to false, the
335 application is stopped. If the permission later is set to true,
336 it is restarted.
337 If the application is distributed, setting the permission to
339 false means that the application will be started at, or moved
340 to, another node according to how its distribution is configured
341 (see load/2).
342 The function does not return until the application is started,
344 stopped, or successfully moved to another node. However, in some
345 cases where permission is set to true, the function returns ok
346 even though the application is not started. This is true when an
347 application cannot start because of dependencies to other appli‐
348 cations that are not yet started. When they are started, Appli‐
349 cation is started as well.
350 By default, all applications are loaded with permission true on
352 all nodes. The permission can be configured using the Kernel
353 configuration parameter permissions.
354 set_env(Application, Par, Val) -> ok
356 set_env(Application, Par, Val, Opts) -> ok
358 Types:
360 Application = Par = atom()
362 Val = term()
363 Opts = [{timeout, timeout()} | {persistent, boolean()}]
364 Sets the value of configuration parameter Par for Application.
366 set_env/4 uses the standard gen_server time-out value (5000 ms).
368 Option timeout can be specified if another time-out value is
369 useful, for example, in situations where the application con‐
370 troller is heavily loaded.
371 If set_env/4 is called before the application is loaded, the
373 application environment values specified in file Application.app
374 override the ones previously set. This is also true for applica‐
375 tion reloads.
376 Option persistent can be set to true to guarantee that parame‐
378 ters set with set_env/4 are not overridden by those defined in
379 the application resource file on load. This means that persis‐
380 tent values will stick after the application is loaded and also
381 on application reload.
382 Warning:
384 Use this function only if you know what you are doing, that is,
385 on your own applications. It is very application-dependent and
386 configuration parameter-dependent when and how often the value
387 is read by the application. Careless use of this function can
388 put the application in a weird, inconsistent, and malfunctioning
389 state.
390 start(Application) -> ok | {error, Reason}
393 start(Application, Type) -> ok | {error, Reason}
395 Types:
397 Application = atom()
399 Type = restart_type()
400 Reason = term()
401 Starts Application. If it is not loaded, the application con‐
403 troller first loads it using load/1. It ensures that any
404 included applications are loaded, but does not start them. That
405 is assumed to be taken care of in the code for Application.
406 The application controller checks the value of the application
408 specification key applications, to ensure that all applications
409 needed to be started before this application are running. Other‐
410 wise, {error,{not_started,App}} is returned, where App is the
411 name of the missing application.
412 The application controller then creates an application master
414 for the application. The application master becomes the group
415 leader of all the processes in the application. I/O is forwarded
416 to the previous group leader, though, this is just a way to
417 identify processes that belong to the application. Used for
418 example to find itself from any process, or, reciprocally, to
419 kill them all when it terminates.
420 The application master starts the application by calling the
422 application callback function Module:start/2 as defined by the
423 application specification key mod.
424 Argument Type specifies the type of the application. If omitted,
426 it defaults to temporary.
427 * If a permanent application terminates, all other applica‐
429 tions and the entire Erlang node are also terminated.
430 *
432 * If a transient application terminates with Reason == nor‐
435 mal, this is reported but no other applications are termi‐
436 nated.
437 * If a transient application terminates abnormally, all
439 other applications and the entire Erlang node are also
440 terminated.
441 * If a temporary application terminates, this is reported but
443 no other applications are terminated.
444 Notice that an application can always be stopped explicitly by
446 calling stop/1. Regardless of the type of the application, no
447 other applications are affected.
448 Notice also that the transient type is of little practical use,
450 because when a supervision tree terminates, the reason is set to
451 shutdown, not normal.
452 start_type() -> StartType | undefined | local
454 Types:
456 StartType = start_type()
458 This function is intended to be called by a process belonging to
460 an application, when the application is started, to determine
461 the start type, which is StartType or local.
462 For a description of StartType, see Module:start/2.
464 local is returned if only parts of the application are restarted
466 (by a supervisor), or if the function is called outside a
467 startup.
468 If the process executing the call does not belong to any appli‐
470 cation, the function returns undefined.
471 stop(Application) -> ok | {error, Reason}
473 Types:
475 Application = atom()
477 Reason = term()
478 Stops Application. The application master calls Mod‐
480 ule:prep_stop/1, if such a function is defined, and then tells
481 the top supervisor of the application to shut down (see supervi‐
482 sor(3)). This means that the entire supervision tree, including
483 included applications, is terminated in reversed start order.
484 After the shutdown, the application master calls Module:stop/1.
485 Module is the callback module as defined by the application
486 specification key mod.
487 Last, the application master terminates. Notice that all pro‐
489 cesses with the application master as group leader, that is,
490 processes spawned from a process belonging to the application,
491 are also terminated.
492 When stopped, the application is still loaded.
494 To stop a distributed application, stop/1 must be called on all
496 nodes where it can execute (that is, on all nodes where it has
497 been started). The call to stop/1 on the node where the applica‐
498 tion currently executes stops its execution. The application is
499 not moved between nodes, as stop/1 is called on the node where
500 the application currently executes before stop/1 is called on
501 the other nodes.
502 takeover(Application, Type) -> ok | {error, Reason}
504 Types:
506 Application = atom()
508 Type = restart_type()
509 Reason = term()
510 Takes over the distributed application Application, which exe‐
512 cutes at another node Node. At the current node, the application
513 is restarted by calling Module:start({takeover,Node},StartArgs).
514 Module and StartArgs are retrieved from the loaded application
515 specification. The application at the other node is not stopped
516 until the startup is completed, that is, when Module:start/2 and
517 any calls to Module:start_phase/3 have returned.
518 Thus, two instances of the application run simultaneously during
520 the takeover, so that data can be transferred from the old to
521 the new instance. If this is not an acceptable behavior, parts
522 of the old instance can be shut down when the new instance is
523 started. However, the application cannot be stopped entirely, at
524 least the top supervisor must remain alive.
525 For a description of Type, see start/1,2.
527 unload(Application) -> ok | {error, Reason}
529 Types:
531 Application = atom()
533 Reason = term()
534 Unloads the application specification for Application from the
536 application controller. It also unloads the application specifi‐
537 cations for any included applications. Notice that the function
538 does not purge the Erlang object code.
539 unset_env(Application, Par) -> ok
541 unset_env(Application, Par, Opts) -> ok
543 Types:
545 Application = Par = atom()
547 Opts = [{timeout, timeout()} | {persistent, boolean()}]
548 Removes the configuration parameter Par and its value for Appli‐
550 cation.
551 unset_env/2 uses the standard gen_server time-out value (5000
553 ms). Option timeout can be specified if another time-out value
554 is useful, for example, in situations where the application con‐
555 troller is heavily loaded.
556 unset_env/3 also allows the persistent option to be passed (see
558 set_env/4).
559 Warning:
561 Use this function only if you know what you are doing, that is,
562 on your own applications. It is very application-dependent and
563 configuration parameter-dependent when and how often the value
564 is read by the application. Careless use of this function can
565 put the application in a weird, inconsistent, and malfunctioning
566 state.
567 which_applications() -> [{Application, Description, Vsn}]
570 which_applications(Timeout) -> [{Application, Description, Vsn}]
572 Types:
574 Timeout = timeout()
576 Application = atom()
577 Description = Vsn = string()
578 Returns a list with information about the applications that are
580 currently running. Application is the application name. Descrip‐
581 tion and Vsn are the values of their description and vsn appli‐
582 cation specification keys, respectively.
583 which_applications/0 uses the standard gen_server time-out value
585 (5000 ms). A Timeout argument can be specified if another time-
586 out value is useful, for example, in situations where the appli‐
587 cation controller is heavily loaded.
588
590 The following functions are to be exported from an application callback
591 module.
592
594 Module:start(StartType, StartArgs) -> {ok, Pid} | {ok, Pid, State} |
595 {error, Reason}
596 Types:
598 StartType = start_type()
600 StartArgs = term()
601 Pid = pid()
602 State = term()
603 This function is called whenever an application is started using
605 start/1,2, and is to start the processes of the application. If
606 the application is structured according to the OTP design prin‐
607 ciples as a supervision tree, this means starting the top super‐
608 visor of the tree.
609 StartType defines the type of start:
611 * normal if it is a normal startup.
613 * normal also if the application is distributed and started at
615 the current node because of a failover from another node,
616 and the application specification key start_phases == unde‐
617 fined.
618 * {takeover,Node} if the application is distributed and
620 started at the current node because of a takeover from Node,
621 either because takeover/2 has been called or because the
622 current node has higher priority than Node.
623 * {failover,Node} if the application is distributed and
625 started at the current node because of a failover from Node,
626 and the application specification key start_phases /= unde‐
627 fined.
628 StartArgs is the StartArgs argument defined by the application
630 specification key mod.
631 The function is to return {ok,Pid} or {ok,Pid,State}, where Pid
633 is the pid of the top supervisor and State is any term. If omit‐
634 ted, State defaults to []. If the application is stopped later,
635 State is passed to Module:prep_stop/1.
636 Module:start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason}
638 Types:
640 Phase = atom()
642 StartType = start_type()
643 PhaseArgs = term()
644 Pid = pid()
645 State = state()
646 Starts an application with included applications, when synchro‐
648 nization is needed between processes in the different applica‐
649 tions during startup.
650 The start phases are defined by the application specification
652 key start_phases == [{Phase,PhaseArgs}]. For included applica‐
653 tions, the set of phases must be a subset of the set of phases
654 defined for the including application.
655 The function is called for each start phase (as defined for the
657 primary application) for the primary application and all
658 included applications, for which the start phase is defined.
659 For a description of StartType, see Module:start/2.
661 Module:prep_stop(State) -> NewState
663 Types:
665 State = NewState = term()
667 This function is called when an application is about to be
669 stopped, before shutting down the processes of the application.
670 State is the state returned from Module:start/2, or [] if no
672 state was returned. NewState is any term and is passed to Mod‐
673 ule:stop/1.
674 The function is optional. If it is not defined, the processes
676 are terminated and then Module:stop(State) is called.
677 Module:stop(State)
679 Types:
681 State = term()
683 This function is called whenever an application has stopped. It
685 is intended to be the opposite of Module:start/2 and is to do
686 any necessary cleaning up. The return value is ignored.
687 State is the return value of Module:prep_stop/1, if such a func‐
689 tion exists. Otherwise State is taken from the return value of
690 Module:start/2.
691 Module:config_change(Changed, New, Removed) -> ok
693 Types:
695 Changed = [{Par,Val}]
697 New = [{Par,Val}]
698 Removed = [Par]
699 Par = atom()
700 Val = term()
701 This function is called by an application after a code replace‐
703 ment, if the configuration parameters have changed.
704 Changed is a list of parameter-value tuples including all con‐
706 figuration parameters with changed values.
707 New is a list of parameter-value tuples including all added con‐
709 figuration parameters.
710 Removed is a list of all removed parameters.
712
714 OTP Design Principles, kernel(6), app(4)
715Ericsson AB kernel 7.3 application(3)