From: Lennart Poettering <lennart@poettering.net>
Date: Sun, 22 Dec 2013 01:35:13 +0000 (+0100)
Subject: spec: introduce new value "const" for EmitsChangedSignal annotation
X-Git-Tag: dbus-1.9.2~31
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e26d35c641d9a14c488d104ea9ca514ed88b76a1;p=thirdparty%2Fdbus.git

spec: introduce new value "const" for EmitsChangedSignal annotation

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=72958
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
---

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 2b8d1f50e..71a8987d0 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -3950,7 +3950,7 @@
            </row>
            <row>
              <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
-             <entry>true,invalidates,false</entry>
+             <entry>true,invalidates,const,false</entry>
              <entry>
                <para>
                  If set to <literal>false</literal>, the
@@ -3959,6 +3959,12 @@
                  linkend="standard-interfaces-properties"/> is not
                  guaranteed to be emitted if the property changes.
                </para>
+               <para>
+                 If set to <literal>const</literal> the property never
+                 changes value during the lifetime of the object it
+                 belongs to, and hence the signal is never emitted for
+                 it.
+               </para>
                <para>
                  If set to <literal>invalidates</literal> the signal
                  is emitted but the value is not included in the
@@ -3975,6 +3981,17 @@
                  defaults to the value specified in the enclosing
                  interface element.
                </para>
+               <para>
+                 This annotation is intended to be used by code
+                 generators to implement client-side caching of
+                 property values. For all properties for which the
+                 annotation is set to <literal>const</literal>,
+                 <literal>invalidates</literal> or
+                 <literal>true</literal> the client may
+                 unconditionally cache the values as the properties
+                 don't change or notifications are generated for them
+                 if they do.
+               </para>
              </entry>
            </row>
          </tbody>