Client example: improve commentary

Change-Id: Ibe197b04e362069c3c4d129aad2f6bdf769c8bb7
Signed-off-by: Michal Bloch <m.bloch@samsung.com>

diff --git a/clientExample/app/main.cpp b/clientExample/app/main.cpp
index 59291da..09a1090 100644 (file)
--- a/clientExample/app/main.cpp
+++ b/clientExample/app/main.cpp
@@ -99,9 +99,14 @@ void test_reply_removeuser_callback(int result, void *cb_data)
 {
        assert(cb_data);
 
-       /* NB: no mutex or waiting here. The callback is ran
+       /* NB: no conditional vars here. The callback is ran
         * asynchronously via the main loop. See below,
-        * especially `wait_for_all_pending_callbacks`. */
+        * especially `wait_for_all_pending_callbacks`.
+        *
+        * Again, this is an example so you can still run
+        * this sync like the add_user example, and of course
+        * you may still need thread-safety for data access,
+        * such as with the atomic var below. */
 
        g_atomic_int_inc(&callback_pending_reference);
 
@@ -136,7 +141,11 @@ bool switch_user_test(int user_id)
        }
 
        /* The wait has to be in a loop because of
-        * spurious wakeups, this is a glib issue.
+        * spurious wakeups, this is a general issue
+        * with conditional vars (but keep in mind
+        * it's still better than the alternative as
+        * glib mutexes have undefined behaviour if
+        * locked twice from the same thread).
         *
         * Of course you can use any synchronisation
         * mechanism you want, including none at all. */
@@ -154,6 +163,10 @@ bool switch_user_test(int user_id)
 
 bool switch_to_each_user_to_generate_events()
 {
+       /* A real-world program will probably just want to switch
+        * to a single specific user; here we are running the gamut
+        * just to generate a bunch of events to show the handlers. */
+
        for (int i = firstUser; i <= lastUser; ++i) {
                if (!switch_user_test(i)) {
                        printf("Failed to switch user\n");