GLib/GObject/Pango structure review

[Owen Taylor <otaylor redhat com>]

I just finished doing a review of GLib/GObject/Pango structures for the ability
to do extensions in a  API/ABI compatible fashion.

Structures that present problems in this regard are listed below; many or most
of these are actually API limitations, e.g., there is no way we could extend
GSourceFuncs, because source creation looks like:

  source = g_source_new (&g_timeout_funcs, sizeof (GTimeoutSource));

So, there is no way of knowing what fields in g_timeout_funcs are valid.

To prevent similar problems in the future, I'll suggest that where possible,
we should either avoid the use of structures allocated by the user, or stick
to one of the following patterns:

Initialization function::

 struct _MyFooFuncs 
 {
   void (func_a *) (MyFoo *my_foo);
   void (func_b *) (MyFoo *my_foo);
 };

 typedef (*MyFooInit) (MyFooFuncs *funcs,
                       gpointer    init_data);

 MyFoo *my_foo_new (MyFooInit *init,
                    gpointer   init_data);

Flags for passing in attributes:

 struct _MyFooAttributes 
 {
   int a;
   int b;
 };

 typedef enum {
   MY_FOO_A,
   MY_FOO_B,
 } MyFooFlags;
  
 void my_foo_new (MyFooAttributes *attributes, 
                  MyFooFlags       flags);
 
Flags for querying:

 void my_foo_query (MyFoo           *foo,
                    MyFooAttributes *attributes, 
                    MyFooFlags       flags);
 
Client data pointers for "inheritence" (where possible, use GObject instead):

 struct _MyFoo {
   gpointer client_data;

  /*< private >*/
  [...]
 };

 MyFoo *my_foo_new (MyFooInit *init,
                    gpointer   init_data,
                    gpointer   client_data);

Where none of the above is practical, like GtkItemFactoryEntry, we'll just have to be
willing to go with GtkItemFactoryEntryEx if necessary.

Structures like GdkRectangle that have a natural set of fields are clearly exempt
from these comments.

Regards,
                                                Owen


GLib:

  GHook
  GHookList
  GIOChannel
  GIOFuncs
  GMarkupParser
  GMemVTable
  GSource
  GSourceCallbackFuncs
  GSourceFuncs
  GScannerConfig
  GStaticPrivate
  GStaticRecMutex
  GStaticRWLock
  GThread
  GThreadFunctions
  GDebugKey

GObject:

  GClosure
  GEnumValue
  GFlagsValue
  GInterfaceInfo
  GParamSpecTypeInfo
  GTypeFundamentalInfo
  GSignalQuery
  GTypeInfo
  GTypeValueTable
  GTypeQuery

  GEnumClass
  GFlagsClass
  GParamSpecClass
  GTypeInterface

Pango:

  PangoAnalysis
  PangoAttribute
  PangoAttrClass
  PangoItem
  PangoGlyphGeometry
  PangoGlyphInfo

  ENABLE_BACKEND
  PangoFontMetrics
  PangoIncludedModule

  ENABLE_ENGINE
  PangoEngine
  PangoEngineLang
  PangoEngineInfo
  PangoEngineRange
  PangoEngineShape
  PangoIndicScript