Serialize

Serialize — Serialisers and deserialisers

Functions

Types and Values

Includes

#include <libgwyddion/gwyddion.h>

Description

Methods of GwySerializable abstract from the precise byte-for-byte representation of serialised objects. It is conceivable to imagine using for instance HDF5 or XML as the binary format. Functions available here at this moment, however, implement the GWY binary data format, version 3.

Note the initial reference counts 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.

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 calulcate the number of named data items they will serialise to (or provide a reasonable upper estimate of this number). This is done simply by calling gwy_serializable_n_items() on the top-level object, objects that contain other objects must call gwy_serializable_n_items() on these contained objects and sum the results.

Second, a GwySerializableItems item list is created, with size calculated in the first step. All objects are then recursively asked to add items representing their data to this list. This is done simply by calling gwy_serializable_itemize() on the top-level object. The objects may sometimes need to represent certain data differently than the internal representation is, however, expensive transforms should be avoided, especially for arrays. This step can allocate temporary structures.

Third, sizes of each object are calcuated and stored into the object-header items created by gwy_serializable_itemize(). This again is done recursively, but the objects do not participate, the calculation works with the itemised list. This step might not be necessary for other storage formats.

Subsequently, the object tree flattened into an item list is written to the output stream, 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 for all objects. This step frees the temporary storage allocated in the itemization step, if any. This is not done recursively so that objects need not to implement this method, even if they contain other objects, if they themselves do not create any temporary data during itemize(). The methods are called in the inverse order than the objects appear in the list, i.e. the most inner and last objects are processed first. This means that if done() of an object is invoked, all its contained objects have been already processed. At the very end the item list is freed too.

Functions

gwy_deserialize_error_quark()

GQuark
gwy_deserialize_error_quark (void);

Gets the error domain for deserialisation.

See and use GWY_DESERIALIZE_ERROR.

Returns

The error domain.


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.

Parameters

serializable

A serialisable object.

 

output

Output stream to write the serialised object to.

 

error

Location to store the error occuring, NULL to ignore. Errors from G_IO_ERROR domain can occur.

 

Returns

TRUE if the operation succeeded, FALSE if it failed.


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.

Parameters

buffer

Memory containing the serialised representation of one object.

 

size

Size of buffer in bytes. If the buffer is larger than the object representation, non-fatal GWY_DESERIALIZE_ERROR_PADDING will be reported.

 

bytes_consumed

Location to store the number of bytes actually consumed from buffer , or NULL.

 

error_list

Location to store the errors occuring, NULL to ignore. Errors from GWY_DESERIALIZE_ERROR domain can occur.

 

Returns

Newly created object on success, NULL on failure.

[transfer full][allow-none]

Types and Values

GWY_DESERIALIZE_ERROR

#define GWY_DESERIALIZE_ERROR gwy_deserialize_error_quark()

Error domain for deserialisation.

Errors in this domain will be from the GwyDeserializeError enumeration. See GError for information on error domains.


enum GwyDeserializeError

Error codes returned by deserialisation.

In the error code descriptions, fatal error means aborting of deserialisation of the object that is just being unpacked. Non-fatal errors are competely recoverable. If the deserialisation of a contained object is aborted, the unpacking of the container object still continues. Therefore, fatal errors are truly fatal only if they occur for the top-level object.

Members

GWY_DESERIALIZE_ERROR_PADDING

There is too much data to represent given object. This error is non-fatal: the extra data is just ignored.

 

GWY_DESERIALIZE_ERROR_ITEM

Unexpected item was encountered. This error is non-fatal: such item is just ignored.

 

GWY_DESERIALIZE_ERROR_REPLACED

Invalid information (for instance an out-of-bounds value) was encountered and replaced (for instance by a default value). This error is non-fatal. Implementations should use it when they encounter invalid information but are able to proceed.

 

GWY_DESERIALIZE_ERROR_FATAL_MASK

Distinguishes fatal and non-fatal errors (fatal give non-zero value when masked with this mask).

 

GWY_DESERIALIZE_ERROR_TRUNCATED

Data ends in the middle of some item or there is not enough data to represent given object. This error is fatal.

 

GWY_DESERIALIZE_ERROR_SIZE_T

Size is not representable on this system. This can occur on legacy 32bit systems, however, they are incapable of holding such large data in core anyway. This error is fatal.

 

GWY_DESERIALIZE_ERROR_OBJECT

Representation of an object of unknown or deserialisation-incapable type was found. This error is fatal.

 

GWY_DESERIALIZE_ERROR_DATA

Uknown data type (GwySerializableCType) was encountered. This error is fatal.

 

GWY_DESERIALIZE_ERROR_UTF8

Serialised string is not valid UTF-8. This error is fatal.

 

GWY_DESERIALIZE_ERROR_INVALID

Object representation is logicaly inconsistent or otherwise invalid. Reserved for classes to indicate data errors on levels higher than physical representation. This error is fatal.

 

See Also

GwySerializable