4.12.7 GBoxed foreign type

     (g-boxed-foreign name &rest option*)
     
     option ::= :return

name

Name of GBoxed type

option

Option of foreign type

:return

An option that identifies the foreign type which is used at return position (as foreign function return type or as a callback return type)

g-boxed-foreign type deals with marshaling data between Lisp code and foreign code. The marshaling follows the following principles:

• All operations on Lisp objects corresponding to GBoxed types are type-safe and should never lead to any form of memory corruption (if some operation is impossible due to e.g., pointer in opaque pointer wrapper being invalidated, error should be signalled)
• Lisp objects should not be manually managed and are properly reclaimed by garbage collector, leaving no memory leaks
• Foreign code can change objects that are passed to them as arguments. This is required for functions that operate by modifying their arguments
• Lisp code in callbacks can change objects that are passed as arguments. This is required to be able to implement interfaces that have functions that operate by modifying their arguments

The :return option is required to be able to properly manage memory of opaque pointer wrappers and propagate changes to foreign and lisp structures.

In order to be able to correctly use g-boxed-foreign foreign type in callbacks, you should use glib-defcallback. This macro is a thin wrapper around cffi:defcallback that adds proper handling of g-boxed-foreign foreign types.

Examples of usage:

     (define-vtable ("GtkTreeModel" c-gtk-tree-model)
       ...
       (tree-model-get-path-impl tree-model-get-path-cb
         (g-boxed-foreign tree-path :return) (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
       (tree-model-get-value-impl tree-model-get-value-cb
         :void (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (n :int) (value (:pointer g-value)))
       (tree-model-iter-next-impl tree-model-iter-next-cb
         :boolean (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
       ...)
     
     (defcfun gtk-text-iter-forward-search :boolean
       (iter (g-boxed-foreign text-iter))
       (str (:string :free-to-foreign t))
       (flags text-search-flags)
       (match-start (g-boxed-foreign text-iter))
       (match-end (g-boxed-foreign text-iter))
       (limit (g-boxed-foreign text-iter)))