1application(3)             Erlang Module Definition             application(3)
2
3
4

NAME

6       application - Generic OTP application functions
7

DESCRIPTION

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
17       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
22       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
27       For  details  about applications and behaviours, see OTP Design Princi‐
28       ples.
29

DATA TYPES

31       start_type() =
32           normal |
33           {takeover, Node :: node()} |
34           {failover, Node :: node()}
35
36       restart_type() = permanent | transient | temporary
37
38       tuple_of(T)
39
40              A tuple where the elements are of type T.
41

EXPORTS

43       ensure_all_started(Application) -> {ok, Started} | {error, Reason}
44
45       ensure_all_started(Application, Type) ->
46                             {ok, Started} | {error, Reason}
47
48              Types:
49
50                 Application = atom()
51                 Type = restart_type()
52                 Started = [atom()]
53                 Reason = term()
54
55              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
59              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
64              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
68              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
72       ensure_started(Application) -> ok | {error, Reason}
73
74       ensure_started(Application, Type) -> ok | {error, Reason}
75
76              Types:
77
78                 Application = atom()
79                 Type = restart_type()
80                 Reason = term()
81
82              Equivalent to start/1,2 except it returns ok for already started
83              applications.
84
85       get_all_env() -> Env
86
87       get_all_env(Application) -> Env
88
89              Types:
90
91                 Application = atom()
92                 Env = [{Par :: atom(), Val :: term()}]
93
94              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
98              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
102       get_all_key() -> [] | {ok, Keys}
103
104       get_all_key(Application) -> undefined | Keys
105
106              Types:
107
108                 Application = atom()
109                 Keys = {ok, [{Key :: atom(), Val :: term()}, ...]}
110
111              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
115              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
119       get_application() -> undefined | {ok, Application}
120
121       get_application(PidOrModule) -> undefined | {ok, Application}
122
123              Types:
124
125                 PidOrModule = (Pid :: pid()) | (Module :: module())
126                 Application = atom()
127
128              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
132              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
136       get_env(Par) -> undefined | {ok, Val}
137
138       get_env(Application, Par) -> undefined | {ok, Val}
139
140              Types:
141
142                 Application = Par = atom()
143                 Val = term()
144
145              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
149              Returns undefined if any of the following applies:
150
151                * The specified application is not loaded.
152
153                * The configuration parameter does not exist.
154
155                * The process executing the call does not belong to any appli‐
156                  cation.
157
158       get_env(Application, Par, Def) -> Val
159
160              Types:
161
162                 Application = Par = atom()
163                 Def = Val = term()
164
165              Works  like  get_env/2  but returns value Def when configuration
166              parameter Par does not exist.
167
168       get_key(Key) -> undefined | {ok, Val}
169
170       get_key(Application, Key) -> undefined | {ok, Val}
171
172              Types:
173
174                 Application = Key = atom()
175                 Val = term()
176
177              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
181              Returns undefined if any of the following applies:
182
183                * The specified application is not loaded.
184
185                * The specification key does not exist.
186
187                * The process executing the call does not belong to any appli‐
188                  cation.
189
190       load(AppDescr) -> ok | {error, Reason}
191
192       load(AppDescr, Distributed) -> ok | {error, Reason}
193
194              Types:
195
196                 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
223              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
228              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
233              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
237              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
247              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
251              Example:
252
253              Nodes = [cp1@cave, {cp2@cave, cp3@cave}]
254
255              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
259              If Distributed == default, the value for the application in  the
260              Kernel configuration parameter distributed is used.
261
262       loaded_applications() -> [{Application, Description, Vsn}]
263
264              Types:
265
266                 Application = atom()
267                 Description = Vsn = string()
268
269              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
275       set_env(Config) -> ok
276
277       set_env(Config, Opts) -> ok
278
279              Types:
280
281                 Config = [{Application, Env}]
282                 Application = atom()
283                 Env = [{Par :: atom(), Val :: term()}]
284                 Opts = [{timeout, timeout()} | {persistent, boolean()}]
285
286              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
291              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
296              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
302              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
307              set_env/1 is equivalent to set_env(Config, []).
308
309          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
317
318       permit(Application, Permission) -> ok | {error, Reason}
319
320              Types:
321
322                 Application = atom()
323                 Permission = boolean()
324                 Reason = term()
325
326              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
330              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
334              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
338              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
343              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
351              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
355       set_env(Application, Par, Val) -> ok
356
357       set_env(Application, Par, Val, Opts) -> ok
358
359              Types:
360
361                 Application = Par = atom()
362                 Val = term()
363                 Opts = [{timeout, timeout()} | {persistent, boolean()}]
364
365              Sets the value of configuration parameter Par for Application.
366
367              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
372              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
377              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
383          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
391
392       start(Application) -> ok | {error, Reason}
393
394       start(Application, Type) -> ok | {error, Reason}
395
396              Types:
397
398                 Application = atom()
399                 Type = restart_type()
400                 Reason = term()
401
402              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
407              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
413              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
421              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
425              Argument Type specifies the type of the application. If omitted,
426              it defaults to temporary.
427
428                * If  a  permanent  application terminates, all other applica‐
429                  tions and the entire Erlang node are also terminated.
430
431                *
432
433
434                  * If a transient application terminates with Reason ==  nor‐
435                    mal, this is reported but no other applications are termi‐
436                    nated.
437
438                  * If a  transient  application  terminates  abnormally,  all
439                    other  applications  and  the  entire Erlang node are also
440                    terminated.
441
442                * If a temporary application terminates, this is reported  but
443                  no other applications are terminated.
444
445              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
449              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
453       start_type() -> StartType | undefined | local
454
455              Types:
456
457                 StartType = start_type()
458
459              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
463              For a description of StartType, see Module:start/2.
464
465              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
469              If  the process executing the call does not belong to any appli‐
470              cation, the function returns undefined.
471
472       stop(Application) -> ok | {error, Reason}
473
474              Types:
475
476                 Application = atom()
477                 Reason = term()
478
479              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
488              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
493              When stopped, the application is still loaded.
494
495              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
503       takeover(Application, Type) -> ok | {error, Reason}
504
505              Types:
506
507                 Application = atom()
508                 Type = restart_type()
509                 Reason = term()
510
511              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
519              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
526              For a description of Type, see start/1,2.
527
528       unload(Application) -> ok | {error, Reason}
529
530              Types:
531
532                 Application = atom()
533                 Reason = term()
534
535              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
540       unset_env(Application, Par) -> ok
541
542       unset_env(Application, Par, Opts) -> ok
543
544              Types:
545
546                 Application = Par = atom()
547                 Opts = [{timeout, timeout()} | {persistent, boolean()}]
548
549              Removes the configuration parameter Par and its value for Appli‐
550              cation.
551
552              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
557              unset_env/3 also allows the persistent option to be passed  (see
558              set_env/4).
559
560          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
568
569       which_applications() -> [{Application, Description, Vsn}]
570
571       which_applications(Timeout) -> [{Application, Description, Vsn}]
572
573              Types:
574
575                 Timeout = timeout()
576                 Application = atom()
577                 Description = Vsn = string()
578
579              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
584              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

