4.12 GBoxed

• define-g-boxed-cstruct
• define-g-boxed-variant-cstruct
• define-g-boxed-opaque
• g-boxed-opaque
• define-boxed-opaque-accessor
• boxed-related-symbols
• GBoxed foreign type
• copy-boxed-slots-to-foreign
• with-boxed-foreign-array

GObject manual defines this type in the following way:

“GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy and free them, beyond that they are treated as opaque chunks of memory.

Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-GObject based libraries.”

Naturally, it is hard to provide support for “arbitrary C structures”. We support a few useful use cases of GBoxed types:

• Simple C structures. A Lisp structure is a one-to-one correspondence to C structure and is passes to and from foreign code by copying the data it contains. Examples of simple structures are GdkPoint, GdkRectangle.
• “Variant” C structures. A one common idiom of C is to define a union of structures sharing the same parts in order to implement the polymorphism of structures. These structures are mapped to a hierarchy of Lisp structures (where one structure subclasses another via the :include defstruct option).

  For example, Gdk has structure GdkEvent which is a union of GdkEventAny, GdkEventExpose and other structures. These structures have common slots: “type”, “window”, “send_event”. By dispatching on “type”, user or GdkEvent structure knows which of GdkEvent* structures it has and can access other fields.

• Opaque C structures. A C structure the has “hidden” fields and should only created/destroyed with specific functions and be accessed only with specific accessors. Example of such structures is GtkTreePath.