diff options
| -rw-r--r-- | src/include/eiotas_board.h | 32 | ||||
| -rw-r--r-- | src/include/eiotas_door.h | 30 | ||||
| -rw-r--r-- | src/include/eiotas_iota.h | 33 | ||||
| -rw-r--r-- | src/include/eiotas_link.h | 13 | ||||
| -rw-r--r-- | src/include/eiotas_main.h | 31 | ||||
| -rw-r--r-- | src/include/eiotas_particle.h | 63 | ||||
| -rw-r--r-- | src/include/eiotas_room.h | 31 | ||||
| -rw-r--r-- | src/include/eiotas_spin.h | 62 | ||||
| -rw-r--r-- | src/include/eiotas_userbits.h | 53 |
9 files changed, 315 insertions, 33 deletions
diff --git a/src/include/eiotas_board.h b/src/include/eiotas_board.h index 4813808..6572faf 100644 --- a/src/include/eiotas_board.h +++ b/src/include/eiotas_board.h @@ -25,16 +25,42 @@ #include <eina_hash.h> +/** + * @typedef Eiotas_Board + * Type for a Particle Merging Door. + */ typedef struct _Eiotas_Board Eiotas_Board; +/** + * @struct _Eiotas_Board + * Struct for a Particle Merging Door. + */ struct _Eiotas_Board { - Eiotas_Iota iota; /* structural info */ - Eiotas_User_Bits user_bits; /* user bits */ - Eina_Hash *postponed; /* TODO Particles */ + Eiotas_Iota iota; /**< structural info */ + Eiotas_User_Bits user_bits; /**< user bits */ + Eina_Hash *postponed; /**< TODO Particles */ }; +/** + * @brief Free allocated resources. + * + * @param board The Eiotas_Board to free. + * + * This function will free all it's user data using user_bits ... FIXME + */ void eiotas_board_free(Eiotas_Board *board); +/** + * @brief Allocate the resources. + * + * @param name The name of this door. + * @param parent The direct hierarchical parent Eiotas_Room. + * @param user_bits A Eiotas_User_Bits initilized with user side pointers. + * + * @return the new allocated Eiotas_Board @c NULL on failure + * + * @see Eiotas_User_Bits + */ EAPI Eiotas_Board* eiotas_board_add(const char* name, Eiotas_Room *parent, Eiotas_User_Bits *user_bits); #endif // __EIOTAS_BOARD_H__ diff --git a/src/include/eiotas_door.h b/src/include/eiotas_door.h index 05060c4..318779f 100644 --- a/src/include/eiotas_door.h +++ b/src/include/eiotas_door.h @@ -25,15 +25,41 @@ #include <eina_types.h> +/** + * @typedef Eiotas_Door + * Type for a basic Door. + */ typedef struct _Eiotas_Door Eiotas_Door; +/** + * @struct _Eiotas_Door + * Struct for a basic Door. + */ struct _Eiotas_Door { - Eiotas_Iota iota; /* structural info */ - Eiotas_User_Bits user_bits; /* user bits */ + Eiotas_Iota iota; /**< structural info */ + Eiotas_User_Bits user_bits; /**< user bits */ }; +/** + * @brief Free allocated resources. + * + * @param door The Eiotas_Door to free. + * + * This function will free all it's user data using user_bits ... FIXME + */ void eiotas_door_free(Eiotas_Door *door); +/** + * @brief Allocate the resources. + * + * @param name The name of this door. + * @param parent The direct hierarchical parent Eiotas_Room. + * @param user_bits A Eiotas_User_Bits initilized with user side pointers. + * + * @return the new allocated Eiotas_Door @c NULL on failure + * + * @see Eiotas_User_Bits + */ EAPI Eiotas_Door* eiotas_door_add(const char* name, Eiotas_Room *parent, Eiotas_User_Bits *user_bits); #endif // __EIOTAS_DOOR_H__ diff --git a/src/include/eiotas_iota.h b/src/include/eiotas_iota.h index 12f093b..d54ae61 100644 --- a/src/include/eiotas_iota.h +++ b/src/include/eiotas_iota.h @@ -21,6 +21,10 @@ #include <eina_stringshare.h> +/** + * @enum _Eiotas_Type + * List of available Eiotas_Iota + */ typedef enum _Eiotas_Type { EIOTAS_TYPE_SPIN=0, @@ -30,18 +34,37 @@ typedef enum _Eiotas_Type EIOTAS_TYPE_COUNT } Eiotas_Type; +/** + * @typedef Eiotas_Iota + * Type for structural and hierachical info + */ typedef struct _Eiotas_Iota Eiotas_Iota; +/** + * @struct _Eiotas_Iota + * Struct for structural and hierachical info. + */ struct _Eiotas_Iota { - Eiotas_Type type; /* type of the iota */ - Eiotas_Iota *spin; /* top level iota which is a Eiotas_Spin */ - Eiotas_Iota *parent; /* direct parent in the hierarchy */ - Eina_Stringshare *name; /* iota's name */ - Eina_Stringshare *path; /* full path to this iota */ + Eiotas_Type type; /**< type of the iota */ + Eiotas_Iota *spin; /**< top level iota which is a Eiotas_Spin */ + Eiotas_Iota *parent; /**< direct parent in the hierarchy */ + Eina_Stringshare *name; /**< iota's name */ + Eina_Stringshare *path; /**< full path to this Eiotas_Iota */ }; +/** + * @brief Print iota information using EINA_LOG_DBG. + * + * @param iota The Eiotas_Iota to show. + */ EAPI void eiotas_iota_show(Eiotas_Iota *iota); +/** + * @brief Free allocated resources. + * + * @param iota The Eiotas_Iota to free. + * + */ void eiotas_iota_free(Eiotas_Iota *iota); #define eiotas_iota_require_particle(_iota) eiotas_spin_require_particle((Eiotas_Spin*)(_iota)->spin) diff --git a/src/include/eiotas_link.h b/src/include/eiotas_link.h index 4692641..4cc4e44 100644 --- a/src/include/eiotas_link.h +++ b/src/include/eiotas_link.h @@ -19,11 +19,24 @@ #ifndef __EIOTAS_LINK_H__ #define __EIOTAS_LINK_H__ +/** + * @typedef Eiotas_Link + * Type for a Link between Eiotas_Iotas. + */ typedef struct _Eiotas_Link Eiotas_Link; +/** + * @struct _Eiotas_Link + * Struct for a Link between Eiotas_Iotas. + */ struct _Eiotas_Link { }; +/** + * @brief Free allocated resources. + * + * @param link The Eiotas_Link to free. + */ void eiotas_link_free(Eiotas_Link *link); #endif // __EIOTAS_LINK_H__ diff --git a/src/include/eiotas_main.h b/src/include/eiotas_main.h index d7ef48c..d75ab96 100644 --- a/src/include/eiotas_main.h +++ b/src/include/eiotas_main.h @@ -21,6 +21,10 @@ #include <eina_types.h> +/** + * @typedef Eiotas_Version + * The version of Eiotas. + */ typedef struct _Eiotas_Version { int major; /**< Major component of the version */ @@ -32,8 +36,35 @@ EAPI extern Eiotas_Version *eiotas_version; EAPI extern int _eiotas_log_dom; +/** + * @brief Initialize the Eiotas library. + * + * @return 1 or greater on success, 0 on error. + * + * This function sets up all the eiotas modules. It returns 0 on + * failure (that is, when one of the module fails to initialize), + * otherwise it returns the number of times it has already been + * called. + * + * When Eiotas is not used anymore, call eiotas_shutdown() to shut down + * the Eiotaslibrary. + */ EAPI int eiotas_init(); +/** + * @brief Shut down the Eiotas library. + * + * @return 0 when all the modules are completely shut down, 1 or + * greater otherwise. + * + * This function shuts down the Eiotas library. It returns 0 when it has + * been called the same number of times than eiotas_init(). In that case + * it shut down all the Eiotas modules. + * + * Once this function succeeds (that is, @c 0 is returned), you must + * not call any of the Eiotas function anymore. You must call + * eiotas_init() again to use the Eiotas functions again. + */ EAPI int eiotas_shutdown(); #endif // __EIOTAS_MAIN_H__ diff --git a/src/include/eiotas_particle.h b/src/include/eiotas_particle.h index 6897d89..3f74040 100644 --- a/src/include/eiotas_particle.h +++ b/src/include/eiotas_particle.h @@ -27,30 +27,75 @@ #include "eiotas_iota.h" +/** + * @typedef Eiotas_Particle + * Type for a Particle, holding data and spinning from Iotas to Iotas. + */ typedef struct _Eiotas_Particle Eiotas_Particle; +/** + * @struct _Eiotas_Particle + * Struct for a Particle, holding data and spinning from Iotas to Iotas. + */ struct _Eiotas_Particle { - EINA_INLIST; - time_t ts; /* creation time */ - Eiotas_Iota *src; /* where it's born */ - Eiotas_Iota *dst; /* current destination */ - Eina_Array *dsts; /* array of destinatinon strings */ - Eina_Hash *payload; /* string data carried by this particle */ - Eina_Inlist *merged; /* list of merged particles */ - Eina_Array *link_fields; /* fields used to generate the link value */ - Eina_Stringshare *link_value; /* computed from link_fields and paylod, used for pearing particles */ + EINA_INLIST; /**< the Eina_Inlist info */ + time_t ts; /**< creation time */ + Eiotas_Iota *src; /**< where it's born */ + Eiotas_Iota *dst; /**< current destination */ + Eina_Array *dsts; /**< array of destinatinon strings */ + Eina_Hash *payload; /**< string data carried by this particle */ + Eina_Inlist *merged; /**< list of merged particles */ + Eina_Array *link_fields; /**< fields used to generate the link value */ + Eina_Stringshare *link_value; /**< computed from link_fields and paylod, used for pearing particles */ }; +/** + * @brief Free allocated resources. + * + * @param particle The Eiotas_Particle to free. + * + * This function will free all the merged Eiotas_Particle + */ void eiotas_particle_free(Eiotas_Particle *particle); +/** + * @brief Allocate the resources. + * + * @return the new allocated Eiotas_Particle @c NULL on failure + */ Eiotas_Particle* eiotas_particle_alloc(); +/** + * @brief Reset the Eiotas_Particle so that it can be required later. + * + * @param particle The Eiotas_Particle to reset + */ EAPI void eiotas_particle_reset(Eiotas_Particle *particle); +/** + * @brief Set @c src and @c ts timestamp. + * + * @param particle The Eiotas_Particle to init + * @param iota The Eiotas_Iota wich will be set as @c src + */ EAPI void eiotas_particle_init(Eiotas_Particle *particle, Eiotas_Iota *iota); +/** + * @brief Merge a particle into the other. + * + * @param particle The Eiotas_Particle to hold @p p + * @param p The Eiotas_Particle to be merged into @p particle + */ EAPI void eiotas_particle_merge(Eiotas_Particle *particle, Eiotas_Particle *p); +/** + * @brief Add destinations to the Eiotas_Particle + * + * @param particle The Eiotas_Particle to add destinations to + * @param destinations A comma separated list of destination "/room0/room1/.../doorx?action" + * + * This function will append each destination found to the destination list of the Eiotas_Particle. + */ EAPI void eiotas_particle_add_destinations(Eiotas_Particle *particle, char* destinations); #endif // __EIOTAS_PARTICLE_H__ diff --git a/src/include/eiotas_room.h b/src/include/eiotas_room.h index 877a91c..644dc0e 100644 --- a/src/include/eiotas_room.h +++ b/src/include/eiotas_room.h @@ -23,16 +23,41 @@ #include <eina_hash.h> +/** + * @typedef Eiotas_Room + * Type for a Room, which holds other child Eiotas_Iotas. + */ typedef struct _Eiotas_Room Eiotas_Room; +/** + * @struct _Eiotas_Room + * Struct for a Room, which holds other child Eiotas_Iotas. + */ struct _Eiotas_Room { - Eiotas_Iota iota; /* structural info */ - Eina_Hash *links; /* TODO */ - Eina_Hash *children; /* stringshared values optimized hash table holding Rooms, Doors and Boards */ + Eiotas_Iota iota; /**< Eiotas_Iota structural info */ + Eina_Hash *links; /**< TODO */ + Eina_Hash *children; /**< stringshared values optimized hash table holding Eiotas_Iotas */ }; +/** + * @brief Free allocated resources. + * + * @param room The Eiotas_Room to free. + * + * This function will free all it's child Eiotas_Iotas. + */ void eiotas_room_free(Eiotas_Room *room); +/** + * @brief Print iota information using EINA_LOG_DBG. + * + * @param name The name of this Eiotas_Iota. + * @param parent The direct hierarchical parent Eiotas_Room. + * + * @return the new Eiotas_Room, @c NULL on failure + * + * This function will register the new room as a child of it's parent Eiotas_Room. + */ EAPI Eiotas_Room* eiotas_room_add(const char* name, Eiotas_Room *parent); #endif // __EIOTAS_ROOM_H__ diff --git a/src/include/eiotas_spin.h b/src/include/eiotas_spin.h index 5f7470b..3854878 100644 --- a/src/include/eiotas_spin.h +++ b/src/include/eiotas_spin.h @@ -26,23 +26,77 @@ #include <eina_inlist.h> #include <eina_array.h> +/** + * @typedef Eiotas_Spin + * Type for a Spin, the top level Room which holds Eiotas_Particle fifos and free Eiotas_Particles. + */ typedef struct _Eiotas_Spin Eiotas_Spin; +/** + * @struct _Eiotas_Spin + * Struct for a Spin, the top level Room which holds Eiotas_Particle fifos and free Eiotas_Particles. + */ struct _Eiotas_Spin { - Eiotas_Room room; /* higher level Room */ - Eina_Array *free_particles; /* lifo of free to reuse Particles TODO support different particle types, use an Eina_Hash */ - Eina_Inlist *app_fifo; /* fifo of application priority particles */ - Eina_Inlist *sys_fifo; /* fifo of system priority particles */ + Eiotas_Room room; /**< higher level Room */ + Eina_Array *free_particles; /**< lifo of free to reuse Eiotas_Particles TODO support different particle types, use an Eina_Hash */ + Eina_Inlist *app_fifo; /**< fifo of application priority particles */ + Eina_Inlist *sys_fifo; /**< fifo of system priority particles */ }; +/** + * @brief Free allocated resources. + * + * @param spin The Eiotas_Spin to free. + * + * This function will free all it's child Iotas, + * all the Eiotas_Particles holded in app_fifo, sys_fifo and free_particles. + */ EAPI void eiotas_spin_free(Eiotas_Spin *spin); +/** + * @brief Allocate the resources. + * + * @param name The name of this spin. + * @param step The count of pointers to add when increasing the fifo size. + * + * @return the new allocated Eiotas_Spin @c NULL on failure + * + * @see eina_array_new(). + */ EAPI Eiotas_Spin* eiotas_spin_add(const char* name, unsigned int step); +/** + * @brief Require a Eiotas_Particle from the free list. + * + * @param spin The Eiotas_Spin to require a Eiotas_Particle from. + * + * @return a ready to use Eiotas_Particle + * + * This function will allocate and initialize a new Eiotas_Particle if there is none in the free list. + */ EAPI Eiotas_Particle* eiotas_spin_require_particle(Eiotas_Spin *spin); +/** + * @brief Release a particle. + * + * @param spin The Eiotas_Spin to restore the particle to. + * @param particle The Eiotas_Particle to be restored. + * + * This function calls eiotas_particle_reset() before giving back the Eiotas_Particle. + * Each Eiotas_Particle merged in the first one are also released. + * + * @see eiotas_particle_reset(). + */ EAPI void eiotas_spin_release_particle(Eiotas_Spin *spin, Eiotas_Particle *particle); +/** + * @brief Appand the Eiotas_Particle to the app or sys fifo. + * + * @param spin The Eiotas_Spin to post the particle to. + * @param particle The Eiotas_Particle to be sent. + * @param system Post to the system fifo us true, otherwise to the application fifo. + * + */ EAPI void eiotas_spin_send_particle(Eiotas_Spin *spin, Eiotas_Particle *particle, Eina_Bool system); #define eiotas_require_particle(_iota) eiotas_spin_require_particle((Eiotas_Spin*)((Eiotas_Iota*)(_iota))->spin) diff --git a/src/include/eiotas_userbits.h b/src/include/eiotas_userbits.h index 4e33d1e..e4149b8 100644 --- a/src/include/eiotas_userbits.h +++ b/src/include/eiotas_userbits.h @@ -22,30 +22,69 @@ #include "eiotas_iota.h" #include "eiotas_particle.h" +/** + * @typedef Eiotas_User_Bits + * Type for a Eiotas_User_Bits. + */ typedef struct _Eiotas_User_Bits Eiotas_User_Bits; +/** + * @typedef Eiotas_User_Data + * Struct for user allocated data attached to a Eiotas_Door or a Eiotas_Board + */ typedef void Eiotas_User_Data; +/** + * @typedef Eiotas_User_Data + * Type for function called on resources free + * + * @see eiotas_door_free() + * @see eiotas_board_free() + */ typedef void (*Eiotas_User_Data_Free) (Eiotas_User_Data*); +/** + * @typedef Eiotas_Receive_Particle + * Type for function called on Eiotas_Particle receive + */ typedef void (*Eiotas_Receive_Particle) (Eiotas_Iota *iota, Eiotas_Particle *particle, Eiotas_User_Data *data); +/** + * @typedef Eiotas_Init + * Type for function called on systsem init + */ typedef void (*Eiotas_Init) (Eiotas_Iota *iota, Eiotas_User_Data *data); +/** + * @typedef Eiotas_Shutdown + * Type for function called on system shutdown + */ typedef void (*Eiotas_Shutdown) (Eiotas_Iota *iota, Eiotas_User_Data *data); +/** + * @typedef Eiotas_Suspend + * Type for function called on system suspend + */ typedef void (*Eiotas_Suspend) (Eiotas_Iota *iota, Eiotas_User_Data *data); +/** + * @typedef Eiotas_Resume + * Type for function called on system resume + */ typedef void (*Eiotas_Resume) (Eiotas_Iota *iota, Eiotas_User_Data *data); +/** + * @typedef _Eiotas_User_Bits + * Type for a Eiotas_User_Bits. + */ struct _Eiotas_User_Bits { - Eiotas_User_Data *data; /* user data */ - Eiotas_User_Data_Free free_fct; /* to free user data */ - Eiotas_Receive_Particle recv_fct; /* to receive and process a particle */ - Eiotas_Init init_fct; /* to initialize user data on system init */ - Eiotas_Shutdown shutdown_fct; /* to finalize user data on system shutdown */ - Eiotas_Suspend suspend_fct; /* to serialize user data on system shutdown */ - Eiotas_Resume resume_fct; /* to deserialize data on system resume */ + Eiotas_User_Data *data; /**< user data */ + Eiotas_User_Data_Free free_fct; /**< to free user data */ + Eiotas_Receive_Particle recv_fct; /**< to receive and process a Eiotas_Particle */ + Eiotas_Init init_fct; /**< to initialize user data on system init */ + Eiotas_Shutdown shutdown_fct; /**< to finalize user data on system shutdown */ + Eiotas_Suspend suspend_fct; /**< to serialize user data on system shutdown */ + Eiotas_Resume resume_fct; /**< to deserialize data on system resume */ }; #endif // __EIOTAS_USERBITS_H__ |