Data Model API
[Containers]

Abstracts data access to hierarchical data in an efficient way, extensible to different backing stores such as database or remote access. More...


Modules

 Data Model Events
 Events and their usage with models.
 Data Model Properties
 Properties and their usage with models.
 Data Model Children
 Children and their usage with models.
 Data Model Iterators
 Iterators and their usage with models.
 Data Model Type management
 Functions and structures related to implementing new types or extending existing ones.
 Data Model Utilities
 Miscellaneous utilities to help usage or debug of Data Model API.

Typedefs

typedef struct _Eina_Model Eina_Model
 Data Model Object.
typedef struct _Eina_Model_Type Eina_Model_Type
 Data Model Type.
typedef struct
_Eina_Model_Interface 
Eina_Model_Interface
 Data Model Interface.
typedef struct
_Eina_Model_Event_Description 
Eina_Model_Event_Description
 Data Model Event Description.

Functions

Eina_Modeleina_model_new (const Eina_Model_Type *type)
 Creates a new model of type Type.
void eina_model_del (Eina_Model *model)
 Frees the memory associated with model.
const Eina_Model_Typeeina_model_type_get (const Eina_Model *model)
 Returns the type of model.
const Eina_Model_Interfaceeina_model_interface_get (const Eina_Model *model, const char *name)
 Returns the interface named name of model.
Eina_Modeleina_model_ref (Eina_Model *model)
 Increases the refcount of model.
Eina_Modeleina_model_xref (Eina_Model *model, const void *id, const char *label)
 Increases the refcount of model, informs reference identifier.
void eina_model_unref (Eina_Model *model)
 Decreases the refcount of model.
void eina_model_xunref (Eina_Model *model, const void *id)
 Decreases the refcount of model, informs reference identifier.
Eina_Modeleina_model_copy (const Eina_Model *model)
 Makes a shallow copy of model.
Eina_Modeleina_model_deep_copy (const Eina_Model *model)
 Makes a deep(complete) copy of model.
int eina_model_compare (const Eina_Model *a, const Eina_Model *b)
 Compares two models.
Eina_Bool eina_model_load (Eina_Model *model)
 Loads the model's data.
Eina_Bool eina_model_unload (Eina_Model *model)
 Unloads the model's data.
char * eina_model_to_string (const Eina_Model *model)
 Convert model to string.
Eina_Modeleina_model_struct_new (const Eina_Value_Struct_Desc *desc)
 Create and setup an instance of EINA_MODEL_TYPE_STRUCT.
Eina_Modeleina_model_type_struct_new (const Eina_Model_Type *type, const Eina_Value_Struct_Desc *desc)
 Create and setup an instance of type subclass of EINA_MODEL_TYPE_STRUCT.
Eina_Bool eina_model_struct_set (Eina_Model *model, const Eina_Value_Struct_Desc *desc, void *memory)
 Configure the internal properties of model implementing EINA_MODEL_INTERFACE_PROPERTIES_STRUCT.
Eina_Bool eina_model_struct_get (const Eina_Model *model, const Eina_Value_Struct_Desc **p_desc, void **p_memory)
 Get the internal properties of model implementing EINA_MODEL_INTERFACE_PROPERTIES_STRUCT.

Variables

Eina_Error EINA_ERROR_MODEL_FAILED
 Defined when model-specific errors happens.
Eina_Error EINA_ERROR_MODEL_METHOD_MISSING
 Defined when model-specific errors happens.
const Eina_Model_InterfaceEINA_MODEL_INTERFACE_CHILDREN_INARRAY
 Implements Eina_Model_Interface_Children (EINA_MODEL_INTERFACE_NAME_CHILDREN) using Eina_Inarray.
const Eina_Model_TypeEINA_MODEL_TYPE_BASE
 Base type for all eina model types.
