Non-instantiatable classed types: interfaces: GObject Reference Manual

## Non-instantiatable classed types: interfaces

This section covers the theory behind interfaces. See How to define and implement interfaces for the recommended way to define an interface.

GType's interfaces are very similar to Java's interfaces. They allow to describe a common API that several classes will adhere to. Imagine the play, pause and stop buttons on hi-fi equipment — those can be seen as a playback interface. Once you know what they do, you can control your CD player, MP3 player or anything that uses these symbols. To declare an interface you have to register a non-instantiatable classed type which derives from GTypeInterface. The following piece of code declares such an interface.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    #define VIEWER_TYPE_EDITABLE viewer_editable_get_type ()
    G_DECLARE_INTERFACE (ViewerEditable, viewer_editable, VIEWER, EDITABLE, GObject)

    struct _ViewerEditableInterface {
      GTypeInterface parent;

      void (*save) (ViewerEditable  *self,
                    GError         **error);
    };

    void viewer_editable_save (ViewerEditable  *self,
                               GError         **error);

The interface function, `viewer_editable_save` is implemented in a pretty simple way:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    void
    viewer_editable_save (ViewerEditable  *self,
                          GError         **error)
    {
      ViewerEditableinterface *iface;

      g_return_if_fail (VIEWER_IS_EDITABLE (self));
      g_return_if_fail (error == NULL || *error == NULL);

      iface = VIEWER_EDITABLE_GET_IFACE (self);
      g_return_if_fail (iface->save != NULL);
      iface->save (self);
    }

`viewer_editable_get_type` registers a type named ViewerEditable which inherits from G_TYPE_INTERFACE. All interfaces must be children of G_TYPE_INTERFACE in the inheritance tree.

An interface is defined by only one structure which must contain as first member a GTypeInterface structure. The interface structure is expected to contain the function pointers of the interface methods. It is good style to define helper functions for each of the interface methods which simply call the interface's method directly: `viewer_editable_save` is one of these.

If you have no special requirements you can use the G_IMPLEMENT_INTERFACE macro to implement an interface:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    static void
    viewer_file_save (ViewerEditable *self)
    {
      g_print ("File implementation of editable interface save method.\n");
    }

    static void
    viewer_file_editable_interface_init (ViewerEditableInterface *iface)
    {
      iface->save = viewer_file_save;
    }

    G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, VIEWER_TYPE_FILE,
                             G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
                                                    viewer_file_editable_interface_init))

If your code does have special requirements, you must write a custom `get_type` function to register your GType which inherits from some GObject and which implements the interface ViewerEditable. For example, this code registers a new ViewerFile class which implements ViewerEditable:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    static void
    viewer_file_save (ViewerEditable *editable)
    {
      g_print ("File implementation of editable interface save method.\n");
    }

    static void
    viewer_file_editable_interface_init (gpointer g_iface,
                                         gpointer iface_data)
    {
      ViewerEditableInterface *iface = g_iface;

      iface->save = viewer_file_save;
    }

    GType
    viewer_file_get_type (void)
    {
      static GType type = 0;
      if (type == 0) {
        const GTypeInfo info = {
          sizeof (ViewerFileClass),
          NULL,   /* base_init */
          NULL,   /* base_finalize */
          NULL,   /* class_init */
          NULL,   /* class_finalize */
          NULL,   /* class_data */
          sizeof (ViewerFile),
          0,      /* n_preallocs */
          NULL    /* instance_init */
        };
        const GInterfaceInfo editable_info = {
          (GInterfaceInitFunc) viewer_file_editable_interface_init,  /* interface_init */
          NULL,   /* interface_finalize */
          NULL    /* interface_data */
        };
        type = g_type_register_static (VIEWER_TYPE_FILE,
                                       "ViewerFile",
                                       &info, 0);
        g_type_add_interface_static (type,
                                     VIEWER_TYPE_EDITABLE,
                                     &editable_info);
      }
      return type;
    }

`g_type_add_interface_static` records in the type system that a given type implements also FooInterface (`foo_interface_get_type` returns the type of FooInterface). The GInterfaceInfo structure holds information about the implementation of the interface:

    1
    2
    3
    4
    5
    6
    struct _GInterfaceInfo
    {
      GInterfaceInitFunc     interface_init;
      GInterfaceFinalizeFunc interface_finalize;
      gpointer               interface_data;
    };

