Merge pull request #2164 from josevalim/jv-set-env-maint

Add application:set_env/1 and application:set_env/2

OTP-15642

4 files changed, 208 insertions, 50 deletions

diff --git a/lib/kernel/doc/src/application.xml b/lib/kernel/doc/src/application.xml
index 4e32c1a3a5..5170502581 100644
--- a/lib/kernel/doc/src/application.xml
+++ b/lib/kernel/doc/src/application.xml
@@ -238,6 +238,41 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code>
       </desc>
     </func>
     <func>
+      <name name="set_env" arity="1" since="OTP @OTP-15642@"/>
+      <name name="set_env" arity="2" since="OTP @OTP-15642@"/>
+      <fsummary>Sets the configuration parameters of multiple applications.</fsummary>
+      <desc>
+        <p>Sets the configuration <c><anno>Config</anno></c> for multiple
+          applications. It is equivalent to calling <c>set_env/4</c> on
+          each application individially, except it is more efficient.
+          The given <c><anno>Config</anno></c> is validated before the
+          configuration is set.</p>
+        <p><c>set_env/2</c> uses the standard <c>gen_server</c> time-out
+          value (5000 ms). Option <c>timeout</c> can be specified
+          if another time-out value is useful, for example, in situations
+          where the application controller is heavily loaded.</p>
+        <p>Option <c>persistent</c> can be set to <c>true</c>
+          to guarantee that parameters set with <c>set_env/2</c>
+          are not overridden by those defined in the application resource
+          file on load. This means that persistent values will stick after the application
+          is loaded and also on application reload.</p>
+        <p>If an application is given more than once or if an application
+          has the same key given more than once, the behaviour is undefined
+          and a warning message will be logged. In future releases, an error
+          will be raised.</p>
+        <p><c>set_env/1</c> is equivalent to <c>set_env(Config, [])</c>.</p>
+        <warning>
+          <p>Use this function only if you know what you are doing,
+            that is, on your own applications. It is very
+            application-dependent and
+            configuration parameter-dependent when and how often
+            the value is read by the application. Careless use
+            of this function can put the application in a
+            weird, inconsistent, and malfunctioning state.</p>
+        </warning>
+      </desc>
+    </func>
+    <func>
       <name name="permit" arity="2" since=""/>
       <fsummary>Change the permission for an application to run at a node.</fsummary>
       <desc>
diff --git a/lib/kernel/src/application.erl b/lib/kernel/src/application.erl
index bc6be2f8f5..5c2e981e4b 100644
--- a/lib/kernel/src/application.erl
+++ b/lib/kernel/src/application.erl
@@ -25,7 +25,7 @@
 	 which_applications/0, which_applications/1,
 	 loaded_applications/0, permit/2]).
 -export([ensure_started/1, ensure_started/2]).
--export([set_env/3, set_env/4, unset_env/2, unset_env/3]).
+-export([set_env/1, set_env/2, set_env/3, set_env/4, unset_env/2, unset_env/3]).
 -export([get_env/1, get_env/2, get_env/3, get_all_env/0, get_all_env/1]).
 -export([get_key/1, get_key/2, get_all_key/0, get_all_key/1]).
 -export([get_application/0, get_application/1, info/0]).
@@ -279,6 +279,26 @@ loaded_applications() ->
 info() -> 
     application_controller:info().
 
+-spec set_env(Config) -> 'ok' when
+      Config :: [{Application, Env}],
+      Application :: atom(),
+      Env :: [{Par :: atom(), Val :: term()}].
+
+set_env(Config) when is_list(Config) ->
+    set_env(Config, []).
+
+-spec set_env(Config, Opts) -> 'ok' when
+      Config :: [{Application, Env}],
+      Application :: atom(),
+      Env :: [{Par :: atom(), Val :: term()}],
+      Opts :: [{timeout, timeout()} | {persistent, boolean()}].
+
+set_env(Config, Opts) when is_list(Config), is_list(Opts) ->
+    case application_controller:set_env(Config, Opts) of
+	ok -> ok;
+	{error, Msg} -> erlang:error({badarg, Msg}, [Config, Opts])
+    end.
+
 -spec set_env(Application, Par, Val) -> 'ok' when
       Application :: atom(),
       Par :: atom(),
diff --git a/lib/kernel/src/application_controller.erl b/lib/kernel/src/application_controller.erl
index a074d2e74b..9a8091fb2e 100644
--- a/lib/kernel/src/application_controller.erl
+++ b/lib/kernel/src/application_controller.erl
@@ -26,7 +26,7 @@
 	 control_application/1,
 	 change_application_data/2, prep_config_change/0, config_change/1,
 	 which_applications/0, which_applications/1,
-	 loaded_applications/0, info/0,
+	 loaded_applications/0, info/0, set_env/2,
 	 get_pid_env/2, get_env/2, get_pid_all_env/1, get_all_env/1,
 	 get_pid_key/2, get_key/2, get_pid_all_key/1, get_all_key/1,
 	 get_master/1, get_application/1, get_application_module/1,
@@ -345,9 +345,6 @@ get_all_env(AppName) ->
     map(fun([Key, Val]) -> {Key, Val} end,
 	ets:match(ac_tab, {{env, AppName, '$1'}, '$2'})).
 
-
-
-
 get_pid_key(Master, Key) ->
     case ets:match(ac_tab, {{application_master, '$1'}, Master}) of
 	[[AppName]] -> get_key(AppName, Key);
@@ -461,6 +458,15 @@ permit_application(ApplName, Flag) ->
 		    {permit_application, ApplName, Flag},
 		    infinity).
 
+set_env(Config, Opts) ->
+    case check_conf_data(Config) of
+	ok ->
+	    Timeout = proplists:get_value(timeout, Opts, 5000),
+	    gen_server:call(?AC, {set_env, Config, Opts}, Timeout);
+
+	{error, _} = Error ->
+	    Error
+    end.
 
 set_env(AppName, Key, Val) ->
     gen_server:call(?AC, {set_env, AppName, Key, Val, []}).
@@ -528,19 +534,17 @@ check_conf_data([]) ->
 check_conf_data(ConfData) when is_list(ConfData) ->
     [Application | ConfDataRem] = ConfData,
     case Application of
-	{kernel, List} when is_list(List) ->
-	    case check_para_kernel(List) of
-		ok ->
-		    check_conf_data(ConfDataRem);
-		Error1 ->
-		    Error1
-	    end;
 	{AppName, List} when is_atom(AppName), is_list(List) ->
-	    case check_para(List, atom_to_list(AppName)) of
-		ok ->
-		    check_conf_data(ConfDataRem);
-		Error2 ->
-		    Error2
+	    case lists:keymember(AppName, 1, ConfDataRem) of
+		true ->
+		    ?LOG_WARNING("duplicate application config: " ++ atom_to_list(AppName));
+		false ->
+		    ok
+	    end,
+
+	    case check_para(List, AppName) of
+		ok -> check_conf_data(ConfDataRem);
+		Error -> Error
 	    end;
 	{AppName, List} when is_list(List)  ->
 	    ErrMsg = "application: "
@@ -553,36 +557,40 @@ check_conf_data(ConfData) when is_list(ConfData) ->
 		++ "; parameters must be a list",
 	    {error, ErrMsg};
 	Else ->
-	    ErrMsg = "invalid application name: " ++ 
-		lists:flatten(io_lib:format(" ~tp",[Else])),
+	    ErrMsg = "invalid application config: "
+		++ lists:flatten(io_lib:format("~tp",[Else])),
 	    {error, ErrMsg}
     end;
 check_conf_data(_ConfData) ->
-    {error, 'configuration must be a list ended by <dot><whitespace>'}.
-    
+    {error, "configuration must be a list ended by <dot><whitespace>"}.
 
-%% Special check of distributed parameter for kernel
-check_para_kernel([]) ->
+
+check_para([], _AppName) ->
     ok;
-check_para_kernel([{distributed, Apps} | ParaList]) when is_list(Apps) ->
-    case check_distributed(Apps) of
-	{error, _ErrorMsg} = Error ->
-	    Error;
-	_ ->
-	    check_para_kernel(ParaList)
+check_para([{Para, Val} | ParaList], AppName) when is_atom(Para) ->
+    case lists:keymember(Para, 1, ParaList) of
+	true ->
+	    ?LOG_WARNING("application: " ++ atom_to_list(AppName) ++
+                             "; duplicate parameter: " ++ atom_to_list(Para));
+	false ->
+	    ok
+    end,
+
+    case check_para_value(Para, Val, AppName) of
+	ok -> check_para(ParaList, AppName);
+	{error, _} = Error -> Error
     end;
-check_para_kernel([{distributed, _Apps} | _ParaList]) ->
-    {error, "application: kernel; erroneous parameter: distributed"};
-check_para_kernel([{Para, _Val} | ParaList]) when is_atom(Para) ->
-    check_para_kernel(ParaList);
-check_para_kernel([{Para, _Val} | _ParaList]) ->
-    {error, "application: kernel; invalid parameter: " ++ 
+check_para([{Para, _Val} | _ParaList], AppName) ->
+    {error, "application: " ++ atom_to_list(AppName) ++ "; invalid parameter name: " ++
      lists:flatten(io_lib:format("~tp",[Para]))};
-check_para_kernel(Else) ->
-    {error, "application: kernel; invalid parameter list: " ++ 
+check_para([Else | _ParaList], AppName) ->
+    {error, "application: " ++ atom_to_list(AppName) ++ "; invalid parameter: " ++
      lists:flatten(io_lib:format("~tp",[Else]))}.
-    
 
+check_para_value(distributed, Apps, kernel) -> check_distributed(Apps);
+check_para_value(_Para, _Val, _AppName) -> ok.
+
+%% Special check of distributed parameter for kernel
 check_distributed([]) ->
     ok;
 check_distributed([{App, List} | Apps]) when is_atom(App), is_list(List) ->
@@ -595,18 +603,6 @@ check_distributed(_Else) ->
     {error, "application: kernel; erroneous parameter: distributed"}.
 
 
-check_para([], _AppName) ->
-    ok;
-check_para([{Para, _Val} | ParaList], AppName) when is_atom(Para) ->
-    check_para(ParaList, AppName);
-check_para([{Para, _Val} | _ParaList], AppName) ->
-    {error, "application: " ++ AppName ++ "; invalid parameter: " ++ 
-     lists:flatten(io_lib:format("~tp",[Para]))};
-check_para([Else | _ParaList], AppName) ->
-    {error, "application: " ++ AppName ++ "; invalid parameter: " ++ 
-     lists:flatten(io_lib:format("~tp",[Else]))}.
-
-
 -type calls() :: 'info' | 'prep_config_change' | 'which_applications'
                | {'config_change' | 'control_application' |
 		  'load_application' | 'start_type' | 'stop_application' |
@@ -863,6 +859,16 @@ handle_call(which_applications, _From, S) ->
 	       end, S#state.running),
     {reply, Reply, S};
 
+handle_call({set_env, Config, Opts}, _From, S) ->
+    _ = [add_env(AppName, Env) || {AppName, Env} <- Config],
+
+    case proplists:get_value(persistent, Opts, false) of
+	true ->
+	    {reply, ok, S#state{conf_data = merge_env(S#state.conf_data, Config)}};
+	false ->
+	    {reply, ok, S}
+    end;
+
 handle_call({set_env, AppName, Key, Val, Opts}, _From, S) ->
     ets:insert(ac_tab, {{env, AppName, Key}, Val}),
     case proplists:get_value(persistent, Opts, false) of
diff --git a/lib/kernel/test/application_SUITE.erl b/lib/kernel/test/application_SUITE.erl
index 5c35b82207..94d7c17712 100644
--- a/lib/kernel/test/application_SUITE.erl
+++ b/lib/kernel/test/application_SUITE.erl
@@ -31,6 +31,7 @@
 	 otp_3002/1, otp_3184/1, otp_4066/1, otp_4227/1, otp_5363/1,
 	 otp_5606/1,
 	 start_phases/1, get_key/1, get_env/1,
+	 set_env/1, set_env_persistent/1, set_env_errors/1,
 	 permit_false_start_local/1, permit_false_start_dist/1, script_start/1, 
 	 nodedown_start/1, init2973/0, loop2973/0, loop5606/1]).
 
@@ -55,6 +56,7 @@ all() ->
      load_use_cache, ensure_started, {group, reported_bugs}, start_phases,
      script_start, nodedown_start, permit_false_start_local,
      permit_false_start_dist, get_key, get_env, ensure_all_started,
+     set_env, set_env_persistent, set_env_errors,
      {group, distr_changed}, config_change, shutdown_func, shutdown_timeout,
      shutdown_deadlock, config_relative_paths,
      persistent_env].
@@ -1944,6 +1946,101 @@ get_appls([_ | T], Res) ->
 get_appls([], Res) ->
     Res.
 
+%% Test set_env/1.
+set_env(Conf) when is_list(Conf) ->
+    ok = application:set_env([{appinc, [{own2, persist}, {not_in_app, persist}]},
+			      {unknown_app, [{key, persist}]}]),
+
+    %% own_env1 and own2 are set in appinc
+    undefined = application:get_env(appinc, own_env1),
+    {ok, persist} = application:get_env(appinc, own2),
+    {ok, persist} = application:get_env(appinc, not_in_app),
+    {ok, persist} = application:get_env(unknown_app, key),
+
+    ok = application:load(appinc()),
+    {ok, value1} = application:get_env(appinc, own_env1),
+    {ok, val2} = application:get_env(appinc, own2),
+    {ok, persist} = application:get_env(appinc, not_in_app),
+    {ok, persist} = application:get_env(unknown_app, key),
+
+    %% On reload, values are lost
+    ok = application:unload(appinc),
+    ok = application:load(appinc()),
+    {ok, value1} = application:get_env(appinc, own_env1),
+    {ok, val2} = application:get_env(appinc, own2),
+    undefined = application:get_env(appinc, not_in_app),
+
+    %% Clean up
+    ok = application:unload(appinc).
+
+%% Test set_env/2 with persistent true.
+set_env_persistent(Conf) when is_list(Conf) ->
+    Opts = [{persistent, true}],
+    ok = application:set_env([{appinc, [{own2, persist}, {not_in_app, persist}]},
+			      {unknown_app, [{key, persist}]}], Opts),
+
+    %% own_env1 and own2 are set in appinc
+    undefined = application:get_env(appinc, own_env1),
+    {ok, persist} = application:get_env(appinc, own2),
+    {ok, persist} = application:get_env(appinc, not_in_app),
+    {ok, persist} = application:get_env(unknown_app, key),
+
+    ok = application:load(appinc()),
+    {ok, value1} = application:get_env(appinc, own_env1),
+    {ok, persist} = application:get_env(appinc, own2),
+    {ok, persist} = application:get_env(appinc, not_in_app),
+    {ok, persist} = application:get_env(unknown_app, key),
+
+    %% On reload, values are not lost
+    ok = application:unload(appinc),
+    ok = application:load(appinc()),
+    {ok, value1} = application:get_env(appinc, own_env1),
+    {ok, persist} = application:get_env(appinc, own2),
+    {ok, persist} = application:get_env(appinc, not_in_app),
+
+    %% Clean up
+    ok = application:unload(appinc).
+
+set_env_errors(Conf) when is_list(Conf) ->
+    "application: 1; application name must be an atom" =
+	badarg_msg(fun() -> application:set_env([{1, []}]) end),
+
+    "application: foo; parameters must be a list" =
+	badarg_msg(fun() -> application:set_env([{foo, bar}]) end),
+
+    "invalid application config: foo_bar" =
+	badarg_msg(fun() -> application:set_env([foo_bar]) end),
+
+    "application: foo; invalid parameter name: 1" =
+	badarg_msg(fun() -> application:set_env([{foo, [{1, 2}]}]) end),
+
+    "application: foo; invalid parameter: config" =
+	badarg_msg(fun() -> application:set_env([{foo, [config]}]) end),
+
+    "application: kernel; erroneous parameter: distributed" =
+	badarg_msg(fun() -> application:set_env([{kernel, [{distributed, config}]}]) end),
+
+    %% This will raise in the future
+    ct:capture_start(),
+    _ = application:set_env([{foo, []}, {foo, []}]),
+    timer:sleep(100),
+    ct:capture_stop(),
+    [_ | _] = string:find(ct:capture_get(), "duplicate application config: foo"),
+
+    ct:capture_start(),
+    _ = application:set_env([{foo, [{bar, baz}, {bar, bat}]}]),
+    timer:sleep(100),
+    ct:capture_stop(),
+    [_ | _] = string:find(ct:capture_get(), "application: foo; duplicate parameter: bar"),
+
+    ok.
+
+badarg_msg(Fun) ->
+    try Fun() of
+	_ -> ct:fail(try_succeeded)
+    catch
+	error:{badarg, Msg} -> Msg
+    end.
 
 %% Test set_env/4 and unset_env/3 with persistent true.
 persistent_env(Conf) when is_list(Conf) ->