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.

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.

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.