const Eina_Model_TypeEINA_MODEL_TYPE_MIXIN
 Type that uses EINA_MODEL_INTERFACE_NAME_PROPERTIES and EINA_MODEL_INTERFACE_NAME_CHILDREN to manage the model.
const Eina_Model_TypeEINA_MODEL_TYPE_GENERIC
 Subclass of EINA_MODEL_TYPE_MIXIN that uses EINA_MODEL_INTERFACE_PROPERTIES_HASH and EINA_MODEL_INTERFACE_CHILDREN_INARRAY.
const Eina_Model_TypeEINA_MODEL_TYPE_STRUCT
 Subclass of EINA_MODEL_TYPE_MIXIN that uses EINA_MODEL_INTERFACE_PROPERTIES_STRUCT and EINA_MODEL_INTERFACE_CHILDREN_INARRAY.
const char * EINA_MODEL_INTERFACE_NAME_PROPERTIES
 Interface that uses Eina_Model_Interface_Properties as Eina_Model_Interface and can manage the model properties.
const Eina_Model_InterfaceEINA_MODEL_INTERFACE_PROPERTIES_HASH
 Implements Eina_Model_Interface_Properties (EINA_MODEL_INTERFACE_NAME_PROPERTIES) using Eina_Hash.
const Eina_Model_InterfaceEINA_MODEL_INTERFACE_PROPERTIES_STRUCT
 Implements Eina_Model_Interface_Properties (EINA_MODEL_INTERFACE_NAME_PROPERTIES) using Eina_Value_Struct.
const char * EINA_MODEL_INTERFACE_NAME_CHILDREN
 Interface that uses Eina_Model_Interface_Children as Eina_Model_Interface and can manage the model children.

Detailed Description

Abstracts data access to hierarchical data in an efficient way, extensible to different backing stores such as database or remote access.

It is heavily based on Eina_Value, as properties are exchanged using this data type as interface, although internally models may store them as they want. See Generic Value Storage.

Although extensible and easy to optimize, a simple generic type is provided as EINA_MODEL_TYPE_GENERIC. It is recommended that people use it during development, get the logic right and just then optimize what is needed (properties or children management).

Not as generic as EINA_MODEL_TYPE_GENERIC, but way more efficient is EINA_MODEL_TYPE_STRUCT that instead of a hash of properties of any type, it uses a struct to map properties. Its properties are fixed set of names and they have fixed type, as defined by the Eina_Value_Struct_Desc description used internally.

Examples:


Typedef Documentation

Data Model Type.

See also:
_Eina_Model_Type explains fields.
Since:
1.2

Data Model Interface.

See also:
_Eina_Model_Interface explains fields.
Since:
1.2

Data Model Event Description.

This is used to declare events supported by types and interfaces and also to provide introspection to receivers of signals so they can know which data they are receiving as event_info.

See also:
EINA_MODEL_EVENT_DESCRIPTION()

EINA_MODEL_EVENT_DESCRIPTION_SENTINEL

_Eina_Model_Event_Description explains fields.

Since:
1.2


Function Documentation

Eina_Model* eina_model_new ( const Eina_Model_Type type  ) 

Creates a new model of type Type.

Parameters:
type The type of the model to create.
Returns:
If successfull pointer to model, NULL otherwise.
See also:
_Eina_Model_Type

eina_model_del()

Since:
1.2

References EINA_FALSE, eina_list_append(), eina_lock_release(), eina_lock_take(), EINA_MAGIC_NONE, EINA_MAGIC_SET, eina_mempool_free(), eina_mempool_malloc(), and eina_model_type_check().

Referenced by eina_model_copy(), eina_model_deep_copy(), eina_model_struct_new(), and eina_model_type_struct_new().

void eina_model_del ( Eina_Model model  ) 

Frees the memory associated with model.

Parameters:
model The model instance.
See also:
eina_model_new()
Since:
1.2

Referenced by eina_model_copy(), eina_model_deep_copy(), eina_model_struct_new(), and eina_model_type_struct_new().

