[glib: 3/4] gobject: Add advice on larger alignment requirements for GObject members

[Philip Withnall <pwithnall src gnome org>]

commit 7a8756d247a5c54be121668919ae9cac2f8ae4fb
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Dec 8 14:57:28 2017 +0000

    gobject: Add advice on larger alignment requirements for GObject members
    
    We now guarantee that GObjects will always be allocated at least as
    aligned as the basic types. If you want to put an element in your
    GObject which has higher alignment requirements, we can’t guarantee it
    will be aligned*. If you need it to be aligned, you’ll need to put it on
    the heap (aligned appropriately), or add appropriate padding in your
    GObject struct.
    
    *Actually, GSlice will guarantee that the whole GObject is aligned to at
    least the power of 2 greater than or equal to the size of the GObject,
    which means any element in the GObject struct should always be
    appropriate aligned if the compiler pads it appropriately. If malloc()
    is used, however, it doesn’t make that guarantee, so we can’t make that
    guarantee overall.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    Helps: #1231

 gobject/gobject.c | 4 +++-
 gobject/gobject.h | 6 +++++-
 gobject/gtype.h   | 4 +++-
 3 files changed, 11 insertions(+), 3 deletions(-)
---
diff --git a/gobject/gobject.c b/gobject/gobject.c
index ac94454cd..7499d2ec4 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -1798,7 +1798,9 @@ g_object_get_type (void)
  *
  * Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the
  * alignment of the largest basic GLib type (typically this is #guint64 or
- * #gdouble).
+ * #gdouble). If you need larger alignment for an element in a #GObject, you
+ * should allocate it on the heap (aligned), or arrange for your #GObject to be
+ * appropriately padded.
  *
  * Returns: (transfer full) (type GObject.Object): a new instance of
  *   @object_type
diff --git a/gobject/gobject.h b/gobject/gobject.h
index 8bcb0cdbc..3dc4f7f48 100644
--- a/gobject/gobject.h
+++ b/gobject/gobject.h
@@ -256,7 +256,11 @@ typedef void (*GWeakNotify)                (gpointer      data,
  *
  * Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the
  * alignment of the largest basic GLib type (typically this is #guint64 or
- * #gdouble).
+ * #gdouble). If you need larger alignment for an element in a #GObject, you
+ * should allocate it on the heap (aligned), or arrange for your #GObject to be
+ * appropriately padded. This guarantee applies to the #GObject (or derived)
+ * struct, the #GObjectClass (or derived) struct, and any private data allocated
+ * by G_ADD_PRIVATE().
  */
 struct  _GObject
 {
diff --git a/gobject/gtype.h b/gobject/gtype.h
index cb79caa82..5c9077745 100644
--- a/gobject/gtype.h
+++ b/gobject/gtype.h
@@ -1983,7 +1983,9 @@ guint     g_type_get_type_registration_serial (void);
  *
  * Since GLib 2.72, the returned `MyObjectPrivate` pointer is guaranteed to be
  * aligned to at least the alignment of the largest basic GLib type (typically
- * this is #guint64 or #gdouble).
+ * this is #guint64 or #gdouble). If you need larger alignment for an element in
+ * the struct, you should allocate it on the heap (aligned), or arrange for your
+ * `MyObjectPrivate` struct to be appropriately padded.
  *
  * Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
  * macros, since it depends on variable names from those macros.