[pulseaudio-discuss] RFC: Configuration system

[Tanu Kaskinen]

On Thu, 2012-04-26 at 14:19 +0200, Peter Meerwald wrote:
> Hallo Tanu,
> 
> 
> > == Design ==
> > 
> > The configuration system stores "options". Options have a value and a
> > (multi-part) identifier. The options need at least two pieces of
> > identification information: the object id and the option name. For
> > example, the maximum volume of a port could have object id
> > "foocard:barport" and option id "max-volume". Objects have also a type
> 
> I find this explanation quite confusing;
> 
> is 'option name' the same as 'option id'?
> I suggest to avoid 'option name' so that 'option id' can be understand as 
> being part of the (multi-part) identifier; 
> 
> maybe 'setting id' would be preferable instead of 'option id'
> currently, as I understand, the 'option id' is part of the (multi-part) 
> option identifier and hence option identifier and option id means 
> different things yet sound similar

Good points, I'll make the terminology more consistent. I would prefer
"option id" to refer to the whole three-part identifier and "option
name" to the last part of it. I'm not very keen on switching one or the
other to "setting" - to me that would seem inconsistent. I wonder,
though, if there would be any reason to completely switch the word
"option" to "setting" everywhere? To me (a non-native English speaker)
"option" and "setting" mean the exactly same thing in software context,
but is there some distinction that would make one or the other a better
choice?

> > (e.g. card, port, stream-restore entry). The object ids could have the
> > type information encoded into them, or the type could be a separate
> > identifier. A separate identifier is better, because otherwise you need
> > to store the known options for each object, while it would be easier and
> > more efficient to store the known options for the type of the objects.
> > So, option values can be referenced by giving three identifiers: object
> > type, object id and option name. These can be encoded in a single key
> 
> so what is an object type? what are possible types?
> what is a 'key', is it the same as the (multi-part) identifier?

I gave a few examples of object types: card, port and stream-restore
entry. The concepts in Pulseaudio. By "object type" I mean "class" in
the OOP sense. So in OOP speak, "object type" is class, "object" is
object and "option" is member variable. I don't know if that's correct
usage of the phrase "object type", but I feel that it's a less ambiguous
term than "class". I can easily be convinced to use "class" instead.

The answer to the "key" question is yes. The system could be made look
like a simple key-value store to the outside world, so in that context
it makes more sense to talk about keys than option ids.

> > string (e.g. "core.Port/cardname:portname/max-volume") if so desired,
> > but the configuration system has to have concepts for these three
> > things. We might want to also have a type namespace concept, for example
> 
> is type and namespace the same thing?

Not really. In "core.Port/cardname:portname/max-volume", "core" is the
namespace for the "Port" type. If the namespace wouldn't have any other
purpose than making type names unique (for example, distinguishing
between "stream-restore.Entry" and "device-restore.Entry"), then we
wouldn't necessarily need to talk about namespaces at all - we could
consider that specific naming style in those examples only a convention
- but if the namespace determines the file where those options are
stored, then it has to be a separate concept.

I'll try to clarify the meaning of the namespaces on the wiki page.

> > to split the configuration into one file per namespace (core could have
> > its own namespace and each module could have theirs). In the client API
> > it's probably best to encode the namespace into the object type.
> 
> > >From the configuration system's point of view, all option values are
> > strings. Adding type information would add a lot of complexity and not
> > have very big benefits (is it so?). The options will of course have an
> > implicit type to be useful. The actual users of the options
> > (applications and code in the server) have to validate the values
> > themselves. This means that we should provide parsing functions for
> > clients, at least for any complex types, but preferably also for simple
> 
> for _all_compley types
> 
> > stuff like integers. At server side, values are validated when they are
> > read from the disk and when they are set by clients or by some other
> > code in the server than the "option owner".
> > 
> > Since validation is done by the option owner code, and since modules can
> > implement options, some of the options can be only validated when a
> > specific module is loaded. The way to handle the case, where an
> > application sets an option for a module that is not loaded, is to refuse
> > to set any such options. If the module isn't loaded, from the
> > configuration system's point of view the option doesn't exist.
> 
> > typedef void (*pa_server_configuration_cb_t)(
> >                 pa_context *c,
> >                 const char *object_type,
> >                 const char *object_id,
> >                 const char *option,
> >                 const char *value,
> >                 int eol,
> >                 void *userdata);
> 
> so option is indeed option_id? or setting_id as I suggest

I'd rename option to option_name here.

> > == Open issues ==
> > 
> > The namespace concept might need some refinement. The idea of splitting
> > the storage into one file per module sounds nice, but it might not sense
> 
> it might not _make_ sense
> 
> > to dedicate each object type to one module. Modules may want add options
> 
> want _to_ add
> 
> > to their own object types and to core object types, and possibly also to
> > other modules' types. Let's say there's an object type "Card" in
> > namespace "core", i.e. "core.Card". The alsa modules might want to add
> > an option to core.Cards for enabling and disabling timer-based
> > scheduling. Maybe the options should have namespacing too, i.e. the new
> > option would be "core.Card/foocard/alsa.tsched"? Would every option name
> > have a namespace part? That would be very ugly. How would this example
> > be handled in storage? Is splitting the storage into many files a bad
> > idea anyway?
> 
> how does this mix with dbus properties?

Interesting question. With the currently planned feature set, I would
just add a similar get/set interface to the D-Bus API like the C api is.
If you meant how the namespacing choices affect Pulseaudio's D-Bus API
(I assume you meant that), the answer is that the choices don't affect
the API at all. That's because the API doesn't have any concept of
namespaces anyway.

With a slightly larger set of features (like proper types associated
with the option values instead of just strings) the options probably
could be automatically mapped to properties in the D-Bus API. And with
some more features, the D-Bus, native and HTTP interfaces could just
talk to the "configuration system" (or "object introspection system" at
that point), and new features would automatically get support in all
those interfaces... That would be nice, but not what I want to start
working on now.

Anyway, thinking about how D-Bus would do this might prove fruitful. If
the options were modeled as properties in D-Bus, then the object type
would be the D-Bus interface and the object id would be the D-Bus object
path. Trying to add new properties to an interface at run-time (like
adding the alsa.tsched option to core.Card) is not supported in D-Bus.
The solution would be to make new interface, let's call it
"org.pulseaudio.alsa.Card". The documentation would state that the
"org.pulseaudio.alsa.Card" interface implies that the object implements
also "org.pulseaudio.core.Card". That would imitate a concept of
subinterfaces. I actually like this solution. The only problem is that
you can't enumerate all options of the card with a single query, so you
have to ask for the "core.Card" and "alsa.Card" options separately. This
shouldn't be a significant problem in practice.

So, you can document some object types to be subtypes of other types.
There won't be explicit support for extending the option set of an
object (or object type). There's no need to add namespacing to option
names.

> > Is there need for adding an API for clients for querying whether a
> > specific option is supported? Such API could be added also later, if we
> > are not certain yet.
> 
> querying a default value or values might be useful as well

Yes, sounds like a possible addition.

I think I'm done for today, so I'll do my updates to the wiki tomorrow.
Anyone else is welcome to update the page as well.

Thanks Peter for the quick feedback!

-- 
Tanu