Merge branch 'multithreading' of git@dvcs.projects.maemo.org:ContextKit into multithreading

1 files changed, 19 insertions, 15 deletions

diff --git a/libcontextsubscriber/src/contextproperty.cpp b/libcontextsubscriber/src/contextproperty.cpp
index 5c267c9d..8944c3a6 100644
--- a/libcontextsubscriber/src/contextproperty.cpp
+++ b/libcontextsubscriber/src/contextproperty.cpp
@@ -173,20 +173,23 @@ struct ContextPropertyPrivate
    creation of ContextPropertys with calls to waitForSubscription()
    would prevent this optimization.
 
-   \note The \c ContextProperty class is not thread safe, but
-   reentrant.  This means, that you can create a new ContextProperty
-   class in any thread, but you should only use it from the same
-   thread through its lifetime.  If needed, you can use \c QObject's
-   \c moveToThread method.  Please note that the \c valueChanged()
-   signal has to be connected via \c QueuedConnection if the property
-   is not created in the \c QApplication's main thread (this setting
-   is the default).  Because of the queued connection the thread of
-   the \c ContextProperty has to have an event loop running to get the
-   slots connected to the valueChange signal called.
+   \note The \c ContextProperty class follows the usual QObject rules
+   for non-GUI classes in multi-threaded programs.  In Qt terminology,
+   the ContextProperty class is reentrant but not thread-safe.  This
+   means that you can create ContextProperty instances in any thread
+   and then freely use these instance in their threads, but you can
+   not use a single instance concurrently from multiple threads.
+
+   \note Please pay special attention to how signals and slots work in
+   a multi-threaded program: by default, a slot is emitted in the
+   thread that called QObject::connect().  For this to happen
+   reliably, the thread needs to run a event loop.
+
+   \note See the Qt documentation for \c QThread and related classes
+   for more details.
  */
 
-/// Constructs a new ContextProperty for \a key (e.g. Screen.TopEdge)
-/// and subscribes to it.
+/// Constructs a new ContextProperty for \a key and subscribes to it.
 ContextProperty::ContextProperty(const QString &key, QObject* parent)
     : QObject(parent), priv(0)
 {
@@ -283,9 +286,10 @@ void ContextProperty::waitForSubscription() const
     }
 }
 
-/// Sets all of the ContextProperty instaces immune to 'commanding'
-/// (overriding values done by Context Commander).  If you use this
-/// method, you have to use it before starting any threads.
+/// Sets all of the ContextProperty instances immune to 'external
+/// commanding'.  This is only intended to be used by the Context
+/// Commander itself, so that it can use ContextProperties without
+/// tripping over itself.  Don't use this.
 void ContextProperty::ignoreCommander()
 {
     PropertyHandle::ignoreCommander();