From: Luca Boccassi Date: Wed, 17 Jan 2024 16:59:26 +0000 (+0000) Subject: man: add more suggestions on how to use StartUnit and JobRemoved X-Git-Tag: v256-rc1~1111^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d156e66f826e3eaa4b7d26212870dcfdfd3a16a3;p=thirdparty%2Fsystemd.git man: add more suggestions on how to use StartUnit and JobRemoved This is not immediately clear for users, so spell out the preferred pattern clearly in the D-Bus documentation. --- diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index e2814b7e42e..5f1a5988a0c 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -1291,7 +1291,13 @@ node /org/freedesktop/systemd1 { and terminate all units that aren't dependencies of it. If ignore-dependencies, it will start a unit but ignore all its dependencies. If ignore-requirements, it will start a unit but only ignore the requirement dependencies. It is not recommended to make use of the - latter two options. On completion, this method returns the newly created job object. + latter two options. On reply, if successful, this method returns the newly created job object + which has been enqueued for asynchronous activation. Callers that want to track the outcome of the + actual start operation need to monitor the result of this job. This can be achieved in a race-free + manner by first subscribing to the JobRemoved() signal, then calling + StartUnit() and using the returned job object to filter out unrelated + JobRemoved() signals, until the desired one is received, which will then carry + the result of the start operation. StartUnitReplace() is similar to StartUnit() but replaces a job that is queued for one unit by a job for another unit.