Details of Serialization

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 occurs in several steps.

First, all objects are recursively asked to represent themselves as GwySerializableGroup, which is a list of items. The groups can contain nested groups in v_group item values to represent object- and boxed-valued components. The creation of the items may require the allocation of temporary data structures, if the internal object representation does not match the serialised representation. This step is independent on the serialisation backend format.

Second, the top-level group is written to the output stream, recusring to contiained groups, byte-swapping or otherwise normalizing the data on the fly if necessary. This part strongly depends on the storage format.

Finally, virtual method done() is called on all objects in the tree which define it. This step frees the temporary storage allocated in the itemisation step, if any. It is done in reverse order of which the objects have been serialised, although this should not matter. The serialiser does the recursion. Hence, objects do not need to implement done() if do not needed themselves but some of their member objects might. At the very end the groups are freed too.

gwy_serialize_gio()

gboolean
gwy_serialize_gio (GwySerializable *serializable,
                   GOutputStream *output,
                   GError **error);

Serialises an object to GIO stream in GWY format.

The data writing employs internal buffering. If the output stream is already buffered (e.g., GBufferedOutputStream), the output will be unnecessarily buffered twice.

gwy_serialize_group_gio()

gboolean
gwy_serialize_group_gio (GwySerializableGroup *group,
                         GwySerializeSizeType sizetype,
                         GOutputStream *output,
                         GError **error);

Serialises itemised data to GIO stream in GWY format.

This is low-level function, mean when group was created or modified manually or the itemisation was run separately for some other reason. Use gwy_serialize_gio() for normal object serialisation. Remember to call gwy_serializable_group_done() on the group and gwy_serializable_done() on the top-level object if needed. This function only carries out the serialisation to an output stream.

The data writing employs internal buffering. If the output stream is already buffered (e.g., GBufferedOutputStream), the output will be unnecessarily buffered twice.