[folks] Make Debug public and restrict it to being a singleton

[Philip Withnall <pwithnall src gnome org>]

commit c5ef70859ff19c46f6e3a08a3816a1fc3e0cb6d2
Author: Philip Withnall <philip tecnocode co uk>
Date:   Mon Apr 25 21:07:38 2011 +0100

    Make Debug public and restrict it to being a singleton
    
    Also add some API documentation to its newly-public members and make it
    thread-safe.

 NEWS             |    1 +
 folks/debug.vala |   80 +++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 57 insertions(+), 24 deletions(-)
---
diff --git a/NEWS b/NEWS
index 4c8295d..ec27064 100644
--- a/NEWS
+++ b/NEWS
@@ -49,6 +49,7 @@ API changes:
 * RoleDetails.roles now has type Set<Role>
 * PotentialMatch.known_email_aliases now has type Set<string>
 * PostalAddress.types now has type Set<string>
+* Add Folks.Debug debug controller class
 
 Overview of changes from libfolks 0.4.0 to libfolks 0.5.0
 =========================================================
diff --git a/folks/debug.vala b/folks/debug.vala
index 5e11cea..ac5f043 100644
--- a/folks/debug.vala
+++ b/folks/debug.vala
@@ -21,7 +21,15 @@
 using GLib;
 using Gee;
 
-internal class Folks.Debug : Object
+/**
+ * Manage debug output and status reporting for all folks objects. All GLib
+ * debug logging calls are passed through a log handler in this class, which
+ * allows debug domains to be outputted according to whether they've been
+ * enabled by being passed to { link Debug.dup}.
+ *
+ * @since UNRELEASED
+ */
+public class Folks.Debug : Object
 {
   private enum Domains {
     /* Zero is used for "no debug spew" */
@@ -30,7 +38,7 @@ internal class Folks.Debug : Object
     KEY_FILE_BACKEND = 1 << 2
   }
 
-  private static weak Debug _instance;
+  private static weak Debug _instance; /* needs to be locked when accessed */
   private HashSet<string> _domains;
   private bool _all = false;
 
@@ -52,40 +60,64 @@ internal class Folks.Debug : Object
           (domain_arg, flags, message) => {});
     }
 
-  internal static Debug dup (string? debug_flags)
+  /**
+   * Create or return the singleton { link Debug} class instance.
+   * If the instance doesn't exist already, it will be created with the given
+   * set of debug domains enabled. Otherwise, the existing instance will have
+   * its set of enabled domains changed to the provided set.
+   *
+   * This function is thread-safe.
+   *
+   * @param debug_flags	A comma-separated list of debug domains to enable,
+   *			or null to disable debug output
+   * @return		Singleton { link Debug} instance
+   * @since UNRELEASED
+   */
+  public static Debug dup (string? debug_flags)
     {
-      var retval = _instance;
-
-      if (retval == null)
+      lock (Debug._instance)
         {
-          /* use an intermediate variable to force a strong reference */
-          retval = new Debug ();
-          _instance = retval;
-        }
+          var retval = Debug._instance;
 
-      retval._all = false;
-      retval._domains = new HashSet<string> (str_hash, str_equal);
+          if (retval == null)
+            {
+              /* use an intermediate variable to force a strong reference */
+              retval = new Debug ();
+              Debug._instance = retval;
+            }
 
-      if (debug_flags != null && debug_flags != "")
-        {
-          var domains_split = debug_flags.split (",");
-          foreach (var domain in domains_split)
+          retval._all = false;
+          retval._domains = new HashSet<string> (str_hash, str_equal);
+
+          if (debug_flags != null && debug_flags != "")
             {
-              var domain_lower = domain.down ();
+              var domains_split = debug_flags.split (",");
+              foreach (var domain in domains_split)
+                {
+                  var domain_lower = domain.down ();
 
-              if (GLib.strcmp (domain_lower, "all") == 0)
-                retval._all = true;
-              else
-                retval._domains.add (domain_lower);
+                  if (GLib.strcmp (domain_lower, "all") == 0)
+                    retval._all = true;
+                  else
+                    retval._domains.add (domain_lower);
+                }
             }
+
+          return retval;
         }
+    }
 
-      return retval;
+  private Debug ()
+    {
+      /* Private constructor for singleton */
     }
 
   ~Debug ()
     {
-      /* manually clear the singleton _instance */
-      _instance = null;
+      /* Manually clear the singleton _instance */
+      lock (Debug._instance)
+        {
+          Debug._instance = null;
+        }
     }
 }