Add glib__private__() API to share between glib,gio; port GWakeup to it

Historically we've added random symbols to the public API with warnings
that they're private; examples are:

glib_gettext(), glib_pgettext()
g_thread_functions_for_glib_use, g_thread_use_default_impl, etc.

And we almost added "GWakeup" to public API just to share between glib and
gio.

This new glib__private__() API exports a hidden vtable, and adds a macro
GLIB_PRIVATE_CALL() that makes it generally convenient to use.

This adds an extremely tiny cost for the double indirection; but it has
the benefit that we don't need to either:

1) compile the code into both glib and gio (like GWakeup), with the
   inefficiency that implies.
2) Export a "do not use this" symbol; the serious problem with this is
   that someone CAN use it pretty easily.  Particularly if we document
   it.  It's far, far harder to peek into a structure without a public
   header file.

https://bugzilla.gnome.org/show_bug.cgi?id=657992

gio/Makefile.am

@@ -278,7 +278,6 @@ libgio_2_0_la_SOURCES =		\
 	gasyncresult.c 		\
 	gbufferedinputstream.c 	\
 	gbufferedoutputstream.c \
-	../glib/gwakeup.c	\
 	gcancellable.c 		\
 	gcontenttype.c 		\
 	gcontenttypeprivate.h 	\

gio/gcancellable.c

@@ -23,7 +23,7 @@
 #include "config.h"
 #include "glib.h"
 #include <gioerror.h>
-#include "gwakeup.h"
+#include "glib-private.h"
 #include "gcancellable.h"
 #include "glibintl.h"
 
@@ -67,7 +67,7 @@ g_cancellable_finalize (GObject *object)
   GCancellable *cancellable = G_CANCELLABLE (object);
 
   if (cancellable->priv->wakeup)
-    g_wakeup_free (cancellable->priv->wakeup);
+    GLIB_PRIVATE_CALL (g_wakeup_free) (cancellable->priv->wakeup);
 
   G_OBJECT_CLASS (g_cancellable_parent_class)->finalize (object);
 }
@@ -277,7 +277,7 @@ g_cancellable_reset (GCancellable *cancellable)
   if (priv->cancelled)
     {
       if (priv->wakeup)
-        g_wakeup_acknowledge (priv->wakeup);
+        GLIB_PRIVATE_CALL (g_wakeup_acknowledge) (priv->wakeup);
 
       priv->cancelled = FALSE;
     }
@@ -406,13 +406,13 @@ g_cancellable_make_pollfd (GCancellable *cancellable, GPollFD *pollfd)
 
   if (cancellable->priv->wakeup == NULL)
     {
-      cancellable->priv->wakeup = g_wakeup_new ();
+      cancellable->priv->wakeup = GLIB_PRIVATE_CALL (g_wakeup_new) ();
 
       if (cancellable->priv->cancelled)
-        g_wakeup_signal (cancellable->priv->wakeup);
+        GLIB_PRIVATE_CALL (g_wakeup_signal) (cancellable->priv->wakeup);
     }
 
-  g_wakeup_get_pollfd (cancellable->priv->wakeup, pollfd);
+  GLIB_PRIVATE_CALL (g_wakeup_get_pollfd) (cancellable->priv->wakeup, pollfd);
 
   G_UNLOCK(cancellable);
 
@@ -452,7 +452,7 @@ g_cancellable_release_fd (GCancellable *cancellable)
   priv->fd_refcount--;
   if (priv->fd_refcount == 0)
     {
-      g_wakeup_free (priv->wakeup);
+      GLIB_PRIVATE_CALL (g_wakeup_free) (priv->wakeup);
       priv->wakeup = NULL;
     }
   G_UNLOCK (cancellable);
@@ -499,7 +499,7 @@ g_cancellable_cancel (GCancellable *cancellable)
   priv->cancelled_running = TRUE;
 
   if (priv->wakeup)
-    g_wakeup_signal (priv->wakeup);
+    GLIB_PRIVATE_CALL (g_wakeup_signal) (priv->wakeup);
 
   G_UNLOCK(cancellable);
 

glib/Makefile.am

@@ -143,6 +143,8 @@ libglib_2_0_la_SOURCES = 	\
 	gkeyfile.c		\
 	glibintl.h		\
 	glib_trace.h		\
+	glib-private.h		\
+	glib-private.c		\
 	glist.c			\
 	gmain-internal.h	\
 	gmain.c	 		\

glib/glib-private.c

@@ -0,0 +1,45 @@
+/* GLIB - Library of useful routines for C programming
+ * Copyright (C) 2011 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Author: Colin Walters <walters@verbum.org>
+ */
+
+#include "gutils.h"
+#include "glib-private.h"
+
+/**
+ * glib__private__:
+ * @arg: Do not use this argument
+ *
+ * Do not call this function; it is used to share private
+ * API between glib, gobject, and gio.
+ */
+GLibPrivateVTable *
+glib__private__ (void)
+{
+  static GLibPrivateVTable table = {
+    g_wakeup_new,
+    g_wakeup_free,
+    g_wakeup_get_pollfd,
+    g_wakeup_signal,
+    g_wakeup_acknowledge
+  };
+ 
+  return &table;
+}
+

glib/glib-private.h

@@ -0,0 +1,48 @@
+/* glib-private.h - GLib-internal private API, shared between glib, gobject, gio
+ * Copyright (C) 2011 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#ifndef __GLIB_PRIVATE_H__
+#define __GLIB_PRIVATE_H__
+
+#include <glib.h>
+
+#include "gwakeup.h"
+
+G_BEGIN_DECLS
+
+#define GLIB_PRIVATE_CALL(symbol) (glib__private__()->symbol)
+
+typedef struct {
+  /* See gwakeup.c */
+  GWakeup *   (*g_wakeup_new)         (void);
+  void        (*g_wakeup_free)        (GWakeup *wakeup);
+  void        (*g_wakeup_get_pollfd)  (GWakeup *wakeup,
+				       GPollFD *poll_fd);
+  void        (*g_wakeup_signal)      (GWakeup *wakeup);
+  void        (*g_wakeup_acknowledge) (GWakeup *wakeup);
+
+  /* Add other private functions here, initialize them in gutils.c */
+} GLibPrivateVTable;
+
+GLibPrivateVTable *glib__private__ (void);
+
+
+G_END_DECLS
+
+#endif /* __G_MAIN_H__ */

glib/glib.symbols

@@ -1344,6 +1344,7 @@ g_get_user_name PRIVATE
 g_get_user_name_utf8
 #endif
 glib_check_version
+glib__private__
 g_nullify_pointer
 g_parse_debug_string
 g_path_get_basename