const Eina_Model_Type* eina_model_type_get ( const Eina_Model model  ) 

Returns the type of model.

Parameters:
model The model instance.
Returns:
The type of model.
See also:
eina_model_new()

_Eina_Model_Type

Since:
1.2

const Eina_Model_Interface* eina_model_interface_get ( const Eina_Model model,
const char *  name 
)

Returns the interface named name of model.

Parameters:
model The model instance.
name Name of interface to get.
Returns:
If successfull requested interface, NULL otherwise.
The name of every interface of model will be compared to name, the first one to match will be returned.

See also:
eina_model_new()

_Eina_Model_Interface

Since:
1.2

Eina_Model* eina_model_ref ( Eina_Model model  ) 

Increases the refcount of model.

Parameters:
model The model to increase reference.
Returns:
The model with reference increased.

If successfull pointer to model, NULL otherwise.

See also:
eina_model_new()

eina_model_unref()

Since:
1.2

Eina_Model* eina_model_xref ( Eina_Model model,
const void *  id,
const char *  label 
)

Increases the refcount of model, informs reference identifier.

Parameters:
model The model to increase reference.
id An identifier to mark this reference.
label An optional label to help debug, may be NULL.
Returns:
The model with reference increased.
This extended version of reference explicitly marks the origin of the reference and eina_model_xunref() should be used to check and remove it.

Usually the id is another object, like a parent object, or some class/structure/file/function that is holding the reference for some reason.

Its purpose is to help debuging if Eina was compiled with model usage debug enabled and environment variable EINA_MODEL_DEBUG=1 is set.

It is recommended to use eina_model_xref() and eina_model_xunref() pair whenever you want to be sure you released your references. Both at your own type, or using applications. As an example EINA_MODEL_INTERFACE_CHILDREN_INARRAY will use this to make sure it deleted every managed children.

In order to debug leaks, consider using eina_model_xrefs_get() or eina_models_usage_dump() for a global picture. However, some references are not tracked, namely:

Note:
this function is slower than eina_model_ref() if EINA_MODEL_DEBUG is set to "1" or "backtrace". Otherwise it should have the same performance cost.
See also:
eina_model_ref()

eina_model_xunref()

Since:
1.2

Referenced by eina_models_list_get().

void eina_model_unref ( Eina_Model model  ) 

Decreases the refcount of model.

Parameters:
model The model to decrease reference.
Returns:
If successfull pointer to model, NULL otherwise.
After this function returns, consider model pointer invalid.

See also:
eina_model_ref()

eina_model_del()

Since:
1.2

void eina_model_xunref ( Eina_Model model,
const void *  id 
)

Decreases the refcount of model, informs reference identifier.

Parameters:
model The model to decrease reference.
id An identifier to mark this reference.
Returns:
If successfull pointer to model, NULL otherwise.
This function will match eina_model_xref() and the id must match a previously call, otherwise it will produce an error if EINA_MODEL_DEBUG is set to "1" or "backtrace", and the reference is not decreased!

After this function returns, consider model pointer invalid.

Note:
this function is slower than eina_model_unref() if EINA_MODEL_DEBUG is set to "1" or "backtrace". Otherwise it should have the same performance cost.
See also:
eina_model_xref()
Since:
1.2

References EINA_INLIST_FOREACH, EINA_INLIST_GET, eina_inlist_remove(), and _Eina_Model_XRef::id.

Referenced by eina_models_list_free().

Eina_Model* eina_model_copy ( const Eina_Model model  ) 

Makes a shallow copy of model.

Parameters:
model The model instance.
Returns:
Copied model.
The returned model will have a copy of the properties of model and a reference to the children of model.

See also:
eina_model_deep_copy()
Since:
1.2

References eina_model_del(), and eina_model_new().

Eina_Model* eina_model_deep_copy ( const Eina_Model model  ) 

Makes a deep(complete) copy of model.

Parameters:
model The model instance.
Returns:
Copied model.
The returned model will have a copy of the properties of model, its children will be created by making a deep copy of the children of model.

See also:
eina_model_copy()
Since:
1.2

References eina_model_del(), and eina_model_new().

int eina_model_compare ( const Eina_Model a,
const Eina_Model b 
)

Compares two models.

Parameters:
a The first model to compare.
b The second model to compare.
Returns:
Greater than zero if a > b, zero if a == b and less than zero if a < b
The default comparison checks that the properties of a and b all have the same name and value, and then recursively compares all children.

A model with less properties or children is considered smaller than one with more properties.

Since:
1.2

References eina_error_set().

Eina_Bool eina_model_load ( Eina_Model model  ) 

Loads the model's data.

Parameters:
model The model instance.
Returns:
EINA_TRUE on success, EINA_FALSE on failure.
By convention this means loading data from an external source and populating the models properties and children with it. For example in the case of file system backed model, this means opening the relevant files and reading the data from them(creating the properties and children from it).
Warning:
This convention should be followed, but no guarantees of behaviour by user defined types can be given.
Note:
The types provided by Eina_Model don't implement this method.

Calling this function on a model that doesn't implement it returns EINA_TRUE without any effect on model.

See also:
eina_model_unload()
Since:
1.2

References eina_error_set(), and EINA_FALSE.

Eina_Bool eina_model_unload ( Eina_Model model  ) 

Unloads the model's data.

Parameters:
model The model instance.
Returns:
EINA_TRUE on success, EINA_FALSE on failure.
By convention this means releasing data gotten from an external source. For example of a database backed model this might mean releasing the iterator for the currently loaded data or deleting a temporary table.
Warning:
This convention should be followed, but no guarantees of behaviour by user defined types can be given.
Note:
The types provided by Eina_Model don't implement this method.

Calling this function on a model that doesn't implement it returns EINA_TRUE without any effect on model.

See also:
eina_model_load()
Since:
1.2

References eina_error_set(), and EINA_FALSE.

char* eina_model_to_string ( const Eina_Model model  ) 

Convert model to string.

Parameters:
model the model instance.
Returns:
Newly allocated memory or NULL on failure.
The default format of the ouput is: Type_Name({Property_Name: Property_Value, ...}, [Child0, Child1, ...])

Where:

Since:
1.2

Eina_Model* eina_model_struct_new ( const Eina_Value_Struct_Desc desc  ) 

Create and setup an instance of EINA_MODEL_TYPE_STRUCT.

Parameters:
desc struct description to use for properties.
Returns:
newly created and set model, or NULL on errors.
See also:
eina_model_type_struct_new()
Since:
1.2

References eina_model_del(), eina_model_new(), EINA_VALUE_STRUCT_DESC_VERSION, and _Eina_Value_Struct_Desc::version.

Eina_Model* eina_model_type_struct_new ( const Eina_Model_Type type,
const Eina_Value_Struct_Desc desc 
)

Create and setup an instance of type subclass of EINA_MODEL_TYPE_STRUCT.

Parameters:
type a type which is subclass of EINA_MODEL_TYPE_STRUCT.
desc struct description to use for properties.
Returns:
newly created and set model, or NULL on errors.
See also:
eina_model_struct_new()
Since:
1.2

References eina_model_del(), eina_model_new(), eina_model_type_subclass_check(), EINA_VALUE_STRUCT_DESC_VERSION, and _Eina_Value_Struct_Desc::version.

Eina_Bool eina_model_struct_set ( Eina_Model model,
const Eina_Value_Struct_Desc desc,
void *  memory 
)

Configure the internal properties of model implementing EINA_MODEL_INTERFACE_PROPERTIES_STRUCT.

