Details of Deserialization

The following information is not necessary for implementing GwySerializable interface in your classes, but it can help prevent wrong decision about serialised representation of your objects. Also, it might help implementing a different serialisation backend than GWY files.

Serialization has two basic steps.

First, the serialised buffer is parse into a tree of GwySerializableGroup, using v_group for nested objects. This step checks basic validity of the serialised representation. If it succeeds, the GwySerializableGroup tree is well-formed, although it may not represent valid Gwyddion object data. If only this step is run, it can also be used to represent other things than Gwyddion files. This is also the only backend-depndent step which would be implemented differently for HDF5 as the serialisation format, for instance.

Second, objects are reconstructed from the tree in a depth-first order. When an object's GwySerializable construct() method is called, its object- and boxed-valued components have already been constructed and it can get them by reading v_object or v_boxed values of GwySerializableValue.

There is also some cleanup. But it is done during the second step, not as a separate pass.

gwy_deserialize_memory()

GObject *
gwy_deserialize_memory (const guchar *buffer,
                        gsize size,
                        gsize *bytes_consumed,
                        GwyErrorList **error_list);

Deserialises an object in GWY format from plain memory buffer.

The initial references of restored objects are according to their nature. For instance, a GInitiallyUnowned will have a floating reference, a plain GObject will have a reference count of 1, etc.

Deserialization sidesteps the typical object creation somewhat. It needs to construct an object given its class name, and for that the type has to be already registered in the GObject type system. Library initialisation functions such as gwy_init() or gwy_app_init() normally take care of it. If you introduce your own serialisable objects (or avoid the initialisation functions for some reason), force the registration of all relevant types for instance by calling g_type_class_peak(MY_TYPE_WHATEVER).

Errors from GWY_DESERIALIZE_ERROR domain can always occur in error_list . For most objects, these are the only errors that can occur. However, special objects can report more specific non-fatal errors from their own domain. For example, GwyFile does.

gwy_deserialize_group_memory()

GwySerializableGroup *
gwy_deserialize_group_memory (const guchar *buffer,
                              gsize size,
                              GwySerializeSizeType sizetype,
                              GwyErrorList **error_list);

Deserialises GWY format from plain memory buffer to itemised representation.

This is a low-level function. Usually, you use a function such as gwy_deserialize_memory() to immediately construct the object. For this function, the serialised data must be well-formed but are not required to represent actual Gwyddion objects. This is only required when objects are constructed from the itemised representation – which can, however, be used for other purposes if needed.

The number of bytes consumed can be obtained by looking at the byte size of the returned group.

Object and item names (and possibly other data as well) in the returned group can simply be pointers inside buffer . Therefore, buffer must outlive the group.

gwy_deserialize_construct()

GObject *
gwy_deserialize_construct (GwySerializableGroup *group,
                           GwyErrorList **error_list);

Creates an object from itemised representation.

This is a low-level function. Usually, you use a function such as gwy_deserialize_memory() to immediately construct the object.

The initial references of restored objects are according to their nature. For instance, a GInitiallyUnowned will have a floating reference, a plain GObject will have a reference count of 1, etc.