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...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:
- Eina_Model inheritance and function overriding inheritance example, uses EINA_MODEL_TYPE_GENERIC
- Creating a simple model contains an easy to follow example that demonstrates several of the important features of eina_model, uses EINA_MODEL_TYPE_GENERIC.
- Using Eina_Model and inheritance walk-through example on how to inherit types, a suggestion of eina_model_load() usage and uses EINA_MODEL_TYPE_STRUCT.
- Eina_Model inheritance, interfaces, and function overriding Advanced inheritance, interfaces and interface function overloading example.
Typedef Documentation
Data Model Object.
This is an opaque handle that is created with eina_model_new() and released with eina_model_unref().
It contains properties, children and may emit events. See respectively:
- eina_model_property_get() and eina_model_property_set()
- eina_model_child_get() and eina_model_child_set()
- eina_model_event_names_list_get(), eina_model_event_callback_add() and eina_model_event_callback_del()
- See also:
- eina_model_new()
eina_model_ref() and eina_model_xref()
eina_model_unref(), eina_model_xunref() and eina_model_del()
- 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
- 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()
- 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.
- See also:
- eina_model_new()
- 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()
- 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.
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:
- eina_model_new()
- eina_model_child_get()
- eina_model_child_iterator_get()
- eina_model_child_reversed_iterator_get()
- eina_model_child_sorted_iterator_get()
- eina_model_child_filtered_iterator_get()
- eina_model_child_slice_iterator_get()
- eina_model_child_slice_reversed_iterator_get()
- eina_model_child_slice_sorted_iterator_get()
- eina_model_child_slice_filtered_iterator_get()
- 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()
- 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.
- See also:
- eina_model_ref()
- 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.
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.
- 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.
- 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
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.
- 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.
- 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.
Where:
- Type_Name: eina_model_type_name_get(eina_model_type_get(model))
- Properties are sorted alphabetically.
- Property_Value is created using eina_value_to_string().
- Children are converted using eina_model_to_string()
- 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.
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.
- 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.
- 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