From 49ed7d364a98af60404e5bea073328f11d595465 Mon Sep 17 00:00:00 2001 From: "Jonas M. Gastal" Date: Wed, 21 Mar 2012 14:14:50 +0000 Subject: [PATCH] Ecore FD handler docs. SVN revision: 69540 --- legacy/ecore/src/lib/ecore/Ecore.h | 118 +++++++++++++++++++++--- legacy/ecore/src/lib/ecore/ecore_main.c | 86 ----------------- 2 files changed, 103 insertions(+), 101 deletions(-) diff --git a/legacy/ecore/src/lib/ecore/Ecore.h b/legacy/ecore/src/lib/ecore/Ecore.h index f3d8a70af0..9e218d9508 100644 --- a/legacy/ecore/src/lib/ecore/Ecore.h +++ b/legacy/ecore/src/lib/ecore/Ecore.h @@ -947,24 +947,30 @@ EAPI void ecore_exe_hup(Ecore_Exe *exe); /** * @defgroup Ecore_FD_Handler_Group File Event Handling Functions * - * Functions that deal with file descriptor handlers. + * @brief Functions that deal with file descriptor handlers. * - * The @ref Ecore_Fd_Handler can be used to watch a file descriptor - * for data available for reading, for the availability to write - * without blocking, and for errors on the file descriptor. + * File descriptor handlers facilitate reading, writing and checking for errors + * without blocking the program or doing expensive pooling. This can be used to + * monitor a socket, pipe, or other stream for which an FD can be had. * - *ecore_main_fd_handler_add() is used to setup a handler for a - * given file descriptor. This file descriptor can be the standard - * input, a network socket, a stream received through some driver - * of a hardware decoder, etc. Thus it can contain errors, like a - * disconnection, a broken pipe, and so, and that's why it's - * possible to check for these errors with the @ref ECORE_FD_ERROR - * flag. + * @warning This function @b can't be used for monitoring to regular files! * - * An @ref Ecore_Fd_Handler can be used to watch on a file - * descriptor without blocking, still being able to receive events, - * expire timers, and watch for other things that happen in - * the Ecore main loop. + * One common FD to be monitored is the standard input(stdin), monitoring it for + * reading requires a single call: + * @code + * static Eina_Bool + * _my_cb_func(void *data, Ecore_Fd_Handler *handler) + * { + * char c; + * scanf("%c", &c); //Guaranteed not to block + * ... do stuff with c ... + * } + * ecore_main_fd_handler_add(STDIN_FILENO, ECORE_FD_READ, _my_cb_func, NULL, NULL, NULL); + * @endcode + * + * When using a socket, pipe or other stream it's important to remember that + * errors may occur and as such to monitor not only for reading/writing but also + * for errors using the @ref ECORE_FD_ERROR flag. * * Example of use of a file descriptor handler: * @li @ref ecore_fd_handler_example_c @@ -1002,11 +1008,93 @@ typedef void (*Ecore_Fd_Prep_Cb)(void *data, Ecore_Fd_Handler *fd_handler); */ typedef Eina_Bool (*Ecore_Win32_Handle_Cb)(void *data, Ecore_Win32_Handler *wh); +/** + * @brief Adds a callback for activity on the given file descriptor. + * + * @param fd The file descriptor to watch. + * @param flags To monitor it for reading use @c ECORE_FD_READ, for writing @c + * ECORE_FD_WRITE, and for error @c ECORE_FD_ERROR. Values bay |(ored). + * @param func The callback function. + * @param data The data to pass to the callback. + * @param buf_func The function to call to check if any data has been buffered + * and already read from the fd. May be @c NULL. + * @param buf_data The data to pass to the @p buf_func function. + * @return A fd handler handle on success, @c NULL otherwise. + * + * @a func will be called during the execution of @ref Ecore_Main_Loop_Page + * when the file descriptor is available for reading, writing, or there has been + * an error(depending on the given @a flags). + * + * When @a func returns ECORE_CALLBACK_CANCEL, it indicates that the + * handler should be marked for deletion (identical to calling @ref + * ecore_main_fd_handler_del). + * + * @warning @a buf_func is meant for @b internal use only and should be @b + * avoided. + * + * The return value of @a buf_func has a different meaning, when it returns + * ECORE_CALLBACK_CANCEL, it indicates that @a func @b shouldn't be called, and + * when it returns ECORE_CALLBACK_RENEW it indicates @a func should be called. + * The return value of @a buf_func will not cause the FD handler to be deleted. + * + * @a buf_func is called during event loop handling to check if data that has + * been read from the file descriptor is in a buffer and is available to read. + * Some systems, notably xlib, handle their own buffering, and would otherwise + * not work with select(). These systems should use a @a buf_func. This is a + * most annoying hack, only ecore_x uses it, so refer to that for an example. + */ EAPI Ecore_Fd_Handler *ecore_main_fd_handler_add(int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data); +/** + * @brief Set the prepare callback with data for a given #Ecore_Fd_Handler + * + * @param fd_handler The fd handler + * @param func The prep function + * @param data The data to pass to the prep function + * + * This function will be called prior to any fd handler's callback function + * (even the other fd handlers), before entering the main loop select function. + * + * @note Once a prepare callback is set for a fd handler, it cannot be changed. + * You need to delete the fd handler and create a new one, to set another + * callback. + * @note You probably don't need this function. It is only necessary for very + * uncommon cases that need special behavior. + */ EAPI void ecore_main_fd_handler_prepare_callback_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data); +/** + * @brief Marks an FD handler for deletion. + * @param fd_handler The FD handler. + * @return The data pointer set using @ref ecore_main_fd_handler_add, for @a + * fd_handler on success, @c NULL otherwise. + * This function marks an fd handler to be deleted during an iteration of the + * main loop. It does NOT close the associated fd! + * + * @warning If the underlying fd is already closed ecore may complain if the + * main loop is using epoll internally, and also in some rare cases this may + * cause crashes and instability. Remember to delete your fd handlers before the + * fds they listen to are closed. + */ EAPI void *ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler); +/** + * @brief Retrieves the file descriptor that the given handler is handling. + * @param fd_handler The given FD handler. + * @return The file descriptor the handler is watching. + */ EAPI int ecore_main_fd_handler_fd_get(Ecore_Fd_Handler *fd_handler); +/** + * @brief Gets which flags are active on an FD handler. + * @param fd_handler The given FD handler. + * @param flags The flags, @c ECORE_FD_READ, @c ECORE_FD_WRITE or @c + * ECORE_FD_ERROR to query. + * @return #EINA_TRUE if any of the given flags are active, #EINA_FALSE + * otherwise. + */ EAPI Eina_Bool ecore_main_fd_handler_active_get(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags); +/** + * @brief Set what active streams the given FD handler should be monitoring. + * @param fd_handler The given FD handler. + * @param flags The flags to be watching. + */ EAPI void ecore_main_fd_handler_active_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags); EAPI Ecore_Win32_Handler *ecore_main_win32_handler_add(void *h, Ecore_Win32_Handle_Cb func, const void *data); diff --git a/legacy/ecore/src/lib/ecore/ecore_main.c b/legacy/ecore/src/lib/ecore/ecore_main.c index 8f438bd326..587c83be24 100644 --- a/legacy/ecore/src/lib/ecore/ecore_main.c +++ b/legacy/ecore/src/lib/ecore/ecore_main.c @@ -964,39 +964,6 @@ ecore_main_loop_select_func_get(void) return main_loop_select; } -/** - * Adds a callback for activity on the given file descriptor. - * - * @p func will be called during the execution of @ref ecore_main_loop_begin - * when the file descriptor is available for reading, or writing, or both. - * - * Normally when @p func returns ECORE_CALLBACK_CANCEL, it indicates that the - * handler should be marked for deletion (identical to calling @ref ecore_main_fd_handler_del). - * However, if the @p buf_func is supplied, then the return value from the @p func indicates that - * @p func should be called repeatedly until it returns ECORE_CALLBACK_CANCEL. - * - * @p buf_func is called during event loop handling to check if data that has - * been read from the file descriptor is in a buffer and is available to - * read. Some systems (notably xlib) handle their own buffering, and would - * otherwise not work with select(). These systems should use a @p buf_func. - * This is a most annoying hack, only ecore_x uses it, so refer to that for - * an example. NOTE - @p func should probably return ECORE_CALLBACK_RENEW always if - * @p buf_func is used, to avoid confusion with the other return value - * semantics. - * - * @param fd The file descriptor to watch. - * @param flags To watch it for read (@c ECORE_FD_READ) and/or - * (@c ECORE_FD_WRITE) write ability. @c ECORE_FD_ERROR - * - * @param func The callback function. - * @param data The data to pass to the callback. - * @param buf_func The function to call to check if any data has been - * buffered and already read from the fd. Can be @c NULL. - * @param buf_data The data to pass to the @p buf_func function. - * @return A fd handler handle if successful. @c NULL otherwise. - * @note This function CANNOT be used for reading/writing to regular files! - * @ingroup Ecore_FD_Handler_Group - */ EAPI Ecore_Fd_Handler * ecore_main_fd_handler_add(int fd, Ecore_Fd_Handler_Flags flags, @@ -1078,20 +1045,6 @@ ecore_main_win32_handler_add(void *h __UNUSED__, #endif -/** - * Marks an FD handler for deletion. - * @param fd_handler The FD handler. - * @return The data pointer set using @ref ecore_main_fd_handler_add, - * for @p fd_handler on success. @c NULL otherwise. - * @ingroup Ecore_FD_Handler_Group - * This function marks an fd handler to be deleted during an iteration of the main loop. - * It does NOT close the associated fd! - * - * @note If the underlying fd is already closed ecore may complain if the main loop - * is using epoll internally, and also in some rare cases this may cause - * crashes and instability. Remember to delete your fd handlers before the - * fds they listen to are closed. - */ EAPI void * ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler) { @@ -1135,24 +1088,6 @@ ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler __UNUSED__) #endif -/** - * @brief Set the prepare callback with data for a given #Ecore_Fd_Handler - * - * @param fd_handler The fd handler - * @param func The prep function - * @param data The data to pass to the prep function - * - * This function will be called prior to any fd handler's callback function - * (even the other fd handlers), before entering the main loop select function. - * - * @note Once a prepare callback is set for a fd handler, it cannot be changed. - * You need to delete the fd handler and create a new one, to set another - * callback. - * @note You probably don't need this function. It is only necessary for very - * uncommon cases that need special behavior. - * - * @ingroup Ecore_FD_Handler_Group - */ EAPI void ecore_main_fd_handler_prepare_callback_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, @@ -1176,12 +1111,6 @@ unlock: _ecore_unlock(); } -/** - * Retrieves the file descriptor that the given handler is handling. - * @param fd_handler The given FD handler. - * @return The file descriptor the handler is watching. - * @ingroup Ecore_FD_Handler_Group - */ EAPI int ecore_main_fd_handler_fd_get(Ecore_Fd_Handler *fd_handler) { @@ -1201,15 +1130,6 @@ unlock: return fd; } -/** - * Return if read, write or error, or a combination thereof, is active on the - * file descriptor of the given FD handler. - * @param fd_handler The given FD handler. - * @param flags The flags, @c ECORE_FD_READ, @c ECORE_FD_WRITE or - * @c ECORE_FD_ERROR to query. - * @return #EINA_TRUE if any of the given flags are active. #EINA_FALSE otherwise. - * @ingroup Ecore_FD_Handler_Group - */ EAPI Eina_Bool ecore_main_fd_handler_active_get(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags) @@ -1232,12 +1152,6 @@ unlock: return ret; } -/** - * Set what active streams the given FD handler should be monitoring. - * @param fd_handler The given FD handler. - * @param flags The flags to be watching. - * @ingroup Ecore_FD_Handler_Group - */ EAPI void ecore_main_fd_handler_active_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags)