[logger] Add SetOrUpdate parameter to handler callback changing_config

Since logger has now knowledge of the handler specific data ('config'
field in the handler configuration map), it can not merge this data
structure with default or old values upon configuration
change. Instead, the handler callback changing_config must do
this. Earlier, this callback did not reflect if the configuration
change was initiated by a call to set_handler_config or
update_handler_config, so the handler did not know if unspecified
fields should get default values or the values from the existing
configuration.

To overcome this problem, the new parameter SetOrUpdate is added to
this callback. If SetOrUpdate equals set, then default values should
be used. If SetOrUpdate equals update, then existing configuration
values should be used.

2 files changed, 23 insertions, 9 deletions

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 464c65ba76..8f54d0e54f 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -1041,10 +1041,11 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
     </func>
 
     <func>
-      <name>HModule:changing_config(Config1, Config2) -> {ok, Config3} | {error, Reason}</name>
+      <name>HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Config} | {error, Reason}</name>
       <fsummary>The configuration for this handler is about to change.</fsummary>
       <type>
-	<v>Config1 = Config2 = Config3 =
+	<v>SetOrUpdate = set | update</v>
+	<v>OldConfig = NewConfig = Config =
 	  <seealso marker="#type-handler_config">handler_config()</seealso></v>
 	<v>Reason = term()</v>
       </type>
@@ -1053,12 +1054,25 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
 	<p>The function is called on a temporary process when the
 	  configuration for a handler is about to change. The purpose
 	  is to verify and act on the new configuration.</p>
-	<p><c>Config1</c> is the existing configuration
-	  and <c>Config2</c> is the new configuration.</p>
+	<p><c>OldConfig</c> is the existing configuration
+	  and <c>NewConfig</c> is the new configuration.</p>
 	<p>The handler identity is associated with the <c>id</c> key
-	  in <c>Config1</c>.</p>
+	  in <c>OldConfig</c>.</p>
+	<p><c>SetOrUpdate</c> has the value <c>set</c> if the
+	  configuration change originates from a call to
+	  <seealso marker="#set_handler_config-2">
+	    <c>set_handler_config/2,3</c></seealso>, and <c>update</c>
+	  if it originates from <seealso marker="#update_handler_config-2">
+	    <c>update_handler_config/2</c></seealso>. The handler can
+	  use this parameteter to decide how to update the value of
+	  the <c>config</c> field, that is, the handler specific
+	  configuration data. Typically, if <c>SetOrUpdate</c>
+	  equals <c>set</c>, values that are not specified must be
+	  given their default values. If <c>SetOrUpdate</c>
+	  equals <c>update</c>, the values found in <c>OldConfig</c>
+	  must be used instead.</p>
 	<p>If everything succeeds, the callback function must return a
-	  possibly adjusted configuration in <c>{ok,Config3}</c>.</p>
+	  possibly adjusted configuration in <c>{ok,Config}</c>.</p>
 	<p>If the configuration is faulty, the callback function must
 	  return <c>{error,Reason}</c>.</p>
       </desc>
diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index 4a81cfa34a..7e88f82dad 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -384,7 +384,7 @@ logger:debug(#{got => connection_request, id => Id, state => State},
 
     <p>In addition to the mandatory callback function <c>log/2</c>, a
       handler module can export the optional callback
-      functions <c>adding_handler/1</c>, <c>changing_config/2</c>
+      functions <c>adding_handler/1</c>, <c>changing_config/3</c>
       and <c>removing_handler/1</c>. See
       section <seealso marker="logger#handler_callback_functions">Handler
       Callback Functions</seealso> in the logger(3) manual page for
@@ -1024,7 +1024,7 @@ ok</pre>
     <list>
       <item><c>adding_handler(Config)</c></item>
       <item><c>removing_handler(Config)</c></item>
-      <item><c>changing_config(OldConfig, NewConfig)</c></item>
+      <item><c>changing_config(SetOrUpdate, OldConfig, NewConfig)</c></item>
     </list>
     <p>When a handler is added, by for example a call
       to <seealso marker="logger#add_handler-3">
@@ -1045,7 +1045,7 @@ ok</pre>
       or <seealso marker="logger#update_handler_config/2">
 	<c>logger:update_handler_config/2</c></seealso> is called,
       Logger
-      calls <c>HModule:changing_config(OldConfig, NewConfig)</c>. If
+      calls <c>HModule:changing_config(SetOrUpdate, OldConfig, NewConfig)</c>. If
       this function returns <c>{ok,NewConfig1}</c>, Logger
       writes <c>NewConfig1</c> to the configuration database.</p>