From 28bbac7dc8d60eea409d7e13229c248550b81dbd Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 21 Nov 2016 20:12:57 +0000 Subject: [PATCH] Spec: document what auto-starting is, and recommend it For something we recommend, that is important enough to have its own header flag, it doesn't have very good documentation. Redo the text to suggest that auto-starting is the normal thing and StartServiceByName is the oddity. That's usually a good principle to follow, since it dodges time-of-check/time-of-use issues, and the method call that you presumably wanted to do needs to handle errors anyway. Signed-off-by: Simon McVittie Reviewed-by: Philip Withnall Bug: https://bugs.freedesktop.org/show_bug.cgi?id=98671 --- doc/dbus-specification.xml | 54 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 7 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 6199396..5feffa3 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1930,7 +1930,9 @@ Unless a message has the flag NO_AUTO_START, if the destination name does not exist then a program to own the destination - name will be started before the message is delivered. The message + name will be started before the message is delivered. See + . + The message will be held until the new program is successfully started or has failed to start; in case of failure, an error will be returned. This flag is only relevant in the context of a message bus, it is ignored @@ -4979,15 +4981,34 @@ service or an activatable service. + + + In D-Bus, starting a service is normally done by + auto-starting, which is one form of activation. + In auto-starting, applications send a + message to a particular well-known name, such as + com.example.TextEditor, without specifying the + NO_AUTO_START flag in the message header. + If no application on the bus owns the requested name, but the bus + daemon does know how to start an activatable service for that name, + then the bus daemon will start that service, wait for it to request + that name, and deliver the message to it. + + - With D-Bus, starting a service is normally done by name. That is, - applications ask the message bus to start some program that will own a - well-known name, such as com.example.TextEditor. - This implies a contract documented along with the name + It is also possible for applications to send an explicit request to + start a service: this is another form of activation, distinct from + auto-starting. See + for details. + + + + In either case, this implies a contract documented along with the name com.example.TextEditor for which object the owner of that name will provide, and what interfaces those objects will have. + To find an executable corresponding to a particular name, the bus daemon looks for service description files. Service @@ -5762,8 +5783,27 @@ - Tries to launch the executable associated with a name. For more information, see . - + Tries to launch the executable associated with a name (service + activation), as an explicit request. This is an alternative to + relying on auto-starting. For more information on how services + are activated and the difference between auto-starting and explicit + activation, see + . + + + It is often preferable to carry out auto-starting + instead of calling this method. This is because calling this method + is subject to a + time-of-check/time-of-use + issue: if a caller asks the message bus to start a service so that + the same caller can make follow-up method calls to that service, + the fact that the message bus was able to start the required + service is no guarantee that it will not have crashed or otherwise + exited by the time the caller makes those follow-up method calls. + As a result, calling this method does not remove the need for + the caller to handle errors from method calls. Given that fact, + it is usually simpler to rely on auto-starting, in which the + required service starts as a side-effect of the first method call. The return value can be one of the following values: -- 2.7.4