After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 795062 - Incorrect documentation about GSettings child add/remove notifications
Incorrect documentation about GSettings child add/remove notifications
Status: RESOLVED OBSOLETE
Product: glib
Classification: Platform
Component: gsettings
2.56.x
Other All
: Normal normal
: ---
Assigned To: gtkdev
gtkdev
Depends on:
Blocks:
 
 
Reported: 2018-04-08 05:30 UTC by Tanu Kaskinen
Modified: 2018-05-24 20:23 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
GSettings: Don't mention nonexistent signal in doc (1.05 KB, patch)
2018-04-09 13:16 UTC, Daniel Boles
committed Details | Review

Description Tanu Kaskinen 2018-04-08 05:30:05 UTC
g_settings_get_children() has this sentence in its documentation:

    For GSettings objects that are lists, this value can change at any time
    and you should connect to the "children-changed" signal to watch for
    those changes.

First of all, I don't understand what it means for a GSettings object to be a list. Does that have to be declared in some special way in the schema, or is the object a list just because the application uses it as a list (i.e. containing a variable number of childern of the same type)? I didn't find an answer to this in the documentation.

The main problem with the sentence, however, is that the "children-changed" signal doesn't exist. I grepped the glib source code and this is the only place where the string "children-changed" appears.

How are applications supposed to get notifications about new and removed children? Can the "change-event" signal be used for that? Or is it actually impossible to create children dynamically, i.e. all children should be declared in the schema?
Comment 1 Christian Persch 2018-04-08 10:17:49 UTC
The children-changed signal would have been added by bug 622126, but that's not done and probably won't ever be done.

So this paragraph should be excised from the docs.
Comment 2 Tanu Kaskinen 2018-04-08 12:04:42 UTC
Ok, so I'll have to make do with static objects.

This paragraph might need some improvement as well:

    Normally, a schema has a fixed path that determines where the settings
    are stored in the conceptual global tree of settings. However, schemas
    can also be 'relocatable', i.e. not equipped with a fixed path. This
    is useful e.g. when the schema describes an 'account', and you want to
    be able to store a arbitrary number of accounts.

The example of "arbitrary number of accounts" gives the impression that the objects don't need to be predefined in the schema.
Comment 3 Daniel Boles 2018-04-09 13:12:48 UTC
(In reply to Christian Persch from comment #1)
> The children-changed signal would have been added by bug 622126, but that's
> not done and probably won't ever be done.
> 
> So this paragraph should be excised from the docs.

It was rather added here:

commit 77e3badcf3f15c7ac235904160d775febfcebcb5
Author: Ryan Lortie <desrt@desrt.ca>
Date:   Mon Sep 6 12:47:37 2010 -0400

    split GSettings.list_items => list_{children,keys}

    This is an incompatible public API/ABI change.


(In reply to Tanu Kaskinen from comment #2)
> The example of "arbitrary number of accounts" gives the impression that the
> objects don't need to be predefined in the schema.

What does "an object being predefined" mean? Only the structure need be defined, and instances of it can be located at any path, hence being relocatable. Generally, if you think something needs improved, you should suggest how. :P
Comment 4 Daniel Boles 2018-04-09 13:16:28 UTC
Created attachment 370688 [details] [review]
GSettings: Don't mention nonexistent signal in doc

1000 hours in vim
Comment 5 Philip Withnall 2018-04-09 13:33:24 UTC
Review of attachment 370688 [details] [review]:

Yup
Comment 6 Tanu Kaskinen 2018-04-09 16:34:10 UTC
(In reply to Daniel Boles from comment #3)
> (In reply to Tanu Kaskinen from comment #2)
> > The example of "arbitrary number of accounts" gives the impression that the
> > objects don't need to be predefined in the schema.
> 
> What does "an object being predefined" mean? Only the structure need be
> defined, and instances of it can be located at any path, hence being
> relocatable. Generally, if you think something needs improved, you should
> suggest how. :P

"An object being predefined" means that it's in the schema. Note that a relocatable schema is useful even if all objects are predefined, because a relocatable schema can be reused by multiple objects (by using <child>).

You seem to be saying that it's actually possible to create objects without declaring them in the schema XML. I guess this can be done with g_settings_new_with_path(). However, if application A does that, there appears to be no mechanism to get notified in application B about the new object. And I don't see any way to remove objects. So if dynamic objects are supported, the support is rather limited.

Regarding the patch, it's an improvement, but the paragraph still talks about a race condition in case an object is removed between the g_settings_list_children() and g_settings_get_child() calls. Can that actually happen? Or should the documentation be changed? Or maybe the documentation should keep the warning, because maybe some day the support for removing objects will be implemented. Also, what does "GSettings objects that are lists" mean, given that the GSettingsList implementation was never finished?
Comment 7 Daniel Boles 2018-04-09 17:22:59 UTC
To me, an "object" means an *instance* of a relocatable schema, e.g. one account from the "arbitrary number of accounts" you originally quoted. So the schema needs declared, obviously, but individual instances of it do not. Of course, this works, as I can attest personally.

The support may be limited. I don't know as it has done everything I've personally needed so far. But this bug is about "Incorrect documentation", not limited support for doing dynamic stuff with relocatable schemas and their instances; if you want the latter, please open a new bug. Until then, feel free to suggest further improvements to the docs here.
Comment 8 Philip Withnall 2018-04-09 17:25:26 UTC
(In reply to Daniel Boles from comment #7)
> But this bug is about "Incorrect documentation",
> not limited support for doing dynamic stuff with relocatable schemas and
> their instances; if you want the latter, please open a new bug.

Actually, just subscribe to bug #622126, which directly concerns listing relocatable schema paths.
Comment 9 Tanu Kaskinen 2018-04-09 17:51:53 UTC
(In reply to Daniel Boles from comment #7)
> The support may be limited. I don't know as it has done everything I've
> personally needed so far. But this bug is about "Incorrect documentation",
> not limited support for doing dynamic stuff with relocatable schemas and
> their instances; if you want the latter, please open a new bug. Until then,
> feel free to suggest further improvements to the docs here.

Sorry for not having provided very concrete suggestions for improvements. I'm new to GSettings, so I need to understand what it can and what it can't do before I know what the documentation should say.

I suppose there's not much strictly incorrect stuff left. I have some suggestions for improving this paragraph:

    For GSettings objects that are lists, this value can change at any time.
    Note that there is a race condition here: you may request a child after
    listing it only for it to have been destroyed in the meantime. For this
    reason, g_settings_get_child() may return NULL even for a child that was
    listed by this function.

I think "For GSettings objects that are lists" can be simply removed. As far as I can tell, there's no special list kind of GSettings objects. Any GSettings object can have its children removed.

A note could be added that explains how the race condition is possible: "Children can't be removed by using the GSettings interface itself, but the backend may support object removal, so if the backend is accessed by some other means than GSettings, children can get removed at any time." This is pure speculation on my part, since I don't know how the backends work.

Another useful note: "Getting notifications about added or removed children is not currently possible."
Comment 10 GNOME Infrastructure Team 2018-05-24 20:23:26 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to GNOME's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/glib/issues/1362.