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.
57 Returns {ok, AppNames} for a successful start or for an already
59 started application (which is, however, omitted from the App‐
60 Names list).
61 The function reports {error, {AppName,Reason}} for errors, where
63 Reason is any possible reason returned by start/1,2 when start‐
64 ing a specific dependency.
65 If an error occurs, the applications started by the function are
67 stopped to bring the set of running applications back to its
68 initial state.
69 ensure_started(Application) -> ok | {error, Reason}
71 ensure_started(Application, Type) -> ok | {error, Reason}
73 Types:
75 Application = atom()
77 Type = restart_type()
78 Reason = term()
79 Equivalent to start/1,2 except it returns ok for already started
81 applications.
82 get_all_env() -> Env
84 get_all_env(Application) -> Env
86 Types:
88 Application = atom()
90 Env = [{Par :: atom(), Val :: term()}]
91 Returns the configuration parameters and their values for Appli‐
93 cation. If the argument is omitted, it defaults to the applica‐
94 tion of the calling process.
95 If the specified application is not loaded, or if the process
97 executing the call does not belong to any application, the func‐
98 tion returns [].
99 get_all_key() -> [] | {ok, Keys}
101 get_all_key(Application) -> undefined | Keys
103 Types:
105 Application = atom()
107 Keys = {ok, [{Key :: atom(), Val :: term()}, ...]}
108 Returns the application specification keys and their values for
110 Application. If the argument is omitted, it defaults to the
111 application of the calling process.
112 If the specified application is not loaded, the function returns
114 undefined. If the process executing the call does not belong to
115 any application, the function returns [].
116 get_application() -> undefined | {ok, Application}
118 get_application(PidOrModule) -> undefined | {ok, Application}
120 Types:
122 PidOrModule = (Pid :: pid()) | (Module :: module())
124 Application = atom()
125 Returns the name of the application to which the process Pid or
127 the module Module belongs. Providing no argument is the same as
128 calling get_application(self()).
129 If the specified process does not belong to any application, or
131 if the specified process or module does not exist, the function
132 returns undefined.
133 get_env(Par) -> undefined | {ok, Val}
135 get_env(Application, Par) -> undefined | {ok, Val}
137 Types:
139 Application = Par = atom()
141 Val = term()
142 Returns the value of configuration parameter Par for Applica‐
144 tion. If the application argument is omitted, it defaults to the
145 application of the calling process.
146 Returns undefined if any of the following applies:
148 * The specified application is not loaded.
150 * The configuration parameter does not exist.
152 * The process executing the call does not belong to any appli‐
154 cation.
155 get_env(Application, Par, Def) -> Val
157 Types:
159 Application = Par = atom()
161 Def = Val = term()
162 Works like get_env/2 but returns value Def when configuration
164 parameter Par does not exist.
165 get_key(Key) -> undefined | {ok, Val}
167 get_key(Application, Key) -> undefined | {ok, Val}
169 Types:
171 Application = Key = atom()
173 Val = term()
174 Returns the value of the application specification key Key for
176 Application. If the application argument is omitted, it defaults
177 to the application of the calling process.
178 Returns undefined if any of the following applies:
180 * The specified application is not loaded.
182 * The specification key does not exist.
184 * The process executing the call does not belong to any appli‐
186 cation.
187 load(AppDescr) -> ok | {error, Reason}
189 load(AppDescr, Distributed) -> ok | {error, Reason}
191 Types:
193 AppDescr = Application | (AppSpec :: application_spec())
195 Application = atom()
196 Distributed =
197 {Application, Nodes} | {Application, Time, Nodes} |
198 default
199 Nodes = [node() | tuple_of(node())]
200 Time = integer() >= 1
201 Reason = term()
202 application_spec() =
203 {application,
204 Application :: atom(),
205 AppSpecKeys :: [application_opt()]}
206 application_opt() =
207 {description, Description :: string()} |
208 {vsn, Vsn :: string()} |
209 {id, Id :: string()} |
210 {modules, [Module :: module()]} |
211 {registered, Names :: [Name :: atom()]} |
212 {applications, [Application :: atom()]} |
213 {included_applications, [Application :: atom()]} |
214 {env, [{Par :: atom(), Val :: term()}]} |
215 {start_phases,
216 [{Phase :: atom(), PhaseArgs :: term()}] | undefined} |
217 {maxT, MaxT :: timeout()} |
218 {maxP, MaxP :: integer() >= 1 | infinity} |
219 {mod, Start :: {Module :: module(), StartArgs :: term()}}
220 Loads the application specification for an application into the
222 application controller. It also loads the application specifica‐
223 tions for any included applications. Notice that the function
224 does not load the Erlang object code.
225 The application can be specified by its name Application. In
227 this case, the application controller searches the code path for
228 the application resource file Application.app and loads the
229 specification it contains.
230 The application specification can also be specified directly as
232 a tuple AppSpec, having the format and contents as described in
233 app(4).
234 If Distributed == {Application,[Time,]Nodes}, the application
236 becomes distributed. The argument overrides the value for the
237 application in the Kernel configuration parameter distributed.
238 Application must be the application name (same as in the first
239 argument). If a node crashes and Time is specified, the applica‐
240 tion controller waits for Time milliseconds before attempting to
241 restart the application on another node. If Time is not speci‐
242 fied, it defaults to 0 and the application is restarted immedi‐
243 ately.
244 Nodes is a list of node names where the application can run, in
246 priority from left to right. Node names can be grouped using
247 tuples to indicate that they have the same priority.
248 Example:
250 Nodes = [cp1@cave, {cp2@cave, cp3@cave}]
252 This means that the application is preferably to be started at
254 cp1@cave. If cp1@cave is down, the application is to be started
255 at cp2@cave or cp3@cave.
256 If Distributed == default, the value for the application in the
258 Kernel configuration parameter distributed is used.
259 loaded_applications() -> [{Application, Description, Vsn}]
261 Types:
263 Application = atom()
265 Description = Vsn = string()
266 Returns a list with information about the applications, and
268 included applications, which are loaded using load/1,2. Applica‐
269 tion is the application name. Description and Vsn are the values
270 of their description and vsn application specification keys,
271 respectively.
272 permit(Application, Permission) -> ok | {error, Reason}
274 Types:
276 Application = atom()
278 Permission = boolean()
279 Reason = term()
280 Changes the permission for Application to run at the current
282 node. The application must be loaded using load/1,2 for the
283 function to have effect.
284 If the permission of a loaded, but not started, application is
286 set to false, start returns ok but the application is not
287 started until the permission is set to true.
288 If the permission of a running application is set to false, the
290 application is stopped. If the permission later is set to true,
291 it is restarted.
292 If the application is distributed, setting the permission to
294 false means that the application will be started at, or moved
295 to, another node according to how its distribution is configured
296 (see load/2).
297 The function does not return until the application is started,
299 stopped, or successfully moved to another node. However, in some
300 cases where permission is set to true, the function returns ok
301 even though the application is not started. This is true when an
302 application cannot start because of dependencies to other appli‐
303 cations that are not yet started. When they are started, Appli‐
304 cation is started as well.
305 By default, all applications are loaded with permission true on
307 all nodes. The permission can be configured using the Kernel
308 configuration parameter permissions.
309 set_env(Application, Par, Val) -> ok
311 set_env(Application, Par, Val, Opts) -> ok
313 Types:
315 Application = Par = atom()
317 Val = term()
318 Opts = [{timeout, timeout()} | {persistent, boolean()}]
319 Sets the value of configuration parameter Par for Application.
321 set_env/4 uses the standard gen_server time-out value (5000 ms).
323 Option timeout can be specified if another time-out value is
324 useful, for example, in situations where the application con‐
325 troller is heavily loaded.
326 If set_env/4 is called before the application is loaded, the
328 application environment values specified in file Application.app
329 override the ones previously set. This is also true for applica‐
330 tion reloads.
331 Option persistent can be set to true to guarantee that parame‐
333 ters set with set_env/4 are not overridden by those defined in
334 the application resource file on load. This means that persis‐
335 tent values will stick after the application is loaded and also
336 on application reload.
337 Warning:
339 Use this function only if you know what you are doing, that is,
340 on your own applications. It is very application-dependent and
341 configuration parameter-dependent when and how often the value
342 is read by the application. Careless use of this function can
343 put the application in a weird, inconsistent, and malfunctioning
344 state.
345 start(Application) -> ok | {error, Reason}
348 start(Application, Type) -> ok | {error, Reason}
350 Types:
352 Application = atom()
354 Type = restart_type()
355 Reason = term()
356 Starts Application. If it is not loaded, the application con‐
358 troller first loads it using load/1. It ensures that any
359 included applications are loaded, but does not start them. That
360 is assumed to be taken care of in the code for Application.
361 The application controller checks the value of the application
363 specification key applications, to ensure that all applications
364 needed to be started before this application are running. Other‐
365 wise, {error,{not_started,App}} is returned, where App is the
366 name of the missing application.
367 The application controller then creates an application master
369 for the application. The application master is the group leader
370 of all the processes in the application. The application master
371 starts the application by calling the application callback func‐
372 tion Module:start/2 as defined by the application specification
373 key mod.
374 Argument Type specifies the type of the application. If omitted,
376 it defaults to temporary.
377 * If a permanent application terminates, all other applica‐
379 tions and the entire Erlang node are also terminated.
380 *
382 * If a transient application terminates with Reason == nor‐
385 mal, this is reported but no other applications are termi‐
386 nated.
387 * If a transient application terminates abnormally, all
389 other applications and the entire Erlang node are also
390 terminated.
391 * If a temporary application terminates, this is reported but
393 no other applications are terminated.
394 Notice that an application can always be stopped explicitly by
396 calling stop/1. Regardless of the type of the application, no
397 other applications are affected.
398 Notice also that the transient type is of little practical use,
400 because when a supervision tree terminates, the reason is set to
401 shutdown, not normal.
402 start_type() -> StartType | undefined | local
404 Types:
406 StartType = start_type()
408 This function is intended to be called by a process belonging to
410 an application, when the application is started, to determine
411 the start type, which is StartType or local.
412 For a description of StartType, see Module:start/2.
414 local is returned if only parts of the application are restarted
416 (by a supervisor), or if the function is called outside a
417 startup.
418 If the process executing the call does not belong to any appli‐
420 cation, the function returns undefined.
421 stop(Application) -> ok | {error, Reason}
423 Types:
425 Application = atom()
427 Reason = term()
428 Stops Application. The application master calls Mod‐
430 ule:prep_stop/1, if such a function is defined, and then tells
431 the top supervisor of the application to shut down (see supervi‐
432 sor(3)). This means that the entire supervision tree, including
433 included applications, is terminated in reversed start order.
434 After the shutdown, the application master calls Module:stop/1.
435 Module is the callback module as defined by the application
436 specification key mod.
437 Last, the application master terminates. Notice that all pro‐
439 cesses with the application master as group leader, that is,
440 processes spawned from a process belonging to the application,
441 are also terminated.
442 When stopped, the application is still loaded.
444 To stop a distributed application, stop/1 must be called on all
446 nodes where it can execute (that is, on all nodes where it has
447 been started). The call to stop/1 on the node where the applica‐
448 tion currently executes stops its execution. The application is
449 not moved between nodes, as stop/1 is called on the node where
450 the application currently executes before stop/1 is called on
451 the other nodes.
452 takeover(Application, Type) -> ok | {error, Reason}
454 Types:
456 Application = atom()
458 Type = restart_type()
459 Reason = term()
460 Takes over the distributed application Application, which exe‐
462 cutes at another node Node. At the current node, the application
463 is restarted by calling Module:start({takeover,Node},StartArgs).
464 Module and StartArgs are retrieved from the loaded application
465 specification. The application at the other node is not stopped
466 until the startup is completed, that is, when Module:start/2 and
467 any calls to Module:start_phase/3 have returned.
468 Thus, two instances of the application run simultaneously during
470 the takeover, so that data can be transferred from the old to
471 the new instance. If this is not an acceptable behavior, parts
472 of the old instance can be shut down when the new instance is
473 started. However, the application cannot be stopped entirely, at
474 least the top supervisor must remain alive.
475 For a description of Type, see start/1,2.
477 unload(Application) -> ok | {error, Reason}
479 Types:
481 Application = atom()
483 Reason = term()
484 Unloads the application specification for Application from the
486 application controller. It also unloads the application specifi‐
487 cations for any included applications. Notice that the function
488 does not purge the Erlang object code.
489 unset_env(Application, Par) -> ok
491 unset_env(Application, Par, Opts) -> ok
493 Types:
495 Application = Par = atom()
497 Opts = [{timeout, timeout()} | {persistent, boolean()}]
498 Removes the configuration parameter Par and its value for Appli‐
500 cation.
501 unset_env/2 uses the standard gen_server time-out value (5000
503 ms). Option timeout can be specified if another time-out value
504 is useful, for example, in situations where the application con‐
505 troller is heavily loaded.
506 unset_env/3 also allows the persistent option to be passed (see
508 set_env/4).
509 Warning:
511 Use this function only if you know what you are doing, that is,
512 on your own applications. It is very application-dependent and
513 configuration parameter-dependent when and how often the value
514 is read by the application. Careless use of this function can
515 put the application in a weird, inconsistent, and malfunctioning
516 state.
517 which_applications() -> [{Application, Description, Vsn}]
520 which_applications(Timeout) -> [{Application, Description, Vsn}]
522 Types:
524 Timeout = timeout()
526 Application = atom()
527 Description = Vsn = string()
528 Returns a list with information about the applications that are
530 currently running. Application is the application name. Descrip‐
531 tion and Vsn are the values of their description and vsn appli‐
532 cation specification keys, respectively.
533 which_applications/0 uses the standard gen_server time-out value
535 (5000 ms). A Timeout argument can be specified if another time-
536 out value is useful, for example, in situations where the appli‐
537 cation controller is heavily loaded.
538
540 The following functions are to be exported from an application callback
541 module.
542
544 Module:start(StartType, StartArgs) -> {ok, Pid} | {ok, Pid, State} |
545 {error, Reason}
546 Types:
548 StartType = start_type()
550 StartArgs = term()
551 Pid = pid()
552 State = term()
553 This function is called whenever an application is started using
555 start/1,2, and is to start the processes of the application. If
556 the application is structured according to the OTP design prin‐
557 ciples as a supervision tree, this means starting the top super‐
558 visor of the tree.
559 StartType defines the type of start:
561 * normal if it is a normal startup.
563 * normal also if the application is distributed and started at
565 the current node because of a failover from another node,
566 and the application specification key start_phases == unde‐
567 fined.
568 * {takeover,Node} if the application is distributed and
570 started at the current node because of a takeover from Node,
571 either because takeover/2 has been called or because the
572 current node has higher priority than Node.
573 * {failover,Node} if the application is distributed and
575 started at the current node because of a failover from Node,
576 and the application specification key start_phases /= unde‐
577 fined.
578 StartArgs is the StartArgs argument defined by the application
580 specification key mod.
581 The function is to return {ok,Pid} or {ok,Pid,State}, where Pid
583 is the pid of the top supervisor and State is any term. If omit‐
584 ted, State defaults to []. If the application is stopped later,
585 State is passed to Module:prep_stop/1.
586 Module:start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason}
588 Types:
590 Phase = atom()
592 StartType = start_type()
593 PhaseArgs = term()
594 Pid = pid()
595 State = state()
596 Starts an application with included applications, when synchro‐
598 nization is needed between processes in the different applica‐
599 tions during startup.
600 The start phases are defined by the application specification
602 key start_phases == [{Phase,PhaseArgs}]. For included applica‐
603 tions, the set of phases must be a subset of the set of phases
604 defined for the including application.
605 The function is called for each start phase (as defined for the
607 primary application) for the primary application and all
608 included applications, for which the start phase is defined.
609 For a description of StartType, see Module:start/2.
611 Module:prep_stop(State) -> NewState
613 Types:
615 State = NewState = term()
617 This function is called when an application is about to be
619 stopped, before shutting down the processes of the application.
620 State is the state returned from Module:start/2, or [] if no
622 state was returned. NewState is any term and is passed to Mod‐
623 ule:stop/1.
624 The function is optional. If it is not defined, the processes
626 are terminated and then Module:stop(State) is called.
627 Module:stop(State)
629 Types:
631 State = term()
633 This function is called whenever an application has stopped. It
635 is intended to be the opposite of Module:start/2 and is to do
636 any necessary cleaning up. The return value is ignored.
637 State is the return value of Module:prep_stop/1, if such a func‐
639 tion exists. Otherwise State is taken from the return value of
640 Module:start/2.
641 Module:config_change(Changed, New, Removed) -> ok
643 Types:
645 Changed = [{Par,Val}]
647 New = [{Par,Val}]
648 Removed = [Par]
649 Par = atom()
650 Val = term()
651 This function is called by an application after a code replace‐
653 ment, if the configuration parameters have changed.
654 Changed is a list of parameter-value tuples including all con‐
656 figuration parameters with changed values.
657 New is a list of parameter-value tuples including all added con‐
659 figuration parameters.
660 Removed is a list of all removed parameters.
662
664 OTP Design Principles, kernel(6), app(4)
665Ericsson AB kernel 5.4.3.2 application(3)