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(Applications) ->
44 {ok, Started} | {error, Reason}
45 ensure_all_started(Applications, Type) ->
47 {ok, Started} | {error, AppReason}
48 ensure_all_started(Applications, Type, Mode) ->
50 {ok, Started} | {error, AppReason}
51 Types:
53 Applications = atom() | [atom()]
55 Type = restart_type()
56 Mode = serial | concurrent
57 Started = [atom()]
58 AppReason = {atom(), term()}
59 Applications is either an an atom() or a list of atom() repre‐
61 senting multiple applications.
62 This function is equivalent to calling start/1,2 repeatedly on
64 all dependencies that are not yet started of each application.
65 Optional dependencies will also be loaded and started if they
66 are available.
67 The Mode argument controls if the applications should be started
69 in serial mode (one at a time) or concurrent mode. In concurrent
70 mode, a dependency graph is built and the leaves of the graph
71 are started concurrently and recursively. In both modes, no as‐
72 sertion can be made about the order the applications are
73 started. If not supplied, it defaults to serial.
74 Returns {ok, AppNames} for a successful start or for an already
76 started application (which is, however, omitted from the App‐
77 Names list).
78 The function reports {error, {AppName,Reason}} for errors, where
80 Reason is any possible reason returned by start/1,2 when start‐
81 ing a specific dependency.
82 If an error occurs, the applications started by the function are
84 stopped to bring the set of running applications back to its
85 initial state.
86 ensure_started(Application) -> ok | {error, Reason}
88 ensure_started(Application, Type) -> ok | {error, Reason}
90 Types:
92 Application = atom()
94 Type = restart_type()
95 Reason = term()
96 Equivalent to start/1,2 except it returns ok for already started
98 applications.
99 get_all_env() -> Env
101 get_all_env(Application) -> Env
103 Types:
105 Application = atom()
107 Env = [{Par :: atom(), Val :: term()}]
108 Returns the configuration parameters and their values for Appli‐
110 cation. If the argument is omitted, it defaults to the applica‐
111 tion of the calling process.
112 If the specified application is not loaded, or if the process
114 executing the call does not belong to any application, the func‐
115 tion returns [].
116 get_all_key() -> [] | {ok, Keys}
118 get_all_key(Application) -> undefined | Keys
120 Types:
122 Application = atom()
124 Keys = {ok, [{Key :: atom(), Val :: term()}, ...]}
125 Returns the application specification keys and their values for
127 Application. If the argument is omitted, it defaults to the ap‐
128 plication of the calling process.
129 If the specified application is not loaded, the function returns
131 undefined. If the process executing the call does not belong to
132 any application, the function returns [].
133 get_application() -> undefined | {ok, Application}
135 get_application(PidOrModule) -> undefined | {ok, Application}
137 Types:
139 PidOrModule = (Pid :: pid()) | (Module :: module())
141 Application = atom()
142 Returns the name of the application to which the process Pid or
144 the module Module belongs. Providing no argument is the same as
145 calling get_application(self()).
146 If the specified process does not belong to any application, or
148 if the specified process or module does not exist, the function
149 returns undefined.
150 get_env(Par) -> undefined | {ok, Val}
152 get_env(Application, Par) -> undefined | {ok, Val}
154 Types:
156 Application = Par = atom()
158 Val = term()
159 Returns the value of configuration parameter Par for Applica‐
161 tion. If the application argument is omitted, it defaults to the
162 application of the calling process.
163 Returns undefined if any of the following applies:
165 * The specified application is not loaded.
167 * The configuration parameter does not exist.
169 * The process executing the call does not belong to any appli‐
171 cation.
172 get_env(Application, Par, Def) -> Val
174 Types:
176 Application = Par = atom()
178 Def = Val = term()
179 Works like get_env/2 but returns value Def when configuration
181 parameter Par does not exist.
182 get_key(Key) -> undefined | {ok, Val}
184 get_key(Application, Key) -> undefined | {ok, Val}
186 Types:
188 Application = Key = atom()
190 Val = term()
191 Returns the value of the application specification key Key for
193 Application. If the application argument is omitted, it defaults
194 to the application of the calling process.
195 Returns undefined if any of the following applies:
197 * The specified application is not loaded.
199 * The specification key does not exist.
201 * The process executing the call does not belong to any appli‐
203 cation.
204 get_supervisor(Application) -> undefined | {ok, Pid}
206 Types:
208 Pid = pid()
210 Application = atom()
211 Returns the Pid of the supervisor running at the root of Appli‐
213 cation.
214 If the specified application does not exist or does not define a
216 callback module, the function returns undefined.
217 load(AppDescr) -> ok | {error, Reason}
219 load(AppDescr, Distributed) -> ok | {error, Reason}
221 Types:
223 AppDescr = Application | (AppSpec :: application_spec())
225 Application = atom()
226 Distributed =
227 {Application, Nodes} | {Application, Time, Nodes} | de‐
228 fault
229 Nodes = [node() | tuple_of(node())]
230 Time = integer() >= 1
231 Reason = term()
232 application_spec() =
233 {application,
234 Application :: atom(),
235 AppSpecKeys :: [application_opt()]}
236 application_opt() =
237 {description, Description :: string()} |
238 {vsn, Vsn :: string()} |
239 {id, Id :: string()} |
240 {modules, [Module :: module()]} |
241 {registered, Names :: [Name :: atom()]} |
242 {applications, [Application :: atom()]} |
243 {included_applications, [Application :: atom()]} |
244 {env, [{Par :: atom(), Val :: term()}]} |
245 {start_phases,
246 [{Phase :: atom(), PhaseArgs :: term()}] | undefined} |
247 {maxT, MaxT :: timeout()} |
248 {maxP, MaxP :: integer() >= 1 | infinity} |
249 {mod, Start :: {Module :: module(), StartArgs :: term()}}
250 Loads the application specification for an application into the
252 application controller. It also loads the application specifica‐
253 tions for any included applications. Notice that the function
254 does not load the Erlang object code.
255 The application can be specified by its name Application. In
257 this case, the application controller searches the code path for
258 the application resource file Application.app and loads the
259 specification it contains.
260 The application specification can also be specified directly as
262 a tuple AppSpec, having the format and contents as described in
263 app(4).
264 If Distributed == {Application,[Time,]Nodes}, the application
266 becomes distributed. The argument overrides the value for the
267 application in the Kernel configuration parameter distributed.
268 Application must be the application name (same as in the first
269 argument). If a node crashes and Time is specified, the applica‐
270 tion controller waits for Time milliseconds before attempting to
271 restart the application on another node. If Time is not speci‐
272 fied, it defaults to 0 and the application is restarted immedi‐
273 ately.
274 Nodes is a list of node names where the application can run, in
276 priority from left to right. Node names can be grouped using tu‐
277 ples to indicate that they have the same priority.
278 Example:
280 Nodes = [cp1@cave, {cp2@cave, cp3@cave}]
282 This means that the application is preferably to be started at
284 cp1@cave. If cp1@cave is down, the application is to be started
285 at cp2@cave or cp3@cave.
286 If Distributed == default, the value for the application in the
288 Kernel configuration parameter distributed is used.
289 loaded_applications() -> [{Application, Description, Vsn}]
291 Types:
293 Application = atom()
295 Description = Vsn = string()
296 Returns a list with information about the applications, and in‐
298 cluded applications, which are loaded using load/1,2. Applica‐
299 tion is the application name. Description and Vsn are the values
300 of their description and vsn application specification keys, re‐
301 spectively.
302 set_env(Config) -> ok
304 set_env(Config, Opts) -> ok
306 Types:
308 Config = [{Application, Env}]
310 Application = atom()
311 Env = [{Par :: atom(), Val :: term()}]
312 Opts = [{timeout, timeout()} | {persistent, boolean()}]
313 Sets the configuration Config for multiple applications. It is
315 equivalent to calling set_env/4 on each application individu‐
316 ally, except it is more efficient. The given Config is validated
317 before the configuration is set.
318 set_env/2 uses the standard gen_server time-out value (5000 ms).
320 Option timeout can be specified if another time-out value is
321 useful, for example, in situations where the application con‐
322 troller is heavily loaded.
323 Option persistent can be set to true to guarantee that parame‐
325 ters set with set_env/2 are not overridden by those defined in
326 the application resource file on load. This means that persis‐
327 tent values will stick after the application is loaded and also
328 on application reload.
329 If an application is given more than once or if an application
331 has the same key given more than once, the behaviour is unde‐
332 fined and a warning message will be logged. In future releases,
333 an error will be raised.
334 set_env/1 is equivalent to set_env(Config, []).
336 Warning:
338 Use this function only if you know what you are doing, that is,
339 on your own applications. It is very application-dependent and
340 configuration parameter-dependent when and how often the value
341 is read by the application. Careless use of this function can
342 put the application in a weird, inconsistent, and malfunctioning
343 state.
344 permit(Application, Permission) -> ok | {error, Reason}
347 Types:
349 Application = atom()
351 Permission = boolean()
352 Reason = term()
353 Changes the permission for Application to run at the current
355 node. The application must be loaded using load/1,2 for the
356 function to have effect.
357 If the permission of a loaded, but not started, application is
359 set to false, start returns ok but the application is not
360 started until the permission is set to true.
361 If the permission of a running application is set to false, the
363 application is stopped. If the permission later is set to true,
364 it is restarted.
365 If the application is distributed, setting the permission to
367 false means that the application will be started at, or moved
368 to, another node according to how its distribution is configured
369 (see load/2).
370 The function does not return until the application is started,
372 stopped, or successfully moved to another node. However, in some
373 cases where permission is set to true, the function returns ok
374 even though the application is not started. This is true when an
375 application cannot start because of dependencies to other appli‐
376 cations that are not yet started. When they are started, Appli‐
377 cation is started as well.
378 By default, all applications are loaded with permission true on
380 all nodes. The permission can be configured using the Kernel
381 configuration parameter permissions.
382 set_env(Application, Par, Val) -> ok
384 set_env(Application, Par, Val, Opts) -> ok
386 Types:
388 Application = Par = atom()
390 Val = term()
391 Opts = [{timeout, timeout()} | {persistent, boolean()}]
392 Sets the value of configuration parameter Par for Application.
394 set_env/4 uses the standard gen_server time-out value (5000 ms).
396 Option timeout can be specified if another time-out value is
397 useful, for example, in situations where the application con‐
398 troller is heavily loaded.
399 If set_env/4 is called before the application is loaded, the ap‐
401 plication environment values specified in file Application.app
402 override the ones previously set. This is also true for applica‐
403 tion reloads.
404 Option persistent can be set to true to guarantee that parame‐
406 ters set with set_env/4 are not overridden by those defined in
407 the application resource file on load. This means that persis‐
408 tent values will stick after the application is loaded and also
409 on application reload.
410 Warning:
412 Use this function only if you know what you are doing, that is,
413 on your own applications. It is very application-dependent and
414 configuration parameter-dependent when and how often the value
415 is read by the application. Careless use of this function can
416 put the application in a weird, inconsistent, and malfunctioning
417 state.
418 start(Application) -> ok | {error, Reason}
421 start(Application, Type) -> ok | {error, Reason}
423 Types:
425 Application = atom()
427 Type = restart_type()
428 Reason = term()
429 Starts Application. If it is not loaded, the application con‐
431 troller first loads it using load/1. It ensures that any in‐
432 cluded applications are loaded, but does not start them. That is
433 assumed to be taken care of in the code for Application.
434 The application controller checks the value of the application
436 specification key applications, to ensure that all applications
437 needed to be started before this application are running. If an
438 application is missing and the application is not marked as op‐
439 tional, {error,{not_started,App}} is returned, where App is the
440 name of the missing application. Note this function makes no at‐
441 tempt to start any of the applications listed in applications,
442 not even optional ones. See ensure_all_started/1,2 for recur‐
443 sively starting the current application and its dependencies.
444 Once validated, the application controller then creates an ap‐
446 plication master for the application. The application master be‐
447 comes the group leader of all the processes in the application.
448 I/O is forwarded to the previous group leader, though, this is
449 just a way to identify processes that belong to the application.
450 Used for example to find itself from any process, or, recipro‐
451 cally, to kill them all when it terminates.
452 The application master starts the application by calling the ap‐
454 plication callback function Module:start/2 as defined by the ap‐
455 plication specification key mod.
456 Argument Type specifies the type of the application. If omitted,
458 it defaults to temporary.
459 * If a permanent application terminates, all other applica‐
461 tions and the entire Erlang node are also terminated.
462 * If a transient application terminates:
464 * with Reason == normal, this is reported but no other ap‐
466 plications are terminated.
467 * abnormally, all other applications and the entire Erlang
469 node are also terminated.
470 * If a temporary application terminates, this is reported but
472 no other applications are terminated.
473 Notice that an application can always be stopped explicitly by
475 calling stop/1. Regardless of the type of the application, no
476 other applications are affected.
477 Notice also that the transient type is of little practical use,
479 because when a supervision tree terminates, the reason is set to
480 shutdown, not normal.
481 start_type() -> StartType | undefined | local
483 Types:
485 StartType = start_type()
487 This function is intended to be called by a process belonging to
489 an application, when the application is started, to determine
490 the start type, which is StartType or local.
491 For a description of StartType, see Module:start/2.
493 local is returned if only parts of the application are restarted
495 (by a supervisor), or if the function is called outside a
496 startup.
497 If the process executing the call does not belong to any appli‐
499 cation, the function returns undefined.
500 stop(Application) -> ok | {error, Reason}
502 Types:
504 Application = atom()
506 Reason = term()
507 Stops Application. The application master calls Mod‐
509 ule:prep_stop/1, if such a function is defined, and then tells
510 the top supervisor of the application to shut down (see supervi‐
511 sor(3)). This means that the entire supervision tree, including
512 included applications, is terminated in reversed start order.
513 After the shutdown, the application master calls Module:stop/1.
514 Module is the callback module as defined by the application
515 specification key mod.
516 Last, the application master terminates. Notice that all pro‐
518 cesses with the application master as group leader, that is,
519 processes spawned from a process belonging to the application,
520 are also terminated.
521 When stopped, the application is still loaded.
523 To stop a distributed application, stop/1 must be called on all
525 nodes where it can execute (that is, on all nodes where it has
526 been started). The call to stop/1 on the node where the applica‐
527 tion currently executes stops its execution. The application is
528 not moved between nodes, as stop/1 is called on the node where
529 the application currently executes before stop/1 is called on
530 the other nodes.
531 takeover(Application, Type) -> ok | {error, Reason}
533 Types:
535 Application = atom()
537 Type = restart_type()
538 Reason = term()
539 Takes over the distributed application Application, which exe‐
541 cutes at another node Node. At the current node, the application
542 is restarted by calling Module:start({takeover,Node},StartArgs).
543 Module and StartArgs are retrieved from the loaded application
544 specification. The application at the other node is not stopped
545 until the startup is completed, that is, when Module:start/2 and
546 any calls to Module:start_phase/3 have returned.
547 Thus, two instances of the application run simultaneously during
549 the takeover, so that data can be transferred from the old to
550 the new instance. If this is not an acceptable behavior, parts
551 of the old instance can be shut down when the new instance is
552 started. However, the application cannot be stopped entirely, at
553 least the top supervisor must remain alive.
554 For a description of Type, see start/1,2.
556 unload(Application) -> ok | {error, Reason}
558 Types:
560 Application = atom()
562 Reason = term()
563 Unloads the application specification for Application from the
565 application controller. It also unloads the application specifi‐
566 cations for any included applications. Notice that the function
567 does not purge the Erlang object code.
568 unset_env(Application, Par) -> ok
570 unset_env(Application, Par, Opts) -> ok
572 Types:
574 Application = Par = atom()
576 Opts = [{timeout, timeout()} | {persistent, boolean()}]
577 Removes the configuration parameter Par and its value for Appli‐
579 cation.
580 unset_env/2 uses the standard gen_server time-out value (5000
582 ms). Option timeout can be specified if another time-out value
583 is useful, for example, in situations where the application con‐
584 troller is heavily loaded.
585 unset_env/3 also allows the persistent option to be passed (see
587 set_env/4).
588 Warning:
590 Use this function only if you know what you are doing, that is,
591 on your own applications. It is very application-dependent and
592 configuration parameter-dependent when and how often the value
593 is read by the application. Careless use of this function can
594 put the application in a weird, inconsistent, and malfunctioning
595 state.
596 which_applications() -> [{Application, Description, Vsn}]
599 which_applications(Timeout) -> [{Application, Description, Vsn}]
601 Types:
603 Timeout = timeout()
605 Application = atom()
606 Description = Vsn = string()
607 Returns a list with information about the applications that are
609 currently running. Application is the application name. Descrip‐
610 tion and Vsn are the values of their description and vsn appli‐
611 cation specification keys, respectively.
612 which_applications/0 uses the standard gen_server time-out value
614 (5000 ms). A Timeout argument can be specified if another time-
615 out value is useful, for example, in situations where the appli‐
616 cation controller is heavily loaded.
617
619 The following functions are to be exported from an application callback
620 module.
621
623 Module:start(StartType, StartArgs) -> {ok, Pid} | {ok, Pid, State} |
624 {error, Reason}
625 Types:
627 StartType = start_type()
629 StartArgs = term()
630 Pid = pid()
631 State = term()
632 This function is called whenever an application is started using
634 start/1,2, and is to start the processes of the application. If
635 the application is structured according to the OTP design prin‐
636 ciples as a supervision tree, this means starting the top super‐
637 visor of the tree.
638 StartType defines the type of start:
640 * normal if it is a normal startup.
642 * normal also if the application is distributed and started at
644 the current node because of a failover from another node,
645 and the application specification key start_phases == unde‐
646 fined.
647 * {takeover,Node} if the application is distributed and
649 started at the current node because of a takeover from Node,
650 either because takeover/2 has been called or because the
651 current node has higher priority than Node.
652 * {failover,Node} if the application is distributed and
654 started at the current node because of a failover from Node,
655 and the application specification key start_phases /= unde‐
656 fined.
657 StartArgs is the StartArgs argument defined by the application
659 specification key mod.
660 The function is to return {ok,Pid} or {ok,Pid,State}, where Pid
662 is the pid of the top supervisor and State is any term. If omit‐
663 ted, State defaults to []. If the application is stopped later,
664 State is passed to Module:prep_stop/1.
665 Module:start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason}
667 Types:
669 Phase = atom()
671 StartType = start_type()
672 PhaseArgs = term()
673 Pid = pid()
674 State = state()
675 Starts an application with included applications, when synchro‐
677 nization is needed between processes in the different applica‐
678 tions during startup.
679 The start phases are defined by the application specification
681 key start_phases == [{Phase,PhaseArgs}]. For included applica‐
682 tions, the set of phases must be a subset of the set of phases
683 defined for the including application.
684 The function is called for each start phase (as defined for the
686 primary application) for the primary application and all in‐
687 cluded applications, for which the start phase is defined.
688 For a description of StartType, see Module:start/2.
690 Module:prep_stop(State) -> NewState
692 Types:
694 State = NewState = term()
696 This function is called when an application is about to be
698 stopped, before shutting down the processes of the application.
699 State is the state returned from Module:start/2, or [] if no
701 state was returned. NewState is any term and is passed to Mod‐
702 ule:stop/1.
703 The function is optional. If it is not defined, the processes
705 are terminated and then Module:stop(State) is called.
706 Module:stop(State)
708 Types:
710 State = term()
712 This function is called whenever an application has stopped. It
714 is intended to be the opposite of Module:start/2 and is to do
715 any necessary cleaning up. The return value is ignored.
716 State is the return value of Module:prep_stop/1, if such a func‐
718 tion exists. Otherwise State is taken from the return value of
719 Module:start/2.
720 Module:config_change(Changed, New, Removed) -> ok
722 Types:
724 Changed = [{Par,Val}]
726 New = [{Par,Val}]
727 Removed = [Par]
728 Par = atom()
729 Val = term()
730 This function is called by an application after a code replace‐
732 ment, if the configuration parameters have changed.
733 Changed is a list of parameter-value tuples including all con‐
735 figuration parameters with changed values.
736 New is a list of parameter-value tuples including all added con‐
738 figuration parameters.
739 Removed is a list of all removed parameters.
741
743 OTP Design Principles, kernel(6), app(4)
744Ericsson AB kernel 9.1 application(3)