### Interface Initialization

When an instantiatable classed type which implements an interface (either directly or by inheriting an implementation from a superclass) is created for the first time, its class structure is initialized following the process described in the section called “Instantiatable classed types: objects”. After that, the interface implementations associated with the type are initialized.

First a memory buffer is allocated to hold the interface structure. The parent's interface structure is then copied over to the new interface structure (the parent interface is already initialized at that point). If there is no parent interface, the interface structure is initialized with zeros. The `g_type` and the `g_instance_type` fields are then initialized: `g_type` is set to the type of the most-derived interface and `g_instance_type` is set to the type of the most derived type which implements this interface.

The interface's `base_init` function is called, and then the interface's `default_init` is invoked. Finally if the type has registered an implementation of the interface, the implementation's `interface_init` function is invoked. If there are multiple implementations of an interface the `base_init` and `interface_init` functions will be invoked once for each implementation initialized.

It is thus recommended to use a `default_init` function to initialize an interface. This function is called only once for the interface no matter how many implementations there are. The `default_init` function is declared by G_DEFINE_INTERFACE which can be used to define the interface:

    1
    2
    3
    4
    5
    6
    7
    G_DEFINE_INTERFACE (ViewerEditable, viewer_editable, G_TYPE_OBJECT)

    static void
    viewer_editable_default_init (ViewerEditableInterface *iface)
    {
      /* add properties and signals here, will only be called once */
    }

Or you can do that yourself in a GType function for your interface:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    GType
    viewer_editable_get_type (void)
    {
      static gsize type_id = 0;
      if (g_once_init_enter (&type_id)) {
        const GTypeInfo info = {
          sizeof (ViewerEditableInterface),
          NULL,   /* base_init */
          NULL,   /* base_finalize */
          viewer_editable_default_init, /* class_init */
          NULL,   /* class_finalize */
          NULL,   /* class_data */
          0,      /* instance_size */
          0,      /* n_preallocs */
          NULL    /* instance_init */
        };
        GType type = g_type_register_static (G_TYPE_INTERFACE,
                                             "ViewerEditable",
                                             &info, 0);
        g_once_init_leave (&type_id, type);
      }
      return type_id;
    }

    static void
    viewer_editable_default_init (ViewerEditableInterface *iface)
    {
      /* add properties and signals here, will only called once */
    }

In summary, interface initialization uses the following functions:

Table 2. Interface Initialization

Invocation time | Function Invoked | Function's parameters | Remark
--- | --- | --- | ---
First call to `g_type_create_instance` for any type implementing interface | interface's `base_init` function | On interface's vtable | Rarely necessary to use this. Called once per instantiated classed type implementing the interface.
First call to `g_type_create_instance` for each type implementing interface | interface's `default_init` function | On interface's vtable | Register interface's signals, properties, etc. here. Will be called once.
First call to `g_type_create_instance` for any type implementing interface | implementation's `interface_init` function | On interface's vtable | Initialize interface implementation. Called for each class that that implements the interface. Initialize the interface method pointers in the interface structure to the implementing class's implementation.

### Interface Destruction

When the last instance of an instantiatable type which registered an interface implementation is destroyed, the interface's implementations associated to the type are destroyed.

To destroy an interface implementation, GType first calls the implementation's `interface_finalize` function and then the interface's most-derived `base_finalize` function.

Again, it is important to understand, as in the section called “Interface Initialization”, that both `interface_finalize` and `base_finalize` are invoked exactly once for the destruction of each implementation of an interface. Thus, if you were to use one of these functions, you would need to use a static integer variable which would hold the number of instances of implementations of an interface such that the interface's class is destroyed only once (when the integer variable reaches zero).

The above process can be summarized as follows:

Table 3. Interface Finalization

Invocation time | Function Invoked | Function's parameters
--- | --- | ---
Last call to `g_type_free_instance` for type implementing interface | interface's `interface_finalize` function | On interface's vtable
interface's `base_finalize` function | On interface's vtable