enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 3 Projects Releases Wiki Activity

Ecore FD handler docs. 

SVN revision: 69540
This commit is contained in:
Jonas M. Gastal 2012-03-21 14:14:50 +00:00
parent 5900e0c953
commit 49ed7d364a
2 changed files with 103 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
legacy/ecore/src/lib/ecore/Ecore.h
View File

@ -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);

86
legacy/ecore/src/lib/ecore/ecore_main.c
View File

@ -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)