forked from enlightenment/efl
eina: Add doxygen in/out tags for cow, cpu, and debug
Reviewers: devilhorns Reviewed By: devilhorns Subscribers: cedric, #committers, zmike Tags: #efl Differential Revision: https://phab.enlightenment.org/D6642
This commit is contained in:
Bryce Harrington
Mike Blumenkrantz
parent
e34136ea72
commit
d9515f002a
|
|
@ -54,11 +54,11 @@ typedef void Eina_Cow_Data;
|
|||
/**
|
||||
* @brief Instantiates a new Eina_Cow pool.
|
||||
*
|
||||
* @param name The name of this pool, used for debugging.
|
||||
* @param struct_size The size of the object from this pool.
|
||||
* @param step How many objects to allocate when the pool gets empty.
|
||||
* @param default_value The default value returned by this pool.
|
||||
* @param gc Is it possible to run garbage collection on this pool.
|
||||
* @param[in] name The name of this pool, used for debugging.
|
||||
* @param[in] struct_size The size of the object from this pool.
|
||||
* @param[in] step How many objects to allocate when the pool gets empty.
|
||||
* @param[in] default_value The default value returned by this pool.
|
||||
* @param[in] gc Is it possible to run garbage collection on this pool.
|
||||
* @return A valid new Eina_Cow, or @c NULL on error.
|
||||
*/
|
||||
EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned int step, const void *default_value, Eina_Bool gc) EINA_WARN_UNUSED_RESULT;
|
||||
|
|
@ -66,21 +66,23 @@ EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned
|
|||
/**
|
||||
* @brief Destroys an Eina_Cow pool and all the allocated memory.
|
||||
*
|
||||
* @param cow The pool to destroy
|
||||
* @param[in] cow The pool to destroy
|
||||
*/
|
||||
EAPI void eina_cow_del(Eina_Cow *cow);
|
||||
|
||||
/**
|
||||
* @brief Returns an initialized pointer from the pool.
|
||||
* @param cow The pool to take things from.
|
||||
*
|
||||
* @param[in] cow The pool to take things from.
|
||||
* @return A pointer to the new pool instance
|
||||
*/
|
||||
EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Frees a pointer from the pool.
|
||||
* @param cow The pool to gave back memory to.
|
||||
* @param data The data to give back.
|
||||
*
|
||||
* @param[in,out] cow The pool to gave back memory to.
|
||||
* @param[in] data The data to give back.
|
||||
*
|
||||
* @note To simplify the caller code *data will point to the default
|
||||
* read only state after the call to this function.
|
||||
|
|
@ -89,19 +91,22 @@ EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data **data);
|
|||
|
||||
/**
|
||||
* @brief Gets a writeable pointer from a const pointer.
|
||||
* @param cow The pool the pointer came from.
|
||||
* @param src The pointer you want to write to.
|
||||
*
|
||||
* @param[in,out] cow The pool the pointer came from.
|
||||
* @param[in] src The pointer you want to write to.
|
||||
*
|
||||
* NOTE: this function is not thread safe, be careful.
|
||||
*/
|
||||
EAPI void *eina_cow_write(Eina_Cow *cow,
|
||||
const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Sets back a pointer into read only.
|
||||
* @param cow The pool the pointer came from.
|
||||
* @param dst The read only version of the pointer.
|
||||
* @param data The pointer to which data was written to.
|
||||
* @param needed_gc Does this pool need to be garbage collected?
|
||||
*
|
||||
* @param[in,out] cow The pool the pointer came from.
|
||||
* @param[in] dst The read only version of the pointer.
|
||||
* @param[in] data The pointer to which data was written to.
|
||||
* @param[in] needed_gc Does this pool need to be garbage collected?
|
||||
*
|
||||
* NOTE: this function is not thread safe, be careful.
|
||||
*/
|
||||
|
|
@ -111,9 +116,10 @@ EAPI void eina_cow_done(Eina_Cow *cow,
|
|||
Eina_Bool needed_gc);
|
||||
/**
|
||||
* @brief Makes the destination contain the same thing as the source pointer.
|
||||
* @param cow The pool the pointers came from.
|
||||
* @param dst The destination to update.
|
||||
* @param src The source of information to copy.
|
||||
*
|
||||
* @param[in,out] cow The pool the pointers came from.
|
||||
* @param[in] dst The destination to update.
|
||||
* @param[in] src The source of information to copy.
|
||||
*/
|
||||
EAPI void eina_cow_memcpy(Eina_Cow *cow,
|
||||
const Eina_Cow_Data * const *dst,
|
||||
|
|
@ -121,7 +127,8 @@ EAPI void eina_cow_memcpy(Eina_Cow *cow,
|
|||
|
||||
/**
|
||||
* @brief Tries to find entries that have the same content and update them.
|
||||
* @param cow The cow to try to compact.
|
||||
*
|
||||
* @param[in,out] cow The cow to try to compact.
|
||||
* @return EINA_TRUE if something was compacted, EINA_FALSE if nothing was.
|
||||
*
|
||||
* There is no guaranty in the time it will require, but should remain low.
|
||||
|
|
@ -133,10 +140,11 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
|
|||
/**
|
||||
* @def EINA_COW_WRITE_BEGIN
|
||||
* @brief Definition for the macro to setup a writeable pointer from a const one.
|
||||
* @param Cow The Eina_Cow where the const pointer came from.
|
||||
* @param Read The const pointer to get a writable handler from.
|
||||
* @param Write_Type The type of the pointer you want to write to.
|
||||
* @param Write The name of the variable where to put the writeable pointer to.
|
||||
*
|
||||
* @param[in,out] Cow The Eina_Cow where the const pointer came from.
|
||||
* @param[in] Read The const pointer to get a writable handler from.
|
||||
* @param[in] Write_Type The type of the pointer you want to write to.
|
||||
* @param[in] Write The name of the variable where to put the writeable pointer to.
|
||||
* @since 1.8.0
|
||||
*
|
||||
* Be careful: this macro opens a C scope that is expected to be closed by
|
||||
|
|
@ -152,9 +160,9 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
|
|||
/**
|
||||
* @def EINA_COW_WRITE_END
|
||||
* @brief Definition for the macro to close the writeable pointer.
|
||||
* @param Cow The Eina_Cow where the const pointer came from.
|
||||
* @param Read The const pointer to get a writable handler from.
|
||||
* @param Write The name of the variable where to put the writeable pointer to.
|
||||
* @param[in,out] Cow The Eina_Cow where the const pointer came from.
|
||||
* @param[in] Read The const pointer to get a writable handler from.
|
||||
* @param[in] Write The name of the variable where to put the writeable pointer to.
|
||||
* @since 1.8.0
|
||||
*
|
||||
* Be careful: this macro close the scope opened by EINA_COW_WRITE_BEGIN().
|
||||
|
|
|
|||
|
|
@ -92,7 +92,7 @@ EAPI int eina_cpu_page_size(void);
|
|||
/**
|
||||
* @brief Reverses the byte order of a 16-bit (destination) register.
|
||||
*
|
||||
* @param x The binary word to swap
|
||||
* @param[in] x The binary word to swap
|
||||
* @return A byte order swapped 16-bit integer.
|
||||
*
|
||||
* On big endian systems, the number is converted to little endian byte order.
|
||||
|
|
@ -103,7 +103,7 @@ static inline unsigned short eina_swap16(unsigned short x);
|
|||
/**
|
||||
* @brief Reverses the byte order of a 32-bit (destination) register.
|
||||
*
|
||||
* @param x The binary word to swap
|
||||
* @param[in] x The binary word to swap
|
||||
* @return A byte order swapped 32-bit integer.
|
||||
*
|
||||
* On big endian systems, the number is converted to little endian byte order.
|
||||
|
|
@ -114,7 +114,7 @@ static inline unsigned int eina_swap32(unsigned int x);
|
|||
/**
|
||||
* @brief Reverses the byte order of a 64-bit (destination) register.
|
||||
*
|
||||
* @param x The binary word to swap
|
||||
* @param[in] x The binary word to swap
|
||||
* @return A byte order swapped 64-bit integer.
|
||||
*
|
||||
* On big endian systems, the number is converted to little endian byte order.
|
||||
|
|
|
|||
|
|
@ -56,10 +56,10 @@ typedef struct _Eina_Debug_Session Eina_Debug_Session;
|
|||
*
|
||||
* A callback invoked when a specific packet is received.
|
||||
*
|
||||
* @param session the session
|
||||
* @param srcid the source id
|
||||
* @param buffer the packet payload data. It doesn't contain any transport information.
|
||||
* @param size the packet payload size
|
||||
* @param[in,out] session the session
|
||||
* @param[in] srcid the source id
|
||||
* @param[in] buffer the packet payload data. It doesn't contain any transport information.
|
||||
* @param[in] size the packet payload size
|
||||
*
|
||||
* return true on success, false if the connection seems compromised
|
||||
*/
|
||||
|
|
@ -75,8 +75,8 @@ typedef Eina_Bool (*Eina_Debug_Cb)(Eina_Debug_Session *session, int srcid, void
|
|||
* layer should not try to send more requests until a new connection is
|
||||
* established.
|
||||
*
|
||||
* @param data data pointer given when registering opcodes
|
||||
* @param status EINA_TRUE if opcodes have been received from the daemon, EINA_FALSE otherwise.
|
||||
* @param[in,out] data data pointer given when registering opcodes
|
||||
* @param[in] status EINA_TRUE if opcodes have been received from the daemon, EINA_FALSE otherwise.
|
||||
*/
|
||||
typedef void (*Eina_Debug_Opcode_Status_Cb)(void *data, Eina_Bool status);
|
||||
|
||||
|
|
@ -86,8 +86,8 @@ typedef void (*Eina_Debug_Opcode_Status_Cb)(void *data, Eina_Bool status);
|
|||
* Dispatcher callback prototype used to override the default dispatcher of a
|
||||
* session.
|
||||
*
|
||||
* @param session the session
|
||||
* @param buffer the packet received
|
||||
* @param[in,out] session the session
|
||||
* @param[in] buffer the packet received
|
||||
*
|
||||
* The given packet is the entire data received, including the header.
|
||||
*
|
||||
|
|
@ -167,7 +167,7 @@ EAPI void eina_debug_disable(void);
|
|||
/**
|
||||
* @brief Connect to the local daemon
|
||||
*
|
||||
* @param is_master true if the application is a debugger. EINA_FALSE otherwise.
|
||||
* @param[in] is_master true if the application is a debugger. EINA_FALSE otherwise.
|
||||
*
|
||||
* @return the session on success or NULL otherwise
|
||||
*/
|
||||
|
|
@ -178,7 +178,7 @@ EAPI Eina_Debug_Session *eina_debug_local_connect(Eina_Bool is_master);
|
|||
*
|
||||
* This function connects to localhost:port.
|
||||
*
|
||||
* @param port the port to connect to
|
||||
* @param[in] port the port to connect to
|
||||
*
|
||||
* @return the session on success or NULL otherwise
|
||||
*/
|
||||
|
|
@ -187,8 +187,7 @@ EAPI Eina_Debug_Session *eina_debug_remote_connect(int port);
|
|||
/**
|
||||
* @brief Terminate the session
|
||||
*
|
||||
* @param session the session to terminate
|
||||
*
|
||||
* @param[in,out] session the session to terminate
|
||||
*/
|
||||
EAPI void eina_debug_session_terminate(Eina_Debug_Session *session);
|
||||
|
||||
|
|
@ -199,15 +198,15 @@ EAPI void eina_debug_session_terminate(Eina_Debug_Session *session);
|
|||
* use the default dispatcher there.
|
||||
* All the packets received in this session will use this dispatcher.
|
||||
*
|
||||
* @param session the session
|
||||
* @disp_cb the new dispatcher for the given session
|
||||
* @param[in,out] session the session
|
||||
* @param[in] disp_cb the new dispatcher for the given session
|
||||
*/
|
||||
EAPI void eina_debug_session_dispatch_override(Eina_Debug_Session *session, Eina_Debug_Dispatch_Cb disp_cb);
|
||||
|
||||
/**
|
||||
* @brief Get the dispatcher of a specific session
|
||||
*
|
||||
* @param session the session
|
||||
* @param[in,out] session the session
|
||||
*
|
||||
* @return the session dispatcher
|
||||
*/
|
||||
|
|
@ -220,8 +219,8 @@ EAPI Eina_Debug_Dispatch_Cb eina_debug_session_dispatch_get(Eina_Debug_Session *
|
|||
* the correct callback according to the opcode.
|
||||
* This is the default dispatcher.
|
||||
*
|
||||
* @param session the session
|
||||
* @param buffer the packet
|
||||
* @param[in,out] session the session
|
||||
* @param[in] buffer the packet
|
||||
*
|
||||
* return true on success, false if the connection seems compromised
|
||||
*/
|
||||
|
|
@ -230,16 +229,15 @@ EAPI Eina_Bool eina_debug_dispatch(Eina_Debug_Session *session, void *buffer);
|
|||
/**
|
||||
* @brief Set data to a session
|
||||
*
|
||||
* @param session the session
|
||||
* @param data the data to set
|
||||
*
|
||||
* @param[in,out] session the session
|
||||
* @param[in] data the data to set
|
||||
*/
|
||||
EAPI void eina_debug_session_data_set(Eina_Debug_Session *session, void *data);
|
||||
|
||||
/**
|
||||
* @brief Get the data attached to a session
|
||||
*
|
||||
* @param session the session
|
||||
* @param[in,out] session the session
|
||||
*
|
||||
* @return the data of the session
|
||||
*/
|
||||
|
|
@ -254,10 +252,10 @@ EAPI void *eina_debug_session_data_get(Eina_Debug_Session *session);
|
|||
* On the reception from the daemon, status_cb function is invoked to inform
|
||||
* the requester that the opcodes can now be used.
|
||||
*
|
||||
* @param session the session
|
||||
* @param ops the operations to register
|
||||
* @param status_cb a function to call when the opcodes are received
|
||||
* @param status_data the data to give to status_cb
|
||||
* @param[in,out] session the session
|
||||
* @param[in] ops the operations to register
|
||||
* @param[in] status_cb a function to call when the opcodes are received
|
||||
* @param[in] status_data the data to give to status_cb
|
||||
*/
|
||||
EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session,
|
||||
const Eina_Debug_Opcode ops[],
|
||||
|
|
@ -268,11 +266,11 @@ EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session,
|
|||
*
|
||||
* The packet will be treated by the debug thread itself.
|
||||
*
|
||||
* @param session the session to use to send the packet
|
||||
* @param dest_id the destination id to send the packet to
|
||||
* @param op the opcode for this packet
|
||||
* @param data payload to send
|
||||
* @param size payload size
|
||||
* @param[in,out] session the session to use to send the packet
|
||||
* @param[in] dest_id the destination id to send the packet to
|
||||
* @param[in] op the opcode for this packet
|
||||
* @param[in] data payload to send
|
||||
* @param[in] size payload size
|
||||
*
|
||||
* @return the number of sent bytes
|
||||
*/
|
||||
|
|
@ -281,9 +279,9 @@ EAPI int eina_debug_session_send(Eina_Debug_Session *session, int dest_id, int o
|
|||
/**
|
||||
* @brief Add a timer
|
||||
*
|
||||
* @param timeout_ms timeout in ms
|
||||
* @param cb callback to call when the timeout is reached
|
||||
* @param data user data
|
||||
* @param[in] timeout_ms timeout in ms
|
||||
* @param[in] cb callback to call when the timeout is reached
|
||||
* @param[in] data user data
|
||||
*
|
||||
* @return the timer handle, NULL on error
|
||||
*/
|
||||
|
|
@ -292,7 +290,7 @@ EAPI Eina_Debug_Timer *eina_debug_timer_add(unsigned int timeout_ms, Eina_Debug_
|
|||
/**
|
||||
* @brief Delete a timer
|
||||
*
|
||||
* @param timer the timer to delete
|
||||
* @param[in,out] timer the timer to delete
|
||||
*
|
||||
* If the timer reaches the end and has not be renewed, trying to delete it will lead to a crash, as
|
||||
* it has already been deleted internally.
|
||||
|
|
|
|||
Loading…
Reference in New Issue