diff --git a/legacy/eina/src/include/Eina.h b/legacy/eina/src/include/Eina.h index a9ed10ce7a..2134e90b70 100644 --- a/legacy/eina/src/include/Eina.h +++ b/legacy/eina/src/include/Eina.h @@ -16,6 +16,7 @@ * Tilman Sauerbeck * Vincent "caro" Torri * Tom Hacohen + * Jonas M. Gastal * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -72,6 +73,7 @@ * @li @ref Eina_Stringshare_Group saves memory by sharing read-only string references. * @li @ref Eina_Tiler_Group split, merge and navigates into 2D tiled regions. * @li @ref Eina_Trash_Group container of unused but allocated data. + * @li @ref Eina_Value_Group container for generic value storage and access. * @li @ref Eina_Model_Group container for data with user defined hierarchy/structure. * * The tools that are available are (see @ref Eina_Tools_Group): diff --git a/legacy/eina/src/include/eina_error.h b/legacy/eina/src/include/eina_error.h index 2b0ae77d8f..dd87edf638 100644 --- a/legacy/eina/src/include/eina_error.h +++ b/legacy/eina/src/include/eina_error.h @@ -180,7 +180,7 @@ EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE; /** * @brief Find the #Eina_Error corresponding to a message string - * @param msg The error message string to match (NOT #NULL) + * @param msg The error message string to match (NOT @c NULL) * @return The #Eina_Error matching @p msg, or 0 on failure * This function attempts to match @p msg with its corresponding #Eina_Error value. * If no such value is found, 0 is returned. diff --git a/legacy/eina/src/include/eina_model.h b/legacy/eina/src/include/eina_model.h index 96bea161bf..df9c1f93ca 100644 --- a/legacy/eina/src/include/eina_model.h +++ b/legacy/eina/src/include/eina_model.h @@ -251,7 +251,7 @@ */ /** - * @defgroup Eina_Model_Group Data Model API. + * @defgroup Eina_Model_Group Data Model API * * Abstracts data access to hierarchical data in an efficient way, * extensible to different backing stores such as database or remote @@ -266,12 +266,20 @@ * use it during development, get the logic right and just then * optimize what is needed (properties or children management). * - * @ref eina_model_02_example_page contains an easy to follow example that - * demonstrates several of the important features of eina_model. + * 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. * - * An inheritance example: @ref eina_model_01_c - * - * And a explained inheritance example: @ref eina_model_03_example_page + * Examples: + * @li @ref eina_model_01_c inheritance example, uses #EINA_MODEL_TYPE_GENERIC + * @li @ref eina_model_02_example_page contains an easy to follow + * example that demonstrates several of the important features of + * eina_model, uses #EINA_MODEL_TYPE_GENERIC. + * @li @ref eina_model_03_example_page walk-through example on how to + * inherit types, a suggestion of eina_model_load() usage and uses + * #EINA_MODEL_TYPE_STRUCT. * * @{ */ @@ -292,15 +300,28 @@ EAPI extern Eina_Error EINA_ERROR_MODEL_METHOD_MISSING; * @typedef Eina_Model * 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: + * @li eina_model_property_get() and eina_model_property_set() + * @li eina_model_child_get() and eina_model_child_set() + * @li eina_model_event_names_list_get(), eina_model_event_callback_add() and eina_model_event_callback_del() + * + * @see eina_model_new() + * @see eina_model_ref() and eina_model_xref() + * @see eina_model_unref(), eina_model_xunref() and eina_model_del() + * @see eina_model_type_get() and eina_model_interface_get() * @since 1.2 */ typedef struct _Eina_Model Eina_Model; - /** * @typedef Eina_Model_Type * Data Model Type. * + * @see #_Eina_Model_Type explains fields. * @since 1.2 */ typedef struct _Eina_Model_Type Eina_Model_Type; @@ -309,6 +330,7 @@ typedef struct _Eina_Model_Type Eina_Model_Type; * @typedef Eina_Model_Interface * Data Model Interface. * + * @see #_Eina_Model_Interface explains fields. * @since 1.2 */ typedef struct _Eina_Model_Interface Eina_Model_Interface; @@ -317,18 +339,17 @@ typedef struct _Eina_Model_Interface Eina_Model_Interface; * @typedef Eina_Model_Event_Description * 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 @c event_info. + * + * @see EINA_MODEL_EVENT_DESCRIPTION() + * @see #EINA_MODEL_EVENT_DESCRIPTION_SENTINEL + * @see #_Eina_Model_Event_Description explains fields. * @since 1.2 */ typedef struct _Eina_Model_Event_Description Eina_Model_Event_Description; -/** - * @typedef Eina_Model_Event_Cb - * Notifies of events in this model. - * - * @since 1.2 - */ -typedef void (*Eina_Model_Event_Cb)(void *data, Eina_Model *model, const Eina_Model_Event_Description *desc, void *event_info); - /** * @brief Creates a new model of type @a Type. * @@ -367,24 +388,6 @@ EAPI const Eina_Model_Type *eina_model_type_get(const Eina_Model *model) EINA_AR EAPI const Eina_Model_Interface *eina_model_interface_get(const Eina_Model *model, const char *name) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; -/** - * @brief Checks if @a model is an instance of @a type. - * - * @see eina_model_new() - * @see _Eina_Model_Type - * @since 1.2 - */ -EAPI Eina_Bool eina_model_instance_check(const Eina_Model *model, - const Eina_Model_Type *type) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; - -/** - * @brief Checks if @a model implements @a iface. - * - * @see _Eina_Model_Interface - * @since 1.2 - */ -EAPI Eina_Bool eina_model_interface_implemented(const Eina_Model *model, const Eina_Model_Interface *iface) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; - /** * @brief Increases the refcount of @a model. * @param model The model to increase reference. @@ -482,46 +485,45 @@ EAPI void eina_model_unref(Eina_Model *model) EINA_ARG_NONNULL(1); EAPI void eina_model_xunref(Eina_Model *model, const void *id) EINA_ARG_NONNULL(1, 2); -/** - * @brief Returns the number of references to @a model. - * @param model The model to query number of references. - * @return number of references to model - * - * @see eina_model_ref() - * @see eina_model_unref() - * @see eina_model_xref() - * @see eina_model_xunref() - * @see eina_model_xrefs_get() - * @since 1.2 - */ -EAPI int eina_model_refcount(const Eina_Model *model) EINA_ARG_NONNULL(1); -typedef struct _Eina_Model_XRef Eina_Model_XRef; -struct _Eina_Model_XRef -{ - EINA_INLIST; - const void *id; /**< as given to eina_model_xref() */ - struct { - const void * const *symbols; /**< only if @c EINA_MODEL_DEBUG=backtrace is set, otherwise is @c NULL */ - unsigned int count; /**< only if @c EINA_MODEL_DEBUG=backtrace is set, otherwise is 0 */ - } backtrace; - char label[]; -}; /** - * @brief Returns the current references of this model. - * @param model The model to query references. - * @return List of reference holders as Eina_Model_XRef. This is the internal - * list for speed purposes, do not modify or free it in anyway! + * @defgroup Eina_Model_Event_Group Data Model Events + * Events and their usage with models. * - * @note This list only exist if environment variable - * @c EINA_MODEL_DEBUG is set to "1" or "backtrace". + * Events are specified by each type and interface level using + * #Eina_Model_Event_Description. One can know all events supported by + * a model with eina_model_event_names_list_get() and then + * eina_model_event_description_get() to retrieve details. + * + * By default the following events are supported in every object: + * @li deleted: last reference was released or eina_model_del() was called. + * @li freed: memory was destroyed, destructors were called. + * @li property,set: eina_model_property_set() was done. + * @li property,deleted: eina_model_property_del() was done. + * @li children,changed: children was changed somehow (added, modified, deleted) + * @li child,inserted: new child was added (eina_model_child_append() or eina_model_child_insert_at()) + * @li child,set: child was replaced (eina_model_child_set()) + * @li child,deleted: eina_model_child_del() was done. + * + * One can be notified of events with eina_model_event_callback_add(). + * + * Types emit these events with eina_model_event_callback_call(), + * these are handled asynchronously unless event is frozen with + * eina_model_event_callback_freeze() is blocking it. In this case the + * events are ignored. Usually this is used in some cases that want to + * avoid storm of events in batch operations. + * + * @{ + */ + +/** + * @typedef Eina_Model_Event_Cb + * Notifies of events in this model. * - * @note The backtrace information is only available if environment - * variable @c EINA_MODEL_DEBUG=backtrace is set. * @since 1.2 */ -EAPI const Eina_Inlist *eina_model_xrefs_get(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_MALLOC; +typedef void (*Eina_Model_Event_Cb)(void *data, Eina_Model *model, const Eina_Model_Event_Description *desc, void *event_info); /** * @brief Add a callback to be called when @a event_name is emited. @@ -567,6 +569,10 @@ EAPI int eina_model_event_callback_freeze(Eina_Model *model, EAPI int eina_model_event_callback_thaw(Eina_Model *model, const char *name) EINA_ARG_NONNULL(1, 2); +/** + * @} + */ + EAPI Eina_Model *eina_model_copy(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_MALLOC; EAPI Eina_Model *eina_model_deep_copy(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_MALLOC; @@ -592,6 +598,19 @@ EAPI Eina_Bool eina_model_load(Eina_Model *model) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_model_unload(Eina_Model *model) EINA_ARG_NONNULL(1); +/** + * @defgroup Eina_Model_Properties_Group Data Model Properties + * Properties and their usage with models. + * + * Properties are attributes of model. They have a name and contain a + * data value (@ref Eina_Value_Group). + * + * The actual values and their types, if it is possible to read and + * write them and if new properties can be created or deleted it is up + * to the type. + * + * @{ + */ EAPI Eina_Bool eina_model_property_get(const Eina_Model *model, const char *name, Eina_Value *value) EINA_ARG_NONNULL(1, 2, 3); @@ -604,6 +623,22 @@ EAPI Eina_Bool eina_model_property_del(Eina_Model *model, EAPI Eina_List *eina_model_properties_names_list_get(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; EAPI void eina_model_properties_names_list_free(Eina_List *list); +/** + * @} + */ + +/** + * @defgroup Eina_Model_Children_Group Data Model Children + * Children and their usage with models. + * + * Children are other model instances that are kept sequentially in + * the model. They are accessed by their integer index within the + * model. Their index may change if child are inserted or deleted + * before them, as in an array. + * + * @{ + */ + EAPI int eina_model_child_count(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** @@ -667,6 +702,20 @@ EAPI int eina_model_child_criteria_match(const Eina_Model *model, EAPI Eina_Bool eina_model_child_sort(Eina_Model *model, Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2); +/** + * @} + */ + +/** + * @defgroup Eina_Model_Iterators_Group Data Model Iterators + * Iterators and their usage with models. + * + * One of the most common tasks of models is to iterate over their + * children, either forwards or backwards, filtering by some criteria + * or a different ordering function. + * + * @{ + */ /** * @brief create an iterator that outputs a child model on each iteration. @@ -820,6 +869,10 @@ EAPI Eina_Iterator *eina_model_child_slice_filtered_iterator_get(Eina_Model *mod const void *data) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; +/** + * @} + */ + /** * @brief Convert model to string. * @param model the model instance. @@ -841,17 +894,40 @@ EAPI char *eina_model_to_string(const Eina_Model *model) EINA_ARG_NONNULL(1) EIN /** * @defgroup Eina_Model_Type_Group Data Model Type management * + * Functions and structures related to implementing new types or + * extending existing ones. + * + * All eina_model_type functions takes an Eina_Model_Type or + * Eina_Model_Interface as parameter and may be used to validate or + * query information about them. + * + * The functions with prefix eina_model_type that matches eina_model + * counterparts, such as eina_model_type_compare() and + * eina_model_compare() are used as "super", that is, calls the @c + * compare() method of the given type (or its parent) instead of the + * most specific type of provided Eina_Model. + * + * Examples: + * @li @ref eina_model_02_example_page contains an easy to follow + * example that demonstrates several of the important features of + * eina_model, uses #EINA_MODEL_TYPE_GENERIC. + * @li @ref eina_model_03_example_page walk-through example on how to + * inherit types, a suggestion of eina_model_load() usage and uses + * #EINA_MODEL_TYPE_STRUCT. + * * @{ */ +/** + * @def EINA_MODEL_TYPE_VERSION + * Current API version, used to validate #_Eina_Model_Type. + */ +#define EINA_MODEL_TYPE_VERSION (1) + /** * @struct _Eina_Model_Type * API to access models. * - * @warning The methods @c setup, @c flush, @c constructor, @c destructor and - * @c property_get are mandatory and must exist, otherwise type cannot - * be used. - * * Each type of the hierarchy and each interface will get its own * private data of size @c private_size (defined at each subtype or * interface), this can be retrieved with @@ -881,6 +957,13 @@ EAPI char *eina_model_to_string(const Eina_Model *model) EINA_ARG_NONNULL(1) EIN * destructors should be called, do them in the desired order from the type * destructor. * + * + * @note The methods @c setup and @c flush should exist if there is + * private data, otherwise memory may be uninitialized or leaks. + * @note It is recommended that @c constructor and @c destructor exist + * to correctly do their roles and call parents in the correct + * order. Whenever they do not exist, their parent pointer is + * called. * @note a runtime check will enforce just types with ABI version * #EINA_MODEL_TYPE_VERSION are used by comparing with the @c version * member. @@ -889,11 +972,6 @@ EAPI char *eina_model_to_string(const Eina_Model *model) EINA_ARG_NONNULL(1) EIN */ struct _Eina_Model_Type { - /** - * @def EINA_MODEL_TYPE_VERSION - * Current API version, used to validate type. - */ -#define EINA_MODEL_TYPE_VERSION (1) unsigned int version; /**< must be #EINA_MODEL_TYPE_VERSION */ unsigned int private_size; /**< used to allocate type private data */ unsigned int type_size; /**< used to know sizeof(Eina_Model_Type) or subtypes (which may be bigger, by including Eina_Model_Type as a header */ @@ -1145,7 +1223,7 @@ EAPI char *eina_model_type_to_string(const Eina_Model_Type *type, * implemented. * * The use of this function is discouraged, you should use - * #eina_model_method_resolve instead. + * eina_model_method_resolve() instead. * * When implementing new types that augments the basic methods from * Eina_Model_Type, the recommended structure layout is as follow: @@ -1195,26 +1273,47 @@ EAPI const void *eina_model_type_method_offset_resolve(const Eina_Model_Type *ty #define eina_model_type_method_resolve(type, model, struct_type, method) eina_model_type_method_offset_resolve((type), (model), offsetof(struct_type, method)) +/** + * @def EINA_MODEL_INTERFACE_VERSION + * Current API version, used to validate #_Eina_Model_Interface. + */ +#define EINA_MODEL_INTERFACE_VERSION (1) + /** * @struct _Eina_Model_Interface - * - * @warning The methods @c setup, @c flush, @c constructor and @c destructor are - * mandatory and must exist, otherwise type cannot be used. + * API to access models. * * Interfaces are managed by name, then multiple Eina_Model_Interface * may have the same name meaning it implements that name. * + * Each interface will get its own private data of size @c + * private_size (defined at each sub interface), this can be retrieved + * with eina_model_interface_private_data_get(). + * + * Private are created @b automatically and should be setup with @c + * setup and flushed with @c flush. All interfaces functions that + * exist are called! Don't call your parent's @c setup or @c flush! + * The setup is done from parent to child. Flush is done from child to + * parent (topological sort is applied to interface graph). + * + * @note The methods @c setup and @c flush should exist if there is + * private data, otherwise memory may be uninitialized or leaks. + * @note It is recommended that @c constructor and @c destructor exist + * to correctly do their roles and call parents in the correct + * order. Whenever they do not exist, their parent pointer is + * called. + * @note Interface's constructor and destructor are only called by + * type counterparts. Unlike setup and flush, they are not + * guaranteed to be called. * @note use the same name pointer on queries to speed up the lookups! + * @note a runtime check will enforce just types with ABI version + * #EINA_MODEL_INTERFACE_VERSION are used by comparing with the + * @c version member. * * @since 1.2 */ struct _Eina_Model_Interface { - /** - * @def EINA_MODEL_INTERFACE_VERSION - * Current API version, used to validate interface. - */ -#define EINA_MODEL_INTERFACE_VERSION (1) unsigned int version; /**< must be #EINA_MODEL_INTERFACE_VERSION */ unsigned int private_size; /**< used to allocate interface private data */ unsigned int interface_size; /**< used to know sizeof(Eina_Model_Interface) or subtypes (which may be bigger, by including Eina_Model_Interface as header */ @@ -1227,10 +1326,10 @@ struct _Eina_Model_Interface Eina_Bool (*destructor)(Eina_Model *model); /**< destruct interface instance, flush will be called after it. Should call parent's destructor if needed. Release reference to other models here. */ Eina_Bool (*copy)(const Eina_Model *src, Eina_Model *dst); /**< copy interface private data, do @b not call parent interface copy! */ Eina_Bool (*deep_copy)(const Eina_Model *src, Eina_Model *dst); /**< deep copy interface private data, do @b not call parent interface deep copy! */ - void *__extension_ptr0; /**< not to be used */ - void *__extension_ptr1; /**< not to be used */ - void *__extension_ptr2; /**< not to be used */ - void *__extension_ptr3; /**< not to be used */ + void *__extension_ptr0; /**< not to be used @internal */ + void *__extension_ptr1; /**< not to be used @internal */ + void *__extension_ptr2; /**< not to be used @internal */ + void *__extension_ptr3; /**< not to be used @internal */ }; #define EINA_MODEL_INTERFACE_INIT(name, iface, private_type, parent, events) \ @@ -1306,13 +1405,38 @@ EAPI Eina_Bool eina_model_interface_deep_copy(const Eina_Model_Interface *iface, EAPI const void *eina_model_interface_method_offset_resolve(const Eina_Model_Interface *iface, const Eina_Model *model, unsigned int offset) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; +/** + * @struct _Eina_Model_Event_Description + * Data Model Event Description. + * + * @see EINA_MODEL_EVENT_DESCRIPTION() + * @see #EINA_MODEL_EVENT_DESCRIPTION_SENTINEL + * @since 1.2 + */ struct _Eina_Model_Event_Description { const char *name; /**< name used for lookups */ const char *type; /**< used for introspection purposes, documents what goes as callback event information (@c event_info) */ const char *doc; /**< documentation for introspection purposes */ }; + +/** + * @def EINA_MODEL_EVENT_DESCRIPTION + * + * Helper to define Eina_Model_Event_Description fields. + * + * @since 1.2 + */ #define EINA_MODEL_EVENT_DESCRIPTION(name, type, doc) {name, type, doc} + +/** + * @def EINA_MODEL_EVENT_DESCRIPTION_SENTINEL + * + * Helper to define Eina_Model_Event_Description fields for sentinel (last + * item). + * + * @since 1.2 + */ #define EINA_MODEL_EVENT_DESCRIPTION_SENTINEL {NULL, NULL, NULL} EAPI Eina_Bool eina_model_type_check(const Eina_Model_Type *type) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; @@ -1388,6 +1512,300 @@ EAPI Eina_Bool eina_model_interface_check(const Eina_Model_Interface *iface) EIN EAPI void *eina_model_interface_private_data_get(const Eina_Model *model, const Eina_Model_Interface *iface) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; +/** + * @def EINA_MODEL_INTERFACE_PROPERTIES_VERSION + * Current API version, used to validate #_Eina_Model_Interface_Properties. + */ +#define EINA_MODEL_INTERFACE_PROPERTIES_VERSION (1) + +/** + * @typedef Eina_Model_Interface_Properties + * Interface to manage model's properties. + * + * This extends #Eina_Model_Interface as expected by interface name + * #EINA_MODEL_INTERFACE_NAME_PROPERTIES. + * + * This interface is meant to help managing properties of a model, it + * is used by #EINA_MODEL_TYPE_MIXIN in order to configure methods for + * children independently from properties. + * + * @see #_Eina_Model_Interface_Properties explains fields. + * @since 1.2 + */ +typedef struct _Eina_Model_Interface_Properties Eina_Model_Interface_Properties; + +/** + * @struct _Eina_Model_Interface_Properties + * Interface to manage model's properties. + * + * This extends #Eina_Model_Interface as expected by interface name + * #EINA_MODEL_INTERFACE_NAME_PROPERTIES. + * + * This interface is meant to help managing properties of a model, it + * is used by #EINA_MODEL_TYPE_MIXIN in order to configure methods for + * children independently from properties. + * + * @since 1.2 + */ +struct _Eina_Model_Interface_Properties +{ + Eina_Model_Interface base; /**< common interface methods */ + unsigned int version; /**< must be #EINA_MODEL_INTERFACE_PROPERTIES_VERSION */ + Eina_Bool (*compare)(const Eina_Model *a, const Eina_Model *b, int *cmp); /**< How to compare properties of this model */ + Eina_Bool (*load)(Eina_Model *model); /**< How to load properties of this model */ + Eina_Bool (*unload)(Eina_Model *model); /**< How to unload properties of this model */ + Eina_Bool (*get)(const Eina_Model *model, const char *name, Eina_Value *value); /**< Retrieve a property of this model given its name. The value will be returned as a copy and must be flushed with eina_value_flush(). The previous contents of value is ignored. */ + Eina_Bool (*set)(Eina_Model *model, const char *name, const Eina_Value *value); /**< Set a property of this model given its name. The value is assumed to be valied and is copied internally, thus it can be safely cleared with eina_value_flush() after this function returns. */ + Eina_Bool (*del)(Eina_Model *model, const char *name); /**< Delete a property given its name */ + Eina_List *(*names_list_get)(const Eina_Model *model); /**< List of stringshare with known property names */ +}; + +EAPI Eina_Bool eina_model_interface_properties_compare(const Eina_Model_Interface *iface, + const Eina_Model *a, + const Eina_Model *b, + int *cmp) EINA_ARG_NONNULL(1, 2, 3, 4) EINA_WARN_UNUSED_RESULT; + +EAPI Eina_Bool eina_model_interface_properties_load(const Eina_Model_Interface *iface, + Eina_Model *model) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Bool eina_model_interface_properties_unload(const Eina_Model_Interface *iface, + Eina_Model *model) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Bool eina_model_interface_properties_get(const Eina_Model_Interface *iface, + const Eina_Model *model, + const char *name, + Eina_Value *value) EINA_ARG_NONNULL(1, 2, 3, 4); +EAPI Eina_Bool eina_model_interface_properties_set(const Eina_Model_Interface *iface, + Eina_Model *model, + const char *name, + const Eina_Value *value) EINA_ARG_NONNULL(1, 2, 3, 4); +EAPI Eina_Bool eina_model_interface_properties_del(const Eina_Model_Interface *iface, + Eina_Model *model, + const char *name) EINA_ARG_NONNULL(1, 2, 3); +EAPI Eina_List *eina_model_interface_properties_names_list_get(const Eina_Model_Interface *iface, + const Eina_Model *model) EINA_ARG_NONNULL(1, 2); /**< list of stringshare */ + +/** + * @typedef Eina_Model_Interface_Children + * Interface to manage model's children. + * + * This extends #Eina_Model_Interface as expected by interface name + * #EINA_MODEL_INTERFACE_NAME_CHILDREN. + * + * This interface is meant to help managing properties of a model, it + * is used by #EINA_MODEL_TYPE_MIXIN in order to configure methods for + * children independently from properties. + * + * @see #_Eina_Model_Interface_Children explains fields. + * @since 1.2 + */ +typedef struct _Eina_Model_Interface_Children Eina_Model_Interface_Children; + +/** + * @def EINA_MODEL_INTERFACE_CHILDREN_VERSION + * Current API version, used to validate #_Eina_Model_Interface_Children. + */ +#define EINA_MODEL_INTERFACE_CHILDREN_VERSION (1) + +/** + * @struct _Eina_Model_Interface_Children + * Interface to manage model's children. + * + * This extends #Eina_Model_Interface as expected by interface name + * #EINA_MODEL_INTERFACE_NAME_CHILDREN. + * + * This interface is meant to help managing properties of a model, it + * is used by #EINA_MODEL_TYPE_MIXIN in order to configure methods for + * children independently from properties. + * + * @since 1.2 + */ +struct _Eina_Model_Interface_Children +{ + Eina_Model_Interface base; /**< common interface methods */ + unsigned int version; /**< must be #EINA_MODEL_INTERFACE_CHILDREN_VERSION */ + Eina_Bool (*compare)(const Eina_Model *a, const Eina_Model *b, int *cmp); /**< How to compare children of this model */ + Eina_Bool (*load)(Eina_Model *model); /**< How to load children of this model */ + Eina_Bool (*unload)(Eina_Model *model); /**< How to unload children of this model */ + int (*count)(const Eina_Model *model); /**< How many children of this model */ + Eina_Model *(*get)(const Eina_Model *model, unsigned int position); /**< Retrieve a child of this model, returned child must have reference increased! */ + Eina_Bool (*set)(Eina_Model *model, unsigned int position, Eina_Model *child); /**< Set (replace) a child of this model, given child will have reference increased! */ + Eina_Bool (*del)(Eina_Model *model, unsigned int position); /**< Delete a child of this model. Existing child will have reference decreased! */ + Eina_Bool (*insert_at)(Eina_Model *model, unsigned int position, Eina_Model *child); /**< Insert a child into this model, given child will have reference increased! All elements towards the end of the internal list will be shifted to the end to make room for the new child. */ + void (*sort)(Eina_Model *model, Eina_Compare_Cb compare); /**< Reorder children to be sorted respecting comparison function @c compare() */ +}; + +EAPI Eina_Bool eina_model_interface_children_compare(const Eina_Model_Interface *iface, + const Eina_Model *a, + const Eina_Model *b, + int *cmp) EINA_ARG_NONNULL(1, 2, 3, 4) EINA_WARN_UNUSED_RESULT; +EAPI Eina_Bool eina_model_interface_children_load(const Eina_Model_Interface *iface, + Eina_Model *model) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Bool eina_model_interface_children_unload(const Eina_Model_Interface *iface, + Eina_Model *model) EINA_ARG_NONNULL(1, 2); +EAPI int eina_model_interface_children_count(const Eina_Model_Interface *iface, + const Eina_Model *model) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Model *eina_model_interface_children_get(const Eina_Model_Interface *iface, + const Eina_Model *model, + unsigned int position) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Bool eina_model_interface_children_set(const Eina_Model_Interface *iface, + Eina_Model *model, + unsigned int position, + Eina_Model *child) EINA_ARG_NONNULL(1, 2, 4); +EAPI Eina_Bool eina_model_interface_children_del(const Eina_Model_Interface *iface, + Eina_Model *model, + unsigned int position) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Bool eina_model_interface_children_insert_at(const Eina_Model_Interface *iface, + Eina_Model *model, + unsigned int position, + Eina_Model *child) EINA_ARG_NONNULL(1, 2, 4); +EAPI void eina_model_interface_children_sort(const Eina_Model_Interface *iface, + Eina_Model *model, + Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3); + + +/** + * @} + */ + +/** + * @defgroup Eina_Model_Utils_Group Data Model Utilities + * + * Miscellaneous utilities to help usage or debug of @ref Eina_Model_Group. + * + * @{ + */ + +/** + * @brief Checks if @a model is an instance of @a type. + * + * @see eina_model_new() + * @see _Eina_Model_Type + * @since 1.2 + */ +EAPI Eina_Bool eina_model_instance_check(const Eina_Model *model, + const Eina_Model_Type *type) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; + +/** + * @brief Checks if @a model implements @a iface. + * + * @see _Eina_Model_Interface + * @since 1.2 + */ +EAPI Eina_Bool eina_model_interface_implemented(const Eina_Model *model, const Eina_Model_Interface *iface) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; + +/** + * @brief Returns the number of references to @a model. + * @param model The model to query number of references. + * @return number of references to model + * + * @see eina_model_ref() + * @see eina_model_unref() + * @see eina_model_xref() + * @see eina_model_xunref() + * @see eina_model_xrefs_get() + * @since 1.2 + */ +EAPI int eina_model_refcount(const Eina_Model *model) EINA_ARG_NONNULL(1); + +/** + * @typedef Eina_Model_XRef + * Extended reference to model. + * + * This is returned by eina_model_xrefs_get() and should never be + * modified. It is managed by eina_model_xref() and + * eina_model_xunref() when @c EINA_MODEL_DEBUG is set to "1" or + * "backtrace". + * + * @see #_Eina_Model_XRef explains fields. + * @since 1.2 + */ +typedef struct _Eina_Model_XRef Eina_Model_XRef; + +/** + * @struct _Eina_Model_XRef + * Extended reference to model. + * + * This is returned by eina_model_xrefs_get() and should never be + * modified. It is managed by eina_model_xref() and + * eina_model_xunref() when @c EINA_MODEL_DEBUG is set to "1" or + * "backtrace". + * + * @see eina_model_xrefs_get() + * @see eina_models_usage_dump() + * @since 1.2 + */ +struct _Eina_Model_XRef +{ + EINA_INLIST; + const void *id; /**< as given to eina_model_xref() */ + struct { + const void * const *symbols; /**< only if @c EINA_MODEL_DEBUG=backtrace is set, otherwise is @c NULL */ + unsigned int count; /**< only if @c EINA_MODEL_DEBUG=backtrace is set, otherwise is 0 */ + } backtrace; + char label[]; /**< Any given label given to eina_model_xref(). */ +}; + +/** + * @brief Returns the current references of this model. + * @param model The model to query references. + * @return List of reference holders as Eina_Model_XRef. This is the internal + * list for speed purposes, do not modify or free it in anyway! + * + * @note This list only exist if environment variable + * @c EINA_MODEL_DEBUG is set to "1" or "backtrace". + * + * @note The backtrace information is only available if environment + * variable @c EINA_MODEL_DEBUG=backtrace is set. + * @since 1.2 + */ +EAPI const Eina_Inlist *eina_model_xrefs_get(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_MALLOC; + +/** + * @brief Dump usage of all existing modules. + * @since 1.2 + */ +EAPI void eina_models_usage_dump(void); + +/** + * @brief Return a list of all live models. + * @return a newly allocated list of Eina_Model. Free using + * eina_models_list_free() + * + * @note this is meant to debug purposes, do not modify the models in + * any way! + * + * @note due performance reasons, this is only @b enabled when + * @c EINA_MODEL_DEBUG is set to "1" or "backtrace". + * + * @since 1.2 + */ +EAPI Eina_List *eina_models_list_get(void); + +/** + * @brief Release list returned by eina_models_list_get() + * @param list the list to release. + */ +EAPI void eina_models_list_free(Eina_List *list); + +/** + * @} + */ + +/** + * @var EINA_MODEL_INTERFACE_CHILDREN_INARRAY + * + * 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 + */ +EAPI extern const Eina_Model_Interface *EINA_MODEL_INTERFACE_CHILDREN_INARRAY; + + /** * @var EINA_MODEL_TYPE_BASE * Base type for all eina model types. @@ -1467,89 +1885,6 @@ EAPI Eina_Model *eina_model_type_struct_new(const Eina_Model_Type *type, const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_MALLOC; - - -/** - * @var EINA_MODEL_INTERFACE_NAME_PROPERTIES - * - * Interface that uses #Eina_Model_Interface_Properties as - * Eina_Model_Interface::value and can manage the model properties. - * - * @since 1.2 - */ -EAPI extern const char *EINA_MODEL_INTERFACE_NAME_PROPERTIES; - -typedef struct _Eina_Model_Interface_Properties Eina_Model_Interface_Properties; -struct _Eina_Model_Interface_Properties -{ - Eina_Model_Interface base; -#define EINA_MODEL_INTERFACE_PROPERTIES_VERSION (1) - unsigned int version; - Eina_Bool (*compare)(const Eina_Model *a, const Eina_Model *b, int *cmp); - Eina_Bool (*load)(Eina_Model *model); - Eina_Bool (*unload)(Eina_Model *model); - Eina_Bool (*get)(const Eina_Model *model, const char *name, Eina_Value *value); - Eina_Bool (*set)(Eina_Model *model, const char *name, const Eina_Value *value); - Eina_Bool (*del)(Eina_Model *model, const char *name); - Eina_List *(*names_list_get)(const Eina_Model *model); /**< list of stringshare */ -}; - -EAPI Eina_Bool eina_model_interface_properties_compare(const Eina_Model_Interface *iface, - const Eina_Model *a, - const Eina_Model *b, - int *cmp) EINA_ARG_NONNULL(1, 2, 3, 4) EINA_WARN_UNUSED_RESULT; - -EAPI Eina_Bool eina_model_interface_properties_load(const Eina_Model_Interface *iface, - Eina_Model *model) EINA_ARG_NONNULL(1, 2); -EAPI Eina_Bool eina_model_interface_properties_unload(const Eina_Model_Interface *iface, - Eina_Model *model) EINA_ARG_NONNULL(1, 2); -EAPI Eina_Bool eina_model_interface_properties_get(const Eina_Model_Interface *iface, - const Eina_Model *model, - const char *name, - Eina_Value *value) EINA_ARG_NONNULL(1, 2, 3, 4); -EAPI Eina_Bool eina_model_interface_properties_set(const Eina_Model_Interface *iface, - Eina_Model *model, - const char *name, - const Eina_Value *value) EINA_ARG_NONNULL(1, 2, 3, 4); -EAPI Eina_Bool eina_model_interface_properties_del(const Eina_Model_Interface *iface, - Eina_Model *model, - const char *name) EINA_ARG_NONNULL(1, 2, 3); -EAPI Eina_List *eina_model_interface_properties_names_list_get(const Eina_Model_Interface *iface, - const Eina_Model *model) EINA_ARG_NONNULL(1, 2); /**< list of stringshare */ - -/** - * @var EINA_MODEL_INTERFACE_PROPERTIES_HASH - * - * 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 EINA_MODEL_INTERFACE_PROPERTIES_STRUCT - * - * @since 1.2 - */ -EAPI extern const Eina_Model_Interface *EINA_MODEL_INTERFACE_PROPERTIES_HASH; - -/** - * @var EINA_MODEL_INTERFACE_PROPERTIES_STRUCT - * - * 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 EINA_MODEL_INTERFACE_PROPERTIES_HASH - * - * @since 1.2 - */ -EAPI extern const Eina_Model_Interface *EINA_MODEL_INTERFACE_PROPERTIES_STRUCT; - /** * @brief Configure the internal properties of model implementing #EINA_MODEL_INTERFACE_PROPERTIES_STRUCT. * @@ -1588,127 +1923,59 @@ EAPI Eina_Bool eina_model_struct_get(const Eina_Model *model, const Eina_Value_Struct_Desc **p_desc, void **p_memory) EINA_ARG_NONNULL(1, 2); +/** + * @var EINA_MODEL_INTERFACE_NAME_PROPERTIES + * + * Interface that uses #Eina_Model_Interface_Properties as + * #Eina_Model_Interface and can manage the model properties. + * + * @since 1.2 + */ +EAPI extern const char *EINA_MODEL_INTERFACE_NAME_PROPERTIES; + +/** + * @var EINA_MODEL_INTERFACE_PROPERTIES_HASH + * + * 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 EINA_MODEL_INTERFACE_PROPERTIES_STRUCT + * + * @since 1.2 + */ +EAPI extern const Eina_Model_Interface *EINA_MODEL_INTERFACE_PROPERTIES_HASH; + +/** + * @var EINA_MODEL_INTERFACE_PROPERTIES_STRUCT + * + * 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 EINA_MODEL_INTERFACE_PROPERTIES_HASH + * + * @since 1.2 + */ +EAPI extern const Eina_Model_Interface *EINA_MODEL_INTERFACE_PROPERTIES_STRUCT; + /** * @var EINA_MODEL_INTERFACE_NAME_CHILDREN * * Interface that uses #Eina_Model_Interface_Children as - * Eina_Model_Interface::value and can manage the model children. + * #Eina_Model_Interface and can manage the model children. * * @since 1.2 */ EAPI extern const char *EINA_MODEL_INTERFACE_NAME_CHILDREN; -/** - * @typedef Eina_Model_Interface_Children - * - * The #Eina_Model_Interface::value when name is - * #EINA_MODEL_INTERFACE_NAME_CHILDREN interface is implemented. - * - * @since 1.2 - */ -typedef struct _Eina_Model_Interface_Children Eina_Model_Interface_Children; - -/** - * @struct _Eina_Model_Interface_Children - * - * The #Eina_Model_Interface::value when name is - * #EINA_MODEL_INTERFACE_NAME_CHILDREN interface is implemented. - * - * The methods are called in the same way children methods from - * #Eina_Model_Type. - * - * @since 1.2 - */ -struct _Eina_Model_Interface_Children -{ - Eina_Model_Interface base; -#define EINA_MODEL_INTERFACE_CHILDREN_VERSION (1) - unsigned int version; - Eina_Bool (*compare)(const Eina_Model *a, const Eina_Model *b, int *cmp); - Eina_Bool (*load)(Eina_Model *model); - Eina_Bool (*unload)(Eina_Model *model); - int (*count)(const Eina_Model *model); - Eina_Model *(*get)(const Eina_Model *model, unsigned int position); - Eina_Bool (*set)(Eina_Model *model, unsigned int position, Eina_Model *child); - Eina_Bool (*del)(Eina_Model *model, unsigned int position); - Eina_Bool (*insert_at)(Eina_Model *model, unsigned int position, Eina_Model *child); - void (*sort)(Eina_Model *model, Eina_Compare_Cb compare); -}; - -EAPI Eina_Bool eina_model_interface_children_compare(const Eina_Model_Interface *iface, - const Eina_Model *a, - const Eina_Model *b, - int *cmp) EINA_ARG_NONNULL(1, 2, 3, 4) EINA_WARN_UNUSED_RESULT; -EAPI Eina_Bool eina_model_interface_children_load(const Eina_Model_Interface *iface, - Eina_Model *model) EINA_ARG_NONNULL(1, 2); -EAPI Eina_Bool eina_model_interface_children_unload(const Eina_Model_Interface *iface, - Eina_Model *model) EINA_ARG_NONNULL(1, 2); -EAPI int eina_model_interface_children_count(const Eina_Model_Interface *iface, - const Eina_Model *model) EINA_ARG_NONNULL(1, 2); -EAPI Eina_Model *eina_model_interface_children_get(const Eina_Model_Interface *iface, - const Eina_Model *model, - unsigned int position) EINA_ARG_NONNULL(1, 2); -EAPI Eina_Bool eina_model_interface_children_set(const Eina_Model_Interface *iface, - Eina_Model *model, - unsigned int position, - Eina_Model *child) EINA_ARG_NONNULL(1, 2, 4); -EAPI Eina_Bool eina_model_interface_children_del(const Eina_Model_Interface *iface, - Eina_Model *model, - unsigned int position) EINA_ARG_NONNULL(1, 2); -EAPI Eina_Bool eina_model_interface_children_insert_at(const Eina_Model_Interface *iface, - Eina_Model *model, - unsigned int position, - Eina_Model *child) EINA_ARG_NONNULL(1, 2, 4); -EAPI void eina_model_interface_children_sort(const Eina_Model_Interface *iface, - Eina_Model *model, - Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3); - -/** - * @var EINA_MODEL_INTERFACE_CHILDREN_INARRAY - * - * 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 - */ -EAPI extern const Eina_Model_Interface *EINA_MODEL_INTERFACE_CHILDREN_INARRAY; - -/** - * @brief Dump usage of all existing modules. - * @since 1.2 - */ -EAPI void eina_models_usage_dump(void); - -/** - * @brief Return a list of all live models. - * @return a newly allocated list of Eina_Model. Free using - * eina_models_list_free() - * - * @note this is meant to debug purposes, do not modify the models in - * any way! - * - * @note due performance reasons, this is only @b enabled when - * @c EINA_MODEL_DEBUG is set to "1" or "backtrace". - * - * @since 1.2 - */ -EAPI Eina_List *eina_models_list_get(void); - -/** - * @brief Release list returned by eina_models_list_get() - * @param list the list to release. - */ -EAPI void eina_models_list_free(Eina_List *list); - -/** - * @} - */ - /** * @} */ diff --git a/legacy/eina/src/include/eina_value.h b/legacy/eina/src/include/eina_value.h index e3a5c5bb33..22048755df 100644 --- a/legacy/eina/src/include/eina_value.h +++ b/legacy/eina/src/include/eina_value.h @@ -43,6 +43,19 @@ /** * @defgroup Eina_Value_Group Generic Value Storage * + * Abstracts generic data storage and access to it in an extensible + * and efficient way. + * + * It comes with pre-defined types for numbers, array, list, hash, + * blob and structs. It is able to convert between data types, + * including to string. + * + * It is meant for simple data types, providing uniform access and + * release functions, useful to exchange data preserving their + * types. For more complex hierarchical data, with properties and + * children, reference counting, inheritance and interfaces, see @ref + * Eina_Model_Group. + * * @{ */ @@ -67,6 +80,9 @@ typedef struct _Eina_Value_Type Eina_Value_Type; * @typedef Eina_Value_Union * Union of all known value types. * + * This is only used to specify the minimum payload memory for #Eina_Value. + * + * @internal * @since 1.2 */ typedef union _Eina_Value_Union Eina_Value_Union; @@ -75,6 +91,9 @@ typedef union _Eina_Value_Union Eina_Value_Union; * @union _Eina_Value_Union * All possible value types. * + * This is only used to specify the minimum payload memory for #Eina_Value. + * + * @internal * @since 1.2 */ union _Eina_Value_Union @@ -841,8 +860,9 @@ static inline const Eina_Value_Type *eina_value_type_get(const Eina_Value *value /** * @typedef Eina_Value_Array - * Value type for #EINA_VALUE_TYPE_ARRAY + * Value type for #EINA_VALUE_TYPE_ARRAY. * + * @see #_Eina_Value_Array explains fields. * @since 1.2 */ typedef struct _Eina_Value_Array Eina_Value_Array; @@ -850,6 +870,7 @@ typedef struct _Eina_Value_Array Eina_Value_Array; /** * @struct _Eina_Value_Array * Used to store the array and its subtype. + * @since 1.2 */ struct _Eina_Value_Array { @@ -1475,8 +1496,9 @@ static inline Eina_Bool eina_value_array_pappend(Eina_Value *value, /** * @typedef Eina_Value_List - * Value type for #EINA_VALUE_TYPE_LIST + * Value type for #EINA_VALUE_TYPE_LIST. * + * @see #_Eina_Value_List explains fields. * @since 1.2 */ typedef struct _Eina_Value_List Eina_Value_List; @@ -1484,6 +1506,7 @@ typedef struct _Eina_Value_List Eina_Value_List; /** * @struct _Eina_Value_List * Used to store the list and its subtype. + * @since 1.2 */ struct _Eina_Value_List { @@ -2096,8 +2119,9 @@ static inline Eina_Bool eina_value_list_pappend(Eina_Value *value, /** * @typedef Eina_Value_Hash - * Value type for #EINA_VALUE_TYPE_HASH + * Value type for #EINA_VALUE_TYPE_HASH. * + * @see #_Eina_Value_Hash explains fields. * @since 1.2 */ typedef struct _Eina_Value_Hash Eina_Value_Hash; @@ -2105,6 +2129,7 @@ typedef struct _Eina_Value_Hash Eina_Value_Hash; /** * @struct _Eina_Value_Hash * Used to store the hash and its subtype. + * @since 1.2 */ struct _Eina_Value_Hash { @@ -2438,10 +2463,17 @@ static inline Eina_Bool eina_value_hash_pget(const Eina_Value *value, /** * @typedef Eina_Value_Blob_Operations * How to manage blob. Any @c NULL callback is ignored. + * @see #_Eina_Value_Blob_Operations explains fields. * @since 1.2 */ typedef struct _Eina_Value_Blob_Operations Eina_Value_Blob_Operations; +/** + * @def EINA_VALUE_BLOB_OPERATIONS_VERSION + * Current API version, used to validate #_Eina_Value_Blob_Operations. + */ +#define EINA_VALUE_BLOB_OPERATIONS_VERSION (1) + /** * @struct _Eina_Value_Blob_Operations * How to manage blob. Any @c NULL callback is ignored. @@ -2449,8 +2481,7 @@ typedef struct _Eina_Value_Blob_Operations Eina_Value_Blob_Operations; */ struct _Eina_Value_Blob_Operations { -#define EINA_VALUE_BLOB_OPERATIONS_VERSION (1) - unsigned int version; /**< must be EINA_VALUE_BLOB_OPERATIONS_VERSION */ + unsigned int version; /**< must be #EINA_VALUE_BLOB_OPERATIONS_VERSION */ void (*free)(const Eina_Value_Blob_Operations *ops, void *memory, size_t size); void *(*copy)(const Eina_Value_Blob_Operations *ops, const void *memory, size_t size); int (*compare)(const Eina_Value_Blob_Operations *ops, const void *data1, size_t size_data1, const void *data2, size_t size_data2); @@ -2470,12 +2501,16 @@ EAPI extern const Eina_Value_Blob_Operations *EINA_VALUE_BLOB_OPERATIONS_MALLOC; /** * @typedef Eina_Value_Blob + * Value type for #EINA_VALUE_TYPE_BLOB. + * + * @see #_Eina_Value_Blob explains fields. * @since 1.2 */ typedef struct _Eina_Value_Blob Eina_Value_Blob; /** * @struct _Eina_Value_Blob + * Used to store the blob information and management operations. * @since 1.2 */ struct _Eina_Value_Blob @@ -2498,6 +2533,11 @@ struct _Eina_Value_Blob /** * @typedef Eina_Value_Struct_Operations * How to manage struct. Any @c NULL callback is ignored. + * + * A structure can specify alternative methods to allocate, free and + * copy itself. See structure definition for all methods. + * + * @see #_Eina_Value_Struct_Operations explains fields. * @since 1.2 */ typedef struct _Eina_Value_Struct_Operations Eina_Value_Struct_Operations; @@ -2505,6 +2545,12 @@ typedef struct _Eina_Value_Struct_Operations Eina_Value_Struct_Operations; /** * @typedef Eina_Value_Struct_Member * Describes a single member of struct. + * + * The member holds a name, type and its byte offset within the struct + * memory. Most Eina_Value_Struct functions takes the member name as + * parameter, as in eina_value_struct_set(). + * + * @see #_Eina_Value_Struct_Member explains fields. * @since 1.2 */ typedef struct _Eina_Value_Struct_Member Eina_Value_Struct_Member; @@ -2512,16 +2558,26 @@ typedef struct _Eina_Value_Struct_Member Eina_Value_Struct_Member; /** * @typedef Eina_Value_Struct_Desc * Describes the struct by listing its size, members and operations. + * @see #_Eina_Value_Struct_Desc explains fields. * @since 1.2 */ typedef struct _Eina_Value_Struct_Desc Eina_Value_Struct_Desc; /** * @typedef Eina_Value_Struct + * Value type for #EINA_VALUE_TYPE_STRUCT. + * + * @see #_Eina_Value_Struct explains fields. * @since 1.2 */ typedef struct _Eina_Value_Struct Eina_Value_Struct; +/** + * @def EINA_VALUE_STRUCT_OPERATIONS_VERSION + * Current API version, used to validate #_Eina_Value_Struct_Operations. + */ +#define EINA_VALUE_STRUCT_OPERATIONS_VERSION (1) + /** * @struct _Eina_Value_Struct_Operations * How to manage struct. Any @c NULL callback is ignored. @@ -2529,13 +2585,12 @@ typedef struct _Eina_Value_Struct Eina_Value_Struct; */ struct _Eina_Value_Struct_Operations { -#define EINA_VALUE_STRUCT_OPERATIONS_VERSION (1) - unsigned int version; /**< must be EINA_VALUE_STRUCT_OPERATIONS_VERSION */ - void *(*alloc)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc); - void (*free)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, void *memory); - void *(*copy)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *memory); - int (*compare)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *data1, const void *data2); - const Eina_Value_Struct_Member *(*find_member)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const char *name); /**< replace the function to find description for member. For huge structures consider using binary search, stringshared, hash or gperf. The default function does linear search using strcmp(). */ + unsigned int version; /**< must be #EINA_VALUE_STRUCT_OPERATIONS_VERSION */ + void *(*alloc)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc); /**< How to allocate struct memory to be managed by the Eina_Value */ + void (*free)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, void *memory); /**< How to release memory managed by the Eina_Value */ + void *(*copy)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *memory); /**< How to copy struct memory from an existing Eina_Value, if not provided alloc() will be used, then every member is copied using eina_value_type_copy() with member's type. */ + int (*compare)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *data1, const void *data2); /**< How to compare two struct memories */ + const Eina_Value_Struct_Member *(*find_member)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const char *name); /**< How to find description for member. For huge structures consider using binary search, stringshared, hash or gperf. The default function does linear search using strcmp(). */ }; /** @@ -2568,23 +2623,48 @@ EAPI extern const Eina_Value_Struct_Operations *EINA_VALUE_STRUCT_OPERATIONS_STR /** * @struct _Eina_Value_Struct_Member + * Describes a single member of struct. + * + * The name is used to lookup the member description. This is done as + * specified as _Eina_Value_Struct_Operations::find_member(). For + * structures with huge number of members, consider using a better + * find_member function to quickly finding it! There are two helper + * operations provided to help this: + * #EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH and + * #EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE, both depend on properly + * set #_Eina_Value_Struct_Desc and #_Eina_Value_Struct_Member. + * + * @see #EINA_VALUE_STRUCT_MEMBER + * @see #EINA_VALUE_STRUCT_MEMBER_SENTINEL + * * @since 1.2 */ struct _Eina_Value_Struct_Member { - const char *name; - const Eina_Value_Type *type; - unsigned int offset; + const char *name; /**< member name, used in lookups such as eina_value_struct_get() */ + const Eina_Value_Type *type; /**< how to use this member */ + unsigned int offset; /**< where this member is located within the structure memory */ }; +/** + * @def EINA_VALUE_STRUCT_DESC_VERSION + * Current API version, used to validate #_Eina_Value_Struct_Desc. + */ +#define EINA_VALUE_STRUCT_DESC_VERSION (1) + /** * @struct _Eina_Value_Struct_Desc + * Describes the struct by listing its size, members and operations. + * + * This is the root of Eina_Value knowledge about the memory it's + * handling as a structure. It adds introspection, saying the byte + * size of the structure, its members and how to manage such members. + * * @since 1.2 */ struct _Eina_Value_Struct_Desc { -#define EINA_VALUE_STRUCT_DESC_VERSION (1) - unsigned int version; /**< must be EINA_VALUE_STRUCT_DESC_VERSION */ + unsigned int version; /**< must be #EINA_VALUE_STRUCT_DESC_VERSION */ const Eina_Value_Struct_Operations *ops; /**< operations, if @c NULL defaults will be used. You may use operations to optimize member lookup using binary search or gperf hash. */ const Eina_Value_Struct_Member *members; /**< array of member descriptions, if @c member_count is zero, then it must be @c NULL terminated. */ unsigned int member_count; /**< if > 0, specifies number of members. If zero then @c members must be NULL terminated. */ @@ -2615,12 +2695,13 @@ struct _Eina_Value_Struct_Desc /** * @struct _Eina_Value_Struct + * Used to store the memory and its description. * @since 1.2 */ struct _Eina_Value_Struct { - const Eina_Value_Struct_Desc *desc; - void *memory; + const Eina_Value_Struct_Desc *desc; /**< How to manage the structure */ + void *memory; /**< The managed structure memory */ }; /** @@ -3041,6 +3122,12 @@ static inline Eina_Bool eina_value_struct_member_value_set(Eina_Value *dst, * @{ */ +/** + * @def EINA_VALUE_TYPE_VERSION + * Current API version, used to validate type. + */ +#define EINA_VALUE_TYPE_VERSION (1) + /** * @struct _Eina_Value_Type * API to access values. @@ -3049,11 +3136,6 @@ static inline Eina_Bool eina_value_struct_member_value_set(Eina_Value *dst, */ struct _Eina_Value_Type { - /** - * @def EINA_VALUE_TYPE_VERSION - * Current API version, used to validate type. - */ -#define EINA_VALUE_TYPE_VERSION (1) unsigned int version; /**< must be #EINA_VALUE_TYPE_VERSION */ unsigned int value_size; /**< byte size of value */ const char *name; /**< name for debug and introspection */