Serializable boxed

Serializable boxed — Making boxed types serialisable

Functions

Types and Values

Includes

#include <libgwyddion/gwyddion.h>

Description

The serialisable boxed protocol is an analogue of the serialisable object protocol described in section GwySerializable where more detailed discussion of the concept can be found. The protocol is intended for simple structs that do not do their own memory management and typically can be bitwise copied. Complex data should be represented as objects.

Boxed structs can be serialised as parts of objects. The top-level item of a serialised representation must be always an object. Also, serialisable boxed structs may contain only atomic types (FIXME: this is not enforced by the implementation at this moment).

Functions

gwy_boxed_type_is_serializable()

gboolean
gwy_boxed_type_is_serializable (GType type);

Determines if a type supports the boxed serialisable protocol.

Parameters

type

Type to query. Any GType may be given, not just boxed types.

 

Returns

TRUE if type was registered as serialisable boxed type, FALSE if it was not.


gwy_serializable_boxed_register_static()

void
gwy_serializable_boxed_register_static
                               (GType type,
                                const GwySerializableBoxedInfo *info);

Registers a serialisable boxed type.

A boxed type must be registered before it can be deserialised. Usually this function is called in gwy_foo_get_type() for the type although it is possible to register foreign boxed types as serialisable. They must be registered soon enough then.

Standard Gwyddion boxed serialisable types are registered by gwy_type_init(), i.e. at the very latest when deserialization is attempted.

Parameters

type

Boxed type to register as serialisable.

 

info

Information how the type implements the serialization protocol. It is not not copied; hence info must be static data or allocated on heap and never freed.

 

gwy_serializable_boxed_assign()

void
gwy_serializable_boxed_assign (GType type,
                               gpointer destination,
                               gconstpointer source);

Copies the value of a boxed struct to another boxed struct.

Parameters

type

Type of destination and source . It must be a serialisable boxed type.

 

destination

Pointer to boxed struct that should be made equal to source .

 

source

Pointer to source boxed struct.

 

gwy_serializable_boxed_equal()

gboolean
gwy_serializable_boxed_equal (GType type,
                              gconstpointer a,
                              gconstpointer b);

Compares the values of two boxed structs for equality.

Parameters

type

Type of a and b . It must be a serialisable boxed type.

 

a

Pointer to one boxed struct of type type .

 

b

Pointer to another boxed struct of type type .

 

Returns

TRUE if a and b are equal, FALSE if they differ.


gwy_serializable_boxed_n_items()

gsize
gwy_serializable_boxed_n_items (GType type);

Obtains the number of items a boxed type serialises to.

Parameters

type

Serialisable boxed type.

 

gwy_serializable_boxed_itemize()

void
gwy_serializable_boxed_itemize (GType type,
                                gpointer boxed,
                                GwySerializableItems *items);

Creates the flattened representation of a serialisable boxed struct.

Parameters

type

Serialisable boxed type.

 

boxed

Pointer to boxed struct of type type .

 

items

List of flattened object tree items to append the representation of boxed to.

 

gwy_serializable_boxed_construct()

gpointer
gwy_serializable_boxed_construct (GType type,
                                  GwySerializableItems *items,
                                  GwyErrorList **error_list);

Constructs a serialisable struct type from its flattened representation.

Parameters

type

Serialisable boxed type.

 

items

List of items to construct the boxed struct from.

 

error_list

Location to store the errors occuring, NULL to ignore.

 

Returns

Newly allocated boxed type with the deserialised data, possibly NULL on fatal failure.

[transfer full]

Types and Values

GwySerializableBoxedInfo

typedef struct {
    gsize    size;
    gsize    n_items;
    gsize    (*itemize)  (gpointer boxed,
                          GwySerializableItems *items);
    gpointer (*construct)(GwySerializableItems *items,
                          GwyErrorList **error_list);
    void     (*assign)   (gpointer destination,
                          gconstpointer source);
    gboolean (*equal)    (gconstpointer a,
                          gconstpointer b);
} GwySerializableBoxedInfo;

Interface implemented by serialisable boxed types.

The fields and methods are similar to GwySerializableInterface where a more detailed discussion can be found. Some notes to the differences:

The number of items n_items is a constant, not a method, which is appropriate for plain old data. However, it is still an upper bound so you can actually serialise less items in GwySerializableBoxedInfo.itemize(). For the same reason, no equivalent of GwySerializableInterface.done() method exists.

Since a serialisable boxed type is a GBoxed, functions such as duplication are realised by the

GBoxed protocol, namely g_boxed_copy() and hence needs not be specified.

Members

gsize size;

Size of the boxed data for bit-wise operable plain old data. If it is non-zero assign and equal must be NULL; assignment and comparison is performed by direct memory copying and comparing. If it is zero these operation are performed usinng assign and equal that must be defined.

 

gsize n_items;

Number of items the boxed struct serialises to.

 

itemize()

Appends flattened representation of the boxed struct to the items list.

 

construct()

Deserialises a boxed struct from array of flattened data items. It returns a newly allocated boxed struct that must be freeable with g_boxed_free().

 

assign()

Makes the content of a boxed struct identical to the content of another boxed struct of the same type. If size is non-zero it can be NULL, meaning implicit bit-for-bit copy.

 

equal()

Compares two boxed data for equality, returns TRUE if they are equal, FALSE if they differ. If size is non-zero it can be NULL, meaning implicit bit-for-bit comparison.