CALLBACK MODULE

590       The following functions are to be exported from an application callback
591       module.
592

EXPORTS

594       Module:start(StartType,  StartArgs)  ->  {ok, Pid} | {ok, Pid, State} |
595       {error, Reason}
596
597              Types:
598
599                 StartType = start_type()
600                 StartArgs = term()
601                 Pid = pid()
602                 State = term()
603
604              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
610              StartType defines the type of start:
611
612                * normal if it is a normal startup.
613
614                * 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
619                * {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
624                * {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
629              StartArgs  is  the StartArgs argument defined by the application
630              specification key mod.
631
632              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
637       Module:start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason}
638
639              Types:
640
641                 Phase = atom()
642                 StartType = start_type()
643                 PhaseArgs = term()
644                 Pid = pid()
645                 State = state()
646
647              Starts  an application with included applications, when synchro‐
648              nization is needed between processes in the  different  applica‐
649              tions during startup.
650
651              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
656              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
660              For a description of StartType, see Module:start/2.
661
662       Module:prep_stop(State) -> NewState
663
664              Types:
665
666                 State = NewState = term()
667
668              This function is called when  an  application  is  about  to  be
669              stopped, before shutting down the processes of the application.
670
671              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
675              The  function  is  optional. If it is not defined, the processes
676              are terminated and then Module:stop(State) is called.
677
678       Module:stop(State)
679
680              Types:
681
682                 State = term()
683
684              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
688              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
692       Module:config_change(Changed, New, Removed) -> ok
693
694              Types:
695
696                 Changed = [{Par,Val}]
697                 New = [{Par,Val}]
698                 Removed = [Par]
699                  Par = atom()
700                  Val = term()
701
702              This function is called by an application after a code  replace‐
703              ment, if the configuration parameters have changed.
704
705              Changed  is  a list of parameter-value tuples including all con‐
706              figuration parameters with changed values.
707
708              New is a list of parameter-value tuples including all added con‐
709              figuration parameters.
710
711              Removed is a list of all removed parameters.
712

SEE ALSO

714       OTP Design Principles, kernel(6), app(4)
715
716
717
718Ericsson AB                       kernel 7.3                    application(3)
Impressum