core/manager: Deprecate StartAuxiliaryScope() method

The method was added with migration of resources in mind (e.g. process's
allocated memory will follow it to the new scope), however, such a
resource migration is not in cgroup semantics. The method may thus have
the intended users and others could be guided to StartTransientUnit().

Since this API was advertised in a regular release, start the removal
with a deprecation message to callers.
Eventually, the goal is to remove the method to clean up DBus API and
simplify code (removal of cgroup_context_copy()).

Part of DBus docs is retained to satisfy build checks.

1 files changed, 3 insertions, 7 deletions

diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index aa4f69deb1..91d7f08449 100644
--- a/man/org.freedesktop.systemd1.xml
+++ b/man/org.freedesktop.systemd1.xml
@@ -277,6 +277,7 @@ node /org/freedesktop/systemd1 {
       GetDynamicUsers(out a(us) users);
       DumpUnitFileDescriptorStore(in  s name,
                                   out a(suuutuusu) entries);
+      @org.freedesktop.DBus.Deprecated("true")
       StartAuxiliaryScope(in  s name,
                           in  ah pidfds,
                           in  t flags,
@@ -619,6 +620,8 @@ node /org/freedesktop/systemd1 {
 
     <!--method GetDynamicUsers is not documented!-->
 
+    <!--method StartAuxiliaryScope is not documented!-->
+
     <!--property SecurityStartTimestampMonotonic is not documented!-->
 
     <!--property SecurityFinishTimestamp is not documented!-->
@@ -1591,13 +1594,6 @@ node /org/freedesktop/systemd1 {
       to <function>DumpFileDescriptorStore()</function> on the
       <interfacename>org.freedesktop.systemd1.Service</interfacename>. For further details, see below.</para>
 
-      <para><function>StartAuxiliaryScope()</function> creates a new scope unit from a service where calling
-      process resides. Set of processes that will be migrated to newly created scope is passed in as an array
-      of pidfds. This is useful for creating auxiliary scopes that should contain worker processes and their lifecycle
-      shouldn't be bound to a lifecycle of the service, e.g. they should continue running after the restart
-      of the service. Note that the main PID of the service can not be migrated to an auxiliary scope.
-      Also, <varname>flags</varname> argument must be 0 and is reserved for future extensions.</para>
-
       <para><function>CleanUnit()</function> deletes the configuration, state, logs, cache and runtime data
       directories and clear out the file descriptors store for the unit, as specified in the mask
       parameters. The possible values are <literal>configuration</literal>, <literal>state</literal>,