diff options
| -rw-r--r-- | src/include/eiotas_board.h | 20 | ||||
| -rw-r--r-- | src/include/eiotas_door.h | 20 | ||||
| -rw-r--r-- | src/include/eiotas_iota.h | 30 | ||||
| -rw-r--r-- | src/include/eiotas_link.h | 18 | ||||
| -rw-r--r-- | src/include/eiotas_main.h | 22 | ||||
| -rw-r--r-- | src/include/eiotas_particle.h | 36 | ||||
| -rw-r--r-- | src/include/eiotas_room.h | 32 | ||||
| -rw-r--r-- | src/include/eiotas_spin.h | 57 | ||||
| -rw-r--r-- | src/include/eiotas_userbits.h | 12 |
9 files changed, 186 insertions, 61 deletions
diff --git a/src/include/eiotas_board.h b/src/include/eiotas_board.h index 6572faf..9f8d5ef 100644 --- a/src/include/eiotas_board.h +++ b/src/include/eiotas_board.h @@ -42,9 +42,19 @@ struct _Eiotas_Board { }; /** + * @defgroup Eiotas_Board Eiotas_Board + * + * A Eiota_Board holds @ref Eiotas_Particle received. + * When two @ref Eiotas_Particle with the same link_value exists, they are merged together + * and delivered to user code through Eiotas_Receive_Particle callback. + * + * @{ + */ + +/** * @brief Free allocated resources. * - * @param board The Eiotas_Board to free. + * @param board The @ref Eiotas_Board to free. * * This function will free all it's user data using user_bits ... FIXME */ @@ -54,13 +64,17 @@ 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 parent The direct hierarchical parent @ref Eiotas_Room. * @param user_bits A Eiotas_User_Bits initilized with user side pointers. * - * @return the new allocated Eiotas_Board @c NULL on failure + * @return the new allocated @ref 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 318779f..d136c1a 100644 --- a/src/include/eiotas_door.h +++ b/src/include/eiotas_door.h @@ -41,9 +41,19 @@ struct _Eiotas_Door { }; /** + * @defgroup Eiotas_Door Eiotas_Door + * + * A Eiota_Door is the main structure used to interact with user code. + * @ref Eiotas_Particle sent to user code are, follower and sent releaseed + * through eiotas_spin_release_particle if not cprrectly managed by user code. + * + * @{ + */ + +/** * @brief Free allocated resources. * - * @param door The Eiotas_Door to free. + * @param door The @ref Eiotas_Door to free. * * This function will free all it's user data using user_bits ... FIXME */ @@ -53,13 +63,17 @@ 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 parent The direct hierarchical parent @ref Eiotas_Room. * @param user_bits A Eiotas_User_Bits initilized with user side pointers. * - * @return the new allocated Eiotas_Door @c NULL on failure + * @return the new allocated @ref 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 d54ae61..36ce1cc 100644 --- a/src/include/eiotas_iota.h +++ b/src/include/eiotas_iota.h @@ -46,29 +46,51 @@ typedef struct _Eiotas_Iota Eiotas_Iota; */ struct _Eiotas_Iota { Eiotas_Type type; /**< type of the iota */ - Eiotas_Iota *spin; /**< top level iota which is a Eiotas_Spin */ + Eiotas_Iota *spin; /**< top level iota which is a @ref 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 */ + Eina_Stringshare *path; /**< full path to this @ref Eiotas_Iota */ }; /** + * @defgroup Eiotas_Iota Eiotas_Iota + * + * This is the structural info stored in each @ref Eiotas_Room, @ref Eiotas_Door, @ref Eiotas_Board + * + * @{ + */ + +/** * @brief Print iota information using EINA_LOG_DBG. * - * @param iota The Eiotas_Iota to show. + * @param iota The @ref Eiotas_Iota to show. */ EAPI void eiotas_iota_show(Eiotas_Iota *iota); /** * @brief Free allocated resources. * - * @param iota The Eiotas_Iota to free. + * @param iota The @ref Eiotas_Iota to free. * */ void eiotas_iota_free(Eiotas_Iota *iota); +/** + * @brief Require a @ref Eiotas_Particle from the free list. + * + * @see eiotas_spin_require_particle + */ #define eiotas_iota_require_particle(_iota) eiotas_spin_require_particle((Eiotas_Spin*)(_iota)->spin) +/** + * @brief Release a particle. + * + * @see eiotas_spin_release_particle + */ #define eiotas_iota_release_particle(_iota,_particle) eiotas_spin_release_particle((Eiotas_Spin*)(_iota)->spin,_particle) +/** + * @} + */ + #endif // __EIOTAS_IOTA_H__ diff --git a/src/include/eiotas_link.h b/src/include/eiotas_link.h index 4cc4e44..2d10300 100644 --- a/src/include/eiotas_link.h +++ b/src/include/eiotas_link.h @@ -21,22 +21,34 @@ /** * @typedef Eiotas_Link - * Type for a Link between Eiotas_Iotas. + * Type for a Link between @ref Eiotas_Iota. */ typedef struct _Eiotas_Link Eiotas_Link; /** * @struct _Eiotas_Link - * Struct for a Link between Eiotas_Iotas. + * Struct for a Link between @ref Eiotas_Iota. */ struct _Eiotas_Link { }; /** + * @defgroup Eiotas_Link Eiotas_Link + * + * A Eiota_Link allows to apply a destination list to a @ref Eiotas_Particle with no defined destination. + * + * @{ + */ + +/** * @brief Free allocated resources. * - * @param link The Eiotas_Link to free. + * @param link The @ref 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 d75ab96..75ac6fe 100644 --- a/src/include/eiotas_main.h +++ b/src/include/eiotas_main.h @@ -23,20 +23,32 @@ /** * @typedef Eiotas_Version - * The version of Eiotas. + * Type for the version of Eiotas. */ -typedef struct _Eiotas_Version +typedef struct _Eiotas_Version Eiotas_Version; + +/** + * @struct _Eiotas_Version + * Struct version of Eiotas. + */ +struct _Eiotas_Version { int major; /**< Major component of the version */ int minor; /**< Minor component of the version */ int micro; /**< Micro component of the version */ -} Eiotas_Version; +}; EAPI extern Eiotas_Version *eiotas_version; EAPI extern int _eiotas_log_dom; /** + * @defgroup Eiotas_Main Eiotas + * + * @{ + */ + +/** * @brief Initialize the Eiotas library. * * @return 1 or greater on success, 0 on error. @@ -67,4 +79,8 @@ EAPI int eiotas_init(); */ EAPI int eiotas_shutdown(); +/** + * @} + */ + #endif // __EIOTAS_MAIN_H__ diff --git a/src/include/eiotas_particle.h b/src/include/eiotas_particle.h index 3f74040..5ea2215 100644 --- a/src/include/eiotas_particle.h +++ b/src/include/eiotas_particle.h @@ -50,52 +50,64 @@ struct _Eiotas_Particle { }; /** + * @defgroup Eiotas_Particle Eiotas_Particle + * + * The central part of Eiotas. The Particle holds, the data, the destination list. + * + * @{ + */ + +/** * @brief Free allocated resources. * - * @param particle The Eiotas_Particle to free. + * @param particle The @ref Eiotas_Particle to free. * - * This function will free all the merged Eiotas_Particle + * This function will free all the merged @ref Eiotas_Particle */ void eiotas_particle_free(Eiotas_Particle *particle); /** * @brief Allocate the resources. * - * @return the new allocated Eiotas_Particle @c NULL on failure + * @return the new allocated @ref Eiotas_Particle @c NULL on failure */ Eiotas_Particle* eiotas_particle_alloc(); /** - * @brief Reset the Eiotas_Particle so that it can be required later. + * @brief Reset the @ref Eiotas_Particle so that it can be required later. * - * @param particle The Eiotas_Particle to reset + * @param particle The @ref 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 + * @param particle The @ref Eiotas_Particle to init + * @param iota The @ref 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 + * @param particle The @ref Eiotas_Particle to hold @p p + * @param p The @ref 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 + * @brief Add destinations to the @ref Eiotas_Particle * - * @param particle The Eiotas_Particle to add destinations to + * @param particle The @ref 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. + * This function will append each destination found to the destination list of the @ref 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 644dc0e..c265344 100644 --- a/src/include/eiotas_room.h +++ b/src/include/eiotas_room.h @@ -25,39 +25,51 @@ /** * @typedef Eiotas_Room - * Type for a Room, which holds other child Eiotas_Iotas. + * Type for a Room, which holds other child @ref Eiotas_Iota. */ typedef struct _Eiotas_Room Eiotas_Room; /** * @struct _Eiotas_Room - * Struct for a Room, which holds other child Eiotas_Iotas. + * Struct for a Room, which holds other child @ref Eiotas_Iota. */ struct _Eiotas_Room { - Eiotas_Iota iota; /**< Eiotas_Iota structural info */ + Eiotas_Iota iota; /**< @ref Eiotas_Iota structural info */ Eina_Hash *links; /**< TODO */ - Eina_Hash *children; /**< stringshared values optimized hash table holding Eiotas_Iotas */ + Eina_Hash *children; /**< stringshared values optimized hash table holding @ref Eiotas_Iota */ }; /** + * @defgroup Eiotas_Room Eiotas_Room + * + * A Eiota_Room may hold children @ref Eiotas_Room or @ref Eiotas_Door (@ref Eiotas_Board). + * + * @{ + */ + +/** * @brief Free allocated resources. * - * @param room The Eiotas_Room to free. + * @param room The @ref Eiotas_Room to free. * - * This function will free all it's child Eiotas_Iotas. + * This function will free all it's child @ref Eiotas_Iota. */ 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. + * @param name The name of this @ref Eiotas_Iota. + * @param parent The direct hierarchical parent @ref Eiotas_Room. * - * @return the new Eiotas_Room, @c NULL on failure + * @return the new @ref Eiotas_Room, @c NULL on failure * - * This function will register the new room as a child of it's parent Eiotas_Room. + * This function will register the new room as a child of it's parent @ref 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 3854878..08742e4 100644 --- a/src/include/eiotas_spin.h +++ b/src/include/eiotas_spin.h @@ -28,28 +28,37 @@ /** * @typedef Eiotas_Spin - * Type for a Spin, the top level Room which holds Eiotas_Particle fifos and free Eiotas_Particles. + * Type for a Spin, the top level Room which holds @ref Eiotas_Particle fifos and free @ref Eiotas_Particle. */ 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 for a Spin, the top level Room which holds @ref Eiotas_Particle fifos and free @ref Eiotas_Particle. */ struct _Eiotas_Spin { 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_Array *free_particles; /**< lifo of free to reuse @ref Eiotas_Particle 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 */ }; /** + * @defgroup Eiotas_Spin Eiotas_Spin + * + * A Eiota_Spin is the top level object. It holds @ref Eiotas_Particle free list, + * @ref Eiotas_Particle system and application fifos. + * + * @{ + */ + +/** * @brief Free allocated resources. * - * @param spin The Eiotas_Spin to free. + * @param spin The @ref 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. + * all the @ref Eiotas_Particle holded in app_fifo, sys_fifo and free_particles. */ EAPI void eiotas_spin_free(Eiotas_Spin *spin); @@ -59,48 +68,62 @@ EAPI void eiotas_spin_free(Eiotas_Spin *spin); * @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 + * @return the new allocated @ref 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. + * @brief Require a @ref Eiotas_Particle from the free list. * - * @param spin The Eiotas_Spin to require a Eiotas_Particle from. + * @param spin The @ref Eiotas_Spin to require a @ref Eiotas_Particle from. * - * @return a ready to use Eiotas_Particle + * @return a ready to use @ref Eiotas_Particle * - * This function will allocate and initialize a new Eiotas_Particle if there is none in the free list. + * This function will allocate and initialize a new @ref 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. + * @param spin The @ref Eiotas_Spin to restore the particle to. + * @param particle The @ref 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. + * This function calls eiotas_particle_reset() before giving back the @ref Eiotas_Particle. + * Each @ref 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. + * @brief Append the @ref 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 spin The @ref Eiotas_Spin to post the particle to. + * @param particle The @ref 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); +/** + * @brief Require a @ref Eiotas_Particle from the free list. + * + * @see eiotas_spin_require_particle + */ #define eiotas_require_particle(_iota) eiotas_spin_require_particle((Eiotas_Spin*)((Eiotas_Iota*)(_iota))->spin) +/** + * @brief Release a particle. + * + * @see eiotas_spin_release_particle + */ #define eiotas_release_particle(_iota,_particle) eiotas_spin_release_particle((Eiotas_Spin*)((Eiotas_Iota*)(_iota))->spin,_particle) +/** + * @} + */ + #endif // __EIOTAS_SPIN_H__ diff --git a/src/include/eiotas_userbits.h b/src/include/eiotas_userbits.h index e4149b8..b48c7c2 100644 --- a/src/include/eiotas_userbits.h +++ b/src/include/eiotas_userbits.h @@ -24,13 +24,13 @@ /** * @typedef Eiotas_User_Bits - * Type for a Eiotas_User_Bits. + * Type for a @ref 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 + * Struct for user allocated data attached to a @ref Eiotas_Door or a @ref Eiotas_Board */ typedef void Eiotas_User_Data; @@ -45,7 +45,7 @@ typedef void (*Eiotas_User_Data_Free) (Eiotas_User_Data*); /** * @typedef Eiotas_Receive_Particle - * Type for function called on Eiotas_Particle receive + * Type for function called on @ref Eiotas_Particle receive */ typedef void (*Eiotas_Receive_Particle) (Eiotas_Iota *iota, Eiotas_Particle *particle, Eiotas_User_Data *data); @@ -74,13 +74,13 @@ typedef void (*Eiotas_Suspend) (Eiotas_Iota *iota, Eiotas_User_Data *data); 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 + * Struct 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 Eiotas_Particle */ + Eiotas_Receive_Particle recv_fct; /**< to receive and process a @ref 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 */ |