Parameters:
model The model instance to configure.
desc The structure description to use.
memory If not NULL, will be copied by model.
Returns:
EINA_TRUE on success, EINA_FALSE on failure.
This will setup the internal pointers so that the given desc is used to manage the properties of this struct.

If a given memory is provided, it will be copied (including members) and no references are taken after this function returns.

See also:
EINA_VALUE_TYPE_STRUCT
Since:
1.2

References _Eina_Model_Interface_Properties::base, EINA_FALSE, EINA_VALUE_STRUCT_DESC_VERSION, and _Eina_Value_Struct_Desc::version.

Eina_Bool eina_model_struct_get ( const Eina_Model model,
const Eina_Value_Struct_Desc **  p_desc,
void **  p_memory 
)

Get the internal properties of model implementing EINA_MODEL_INTERFACE_PROPERTIES_STRUCT.

Parameters:
model the model instance.
p_desc where to return the structure description in use.
p_memory where to return the structure memory in use.
Returns:
EINA_TRUE on success, EINA_FALSE on failure.
No copies are made! The memory and description may be invalidaded by calls to eina_model_struct_set() or eina_model_del().

Since:
1.2

References _Eina_Model_Interface_Properties::base, _Eina_Value_Struct::desc, EINA_FALSE, eina_model_interface_private_data_get(), eina_value_pget(), and _Eina_Value_Struct::memory.


Variable Documentation

Implements Eina_Model_Interface_Children (EINA_MODEL_INTERFACE_NAME_CHILDREN) using Eina_Inarray.

It should be efficient in space and time for most operations.

Note:
it may become slow if eina_model_child_insert_at() is used at(or near) the beginning of the array as the members from that position to the end must be memmove()d.
Since:
1.2

Base type for all eina model types.

Since:
1.2

Type that uses EINA_MODEL_INTERFACE_NAME_PROPERTIES and EINA_MODEL_INTERFACE_NAME_CHILDREN to manage the model.

This is an abstract type, it does not work out of the box as one needs to subclass it and define the interface implementations for properties and children, as done by EINA_MODEL_TYPE_GENERIC

See also:
EINA_MODEL_TYPE_GENERIC
Since:
1.2

Subclass of EINA_MODEL_TYPE_MIXIN that uses EINA_MODEL_INTERFACE_PROPERTIES_HASH and EINA_MODEL_INTERFACE_CHILDREN_INARRAY.

Should be generic enough to hold lots of items with runtime configurable properties of any type.

See also:
EINA_MODEL_TYPE_STRUCT
Since:
1.2

Subclass of EINA_MODEL_TYPE_MIXIN that uses EINA_MODEL_INTERFACE_PROPERTIES_STRUCT and EINA_MODEL_INTERFACE_CHILDREN_INARRAY.

Should be struct enough to hold lots of items with compile time configurable properties of any type.

See also:
EINA_MODEL_TYPE_GENERIC
Since:
1.2

Interface that uses Eina_Model_Interface_Properties as Eina_Model_Interface and can manage the model properties.

Since:
1.2

Implements Eina_Model_Interface_Properties (EINA_MODEL_INTERFACE_NAME_PROPERTIES) using Eina_Hash.

Note:
This function is generic but uses too much space given the hash data type. For huge number of elements it's better to use custom implementation instead.
See also:
EINA_MODEL_INTERFACE_PROPERTIES_STRUCT
Since:
1.2

Implements Eina_Model_Interface_Properties (EINA_MODEL_INTERFACE_NAME_PROPERTIES) using Eina_Value_Struct.

The interface private data is Eina_Value of type EINA_VALUE_TYPE_STRUCT. Properties will be accessed using Eina_Value_Struct::desc information that can be set by types such as EINA_MODEL_TYPE_STRUCT

See also:
EINA_MODEL_INTERFACE_PROPERTIES_HASH
Since:
1.2

Interface that uses Eina_Model_Interface_Children as Eina_Model_Interface and can manage the model children.

Since:
1.2