Activation: new draft

[Richard Hult]

--=-Y8EPzkO7Df+DGTy7dGY5
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

Hi,

Attaching a new draft after feedback from the list and some exchange of
mails with Havoc. Unless people see major problems with it, it should be
ready for a first round of implementation. 

Comments are appreciated,
Richard

-- 
Richard Hult                    richard@imendio.com
Imendio                         http://www.imendio.com

--=-Y8EPzkO7Df+DGTy7dGY5
Content-Disposition: attachment; filename=design-draft.txt
Content-Type: text/plain; name=design-draft.txt; charset=ISO-8859-15
Content-Transfer-Encoding: 7bit

A course-grained design draft for dbus activation.

Activation 
----------

[ This part is already implemented ]

The bus handles the mapping of service names to executables and the
launching of those executables.

To request an activation of a service, clients send an ActivateService
message to the bus.

If the service does not exist in the list of activation entries in the
bus, the error "org.freedesktop.DBus.Error.ServiceNotFound" is returned.

If the service exists and is already running, a reply with the value
DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE is sent.

Finally, if the service is not running, the activation request is added
to a pending activation that is created unless there is already one in
progress for the service. When creating a pending activation, a timeout
is set up to cancel the activation if it has not succeeded after an
amount of time specified in the global bus configuration.

The corresponding executable is spawned asynchronously. If this fails,
one of following error replies is sent for each of the pending
activation requests:

"org.freedesktop.DBus.Error.Spawn.ExecFailed"
"org.freedesktop.DBus.Error.Spawn.ForkFailed"
"org.freedesktop.DBus.Error.Spawn.ChildExited"
"org.freedesktop.DBus.Error.Spawn.ChildSignaled"
"org.freedesktop.DBus.Error.Spawn.Failed"
"org.freedesktop.DBus.Error.TimedOut"

When the executable has started and successfully acquired the service,
the bus replies to all clients that have requested the activation with
value DBUS_ACTIVATION_REPLY_ACTIVATED.

FIXME: The behavior when sending a message to a service with a pending
activation is not specified. It could use the same message queue as
implicit activation will use, or it could be seen as an error.


Activation context
------------------

Services are activated in the same environment as the bus itself,
meaning for example that services will run with the same locale and
DISPLAY environment variable as the bus.

For services that need to be run in a certain context, for example the
same locale as the activating client, that must be handled outside the
bus, for example with a factory service. A framework for such a service
could be designed and written once and shared between different desktops
and applications.


Implicit activation
-------------------

Implicit or automatic activation means that when sending a message to a
service, the service can optionally be activated automatically. The
purpose of implicit activation is to avoid round trips to the bus daemon
by having to activate a service or check if a service is already
activated before sending a message. Implicit activation also provides a
more convenient API for client writers.

In order to send a message with implicit activation, the client sets the
message flag IMPLICIT_ACTIVATION. It is an error to set this flag when
sending a message without the service field set, or when sending to the
special broadcast service org.freedesktop.DBus.Broadcast.

FIXME: Should it be considered an error or should the flag be discarded
in those cases?

The activation is handled just as regular activation, and the message is
added to a message queue for the pending activation. When the activation
succeeds, the messages in the queue are sent as regular messages.

This operation will result in the sender receiving either an activation
error, a send error or a result from the receiver in case the operation
was successful.


Service files
-------------

FIXME: Spec service file format in more detail instead of referring to
desktop file spec.

The bus reads service description files from directories specified in
the bus configuration. For each service that an application provides, a
service file is installed. The file format is similar to that of desktop
entries. All service description files must be in UTF-8 encoding. To
ensure that there will be no name collisions, service files must be
namespaced using the same mechanism as messages and service names.

Example:

# Sample service description file
[D-BUS Service]
Name=org.gnome.ConfigurationDatabase
Exec=/usr/libexec/gconfd-2

There can also be additional arbitrary key/string value pairs, which
must be namespaced with a prefix according to X-{VENDOR}- to avoid name
clashes. The value of such keys may be supplied for different locales
(see desktop entry spec).

The bus must be able to handle many installed services, each with a
number of properties localized into many locales, without degrading
performance. In order to do so, an install-time tool processes the
service files to generate a set of cache files that can be handled more
efficiently during run-time. This means that the cache files are
regenerated when installing a service file.

The Name and Exec properties from all service files in a directory is
concatenated into one file in that directory to avoid opening many
files.

The properties are split out and put in one file per locale, with
fallbacks merged in by the installation tool. If a property does not
have a value in a specific locale, the value from the fallback locale is
used as according to the order LANG_COUNTRY@MODIFIER, LANG_COUNTRY,
LANG@MODIFIER, LANG, C. The encoding field of the locale is not used
since all service files must be in UTF-8 encoding.


Rereading service files
-----------------------

The bus must be able to reread the service files on the fly, since
clients count on the bus to never exit. It should not be necessary to
log out and back in to install a program when using the session bus for
example.

Before trying to launch an executable to activate a service, the
timestamp of the service cache files are checked, and reread if
necessary.


Querying for services
---------------------

As the bus itself only handles mapping service names to executables,
higher level querying features are left to a layer on top of of the bus
core, implemented as a service.

The query service maps properties to service names, and can return a
list of services matching the given criteria such as
"ImplementsInterface == 'org.freedesktop.MusicPlayer'".

When performing a query, the client can optionally specify the locale
code to use so that the query service can return properly localized
values for display in a user interface.

To perform a query, a Query message is sent, with a query string and
list of the properties to send back. The return value is a list of
service names and the values of the requested properties.

Pseudo-code example:

Query ("ImplementsInterface == 'org.freedesktop.MusicPlayer'",
       ["X-MYDESKTOP-Foo", "X-MYDESKTOP-Bar"],
       "sv_SE")

If the locale code is not specified, the locale of the bus will be used,
which is useful for cases where there are no strings to be shown in a
user interface, and the locale does not matter.

Note: The exact syntax of the query language and query API is left
open.


--=-Y8EPzkO7Df+DGTy7dGY5--