diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 61993969..5feffa33 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. + - 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 + 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. + + + + 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: