From 164ea41b3e9a8a9e518c4469631488d0d284c462 Mon Sep 17 00:00:00 2001 From: "Carsten Haitzler (Rasterman)" Date: Sat, 26 Jul 2014 09:19:30 +0900 Subject: [PATCH] move ecore documentation not in headers to .h files for consistency --- src/lib/ecore/Ecore_Common.h | 745 ++++++++++++++++++++++++++++- src/lib/ecore/Ecore_Getopt.h | 178 ++++++- src/lib/ecore/Ecore_Legacy.h | 91 ++++ src/lib/ecore/ecore.c | 69 +-- src/lib/ecore/ecore_app.c | 37 -- src/lib/ecore/ecore_exe.c | 217 --------- src/lib/ecore/ecore_getopt.c | 172 ------- src/lib/ecore/ecore_glib.c | 70 --- src/lib/ecore/ecore_idle_enterer.c | 39 +- src/lib/ecore/ecore_idle_exiter.c | 26 +- src/lib/ecore/ecore_idler.c | 10 +- src/lib/ecore/ecore_job.c | 24 - src/lib/ecore/ecore_main.c | 98 +--- src/lib/ecore/ecore_pipe.c | 77 +-- src/lib/ecore/ecore_poll.c | 4 - src/lib/ecore/ecore_throttle.c | 66 --- src/lib/ecore/ecore_time.c | 56 +-- src/lib/ecore/ecore_timer.c | 143 ------ src/lib/ecore/ecore_timer.eo | 45 +- 19 files changed, 1071 insertions(+), 1096 deletions(-) diff --git a/src/lib/ecore/Ecore_Common.h b/src/lib/ecore/Ecore_Common.h index e41ec5eb68..06b35e5074 100644 --- a/src/lib/ecore/Ecore_Common.h +++ b/src/lib/ecore/Ecore_Common.h @@ -11,8 +11,43 @@ extern "C" { * @{ */ +/** + * Set up connections, signal handlers, sockets etc. + * @return 1 or greater on success, 0 otherwise + * + * This function sets up all singal handlers and the basic event loop. If it + * succeeds, 1 will be returned, otherwise 0 will be returned. + * + * @code + * #include + * + * int main(int argc, char **argv) + * { + * if (!ecore_init()) + * { + * printf("ERROR: Cannot init Ecore!\n"); + * return -1; + * } + * ecore_main_loop_begin(); + * ecore_shutdown(); + * } + * @endcode + */ EAPI int ecore_init(void); + +/** + * Shut down connections, signal handlers sockets etc. + * + * @return 0 if ecore shuts down, greater than 0 otherwise. + * This function shuts down all things set up in ecore_init() and cleans up all + * event queues, handlers, filters, timers, idlers, idle enterers/exiters + * etc. set up after ecore_init() was called. + * + * Do not call this function from any callback that may be called from the main + * loop, as the main loop will then fall over and not function properly. + */ EAPI int ecore_shutdown(void); + /** * @} */ @@ -63,16 +98,164 @@ typedef Eina_Bool (*Ecore_Task_Cb)(void *data); */ typedef int (*Ecore_Select_Function)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); +/** + * Runs a single iteration of the main loop to process everything on the + * queue. + * + * It does everything that is already done inside an @c Ecore main loop, like + * checking for expired timers, idlers, etc. But it will do it only once and + * return, instead of keep watching for new events. + * + * DO NOT use this function unless you are the person God comes to ask for + * advice when He has trouble managing the Universe. + * + * @see ecore_main_loop_iterate_may_block() + */ EAPI void ecore_main_loop_iterate(void); +/** + * Runs a single iteration of the main loop to process everything on the + * queue with block/non-blocking status. + * + * @param may_block A flag if the main loop has a possibility of blocking. + * (@c EINA_TRUE = may block/@c EINA_FALSE = non block) + * + * This is an extension API for ecore_main_loop_iterate() with additional + * parameter. It does everything that is already done inside an + * @c Ecore main loop, like checking for expired timers, idlers, etc. But it + * will do it only once and return, instead of keep watching for new events. + * + * DO NOT use this function unless you are the person God comes to ask for + * advice when He has trouble managing the Universe. + * + * @see ecore_main_loop_iterate() + */ +EAPI int ecore_main_loop_iterate_may_block(int may_block); + +/** + * Sets the function to use when monitoring multiple file descriptors, + * and waiting until one of more of the file descriptors before ready + * for some class of I/O operation. + * + * This function will be used instead of the system call select and + * could possible be used to integrate the Ecore event loop with an + * external event loop. + * + * @warning you don't know how to use, don't even try to use it. + * + * @param func The function to be used. + */ EAPI void ecore_main_loop_select_func_set(Ecore_Select_Function func); + +/** + * Gets the select function set by ecore_select_func_set(), + * or the native select function if none was set. + * + */ EAPI Ecore_Select_Function ecore_main_loop_select_func_get(void); +/** + * Request ecore to integrate GLib's main loop. + * + * This will add a small overhead during every main loop interaction + * by checking glib's default main context (used by its main loop). If + * it have events to be checked (timers, file descriptors or idlers), + * then these will be polled alongside with Ecore's own events, then + * dispatched before Ecore's. This is done by calling + * ecore_main_loop_select_func_set(). + * + * This will cooperate with previously set + * ecore_main_loop_select_func_set() by calling the old + * function. Similarly, if you want to override + * ecore_main_loop_select_func_set() after main loop is integrated, + * call the new select function set by this call (get it by calling + * ecore_main_loop_select_func_get() right after + * ecore_main_loop_glib_integrate()). + * + * This is useful to use GMainLoop libraries, like GTK, GUPnP, + * LibSoup, GConf and more. Adobe Flash plugin and other plugins + * systems depend on this as well. + * + * Once initialized/integrated, it will be valid until Ecore is + * completely shut down. + * + * Example of use: + * @code + * + * int main(void) + * { + * ecore_init(); + * ecore_main_loop_glib_integrate(); + * + * // some code here + * + * ecore_main_loop_begin(); + * + * ecore_shutdown(); + * + * return 0; + * } + * + * @endcode + * + * @note This is only available if Ecore was compiled with GLib support. + * @note You don't need to call this function if Ecore was compiled with + * --with-glib=always. + * + * @return @c EINA_TRUE on success of @c EINA_FALSE if it failed, + * likely no GLib support in Ecore. + */ EAPI Eina_Bool ecore_main_loop_glib_integrate(void); + +/** + * Disable always integrating glib + * + * If ecore is compiled with --with-glib=always (to always call + * ecore_main_loop_glib_integrate() when ecore_init() is called), then calling + * this before calling ecore_init() will disable the integration. + * This is for apps that explicitly do not want this to happen for whatever + * reasons they may have. + */ EAPI void ecore_main_loop_glib_always_integrate_disable(void); +/** + * Runs the application main loop. + * + * This function will not return until @ref ecore_main_loop_quit is called. It + * will check for expired timers, idlers, file descriptors being watched by fd + * handlers, etc. Once everything is done, before entering again on idle state, + * any callback set as @c Idle_Enterer will be called. + * + * Each main loop iteration is done by calling ecore_main_loop_iterate() + * internally. + * + * The polling (select) function used can be changed with + * ecore_main_loop_select_func_set(). + * + * The function used to check for file descriptors, events, and that has a + * timeout for the timers can be changed using + * ecore_main_loop_select_func_set(). + */ EAPI void ecore_main_loop_begin(void); + +/** + * Quits the main loop once all the events currently on the queue have + * been processed. + * + * This function returns immediately, but will mark the ecore_main_loop_begin() + * function to return at the end of the current main loop iteration. + */ EAPI void ecore_main_loop_quit(void); + +/** + * Returns if an animator has ticked off during this loop iteration + * + * @return EINA_TRUE if an animator has been called, EINA_FALSE otherwise. + * + * There should be little need for anyone to use this - ever. + * + * @since 1.9 + */ EAPI Eina_Bool ecore_main_loop_animator_ticked_get(void); /** @@ -384,6 +567,7 @@ struct _Ecore_Event_Signal_Realtime /** Realtime event */ * been called, will not be. */ EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data); + /** * @brief Delete an event handler. * @param event_handler Event handler handle to delete @@ -395,6 +579,7 @@ EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_ * returned. Once a handler is deleted it will no longer be called. */ EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler); + /** * @brief Add an event to the event queue. * @param type The event type to add to the end of the event queue @@ -411,6 +596,7 @@ EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler); * structure pointer. */ EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data); + /** * @brief Delete an event from the queue. * @param event The event handle to delete @@ -423,6 +609,7 @@ EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, vo * you should defer cleaning of this till the free function is called later. */ EAPI void *ecore_event_del(Ecore_Event *event); + /** * @brief Get the data associated with an #Ecore_Event_Handler * @param eh The event handler @@ -432,6 +619,7 @@ EAPI void *ecore_event_del(Ecore_Event *event); * ecore_event_handler_add(). */ EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh); + /** * @brief Set the data associated with an #Ecore_Event_Handler * @param eh The event handler @@ -442,6 +630,7 @@ EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh); * which was previously associated with @p eh by ecore_event_handler_add(). */ EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data); + /** * @brief Allocate a new event type id sensibly and return the new id. * @return A new event type id. @@ -453,6 +642,7 @@ EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *dat * of the process. */ EAPI int ecore_event_type_new(void); + /** * @brief Add a filter the current event queue. * @@ -474,6 +664,7 @@ EAPI int ecore_event_type_new(void); * pointer to clean up. */ EAPI Ecore_Event_Filter *ecore_event_filter_add(Ecore_Data_Cb func_start, Ecore_Filter_Cb func_filter, Ecore_End_Cb func_end, const void *data); + /** * @brief Delete an event filter. * @param ef The event filter handle @@ -482,6 +673,7 @@ EAPI Ecore_Event_Filter *ecore_event_filter_add(Ecore_Data_Cb func_start, Ecore_ * Delete a filter that has been added by its @p ef handle. */ EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef); + /** * @brief Return the current event type being handled. * @return The current event type being handled if inside a handler callback, @@ -497,6 +689,7 @@ EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef); * information about. */ EAPI int ecore_event_current_type_get(void); + /** * @brief Return the current event type pointer handled. * @return The current event pointer being handled if inside a handler callback, @@ -594,7 +787,7 @@ EAPI Ecore_Memory_State ecore_memory_state_get(void); * @since 1.8 */ EAPI void ecore_memory_state_set(Ecore_Memory_State state); - + /** * @enum _Ecore_Power_State @@ -631,7 +824,6 @@ EAPI Ecore_Power_State ecore_power_state_get(void); * @since 1.8 */ EAPI void ecore_power_state_set(Ecore_Power_State state); - /** * @} @@ -747,31 +939,263 @@ struct _Ecore_Exe_Event_Data /** Data from a child process event */ Ecore_Exe_Event_Data_Line *lines; /**< an array of line data if line buffered, the last one has it's line member set to @c NULL */ }; +/** + * Sets the priority at which to launch processes + * + * This sets the priority of processes run by ecore_exe_run() and + * ecore_exe_pipe_run(). + * @li On Windows, the child process is created by default with the + * @ref ECORE_EXE_WIN32_PRIORITY_NORMAL priority, unless the calling + * process is in @ref ECORE_EXE_WIN32_PRIORITY_IDLE or + * @ref ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL priority. In that case, the + * child process inherits this priority. + * @li On other platforms, if set to @ref ECORE_EXE_PRIORITY_INHERIT child + * processes inherits the priority of their parent. This is the default. + * + * @param pri value a Ecore_Exe_Win32_Priority value on Windows, -20 + * to 19 or @ref ECORE_EXE_PRIORITY_INHERIT on other OS. + */ EAPI void ecore_exe_run_priority_set(int pri); + +/** + * Gets the priority at which to launch processes + * + * This gets ths priority of launched processes. See + * ecore_exe_run_priority_set() for details. This just returns the value set + * by this call. + * + * @return the value set by ecore_exe_run_priority_set() + */ EAPI int ecore_exe_run_priority_get(void); + +/** + * Spawns a child process. + * + * This is now just a thin wrapper around ecore_exe_pipe_run() + * @note When you use this function you will have no permissions + * to write or read on the pipe that connects you with the spwaned process. + * If you need to do that use ecore_exe_pipe_run() with the + * appropriated flags. + * + * @param exe_cmd The command to run with @c /bin/sh. + * @param data Data to attach to the returned process handle. + * @return A process handle to the spawned process. + */ EAPI Ecore_Exe *ecore_exe_run(const char *exe_cmd, const void *data); + +/** + * Spawns a child process with its stdin/out available for communication. + * + * This function forks and runs the given command using @c /bin/sh. + * + * Note that the process handle is only valid until a child process + * terminated event is received. After all handlers for the child process + * terminated event have been called, the handle will be freed by Ecore. + * + * This function does the same thing as ecore_exe_run(), but also makes the + * standard in and/or out as well as stderr from the child process available + * for reading or writing. To write use ecore_exe_send(). To read listen to + * ECORE_EXE_EVENT_DATA or ECORE_EXE_EVENT_ERROR events (set up handlers). + * Ecore may buffer read and error data until a newline character if asked + * for with the @p flags. All data will be included in the events (newlines + * will be replaced with NULLS if line buffered). ECORE_EXE_EVENT_DATA events + * will only happen if the process is run with ECORE_EXE_PIPE_READ enabled + * in the flags. The same with the error version. Writing will only be + * allowed with ECORE_EXE_PIPE_WRITE enabled in the flags. + * + * @param exe_cmd The command to run with @c /bin/sh. + * @param flags The flag parameters for how to deal with inter-process I/O + * @param data Data to attach to the returned process handle. + * @return A process handle to the spawned process. + */ EAPI Ecore_Exe *ecore_exe_pipe_run(const char *exe_cmd, Ecore_Exe_Flags flags, const void *data); + +/** + * Defines a function to be called before really freeing the handle data. + * + * This might be useful for language bindings such as Python and Perl + * that need to deallocate wrappers associated with this handle. + * + * This handle should never be modified by this call. It should be + * considered informative only. All getters are valid when the given + * function is called back. + * + * @param exe The child process to attach the pre_free function. + * @param func The function to call before @a exe is freed. + */ EAPI void ecore_exe_callback_pre_free_set(Ecore_Exe *exe, Ecore_Exe_Cb func); + +/** + * Sends data to the given child process which it receives on stdin. + * + * This function writes to a child processes standard in, with unlimited + * buffering. This call will never block. It may fail if the system runs out + * of memory. + * + * @param exe The child process to send to + * @param data The data to send + * @param size The size of the data to send, in bytes + * @return @c EINA_TRUE if successful, @c EINA_FALSE on failure. + */ EAPI Eina_Bool ecore_exe_send(Ecore_Exe *exe, const void *data, int size); + +/** + * The stdin of the given child process will close when the write buffer is empty. + * + * @param exe The child process + */ EAPI void ecore_exe_close_stdin(Ecore_Exe *exe); + +/** + * Sets the auto pipe limits for the given process handle. On Windows + * this function does nothing. + * + * @param exe The given process handle. + * @param start_bytes limit of bytes at start of output to buffer. + * @param end_bytes limit of bytes at end of output to buffer. + * @param start_lines limit of lines at start of output to buffer. + * @param end_lines limit of lines at end of output to buffer. + */ EAPI void ecore_exe_auto_limits_set(Ecore_Exe *exe, int start_bytes, int end_bytes, int start_lines, int end_lines); + +/** + * Gets the auto pipe data for the given process handle + * + * @param exe The given process handle. + * @param flags Is this a ECORE_EXE_PIPE_READ or ECORE_EXE_PIPE_ERROR? + * @return The event data. + */ EAPI Ecore_Exe_Event_Data *ecore_exe_event_data_get(Ecore_Exe *exe, Ecore_Exe_Flags flags); + +/** + * Frees the given event data. + * + * @param e The given event data. + */ EAPI void ecore_exe_event_data_free(Ecore_Exe_Event_Data *data); + +/** + * Frees the given process handle. + * + * Note that the process that the handle represents is unaffected by this + * function. + * + * @param exe The given process handle. + * @return The data attached to the handle when @ref ecore_exe_run was + * called. + */ EAPI void *ecore_exe_free(Ecore_Exe *exe); + +/** + * Retrieves the process ID of the given spawned process. + * @param exe Handle to the given spawned process. + * @return The process ID on success. @c -1 otherwise. + */ EAPI pid_t ecore_exe_pid_get(const Ecore_Exe *exe); + +/** + * Sets the string tag for the given process handle + * + * @param exe The given process handle. + * @param tag The string tag to set on the process handle. + */ EAPI void ecore_exe_tag_set(Ecore_Exe *exe, const char *tag); + +/** + * Retrieves the tag attached to the given process handle. There is no need to + * free it as it just returns the internal pointer value. This value is only + * valid as long as the @p exe is valid or until the tag is set to something + * else on this @p exe. + * + * @param exe The given process handle. + * @return The string attached to @p exe. It is a handle to existing + * internal string and should not be modified, use + * ecore_exe_tag_set() to change it. It might be @c NULL. + */ EAPI const char *ecore_exe_tag_get(const Ecore_Exe *exe); + +/** + * Retrieves the command of the given spawned process. + * @param exe Handle to the given spawned process. + * @return The command on success, @c NULL otherwise. This string is the + * pointer to the internal value and must not be modified in + * any way. + */ EAPI const char *ecore_exe_cmd_get(const Ecore_Exe *exe); + +/** + * Retrieves the data attached to the given process handle. + * @param exe The given process handle. + * @return The data pointer attached to @p exe Given to + * ecore_exe_run() or ecore_exe_pipe_run() + */ EAPI void *ecore_exe_data_get(const Ecore_Exe *exe); + +/** + * Sets the data attached to the given process handle. + * @param exe The given process handle. + * @param data The pointer to attach + * @return The data pointer previously attached to @p exe with + * ecore_exe_run(), ecore_exe_pipe_run(), or ecore_exe_data_set() + * @since 1.1 + */ EAPI void *ecore_exe_data_set(Ecore_Exe *exe, void *data); + +/** + * Retrieves the flags attached to the given process handle. + * @param exe The given process handle. + * @return The flags attached to @p exe. + */ EAPI Ecore_Exe_Flags ecore_exe_flags_get(const Ecore_Exe *exe); + +/** + * Pauses the given process by sending it a @c SIGSTOP signal. + * @param exe Process handle to the given process. + */ EAPI void ecore_exe_pause(Ecore_Exe *exe); + +/** + * Continues the given paused process by sending it a @c SIGCONT signal. + * @param exe Process handle to the given process. + */ EAPI void ecore_exe_continue(Ecore_Exe *exe); + +/** + * Sends the given spawned process a interrupt (@c SIGINT) signal. + * @param exe Process handle to the given process. + */ EAPI void ecore_exe_interrupt(Ecore_Exe *exe); + +/** + * Sends the given spawned process a quit (@c SIGQUIT) signal. + * @param exe Process handle to the given process. + */ EAPI void ecore_exe_quit(Ecore_Exe *exe); + +/** + * Sends the given spawned process a terminate (@c SIGTERM) signal. + * @param exe Process handle to the given process. + */ EAPI void ecore_exe_terminate(Ecore_Exe *exe); + +/** + * Kills the given spawned process by sending it a @c SIGKILL signal. + * @param exe Process handle to the given process. + */ EAPI void ecore_exe_kill(Ecore_Exe *exe); + +/** + * Sends a @c SIGUSR signal to the given spawned process. + * @param exe Process handle to the given process. + * @param num The number user signal to send. Must be either 1 or 2, or + * the signal will be ignored. + */ EAPI void ecore_exe_signal(Ecore_Exe *exe, int num); + +/** + * Sends a @c SIGHUP signal to the given spawned process. + * @param exe Process handle to the given process. + */ EAPI void ecore_exe_hup(Ecore_Exe *exe); /** @@ -979,8 +1403,55 @@ EAPI void *ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler); * @li @ref ecore_time_functions_example_c * @{ */ + +/** + * Retrieves the current system time as a floating point value in seconds. + * + * This uses a monotonic clock and thus never goes back in time while + * machine is live (even if user changes time or timezone changes, + * however it may be reset whenever the machine is restarted). + * + * @see ecore_loop_time_get(). + * @see ecore_time_unix_get(). + * + * @return The number of seconds. Start time is not defined (it may be + * when the machine was booted, unix time, etc), all it is + * defined is that it never goes backwards (unless you got big critical + * messages when the application started). + */ EAPI double ecore_time_get(void); + +/** + * Retrieves the current UNIX time as a floating point value in seconds. + * + * @see ecore_time_get(). + * @see ecore_loop_time_get(). + * + * @return The number of seconds since 12.00AM 1st January 1970. + */ EAPI double ecore_time_unix_get(void); + +/** + * Retrieves the time at which the last loop stopped waiting for timeouts or + * events. + * + * This gets the time that the main loop ceased waiting for timouts and/or + * events to come in or for signals or any other interrupt source. This should + * be considered a reference point for all time based activity that should + * calculate its timepoint from the return of ecore_loop_time_get(). Use this + * UNLESS you absolutely must get the current actual timepoint - then use + * ecore_time_get(). Note that this time is meant to be used as relative to + * other times obtained on this run. If you need absolute time references, use + * ecore_time_unix_get() instead. + * + * This function can be called before any loop has ever been run, but either + * ecore_init() or ecore_time_get() must have been called once. + * + * @return The number of seconds. Start time is not defined (it may be + * when the machine was booted, unix time, etc), all it is + * defined is that it never goes backwards (unless you got big critical + * messages when the application started). + */ EAPI double ecore_loop_time_get(void); /** @@ -1106,6 +1577,7 @@ typedef struct _Ecore_Thread Ecore_Thread; /**< A handle for threaded jobs */ * A callback used by Ecore_Thread helper. */ typedef void (*Ecore_Thread_Cb)(void *data, Ecore_Thread *thread); + /** * @typedef Ecore_Thread_Notify_Cb Ecore_Thread_Notify_Cb * A callback used by the main loop to receive data sent by an @@ -1171,6 +1643,7 @@ typedef void (*Ecore_Thread_Notify_Cb)(void *data, Ecore_Thread *thread, void *m * @see ecore_thread_max_set() */ EAPI Ecore_Thread *ecore_thread_run(Ecore_Thread_Cb func_blocking, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data); + /** * Launch a thread to run a task that can talk back to the main thread * @@ -1214,6 +1687,7 @@ EAPI Ecore_Thread *ecore_thread_run(Ecore_Thread_Cb func_blocking, Ecore_Thread_ EAPI Ecore_Thread *ecore_thread_feedback_run(Ecore_Thread_Cb func_heavy, Ecore_Thread_Notify_Cb func_notify, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data, Eina_Bool try_no_queue); + /** * Cancel a running thread. * @@ -1250,6 +1724,7 @@ EAPI Ecore_Thread *ecore_thread_feedback_run(Ecore_Thread_Cb func_heavy, Ecore_T * @see ecore_thread_check() */ EAPI Eina_Bool ecore_thread_cancel(Ecore_Thread *thread); + /** * Checks if a thread is pending cancellation * @@ -1270,6 +1745,7 @@ EAPI Eina_Bool ecore_thread_cancel(Ecore_Thread *thread); * @see ecore_thread_cancel() */ EAPI Eina_Bool ecore_thread_check(Ecore_Thread *thread); + /** * Sends data from the worker thread to the main loop * @@ -1292,6 +1768,7 @@ EAPI Eina_Bool ecore_thread_check(Ecore_Thread *thread); * @see ecore_thread_feedback_run() */ EAPI Eina_Bool ecore_thread_feedback(Ecore_Thread *thread, const void *msg_data); + /** * Asks for the function in the thread to be called again at a later time * @@ -1316,6 +1793,7 @@ EAPI Eina_Bool ecore_thread_feedback(Ecore_Thread *thread, const void *msg_data) * effect. */ EAPI Eina_Bool ecore_thread_reschedule(Ecore_Thread *thread); + /** * Gets the number of active threads running jobs * @@ -1330,6 +1808,7 @@ EAPI Eina_Bool ecore_thread_reschedule(Ecore_Thread *thread); * falls back to using one from the pool. */ EAPI int ecore_thread_active_get(void); + /** * Gets the number of short jobs waiting for a thread to run * @@ -1339,6 +1818,7 @@ EAPI int ecore_thread_active_get(void); * pending, waiting for a thread to become available to run them. */ EAPI int ecore_thread_pending_get(void); + /** * Gets the number of feedback jobs waiting for a thread to run * @@ -1348,6 +1828,7 @@ EAPI int ecore_thread_pending_get(void); * that are pending, waiting for a thread to become available to run them. */ EAPI int ecore_thread_pending_feedback_get(void); + /** * Gets the total number of pending jobs * @@ -1357,6 +1838,7 @@ EAPI int ecore_thread_pending_feedback_get(void); *ecore_thread_pending_feedback_get(). */ EAPI int ecore_thread_pending_total_get(void); + /** * Gets the maximum number of threads that can run simultaneously * @@ -1376,6 +1858,7 @@ EAPI int ecore_thread_pending_total_get(void); * @see ecore_thread_max_reset() */ EAPI int ecore_thread_max_get(void); + /** * Sets the maximum number of threads allowed to run simultaneously * @@ -1389,6 +1872,7 @@ EAPI int ecore_thread_max_get(void); * @see ecore_thread_max_reset() */ EAPI void ecore_thread_max_set(int num); + /** * Resets the maximum number of concurrently running threads to the default * @@ -1399,6 +1883,7 @@ EAPI void ecore_thread_max_set(int num); * @see ecore_thread_max_set() */ EAPI void ecore_thread_max_reset(void); + /** * Gets the number of threads available for running tasks * @@ -1411,6 +1896,7 @@ EAPI void ecore_thread_max_reset(void); * running. */ EAPI int ecore_thread_available_get(void); + /** * Adds some data to a hash local to the thread * @@ -1497,6 +1983,7 @@ EAPI int ecore_thread_available_get(void); */ EAPI Eina_Bool ecore_thread_local_data_add(Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct); + /** * Sets some data in the hash local to the given thread * @@ -1525,6 +2012,7 @@ EAPI Eina_Bool ecore_thread_local_data_add(Ecore_Thread *thread, const char *key * @see ecore_thread_local_data_find() */ EAPI void *ecore_thread_local_data_set(Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb); + /** * Gets data stored in the hash local to the given thread * @@ -1543,6 +2031,7 @@ EAPI void *ecore_thread_local_data_set(Ecore_Thread *thread, const char *key, vo * @see ecore_thread_local_data_wait() */ EAPI void *ecore_thread_local_data_find(Ecore_Thread *thread, const char *key); + /** * Deletes from the thread's hash the data corresponding to the given key * @@ -1608,6 +2097,7 @@ EAPI Eina_Bool ecore_thread_local_data_del(Ecore_Thread *thread, const char *key * @see ecore_thread_global_data_find() */ EAPI Eina_Bool ecore_thread_global_data_add(const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct); + /** * Sets some data in the hash shared by all threads * @@ -1630,6 +2120,7 @@ EAPI Eina_Bool ecore_thread_global_data_add(const char *key, void *value, Eina_F * @see ecore_thread_global_data_find() */ EAPI void *ecore_thread_global_data_set(const char *key, void *value, Eina_Free_Cb cb); + /** * Gets data stored in the hash shared by all threads * @@ -1647,6 +2138,7 @@ EAPI void *ecore_thread_global_data_set(const char *key, void *value, Eina_Free_ * @see ecore_thread_global_data_wait() */ EAPI void *ecore_thread_global_data_find(const char *key); + /** * Deletes from the shared hash the data corresponding to the given key * @@ -1670,6 +2162,7 @@ EAPI void *ecore_thread_global_data_find(const char *key); * @see ecore_thread_global_data_add() */ EAPI Eina_Bool ecore_thread_global_data_del(const char *key); + /** * Gets data stored in the shared hash, or wait for it if it doesn't exist * @@ -1732,20 +2225,117 @@ typedef struct _Ecore_Pipe Ecore_Pipe; /**< A handle for pipes */ */ typedef void (*Ecore_Pipe_Cb)(void *data, void *buffer, unsigned int nbyte); +/** + * Create two file descriptors (sockets on Windows). Add + * a callback that will be called when the file descriptor that + * is listened receives data. An event is also put in the event + * queue when data is received. + * + * @param handler The handler called when data is received. + * @param data Data to pass to @p handler when it is called. + * @return A newly created Ecore_Pipe object if successful. + * @c NULL otherwise. + */ EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); + +/** + * Create a pipe with more parameters + * + * @param hanlder Same as ecore_pipe_add() + * @param data Same as ecore_pipe_add() + * @param fd_read An fd to use for reading or -1 otherwise + * @param fd_write An fd to use for writing or -1 otherwise + * @param read_survive_fork Should read fd survive a fork + * @param write_survive_fork Should write fd survive a fork + * + * This is the same as ecore_pipe_add() but with some added parameters. + * + * @see ecore_pipe_add() + */ EAPI Ecore_Pipe *ecore_pipe_full_add(Ecore_Pipe_Cb handler, - const void *data, - int fd_read, int fd_write, - Eina_Bool read_survive_fork, - Eina_Bool write_survive_fork); + const void *data, + int fd_read, int fd_write, + Eina_Bool read_survive_fork, + Eina_Bool write_survive_fork); + +/** + * Free an Ecore_Pipe object created with ecore_pipe_add(). + * + * @param p The Ecore_Pipe object to be freed. + * @return The pointer to the private data + */ EAPI void *ecore_pipe_del(Ecore_Pipe *p); + +/** + * Write on the file descriptor the data passed as parameter. + * + * @param p The Ecore_Pipe object. + * @param buffer The data to write into the pipe. + * @param nbytes The size of the @p buffer in bytes + * @return @c EINA_TRUE on a successful write, @c EINA_FALSE on error. + */ EAPI Eina_Bool ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes); + +/** + * Close the write end of an Ecore_Pipe object created with ecore_pipe_add(). + * + * @param p The Ecore_Pipe object. + */ EAPI void ecore_pipe_write_close(Ecore_Pipe *p); + +/** + * Close the read end of an Ecore_Pipe object created with ecore_pipe_add(). + * + * @param p The Ecore_Pipe object. + */ EAPI void ecore_pipe_read_close(Ecore_Pipe *p); + +/** + * Get the pipe read file descriptor + * + * @param p The Ecore_Pipe object query. + * @return The file descriptor or -1 if none + */ EAPI int ecore_pipe_read_fd(Ecore_Pipe *p); + +/** + * Get the pipe write file descriptor + * + * @param p The Ecore_Pipe object query. + * @return The file descriptor or -1 if none + */ EAPI int ecore_pipe_write_fd(Ecore_Pipe *p); + +/** + * Start monitoring again the pipe for reading. See ecore_pipe_freeze() for + * stopping the monitoring activity. This will not work if + * ecore_pipe_read_close() was previously called on the same pipe. + * + * @param p The Ecore_Pipe object. + * @since 1.1 + */ EAPI void ecore_pipe_thaw(Ecore_Pipe *p); + +/** + * Stop monitoring if necessary the pipe for reading. See ecore_pipe_thaw() + * for monitoring it again. + * + * @param p The Ecore_Pipe object. + * @since 1.1 + */ EAPI void ecore_pipe_freeze(Ecore_Pipe *p); + +/** + * @brief Wait from another thread on the read side of a pipe. + * + * @param p The pipe to watch on. + * @param message_count The minimal number of message to wait before exiting. + * @param wait The amount of time in second to wait before exiting. + * @return the number of message catched during that wait call. + * @since 1.1 + * + * Negative value for @p wait means infite wait. + */ EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, double wait); /** @@ -1759,8 +2349,37 @@ EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, double wait); * @{ */ +/** + * Set up the programs command-line arguments. + * @param argc The same as passed as argc to the programs main() function + * @param argv The same as passed as argv to the programs main() function + * + * A call to this function will store the programs command-line arguments + * for later use by ecore_app_restart() or ecore_app_args_get(). + */ EAPI void ecore_app_args_set(int argc, const char **argv); + +/** + * Return the programs stored command-line arguments. + * @param argc A pointer to the return value to hold argc + * @param argv A pointer to the return value to hold argv + * + * When called, this funciton returns the arguments for the program stored by + * ecore_app_args_set(). The integer pointed to by @p argc will be filled, if + * the pointer is not NULL, and the string array pointer @p argv will be filled + * also if the pointer is not NULL. The values they are filled with will be the + * same set by ecore_app_args_set(). + */ EAPI void ecore_app_args_get(int *argc, char ***argv); + +/** + * Restart the program executable with the command-line arguments stored. + * + * This function will restart & re-execute this program in place of itself + * using the command-line arguments stored by ecore_app_args_set(). This is + * an easy way for a program to restart itself for cleanup purposes, + * configuration reasons or in the event of a crash. + */ EAPI void ecore_app_restart(void); /** @@ -1791,7 +2410,64 @@ EAPI void ecore_app_no_system_modules(void); * @{ */ +/** + * Increase throttle amount + * + * This will increase or decrease (if @p amount is positive or negative) the + * amount of "voluntary throttling" ecore will do to its main loop while + * running. This is intended to be used to limit animations and wakeups when + * in a strict power management state. The higher the current throttle value + * (which can be retrieved by ecore_throttle_get() ), the more throttling + * takes place. If the current throttle value is 0, then no throttling takes + * place at all. + * + * The value represents how long the ecore main loop will sleep (in seconds) + * before it goes into a fully idle state waiting for events, input or + * timing events to wake it up. For example, if the current throttle level + * is 0.5, then after every time the main loop cycles and goes into idle + * after processing all events, the main loop will explicitly sleep for 0.5 + * seconds before sitting and waiting for incoming events or timeouts, thus + * preventing animation, async IO and network handling etc. for that period + * of time. Of course these events, data and timeouts will be buffered, + * thus not losing anything, simply delaying when they get handled by the + * throttle value. + * + * Example: + * @code + * void enter_powersave(void) { + * ecore_throttle_adjust(0.2); + * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); + * } + * + * void enter_deep_powersave(void) { + * ecore_throttle_adjust(0.5); + * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); + * } + * + * void exit_powersave(void) { + * ecore_throttle_adjust(-0.2); + * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); + * } + * + * void exit_deep_powersave(void) { + * ecore_throttle_adjust(-0.5); + * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); + * } + * @endcode + * + * @param amount Amount (in seconds) to adjust by + */ EAPI void ecore_throttle_adjust(double amount); + +/** + * Get current throttle level + * + * This gets the current throttling level, which can be adjusted by + * ecore_throttle_adjust(). The value is in seconds. Please see + * ecore_throttle_adjust() for more information. + * + * @return The current throttle level + */ EAPI double ecore_throttle_get(void); /** @@ -1857,6 +2533,7 @@ typedef Eo Ecore_Poller; /**< A handle for pollers */ * @p type to the time period defined by @p poll_time. */ EAPI void ecore_poller_poll_interval_set(Ecore_Poller_Type type, double poll_time); + /** * @brief Gets the time(in seconds) between ticks for the given poller type. * @param type The poller type to query. @@ -1963,6 +2640,7 @@ typedef Eo Ecore_Animator; /**< A handle for animators */ * @note The default @p frametime value is 1/30th of a second. */ EAPI void ecore_animator_frametime_set(double frametime); + /** * @brief Get the animator call interval in seconds. * @@ -1973,6 +2651,7 @@ EAPI void ecore_animator_frametime_set(double frametime); * @see ecore_animator_frametime_set() */ EAPI double ecore_animator_frametime_get(void); + /** * @brief Maps an input position from 0.0 to 1.0 along a timeline to a * position in a different curve. @@ -2122,6 +2801,7 @@ EAPI double ecore_animator_pos_map_n(double pos, Ecore_Pos_Map map, int v_size, * over 1 frame. */ EAPI void ecore_animator_source_set(Ecore_Animator_Source source); + /** * @brief Get the animator source currently set. * @@ -2132,6 +2812,7 @@ EAPI void ecore_animator_source_set(Ecore_Animator_Source source); * @see ecore_animator_source_set() */ EAPI Ecore_Animator_Source ecore_animator_source_get(void); + /** * @brief Set the function that begins a custom animator tick source * @@ -2152,6 +2833,7 @@ EAPI Ecore_Animator_Source ecore_animator_source_get(void); * @see ecore_animator_custom_tick() */ EAPI void ecore_animator_custom_source_tick_begin_callback_set(Ecore_Cb func, const void *data); + /** * @brief Set the function that ends a custom animator tick source * @@ -2169,6 +2851,7 @@ EAPI void ecore_animator_custom_source_tick_begin_callback_set(Ecore_Cb func, co * @see ecore_animator_custom_tick() */ EAPI void ecore_animator_custom_source_tick_end_callback_set(Ecore_Cb func, const void *data); + /** * @brief Trigger a custom animator tick * @@ -2217,8 +2900,58 @@ EAPI void ecore_animator_custom_tick(void); */ typedef Eo Ecore_Timer; /**< A handle for timers */ +/** + * Retrieves the current precision used by timer infrastructure. + * @return Current precision. + * @see ecore_timer_precision_set() + */ EAPI double ecore_timer_precision_get(void); + +/** + * @brief Sets the precision to be used by timer infrastructure. + * + * @param value allowed introduced timeout delay, in seconds. + * + * This sets the precision for @b all timers. The precision determines how much + * of an difference from the requested interval is acceptable. One common reason + * to use this function is to @b increase the allowed timeout and thus @b + * decrease precision of the timers, this is because less precise the timers + * result in the system waking up less often and thus consuming less resources. + * + * Be aware that kernel may delay delivery even further, these delays + * are always possible due other tasks having higher priorities or + * other scheduler policies. + * + * Example: + * We have 2 timers, one that expires in a 2.0s and another that + * expires in 2.1s, if precision is 0.1s, then the Ecore will request + * for the next expire to happen in 2.1s and not 2.0s and another one + * of 0.1 as it would before. + * + * @note Ecore is smart enough to see if there are timers in the + * precision range, if it does not, in our example if no second timer + * in (T + precision) existed, then it would use the minimum timeout. + */ EAPI void ecore_timer_precision_set(double precision); + +/** + * Creates a timer to call the given function in the given period of time. + * @param in The interval in seconds. + * @param func The given function. If @p func returns 1, the timer is + * rescheduled for the next interval @p in. + * @param data Data to pass to @p func when it is called. + * @return A timer object on success. @c NULL on failure. + * + * This function adds a timer and returns its handle on success and NULL on + * failure. The function @p func will be called every @p in seconds. The + * function will be passed the @p data pointer as its parameter. + * + * When the timer @p func is called, it must return a value of either 1 + * (or ECORE_CALLBACK_RENEW) or 0 (or ECORE_CALLBACK_CANCEL). + * If it returns 1, it will be called again at the next tick, or if it returns + * 0 it will be deleted automatically making any references/handles for it + * invalid. + */ EAPI char *ecore_timer_dump(void); /** diff --git a/src/lib/ecore/Ecore_Getopt.h b/src/lib/ecore/Ecore_Getopt.h index e4f5eb52b7..33e4dbf1f3 100644 --- a/src/lib/ecore/Ecore_Getopt.h +++ b/src/lib/ecore/Ecore_Getopt.h @@ -409,18 +409,194 @@ struct _Ecore_Getopt #define ECORE_GETOPT_VALUE_LIST(val) {.listp = &(val)} #define ECORE_GETOPT_VALUE_NONE {.ptrp = NULL} +/** + * Show nicely formatted help message for the given parser. + * + * @param fp The file the message will be printed on. + * @param parser The parser to be used. + * + * @see ecore_getopt_help_category() + */ EAPI void ecore_getopt_help(FILE *fp, const Ecore_Getopt *info); + +/** + * Show help for a single category (along with program usage and description). + * + * @param fp The file the message will be printed on. + * @param parser The parser to be used. + * @param category The category to print. + * + * @return @c EINA_TRUE when the category exists, @c EINA_FALSE otherwise. + * + * @see ecore_getopt_help() + */ EAPI Eina_Bool ecore_getopt_help_category(FILE *fp, const Ecore_Getopt *info, const char *category); + +/** + * Check parser for duplicate entries, print them out. + * + * @return @c EINA_TRUE if there are duplicates, @c EINA_FALSE otherwise. + * @param parser The parser to be checked. + */ EAPI Eina_Bool ecore_getopt_parser_has_duplicates(const Ecore_Getopt *parser); + +/** + * Parse command line parameters. + * + * Walks the command line parameters and parse them based on @a parser + * description, doing actions based on @c parser->descs->action, like + * showing help text, license, copyright, storing values in values and + * so on. + * + * It is expected that values is of the same size than @c parser->descs, + * options that do not need a value it will be left untouched. + * + * All values are expected to be initialized before use. Options with + * action @c ECORE_GETOPT_ACTION_STORE and non required arguments + * (others than @c ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES), are expected + * to provide a value in @c def to be used. + * + * The following actions will store @c 1 on value as a boolean + * (@c value->boolp) if it's not @c NULL to indicate these actions were + * executed: + * - @c ECORE_GETOPT_ACTION_HELP + * - @c ECORE_GETOPT_ACTION_VERSION + * - @c ECORE_GETOPT_ACTION_COPYRIGHT + * - @c ECORE_GETOPT_ACTION_LICENSE + * + * Just @c ECORE_GETOPT_ACTION_APPEND will allocate memory and thus + * need to be freed. For consistency between all of appended subtypes, + * @c eina_list->data will contain an allocated memory with the value, + * that is, for @c ECORE_GETOPT_TYPE_STR it will contain a copy of the + * argument, @c ECORE_GETOPT_TYPE_INT a pointer to an allocated + * integer and so on. + * + * If parser is in strict mode (see @c Ecore_Getopt->strict), then any + * error will abort parsing and @c -1 is returned. Otherwise it will try + * to continue as far as possible. + * + * This function may reorder @a argv elements. + * + * Translation of help strings (description), metavar, usage, license + * and copyright may be translated, standard/global gettext() call + * will be applied on them if ecore was compiled with such support. + * + * This function will @b not parse positional arguments! If these are + * declared (metavar is defined with both shortname and longname being + * empty), then you must call ecore_getopt_parse_positional() with the + * last argument (@c start) being the result of this function. This is + * done so you can have "quit options", those that once called you + * want to exit without doing further parsing, as is the case with + * help, license, copyright, version and eventually others you may + * define. + * + * @param parser description of how to work. + * @param values where to store values, it is assumed that this is a vector + * of the same size as @c parser->descs. Values should be previously + * initialized. + * @param argc how many elements in @a argv. If not provided it will be + * retrieved with ecore_app_args_get(). + * @param argv command line parameters. + * + * @return index of first non-option parameter or -1 on error. + * + * @see ecore_getopt_parse_positional() + */ EAPI int ecore_getopt_parse(const Ecore_Getopt *parser, Ecore_Getopt_Value *values, int argc, char **argv); +/** + * Parse command line positional parameters. + * + * Walks the command line positional parameters (those that do not + * start with "-" or "--") and parse them based on @a parser + * description, doing actions based on @c parser->descs->action, like + * storing values of some type. + * + * It is expected that @a values is of the same size than @c + * parser->descs, same as with ecore_getopt_parse(). + * + * All values are expected to be initialized before use. + * + * Unlike the ecore_getopt_parse(), only the following options are + * supported: + * - @c ECORE_GETOPT_ACTION_STORE + * - @c ECORE_GETOPT_ACTION_CHOICE + * - @c ECORE_GETOPT_ACTION_APPEND + * - @c ECORE_GETOPT_ACTION_CALLBACK + * + * There is a special case for @c ECORE_GETOPT_ACTION_APPEND as it + * will consume all remaining elements. It is also special in the + * sense that it will allocate memory and thus need to be freed. For + * consistency between all of appended subtypes, @c eina_list->data + * will contain an allocated memory with the value, that is, for @c + * ECORE_GETOPT_TYPE_STR it will contain a copy of the argument, @c + * ECORE_GETOPT_TYPE_INT a pointer to an allocated integer and so on. + * + * If parser is in strict mode (see @c Ecore_Getopt->strict), then any + * error will abort parsing and @c -1 is returned. Otherwise it will try + * to continue as far as possible. + * + * Translation of help strings (description) and metavar may be done, + * standard/global gettext() call will be applied on them if ecore was + * compiled with such support. + * + * @param parser description of how to work. + * @param values where to store values, it is assumed that this is a vector + * of the same size as @c parser->descs. Values should be previously + * initialized. + * @param argc how many elements in @a argv. If not provided it will be + * retrieved with ecore_app_args_get(). + * @param argv command line parameters. + * @param start the initial position argument to look at, usually the + * return of ecore_getopt_parse(). If less than 1, will try to + * find it automatically. + * + * @return index of first non-option parameter or -1 on error. If the + * last positional argument is of action @c + * ECORE_GETOPT_ACTION_APPEND then it will be the same as @a argc. + */ EAPI int ecore_getopt_parse_positional(const Ecore_Getopt *parser, Ecore_Getopt_Value *values, int argc, char **argv, int start); +/** + * Utility to free list and nodes allocated by @a ECORE_GETOPT_ACTION_APPEND. + * + * @param list pointer to list to be freed. + * @return always @c NULL, so you can easily make your list head @c NULL. + */ EAPI Eina_List *ecore_getopt_list_free(Eina_List *list); -/* helper functions to be used with ECORE_GETOPT_CALLBACK_*() */ +/** + * Helper ecore_getopt callback to parse geometry (x:y:w:h). + * + * @param parser This parameter isn't in use. + * @param desc This parameter isn't in use. + * @param str Geometry value + * @param data This parameter isn't in use. + * @param storage must be a pointer to @c Eina_Rectangle and will be used to + * store the four values passed in the given string. + * @return @c EINA_TRUE on success, @c EINA_FALSE on incorrect geometry value. + * + * This is a helper functions to be used with ECORE_GETOPT_CALLBACK_*(). + * + * @c callback_data value is ignored, you can safely use @c NULL. + */ EAPI Eina_Bool ecore_getopt_callback_geometry_parse(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, Ecore_Getopt_Value *storage); + +/** + * Helper ecore_getopt callback to parse geometry size (WxH). + * + * @param parser This parameter isn't in use. + * @param desc This parameter isn't in use. + * @param str size value + * @param data This parameter isn't in use. + * @param storage must be a pointer to @c Eina_Rectangle and will be used to + * store the two values passed in the given string and @c 0 in the x and y + * fields. + * @return @c EINA_TRUE on success, @c EINA_FALSE on incorrect size value. + * + * @c callback_data value is ignored, you can safely use @c NULL. + */ EAPI Eina_Bool ecore_getopt_callback_size_parse(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, Ecore_Getopt_Value *storage); #ifdef __cplusplus diff --git a/src/lib/ecore/Ecore_Legacy.h b/src/lib/ecore/Ecore_Legacy.h index 66a50e310f..5ef10d5f63 100644 --- a/src/lib/ecore/Ecore_Legacy.h +++ b/src/lib/ecore/Ecore_Legacy.h @@ -34,6 +34,7 @@ extern "C" { * invalid. */ EAPI Ecore_Poller *ecore_poller_add(Ecore_Poller_Type type, int interval, Ecore_Task_Cb func, const void *data); + /** * @brief Delete the specified poller from the timer list. * @param poller The poller to delete. @@ -81,6 +82,7 @@ EAPI void *ecore_poller_del(Ecore_Poller *poller); * @see ecore_animator_frametime_set() */ EAPI Ecore_Animator *ecore_animator_add(Ecore_Task_Cb func, const void *data); + /** * @brief Add an animator that runs for a limited time * @@ -109,6 +111,7 @@ EAPI Ecore_Animator *ecore_animator_add(Ecore_Task_Cb func, const void *data); * @since 1.1.0 */ EAPI Ecore_Animator *ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data); + /** * @brief Delete the specified animator from the animator list. * @@ -123,6 +126,7 @@ EAPI Ecore_Animator *ecore_animator_timeline_add(double runtime, Ecore_Timeline_ * deletion. */ EAPI void *ecore_animator_del(Ecore_Animator *animator); + /** * @brief Suspend the specified animator. * @@ -138,6 +142,7 @@ EAPI void *ecore_animator_del(Ecore_Animator *animator); * have it's execution halted if @p runtime elapsed. */ EAPI void ecore_animator_freeze(Ecore_Animator *animator); + /** * @brief Restore execution of the specified animator. * @@ -159,11 +164,38 @@ EAPI void ecore_animator_thaw(Ecore_Animator *animator); * * @{ */ + EAPI Ecore_Timer *ecore_timer_add(double in, Ecore_Task_Cb func, const void *data); + +/** + * Creates a timer to call the given function in the given period of time. + * @param in The interval in seconds from current loop time. + * @param func The given function. If @p func returns 1, the timer is + * rescheduled for the next interval @p in. + * @param data Data to pass to @p func when it is called. + * @return A timer object on success. @c NULL on failure. + * + * This is the same as ecore_timer_add(), but "now" is the time from + * ecore_loop_time_get() not ecore_time_get() as ecore_timer_add() uses. See + * ecore_timer_add() for more details. + */ EAPI Ecore_Timer *ecore_timer_loop_add(double in, Ecore_Task_Cb func, const void *data); + +/** + * Delete the specified timer from the timer list. + * @param timer The timer to delete. + * @return The data pointer set for the timer when @ref ecore_timer_add was + * called. @c NULL is returned if the function is unsuccessful. + * + * Note: @p timer must be a valid handle. If the timer function has already + * returned 0, the handle is no longer valid (and does not need to be delete). + */ EAPI void *ecore_timer_del(Ecore_Timer *timer); + EAPI void ecore_timer_freeze(Ecore_Timer *timer); + EAPI Eina_Bool ecore_timer_freeze_get(Ecore_Timer *timer); + EAPI void ecore_timer_thaw(Ecore_Timer *timer); #include "ecore_timer.eo.legacy.h" @@ -201,11 +233,55 @@ EAPI Ecore_Idler *ecore_idler_add(Ecore_Task_Cb func, const void *data); */ EAPI void *ecore_idler_del(Ecore_Idler *idler); +/** + * Add an idle enterer handler. + * @param func The function to call when entering an idle state. + * @param data The data to be passed to the @p func call + * @return A handle to the idle enterer callback if successful. Otherwise, + * NULL is returned. + * @note The function func will be called every time the main loop is entering + * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 + * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer. + */ EAPI Ecore_Idle_Enterer *ecore_idle_enterer_add(Ecore_Task_Cb func, const void *data); + +/** + * Add an idle enterer handler at the start of the list so it gets called earlier than others. + * @param func The function to call when entering an idle state. + * @param data The data to be passed to the @p func call + * @return A handle to the idle enterer callback if successful. Otherwise, + * NULL is returned. + * @note The function func will be called every time the main loop is entering + * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 + * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer. + */ EAPI Ecore_Idle_Enterer *ecore_idle_enterer_before_add(Ecore_Task_Cb func, const void *data); + +/** + * Delete an idle enterer callback. + * @param idle_enterer The idle enterer to delete + * @return The data pointer passed to the idler enterer callback on success. + * NULL otherwise. + */ EAPI void *ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer); +/** + * Add an idle exiter handler. + * @param func The function to call when exiting an idle state. + * @param data The data to be passed to the @p func call + * @return A handle to the idle exiter callback on success. NULL otherwise. + * @note The function func will be called every time the main loop is exiting + * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 + * (or ECORE_CALLBACK_CANCEL) deletes the idle exiter. + */ EAPI Ecore_Idle_Exiter *ecore_idle_exiter_add(Ecore_Task_Cb func, const void *data); + +/** + * Delete an idle exiter handler from the list to be run on exiting idle state. + * @param idle_exiter The idle exiter to delete + * @return The data pointer that was being being passed to the handler if + * successful. NULL otherwise. + */ EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); #include "ecore_idler.eo.legacy.h" @@ -219,7 +295,22 @@ EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); * * @{ */ +/** + * Add a job to the event queue. + * @param func The function to call when the job gets handled. + * @param data Data pointer to be passed to the job function when the job is + * handled. + * @return The handle of the job. @c NULL is returned if the job could not be + * added to the queue. + * @note Once the job has been executed, the job handle is invalid. + */ EAPI Ecore_Job *ecore_job_add(Ecore_Cb func, const void *data); + +/** + * Delete a queued job that has not yet been executed. + * @param obj Handle of the job to delete. + * @return The data pointer that was to be passed to the job. + */ EAPI void *ecore_job_del(Ecore_Job *obj); #include "ecore_job.eo.legacy.h" diff --git a/src/lib/ecore/ecore.c b/src/lib/ecore/ecore.c index 10a18cdc17..d0ee1e95f5 100644 --- a/src/lib/ecore/ecore.c +++ b/src/lib/ecore/ecore.c @@ -115,7 +115,7 @@ static Ecore_Timer *_systemd_watchdog = NULL; Eina_Lock _ecore_main_loop_lock; int _ecore_main_lock_count; -/** OpenBSD does not define CODESET +/* OpenBSD does not define CODESET * FIXME ?? */ @@ -197,34 +197,6 @@ ecore_app_no_system_modules(void) _no_system_modules = EINA_TRUE; } -/** - * @addtogroup Ecore_Init_Group - * - * @{ - */ - -/** - * Set up connections, signal handlers, sockets etc. - * @return 1 or greater on success, 0 otherwise - * - * This function sets up all singal handlers and the basic event loop. If it - * succeeds, 1 will be returned, otherwise 0 will be returned. - * - * @code - * #include - * - * int main(int argc, char **argv) - * { - * if (!ecore_init()) - * { - * printf("ERROR: Cannot init Ecore!\n"); - * return -1; - * } - * ecore_main_loop_begin(); - * ecore_shutdown(); - * } - * @endcode - */ EAPI int ecore_init(void) { @@ -312,14 +284,14 @@ ecore_init(void) { double sec; - sec = ((double) atoi(getenv("WATCHDOG_USEC"))) / 1000 / 1000; + sec = ((double) atoi(getenv("WATCHDOG_USEC"))) / 1000 / 1000; - _systemd_watchdog = ecore_timer_add(sec / 2, _systemd_watchdog_cb, NULL); - unsetenv("WATCHDOG_USEC"); + _systemd_watchdog = ecore_timer_add(sec / 2, _systemd_watchdog_cb, NULL); + unsetenv("WATCHDOG_USEC"); - INF("Setup systemd watchdog to : %f", sec); + INF("Setup systemd watchdog to : %f", sec); - _systemd_watchdog_cb(NULL); + _systemd_watchdog_cb(NULL); } #endif @@ -329,8 +301,8 @@ ecore_init(void) _ecore_init_count_threshold = _ecore_init_count; eina_log_timing(_ecore_log_dom, - EINA_LOG_STATE_STOP, - EINA_LOG_STATE_INIT); + EINA_LOG_STATE_STOP, + EINA_LOG_STATE_INIT); return _ecore_init_count; @@ -347,17 +319,6 @@ shutdown_evil: return --_ecore_init_count; } -/** - * Shut down connections, signal handlers sockets etc. - * - * @return 0 if ecore shuts down, greater than 0 otherwise. - * This function shuts down all things set up in ecore_init() and cleans up all - * event queues, handlers, filters, timers, idlers, idle enterers/exiters - * etc. set up after ecore_init() was called. - * - * Do not call this function from any callback that may be called from the main - * loop, as the main loop will then fall over and not function properly. - */ EAPI int ecore_shutdown(void) { @@ -378,14 +339,14 @@ ecore_shutdown(void) ecore_system_modules_unload(); eina_log_timing(_ecore_log_dom, - EINA_LOG_STATE_START, - EINA_LOG_STATE_SHUTDOWN); + EINA_LOG_STATE_START, + EINA_LOG_STATE_SHUTDOWN); #ifdef HAVE_SYSTEMD if (_systemd_watchdog) { - ecore_timer_del(_systemd_watchdog); - _systemd_watchdog = NULL; + ecore_timer_del(_systemd_watchdog); + _systemd_watchdog = NULL; } #endif @@ -557,10 +518,6 @@ ecore_fork_reset(void) #endif } -/** - * @} - */ - EAPI void ecore_main_loop_thread_safe_call_async(Ecore_Cb callback, void *data) @@ -1070,4 +1027,4 @@ ecore_memory_state_set(Ecore_Memory_State state) ecore_event_add(ECORE_EVENT_MEMORY_STATE, NULL, NULL, NULL); } -#include "ecore_parent.eo.c" \ No newline at end of file +#include "ecore_parent.eo.c" diff --git a/src/lib/ecore/ecore_app.c b/src/lib/ecore/ecore_app.c index 716cd4a1aa..a2e9cd1fb3 100644 --- a/src/lib/ecore/ecore_app.c +++ b/src/lib/ecore/ecore_app.c @@ -19,20 +19,6 @@ static int app_argc = 0; static char **app_argv = NULL; -/** - * @addtogroup Ecore_Application_Group - * - * @{ - */ - -/** - * Set up the programs command-line arguments. - * @param argc The same as passed as argc to the programs main() function - * @param argv The same as passed as argv to the programs main() function - * - * A call to this function will store the programs command-line arguments - * for later use by ecore_app_restart() or ecore_app_args_get(). - */ EAPI void ecore_app_args_set(int argc, const char **argv) @@ -45,17 +31,6 @@ ecore_app_args_set(int argc, app_argv = (char **)argv; } -/** - * Return the programs stored command-line arguments. - * @param argc A pointer to the return value to hold argc - * @param argv A pointer to the return value to hold argv - * - * When called, this funciton returns the arguments for the program stored by - * ecore_app_args_set(). The integer pointed to by @p argc will be filled, if - * the pointer is not NULL, and the string array pointer @p argv will be filled - * also if the pointer is not NULL. The values they are filled with will be the - * same set by ecore_app_args_set(). - */ EAPI void ecore_app_args_get(int *argc, char ***argv) @@ -66,14 +41,6 @@ ecore_app_args_get(int *argc, if (argv) *argv = app_argv; } -/** - * Restart the program executable with the command-line arguments stored. - * - * This function will restart & re-execute this program in place of itself - * using the command-line arguments stored by ecore_app_args_set(). This is - * an easy way for a program to restart itself for cleanup purposes, - * configuration reasons or in the event of a crash. - */ EAPI void ecore_app_restart(void) { @@ -89,7 +56,3 @@ ecore_app_restart(void) execvp(app_argv[0], args); #endif } - -/** - * @} - */ diff --git a/src/lib/ecore/ecore_exe.c b/src/lib/ecore/ecore_exe.c index b37da22994..5e90346dc2 100644 --- a/src/lib/ecore/ecore_exe.c +++ b/src/lib/ecore/ecore_exe.c @@ -314,30 +314,8 @@ _ecore_exe_check_errno(int result, return result; } -/** - * @addtogroup Ecore_Exe_Group - * - * @{ - */ - static int run_pri = ECORE_EXE_PRIORITY_INHERIT; -/** - * Sets the priority at which to launch processes - * - * This sets the priority of processes run by ecore_exe_run() and - * ecore_exe_pipe_run(). - * @li On Windows, the child process is created by default with the - * @ref ECORE_EXE_WIN32_PRIORITY_NORMAL priority, unless the calling - * process is in @ref ECORE_EXE_WIN32_PRIORITY_IDLE or - * @ref ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL priority. In that case, the - * child process inherits this priority. - * @li On other platforms, if set to @ref ECORE_EXE_PRIORITY_INHERIT child - * processes inherits the priority of their parent. This is the default. - * - * @param pri value a Ecore_Exe_Win32_Priority value on Windows, -20 - * to 19 or @ref ECORE_EXE_PRIORITY_INHERIT on other OS. - */ EAPI void ecore_exe_run_priority_set(int pri) { @@ -345,15 +323,6 @@ ecore_exe_run_priority_set(int pri) run_pri = pri; } -/** - * Gets the priority at which to launch processes - * - * This gets ths priority of launched processes. See - * ecore_exe_run_priority_set() for details. This just returns the value set - * by this call. - * - * @return the value set by ecore_exe_run_priority_set() - */ EAPI int ecore_exe_run_priority_get(void) { @@ -361,19 +330,6 @@ ecore_exe_run_priority_get(void) return run_pri; } -/** - * Spawns a child process. - * - * This is now just a thin wrapper around ecore_exe_pipe_run() - * @note When you use this function you will have no permissions - * to write or read on the pipe that connects you with the spwaned process. - * If you need to do that use ecore_exe_pipe_run() with the - * appropriated flags. - * - * @param exe_cmd The command to run with @c /bin/sh. - * @param data Data to attach to the returned process handle. - * @return A process handle to the spawned process. - */ EAPI Ecore_Exe * ecore_exe_run(const char *exe_cmd, const void *data) @@ -382,31 +338,6 @@ ecore_exe_run(const char *exe_cmd, return ecore_exe_pipe_run(exe_cmd, 0, data); } -/** - * Spawns a child process with its stdin/out available for communication. - * - * This function forks and runs the given command using @c /bin/sh. - * - * Note that the process handle is only valid until a child process - * terminated event is received. After all handlers for the child process - * terminated event have been called, the handle will be freed by Ecore. - * - * This function does the same thing as ecore_exe_run(), but also makes the - * standard in and/or out as well as stderr from the child process available - * for reading or writing. To write use ecore_exe_send(). To read listen to - * ECORE_EXE_EVENT_DATA or ECORE_EXE_EVENT_ERROR events (set up handlers). - * Ecore may buffer read and error data until a newline character if asked - * for with the @p flags. All data will be included in the events (newlines - * will be replaced with NULLS if line buffered). ECORE_EXE_EVENT_DATA events - * will only happen if the process is run with ECORE_EXE_PIPE_READ enabled - * in the flags. The same with the error version. Writing will only be - * allowed with ECORE_EXE_PIPE_WRITE enabled in the flags. - * - * @param exe_cmd The command to run with @c /bin/sh. - * @param flags The flag parameters for how to deal with inter-process I/O - * @param data Data to attach to the returned process handle. - * @return A process handle to the spawned process. - */ EAPI Ecore_Exe * ecore_exe_pipe_run(const char *exe_cmd, Ecore_Exe_Flags flags, @@ -709,19 +640,6 @@ ecore_exe_pipe_run(const char *exe_cmd, return exe; } -/** - * Defines a function to be called before really freeing the handle data. - * - * This might be useful for language bindings such as Python and Perl - * that need to deallocate wrappers associated with this handle. - * - * This handle should never be modified by this call. It should be - * considered informative only. All getters are valid when the given - * function is called back. - * - * @param exe The child process to attach the pre_free function. - * @param func The function to call before @a exe is freed. - */ EAPI void ecore_exe_callback_pre_free_set(Ecore_Exe *exe, Ecore_Exe_Cb func) @@ -736,18 +654,6 @@ ecore_exe_callback_pre_free_set(Ecore_Exe *exe, exe->pre_free_cb = func; } -/** - * Sends data to the given child process which it receives on stdin. - * - * This function writes to a child processes standard in, with unlimited - * buffering. This call will never block. It may fail if the system runs out - * of memory. - * - * @param exe The child process to send to - * @param data The data to send - * @param size The size of the data to send, in bytes - * @return @c EINA_TRUE if successful, @c EINA_FALSE on failure. - */ EAPI Eina_Bool ecore_exe_send(Ecore_Exe *exe, const void *data, @@ -789,11 +695,6 @@ ecore_exe_send(Ecore_Exe *exe, return EINA_TRUE; } -/** - * The stdin of the given child process will close when the write buffer is empty. - * - * @param exe The child process - */ EAPI void ecore_exe_close_stdin(Ecore_Exe *exe) { @@ -806,16 +707,6 @@ ecore_exe_close_stdin(Ecore_Exe *exe) exe->close_stdin = 1; } -/** - * Sets the auto pipe limits for the given process handle. On Windows - * this function does nothing. - * - * @param exe The given process handle. - * @param start_bytes limit of bytes at start of output to buffer. - * @param end_bytes limit of bytes at end of output to buffer. - * @param start_lines limit of lines at start of output to buffer. - * @param end_lines limit of lines at end of output to buffer. - */ EAPI void ecore_exe_auto_limits_set(Ecore_Exe *exe, int start_bytes, @@ -875,13 +766,6 @@ ecore_exe_auto_limits_set(Ecore_Exe *exe, */ } -/** - * Gets the auto pipe data for the given process handle - * - * @param exe The given process handle. - * @param flags Is this a ECORE_EXE_PIPE_READ or ECORE_EXE_PIPE_ERROR? - * @return The event data. - */ EAPI Ecore_Exe_Event_Data * ecore_exe_event_data_get(Ecore_Exe *exe, Ecore_Exe_Flags flags) @@ -1008,12 +892,6 @@ ecore_exe_event_data_get(Ecore_Exe *exe, return e; } -/** - * Sets the string tag for the given process handle - * - * @param exe The given process handle. - * @param tag The string tag to set on the process handle. - */ EAPI void ecore_exe_tag_set(Ecore_Exe *exe, const char *tag) @@ -1031,17 +909,6 @@ ecore_exe_tag_set(Ecore_Exe *exe, exe->tag = NULL; } -/** - * Retrieves the tag attached to the given process handle. There is no need to - * free it as it just returns the internal pointer value. This value is only - * valid as long as the @p exe is valid or until the tag is set to something - * else on this @p exe. - * - * @param exe The given process handle. - * @return The string attached to @p exe. It is a handle to existing - * internal string and should not be modified, use - * ecore_exe_tag_set() to change it. It might be @c NULL. - */ EAPI const char * ecore_exe_tag_get(const Ecore_Exe *exe) { @@ -1054,16 +921,6 @@ ecore_exe_tag_get(const Ecore_Exe *exe) return exe->tag; } -/** - * Frees the given process handle. - * - * Note that the process that the handle represents is unaffected by this - * function. - * - * @param exe The given process handle. - * @return The data attached to the handle when @ref ecore_exe_run was - * called. - */ EAPI void * ecore_exe_free(Ecore_Exe *exe) { @@ -1125,11 +982,6 @@ ecore_exe_free(Ecore_Exe *exe) return data; } -/** - * Frees the given event data. - * - * @param e The given event data. - */ EAPI void ecore_exe_event_data_free(Ecore_Exe_Event_Data *e) { @@ -1139,11 +991,6 @@ ecore_exe_event_data_free(Ecore_Exe_Event_Data *e) free(e); } -/** - * Retrieves the process ID of the given spawned process. - * @param exe Handle to the given spawned process. - * @return The process ID on success. @c -1 otherwise. - */ EAPI pid_t ecore_exe_pid_get(const Ecore_Exe *exe) { @@ -1156,13 +1003,6 @@ ecore_exe_pid_get(const Ecore_Exe *exe) return exe->pid; } -/** - * Retrieves the command of the given spawned process. - * @param exe Handle to the given spawned process. - * @return The command on success, @c NULL otherwise. This string is the - * pointer to the internal value and must not be modified in - * any way. - */ EAPI const char * ecore_exe_cmd_get(const Ecore_Exe *exe) { @@ -1175,12 +1015,6 @@ ecore_exe_cmd_get(const Ecore_Exe *exe) return exe->cmd; } -/** - * Retrieves the data attached to the given process handle. - * @param exe The given process handle. - * @return The data pointer attached to @p exe Given to - * ecore_exe_run() or ecore_exe_pipe_run() - */ EAPI void * ecore_exe_data_get(const Ecore_Exe *exe) { @@ -1193,14 +1027,6 @@ ecore_exe_data_get(const Ecore_Exe *exe) return exe->data; } -/** - * Sets the data attached to the given process handle. - * @param exe The given process handle. - * @param data The pointer to attach - * @return The data pointer previously attached to @p exe with - * ecore_exe_run(), ecore_exe_pipe_run(), or ecore_exe_data_set() - * @since 1.1 - */ EAPI void * ecore_exe_data_set(Ecore_Exe *exe, void *data) @@ -1217,11 +1043,6 @@ ecore_exe_data_set(Ecore_Exe *exe, return ret; } -/** - * Retrieves the flags attached to the given process handle. - * @param exe The given process handle. - * @return The flags attached to @p exe. - */ EAPI Ecore_Exe_Flags ecore_exe_flags_get(const Ecore_Exe *exe) { @@ -1234,10 +1055,6 @@ ecore_exe_flags_get(const Ecore_Exe *exe) return exe->flags; } -/** - * Pauses the given process by sending it a @c SIGSTOP signal. - * @param exe Process handle to the given process. - */ EAPI void ecore_exe_pause(Ecore_Exe *exe) { @@ -1250,10 +1067,6 @@ ecore_exe_pause(Ecore_Exe *exe) kill(exe->pid, SIGSTOP); } -/** - * Continues the given paused process by sending it a @c SIGCONT signal. - * @param exe Process handle to the given process. - */ EAPI void ecore_exe_continue(Ecore_Exe *exe) { @@ -1266,10 +1079,6 @@ ecore_exe_continue(Ecore_Exe *exe) kill(exe->pid, SIGCONT); } -/** - * Sends the given spawned process a interrupt (@c SIGINT) signal. - * @param exe Process handle to the given process. - */ EAPI void ecore_exe_interrupt(Ecore_Exe *exe) { @@ -1283,10 +1092,6 @@ ecore_exe_interrupt(Ecore_Exe *exe) kill(exe->pid, SIGINT); } -/** - * Sends the given spawned process a quit (@c SIGQUIT) signal. - * @param exe Process handle to the given process. - */ EAPI void ecore_exe_quit(Ecore_Exe *exe) { @@ -1300,10 +1105,6 @@ ecore_exe_quit(Ecore_Exe *exe) kill(exe->pid, SIGQUIT); } -/** - * Sends the given spawned process a terminate (@c SIGTERM) signal. - * @param exe Process handle to the given process. - */ EAPI void ecore_exe_terminate(Ecore_Exe *exe) { @@ -1318,10 +1119,6 @@ ecore_exe_terminate(Ecore_Exe *exe) kill(exe->pid, SIGTERM); } -/** - * Kills the given spawned process by sending it a @c SIGKILL signal. - * @param exe Process handle to the given process. - */ EAPI void ecore_exe_kill(Ecore_Exe *exe) { @@ -1348,12 +1145,6 @@ ecore_exe_kill(Ecore_Exe *exe) kill(exe->pid, SIGKILL); } -/** - * Sends a @c SIGUSR signal to the given spawned process. - * @param exe Process handle to the given process. - * @param num The number user signal to send. Must be either 1 or 2, or - * the signal will be ignored. - */ EAPI void ecore_exe_signal(Ecore_Exe *exe, int num) @@ -1370,10 +1161,6 @@ ecore_exe_signal(Ecore_Exe *exe, kill(exe->pid, SIGUSR2); } -/** - * Sends a @c SIGHUP signal to the given spawned process. - * @param exe Process handle to the given process. - */ EAPI void ecore_exe_hup(Ecore_Exe *exe) { @@ -1386,10 +1173,6 @@ ecore_exe_hup(Ecore_Exe *exe) kill(exe->pid, SIGHUP); } -/** - * @} - */ - static Ecore_Exe * _ecore_exe_is_it_alive(pid_t pid) { diff --git a/src/lib/ecore/ecore_getopt.c b/src/lib/ecore/ecore_getopt.c index 6fc0c64d83..79e09cce75 100644 --- a/src/lib/ecore/ecore_getopt.c +++ b/src/lib/ecore/ecore_getopt.c @@ -814,14 +814,6 @@ _ecore_getopt_help_prepare(const Ecore_Getopt *parser) return EINA_TRUE; } -/** - * Show nicely formatted help message for the given parser. - * - * @param fp The file the message will be printed on. - * @param parser The parser to be used. - * - * @see ecore_getopt_help_category() - */ EAPI void ecore_getopt_help(FILE *fp, const Ecore_Getopt *parser) @@ -834,17 +826,6 @@ ecore_getopt_help(FILE *fp, _ecore_getopt_help_options(fp, parser); } -/** - * Show help for a single category (along with program usage and description). - * - * @param fp The file the message will be printed on. - * @param parser The parser to be used. - * @param category The category to print. - * - * @return @c EINA_TRUE when the category exists, @c EINA_FALSE otherwise. - * - * @see ecore_getopt_help() - */ EAPI Eina_Bool ecore_getopt_help_category(FILE *fp, const Ecore_Getopt *parser, @@ -1980,12 +1961,6 @@ _ecore_getopt_parse_find_long_other(const Ecore_Getopt *parser, return NULL; } -/** - * Check parser for duplicate entries, print them out. - * - * @return @c EINA_TRUE if there are duplicates, @c EINA_FALSE otherwise. - * @param parser The parser to be checked. - */ EAPI Eina_Bool ecore_getopt_parser_has_duplicates(const Ecore_Getopt *parser) { @@ -2037,68 +2012,6 @@ _ecore_getopt_find_help(const Ecore_Getopt *parser) return NULL; } -/** - * Parse command line parameters. - * - * Walks the command line parameters and parse them based on @a parser - * description, doing actions based on @c parser->descs->action, like - * showing help text, license, copyright, storing values in values and - * so on. - * - * It is expected that values is of the same size than @c parser->descs, - * options that do not need a value it will be left untouched. - * - * All values are expected to be initialized before use. Options with - * action @c ECORE_GETOPT_ACTION_STORE and non required arguments - * (others than @c ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES), are expected - * to provide a value in @c def to be used. - * - * The following actions will store @c 1 on value as a boolean - * (@c value->boolp) if it's not @c NULL to indicate these actions were - * executed: - * - @c ECORE_GETOPT_ACTION_HELP - * - @c ECORE_GETOPT_ACTION_VERSION - * - @c ECORE_GETOPT_ACTION_COPYRIGHT - * - @c ECORE_GETOPT_ACTION_LICENSE - * - * Just @c ECORE_GETOPT_ACTION_APPEND will allocate memory and thus - * need to be freed. For consistency between all of appended subtypes, - * @c eina_list->data will contain an allocated memory with the value, - * that is, for @c ECORE_GETOPT_TYPE_STR it will contain a copy of the - * argument, @c ECORE_GETOPT_TYPE_INT a pointer to an allocated - * integer and so on. - * - * If parser is in strict mode (see @c Ecore_Getopt->strict), then any - * error will abort parsing and @c -1 is returned. Otherwise it will try - * to continue as far as possible. - * - * This function may reorder @a argv elements. - * - * Translation of help strings (description), metavar, usage, license - * and copyright may be translated, standard/global gettext() call - * will be applied on them if ecore was compiled with such support. - * - * This function will @b not parse positional arguments! If these are - * declared (metavar is defined with both shortname and longname being - * empty), then you must call ecore_getopt_parse_positional() with the - * last argument (@c start) being the result of this function. This is - * done so you can have "quit options", those that once called you - * want to exit without doing further parsing, as is the case with - * help, license, copyright, version and eventually others you may - * define. - * - * @param parser description of how to work. - * @param values where to store values, it is assumed that this is a vector - * of the same size as @c parser->descs. Values should be previously - * initialized. - * @param argc how many elements in @a argv. If not provided it will be - * retrieved with ecore_app_args_get(). - * @param argv command line parameters. - * - * @return index of first non-option parameter or -1 on error. - * - * @see ecore_getopt_parse_positional() - */ EAPI int ecore_getopt_parse(const Ecore_Getopt *parser, Ecore_Getopt_Value *values, @@ -2163,57 +2076,6 @@ error: return -1; } -/** - * Parse command line positional parameters. - * - * Walks the command line positional parameters (those that do not - * start with "-" or "--") and parse them based on @a parser - * description, doing actions based on @c parser->descs->action, like - * storing values of some type. - * - * It is expected that @a values is of the same size than @c - * parser->descs, same as with ecore_getopt_parse(). - * - * All values are expected to be initialized before use. - * - * Unlike the ecore_getopt_parse(), only the following options are - * supported: - * - @c ECORE_GETOPT_ACTION_STORE - * - @c ECORE_GETOPT_ACTION_CHOICE - * - @c ECORE_GETOPT_ACTION_APPEND - * - @c ECORE_GETOPT_ACTION_CALLBACK - * - * There is a special case for @c ECORE_GETOPT_ACTION_APPEND as it - * will consume all remaining elements. It is also special in the - * sense that it will allocate memory and thus need to be freed. For - * consistency between all of appended subtypes, @c eina_list->data - * will contain an allocated memory with the value, that is, for @c - * ECORE_GETOPT_TYPE_STR it will contain a copy of the argument, @c - * ECORE_GETOPT_TYPE_INT a pointer to an allocated integer and so on. - * - * If parser is in strict mode (see @c Ecore_Getopt->strict), then any - * error will abort parsing and @c -1 is returned. Otherwise it will try - * to continue as far as possible. - * - * Translation of help strings (description) and metavar may be done, - * standard/global gettext() call will be applied on them if ecore was - * compiled with such support. - * - * @param parser description of how to work. - * @param values where to store values, it is assumed that this is a vector - * of the same size as @c parser->descs. Values should be previously - * initialized. - * @param argc how many elements in @a argv. If not provided it will be - * retrieved with ecore_app_args_get(). - * @param argv command line parameters. - * @param start the initial position argument to look at, usually the - * return of ecore_getopt_parse(). If less than 1, will try to - * find it automatically. - * - * @return index of first non-option parameter or -1 on error. If the - * last positional argument is of action @c - * ECORE_GETOPT_ACTION_APPEND then it will be the same as @a argc. - */ EAPI int ecore_getopt_parse_positional(const Ecore_Getopt *parser, Ecore_Getopt_Value *values, @@ -2280,12 +2142,6 @@ error: return -1; } -/** - * Utility to free list and nodes allocated by @a ECORE_GETOPT_ACTION_APPEND. - * - * @param list pointer to list to be freed. - * @return always @c NULL, so you can easily make your list head @c NULL. - */ EAPI Eina_List * ecore_getopt_list_free(Eina_List *list) { @@ -2296,19 +2152,6 @@ ecore_getopt_list_free(Eina_List *list) return NULL; } -/** - * Helper ecore_getopt callback to parse geometry (x:y:w:h). - * - * @param parser This parameter isn't in use. - * @param desc This parameter isn't in use. - * @param str Geometry value - * @param data This parameter isn't in use. - * @param storage must be a pointer to @c Eina_Rectangle and will be used to - * store the four values passed in the given string. - * @return @c EINA_TRUE on success, @c EINA_FALSE on incorrect geometry value. - * - * @c callback_data value is ignored, you can safely use @c NULL. - */ EAPI Eina_Bool ecore_getopt_callback_geometry_parse(const Ecore_Getopt *parser EINA_UNUSED, const Ecore_Getopt_Desc *desc EINA_UNUSED, @@ -2327,20 +2170,6 @@ ecore_getopt_callback_geometry_parse(const Ecore_Getopt *parser EINA_UNUSED return EINA_TRUE; } -/** - * Helper ecore_getopt callback to parse geometry size (WxH). - * - * @param parser This parameter isn't in use. - * @param desc This parameter isn't in use. - * @param str size value - * @param data This parameter isn't in use. - * @param storage must be a pointer to @c Eina_Rectangle and will be used to - * store the two values passed in the given string and @c 0 in the x and y - * fields. - * @return @c EINA_TRUE on success, @c EINA_FALSE on incorrect size value. - * - * @c callback_data value is ignored, you can safely use @c NULL. - */ EAPI Eina_Bool ecore_getopt_callback_size_parse(const Ecore_Getopt *parser EINA_UNUSED, const Ecore_Getopt_Desc *desc EINA_UNUSED, @@ -2360,4 +2189,3 @@ ecore_getopt_callback_size_parse(const Ecore_Getopt *parser EINA_UNUSED, return EINA_TRUE; } - diff --git a/src/lib/ecore/ecore_glib.c b/src/lib/ecore/ecore_glib.c index 465317d3ad..7eacdeb6af 100644 --- a/src/lib/ecore/ecore_glib.c +++ b/src/lib/ecore/ecore_glib.c @@ -262,63 +262,6 @@ _ecore_glib_shutdown(void) #endif } -/** - * @addtogroup Ecore_Main_Loop_Group - * - * @} - */ - -/** - * Request ecore to integrate GLib's main loop. - * - * This will add a small overhead during every main loop interaction - * by checking glib's default main context (used by its main loop). If - * it have events to be checked (timers, file descriptors or idlers), - * then these will be polled alongside with Ecore's own events, then - * dispatched before Ecore's. This is done by calling - * ecore_main_loop_select_func_set(). - * - * This will cooperate with previously set - * ecore_main_loop_select_func_set() by calling the old - * function. Similarly, if you want to override - * ecore_main_loop_select_func_set() after main loop is integrated, - * call the new select function set by this call (get it by calling - * ecore_main_loop_select_func_get() right after - * ecore_main_loop_glib_integrate()). - * - * This is useful to use GMainLoop libraries, like GTK, GUPnP, - * LibSoup, GConf and more. Adobe Flash plugin and other plugins - * systems depend on this as well. - * - * Once initialized/integrated, it will be valid until Ecore is - * completely shut down. - * - * Example of use: - * @code - * - * int main(void) - * { - * ecore_init(); - * ecore_main_loop_glib_integrate(); - * - * // some code here - * - * ecore_main_loop_begin(); - * - * ecore_shutdown(); - * - * return 0; - * } - * - * @endcode - * - * @note This is only available if Ecore was compiled with GLib support. - * @note You don't need to call this function if Ecore was compiled with - * --with-glib=always. - * - * @return @c EINA_TRUE on success of @c EINA_FALSE if it failed, - * likely no GLib support in Ecore. - */ EAPI Eina_Bool ecore_main_loop_glib_integrate(void) { @@ -340,21 +283,8 @@ ecore_main_loop_glib_integrate(void) Eina_Bool _ecore_glib_always_integrate = 1; -/** - * Disable always integrating glib - * - * If ecore is compiled with --with-glib=always (to always call - * ecore_main_loop_glib_integrate() when ecore_init() is called), then calling - * this before calling ecore_init() will disable the integration. - * This is for apps that explicitly do not want this to happen for whatever - * reasons they may have. - */ EAPI void ecore_main_loop_glib_always_integrate_disable(void) { _ecore_glib_always_integrate = 0; } - -/** - * @} - */ diff --git a/src/lib/ecore/ecore_idle_enterer.c b/src/lib/ecore/ecore_idle_enterer.c index 102f5bb89f..5be4f7abf3 100644 --- a/src/lib/ecore/ecore_idle_enterer.c +++ b/src/lib/ecore/ecore_idle_enterer.c @@ -31,12 +31,6 @@ static int idle_enterers_delete_me = 0; static void * _ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer); -/** - * @addtogroup Ecore_Idle_Group - * - * @{ - */ - static Eina_Bool _ecore_idle_enterer_add(Ecore_Idle_Enterer *obj, Ecore_Idle_Enterer_Data *ie, @@ -65,16 +59,6 @@ _ecore_idle_enterer_add(Ecore_Idle_Enterer *obj, return EINA_TRUE; } -/** - * Add an idle enterer handler. - * @param func The function to call when entering an idle state. - * @param data The data to be passed to the @p func call - * @return A handle to the idle enterer callback if successful. Otherwise, - * NULL is returned. - * @note The function func will be called every time the main loop is entering - * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 - * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer. - */ EAPI Ecore_Idle_Enterer * ecore_idle_enterer_add(Ecore_Task_Cb func, const void *data) @@ -97,16 +81,6 @@ unlock: _ecore_unlock(); } -/** - * Add an idle enterer handler at the start of the list so it gets called earlier than others. - * @param func The function to call when entering an idle state. - * @param data The data to be passed to the @p func call - * @return A handle to the idle enterer callback if successful. Otherwise, - * NULL is returned. - * @note The function func will be called every time the main loop is entering - * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 - * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer. - */ EAPI Ecore_Idle_Enterer * ecore_idle_enterer_before_add(Ecore_Task_Cb func, const void *data) @@ -136,12 +110,6 @@ _ecore_idle_enterer_eo_base_constructor(Eo *obj, Ecore_Idle_Enterer_Data *_pd EI ERR("only custom constructor can be used with '%s' class", MY_CLASS_NAME); } -/** - * Delete an idle enterer callback. - * @param idle_enterer The idle enterer to delete - * @return The data pointer passed to the idler enterer callback on success. - * NULL otherwise. - */ EAPI void * ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer) { @@ -156,11 +124,6 @@ ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer) return data; } -/** - * @} - */ - - static void * _ecore_idle_enterer_del(Ecore_Idle_Enterer *obj) { @@ -269,4 +232,4 @@ _ecore_idle_enterer_exist(void) return 0; } -#include "ecore_idle_enterer.eo.c" \ No newline at end of file +#include "ecore_idle_enterer.eo.c" diff --git a/src/lib/ecore/ecore_idle_exiter.c b/src/lib/ecore/ecore_idle_exiter.c index bf9b015c36..0c53ccbbd6 100644 --- a/src/lib/ecore/ecore_idle_exiter.c +++ b/src/lib/ecore/ecore_idle_exiter.c @@ -32,21 +32,6 @@ static int idle_exiters_delete_me = 0; static void * _ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); -/** - * @addtogroup Ecore_Idle_Group - * - * @{ - */ - -/** - * Add an idle exiter handler. - * @param func The function to call when exiting an idle state. - * @param data The data to be passed to the @p func call - * @return A handle to the idle exiter callback on success. NULL otherwise. - * @note The function func will be called every time the main loop is exiting - * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 - * (or ECORE_CALLBACK_CANCEL) deletes the idle exiter. - */ EAPI Ecore_Idle_Exiter * ecore_idle_exiter_add(Ecore_Task_Cb func, const void *data) @@ -93,12 +78,6 @@ _ecore_idle_exiter_eo_base_constructor(Eo *obj, Ecore_Idle_Exiter_Data *_pd EINA ERR("only custom constructor can be used with '%s' class", MY_CLASS_NAME); } -/** - * Delete an idle exiter handler from the list to be run on exiting idle state. - * @param idle_exiter The idle exiter to delete - * @return The data pointer that was being being passed to the handler if - * successful. NULL otherwise. - */ EAPI void * ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter) { @@ -113,9 +92,6 @@ ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter) return data; } -/** - * @} - */ static void * _ecore_idle_exiter_del(Ecore_Idle_Exiter *obj) { @@ -225,4 +201,4 @@ _ecore_idle_exiter_exist(void) return 0; } -#include "ecore_idle_exiter.eo.c" \ No newline at end of file +#include "ecore_idle_exiter.eo.c" diff --git a/src/lib/ecore/ecore_idler.c b/src/lib/ecore/ecore_idler.c index 7650af5363..15b8cdcffc 100644 --- a/src/lib/ecore/ecore_idler.c +++ b/src/lib/ecore/ecore_idler.c @@ -92,14 +92,6 @@ ecore_idler_del(Ecore_Idler *idler) return data; } -/** - * @} - */ - -/** - * @} - */ - static void * _ecore_idler_del(Ecore_Idler *obj) { @@ -205,4 +197,4 @@ _ecore_idler_exist(void) return 0; } -#include "ecore_idler.eo.c" \ No newline at end of file +#include "ecore_idler.eo.c" diff --git a/src/lib/ecore/ecore_job.c b/src/lib/ecore/ecore_job.c index dfa00720b2..93f1d0bd98 100644 --- a/src/lib/ecore/ecore_job.c +++ b/src/lib/ecore/ecore_job.c @@ -45,21 +45,6 @@ _ecore_job_shutdown(void) _ecore_job_handler = NULL; } -/** - * @addtogroup Ecore_Job_Group - * - * @{ - */ - -/** - * Add a job to the event queue. - * @param func The function to call when the job gets handled. - * @param data Data pointer to be passed to the job function when the job is - * handled. - * @return The handle of the job. @c NULL is returned if the job could not be - * added to the queue. - * @note Once the job has been executed, the job handle is invalid. - */ EAPI Ecore_Job * ecore_job_add(Ecore_Cb func, const void *data) @@ -105,11 +90,6 @@ _ecore_job_eo_base_constructor(Eo *obj, Ecore_Job_Data *_pd EINA_UNUSED) ERR("only custom constructor can be used with '%s' class", MY_CLASS_NAME); } -/** - * Delete a queued job that has not yet been executed. - * @param obj Handle of the job to delete. - * @return The data pointer that was to be passed to the job. - */ EAPI void * ecore_job_del(Ecore_Job *obj) { @@ -131,10 +111,6 @@ _ecore_job_eo_base_destructor(Eo *obj, Ecore_Job_Data *_pd EINA_UNUSED) eo_do_super(obj, MY_CLASS, eo_destructor()); } -/** - * @} - */ - static Eina_Bool _ecore_job_event_handler(void *data EINA_UNUSED, int type EINA_UNUSED, diff --git a/src/lib/ecore/ecore_main.c b/src/lib/ecore/ecore_main.c index 5278116124..adb6ae3a66 100644 --- a/src/lib/ecore/ecore_main.c +++ b/src/lib/ecore/ecore_main.c @@ -938,25 +938,6 @@ _ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler) return fd_handler->data; } -/** - * @addtogroup Ecore_Main_Loop_Group - * - * @{ - */ - -/** - * Runs a single iteration of the main loop to process everything on the - * queue. - * - * It does everything that is already done inside an @c Ecore main loop, like - * checking for expired timers, idlers, etc. But it will do it only once and - * return, instead of keep watching for new events. - * - * DO NOT use this function unless you are the person God comes to ask for - * advice when He has trouble managing the Universe. - * - * @see ecore_main_loop_iterate_may_block() - */ EAPI void ecore_main_loop_iterate(void) { @@ -971,23 +952,6 @@ ecore_main_loop_iterate(void) #endif } -/** - * Runs a single iteration of the main loop to process everything on the - * queue with block/non-blocking status. - * - * @param may_block A flag if the main loop has a possibility of blocking. - * (@c EINA_TRUE = may block/@c EINA_FALSE = non block) - * - * This is an extension API for ecore_main_loop_iterate() with additional - * parameter. It does everything that is already done inside an - * @c Ecore main loop, like checking for expired timers, idlers, etc. But it - * will do it only once and return, instead of keep watching for new events. - * - * DO NOT use this function unless you are the person God comes to ask for - * advice when He has trouble managing the Universe. - * - * @see ecore_main_loop_iterate() - */ EAPI int ecore_main_loop_iterate_may_block(int may_block) { @@ -1005,24 +969,6 @@ in_main_loop--; #endif } -/** - * Runs the application main loop. - * - * This function will not return until @ref ecore_main_loop_quit is called. It - * will check for expired timers, idlers, file descriptors being watched by fd - * handlers, etc. Once everything is done, before entering again on idle state, - * any callback set as @c Idle_Enterer will be called. - * - * Each main loop iteration is done by calling ecore_main_loop_iterate() - * internally. - * - * The polling (select) function used can be changed with - * ecore_main_loop_select_func_set(). - * - * The function used to check for file descriptors, events, and that has a - * timeout for the timers can be changed using - * ecore_main_loop_select_func_set(). - */ EAPI void ecore_main_loop_begin(void) { @@ -1049,13 +995,6 @@ ecore_main_loop_begin(void) #endif } -/** - * Quits the main loop once all the events currently on the queue have - * been processed. - * - * This function returns immediately, but will mark the ecore_main_loop_begin() - * function to return at the end of the current main loop iteration. - */ EAPI void ecore_main_loop_quit(void) { @@ -1067,34 +1006,12 @@ ecore_main_loop_quit(void) #endif } -/** - * Returns if an animator has ticked off during this loop iteration - * - * @return EINA_TRUE if an animator has been called, EINA_FALSE otherwise. - * - * There should be little need for anyone to use this - ever. - * - * @since 1.9 - */ EAPI Eina_Bool ecore_main_loop_animator_ticked_get(void) { return _ecore_animator_run_get(); } -/** - * Sets the function to use when monitoring multiple file descriptors, - * and waiting until one of more of the file descriptors before ready - * for some class of I/O operation. - * - * This function will be used instead of the system call select and - * could possible be used to integrate the Ecore event loop with an - * external event loop. - * - * @warning you don't know how to use, don't even try to use it. - * - * @param func The function to be used. - */ EAPI void ecore_main_loop_select_func_set(Ecore_Select_Function func) { @@ -1102,11 +1019,6 @@ ecore_main_loop_select_func_set(Ecore_Select_Function func) main_loop_select = func; } -/** - * Gets the select function set by ecore_select_func_set(), - * or the native select function if none was set. - * - */ EAPI Ecore_Select_Function ecore_main_loop_select_func_get(void) { @@ -1396,10 +1308,6 @@ unlock: _ecore_unlock(); } -/** - * @} - */ - void _ecore_main_shutdown(void) { @@ -1982,7 +1890,7 @@ _ecore_main_loop_iterate_internal(int once_only) _ecore_fps_marker_1(); /* start of the sleeping or looping section */ -start_loop: /***************************************************************/ +start_loop: /*-*************************************************************/ /* any timers re-added as a result of these are allowed to go */ _ecore_timer_enable_new(); /* if we have been asked to quit the mainloop then exit at this point */ @@ -2015,7 +1923,7 @@ start_loop: /***************************************************************/ _ecore_fps_marker_2(); /* actually wake up and deal with input, events etc. */ -process_all: /***********************************************************/ +process_all: /*-*********************************************************/ /* we came out of our "wait state" so idle has exited */ if (!once_only) @@ -2041,7 +1949,7 @@ process_all: /***********************************************************/ _ecore_throttle(); } -done: /*******************************************************************/ +done: /*-*****************************************************************/ in_main_loop--; } diff --git a/src/lib/ecore/ecore_pipe.c b/src/lib/ecore/ecore_pipe.c index 9783c2f5a9..7228abf958 100644 --- a/src/lib/ecore/ecore_pipe.c +++ b/src/lib/ecore/ecore_pipe.c @@ -102,23 +102,6 @@ GENERIC_ALLOC_SIZE_DECLARE(Ecore_Pipe); static Eina_Bool _ecore_pipe_read(void *data, Ecore_Fd_Handler *fd_handler); -/** - * @addtogroup Ecore_Pipe_Group - * - * @{ - */ - -/** - * Create two file descriptors (sockets on Windows). Add - * a callback that will be called when the file descriptor that - * is listened receives data. An event is also put in the event - * queue when data is received. - * - * @param handler The handler called when data is received. - * @param data Data to pass to @p handler when it is called. - * @return A newly created Ecore_Pipe object if successful. - * @c NULL otherwise. - */ EAPI Ecore_Pipe * ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data) @@ -132,12 +115,6 @@ ecore_pipe_add(Ecore_Pipe_Cb handler, return p; } -/** - * Free an Ecore_Pipe object created with ecore_pipe_add(). - * - * @param p The Ecore_Pipe object to be freed. - * @return The pointer to the private data - */ EAPI void * ecore_pipe_del(Ecore_Pipe *p) { @@ -150,11 +127,6 @@ ecore_pipe_del(Ecore_Pipe *p) return r; } -/** - * Close the read end of an Ecore_Pipe object created with ecore_pipe_add(). - * - * @param p The Ecore_Pipe object. - */ EAPI void ecore_pipe_read_close(Ecore_Pipe *p) { @@ -186,13 +158,6 @@ ecore_pipe_read_fd(Ecore_Pipe *p) return p->fd_read; } -/** - * Stop monitoring if necessary the pipe for reading. See ecore_pipe_thaw() - * for monitoring it again. - * - * @param p The Ecore_Pipe object. - * @since 1.1 - */ EAPI void ecore_pipe_freeze(Ecore_Pipe *p) { @@ -212,14 +177,6 @@ out: _ecore_unlock(); } -/** - * Start monitoring again the pipe for reading. See ecore_pipe_freeze() for - * stopping the monitoring activity. This will not work if - * ecore_pipe_read_close() was previously called on the same pipe. - * - * @param p The Ecore_Pipe object. - * @since 1.1 - */ EAPI void ecore_pipe_thaw(Ecore_Pipe *p) { @@ -242,17 +199,6 @@ out: _ecore_unlock(); } -/** - * @brief Wait from another thread on the read side of a pipe. - * - * @param p The pipe to watch on. - * @param message_count The minimal number of message to wait before exiting. - * @param wait The amount of time in second to wait before exiting. - * @return the number of message catched during that wait call. - * @since 1.1 - * - * Negative value for @p wait means infite wait. - */ EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, @@ -265,11 +211,6 @@ ecore_pipe_wait(Ecore_Pipe *p, return r; } -/** - * Close the write end of an Ecore_Pipe object created with ecore_pipe_add(). - * - * @param p The Ecore_Pipe object. - */ EAPI void ecore_pipe_write_close(Ecore_Pipe *p) { @@ -295,14 +236,6 @@ ecore_pipe_write_fd(Ecore_Pipe *p) return p->fd_write; } -/** - * Write on the file descriptor the data passed as parameter. - * - * @param p The Ecore_Pipe object. - * @param buffer The data to write into the pipe. - * @param nbytes The size of the @p buffer in bytes - * @return @c EINA_TRUE on a successful write, @c EINA_FALSE on error. - */ EAPI Eina_Bool ecore_pipe_write(Ecore_Pipe *p, const void *buffer, @@ -406,7 +339,7 @@ ecore_pipe_full_add(Ecore_Pipe_Cb handler, int fd_read, int fd_write, Eina_Bool read_survive_fork, - Eina_Bool write_survive_fork) + Eina_Bool write_survive_fork) { Ecore_Pipe *p = NULL; int fds[2]; @@ -452,13 +385,9 @@ ecore_pipe_full_add(Ecore_Pipe_Cb handler, p, NULL, NULL); - return p; + return p; } -/** - * @} - */ - /* Private functions */ Ecore_Pipe * _ecore_pipe_add(Ecore_Pipe_Cb handler, @@ -466,7 +395,7 @@ _ecore_pipe_add(Ecore_Pipe_Cb handler, { return ecore_pipe_full_add(handler, data, -1, -1, - EINA_FALSE, EINA_FALSE); + EINA_FALSE, EINA_FALSE); } void * diff --git a/src/lib/ecore/ecore_poll.c b/src/lib/ecore/ecore_poll.c index eeff3c7161..caf194a7fb 100644 --- a/src/lib/ecore/ecore_poll.c +++ b/src/lib/ecore/ecore_poll.c @@ -385,10 +385,6 @@ _ecore_poller_eo_base_destructor(Eo *obj, Ecore_Poller_Data *pd) eo_do_super(obj, MY_CLASS, eo_destructor()); } -/** - * @} - */ - void _ecore_poller_shutdown(void) { diff --git a/src/lib/ecore/ecore_throttle.c b/src/lib/ecore/ecore_throttle.c index 0754e22fcf..0b9e17786b 100644 --- a/src/lib/ecore/ecore_throttle.c +++ b/src/lib/ecore/ecore_throttle.c @@ -10,59 +10,6 @@ static int throttle_val = 0; -/** - * @addtogroup Ecore_Throttle_Group Ecore Throttle functions - * - * @{ - */ - -/** - * Increase throttle amount - * - * This will increase or decrease (if @p amount is positive or negative) the - * amount of "voluntary throttling" ecore will do to its main loop while - * running. This is intended to be used to limit animations and wakeups when - * in a strict power management state. The higher the current throttle value - * (which can be retrieved by ecore_throttle_get() ), the more throttling - * takes place. If the current throttle value is 0, then no throttling takes - * place at all. - * - * The value represents how long the ecore main loop will sleep (in seconds) - * before it goes into a fully idle state waiting for events, input or - * timing events to wake it up. For example, if the current throttle level - * is 0.5, then after every time the main loop cycles and goes into idle - * after processing all events, the main loop will explicitly sleep for 0.5 - * seconds before sitting and waiting for incoming events or timeouts, thus - * preventing animation, async IO and network handling etc. for that period - * of time. Of course these events, data and timeouts will be buffered, - * thus not losing anything, simply delaying when they get handled by the - * throttle value. - * - * Example: - * @code - * void enter_powersave(void) { - * ecore_throttle_adjust(0.2); - * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); - * } - * - * void enter_deep_powersave(void) { - * ecore_throttle_adjust(0.5); - * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); - * } - * - * void exit_powersave(void) { - * ecore_throttle_adjust(-0.2); - * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); - * } - * - * void exit_deep_powersave(void) { - * ecore_throttle_adjust(-0.5); - * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); - * } - * @endcode - * - * @param amount Amount (in seconds) to adjust by - */ EAPI void ecore_throttle_adjust(double amount) { @@ -72,15 +19,6 @@ ecore_throttle_adjust(double amount) if (throttle_val < 0) throttle_val = 0; } -/** - * Get current throttle level - * - * This gets the current throttling level, which can be adjusted by - * ecore_throttle_adjust(). The value is in seconds. Please see - * ecore_throttle_adjust() for more information. - * - * @return The current throttle level - */ EAPI double ecore_throttle_get(void) { @@ -88,10 +26,6 @@ ecore_throttle_get(void) return (double)throttle_val / 1000000.0; } -/** - * @} - */ - void _ecore_throttle(void) { diff --git a/src/lib/ecore/ecore_time.c b/src/lib/ecore/ecore_time.c index d2ac8c4e33..30c54f1082 100644 --- a/src/lib/ecore/ecore_time.c +++ b/src/lib/ecore/ecore_time.c @@ -25,27 +25,6 @@ static double _ecore_time_clock_conversion = 1e-9; #endif double _ecore_time_loop_time = -1.0; -/** - * @addtogroup Ecore_Time_Group - * - * @{ - */ - -/** - * Retrieves the current system time as a floating point value in seconds. - * - * This uses a monotonic clock and thus never goes back in time while - * machine is live (even if user changes time or timezone changes, - * however it may be reset whenever the machine is restarted). - * - * @see ecore_loop_time_get(). - * @see ecore_time_unix_get(). - * - * @return The number of seconds. Start time is not defined (it may be - * when the machine was booted, unix time, etc), all it is - * defined is that it never goes backwards (unless you got big critical - * messages when the application started). - */ EAPI double ecore_time_get(void) { @@ -72,14 +51,6 @@ ecore_time_get(void) #endif } -/** - * Retrieves the current UNIX time as a floating point value in seconds. - * - * @see ecore_time_get(). - * @see ecore_loop_time_get(). - * - * @return The number of seconds since 12.00AM 1st January 1970. - */ EAPI double ecore_time_unix_get(void) { @@ -93,27 +64,6 @@ ecore_time_unix_get(void) #endif } -/** - * Retrieves the time at which the last loop stopped waiting for timeouts or - * events. - * - * This gets the time that the main loop ceased waiting for timouts and/or - * events to come in or for signals or any other interrupt source. This should - * be considered a reference point for all time based activity that should - * calculate its timepoint from the return of ecore_loop_time_get(). Use this - * UNLESS you absolutely must get the current actual timepoint - then use - * ecore_time_get(). Note that this time is meant to be used as relative to - * other times obtained on this run. If you need absolute time references, use - * ecore_time_unix_get() instead. - * - * This function can be called before any loop has ever been run, but either - * ecore_init() or ecore_time_get() must have been called once. - * - * @return The number of seconds. Start time is not defined (it may be - * when the machine was booted, unix time, etc), all it is - * defined is that it never goes backwards (unless you got big critical - * messages when the application started). - */ EAPI double ecore_loop_time_get(void) { @@ -126,11 +76,7 @@ ecore_loop_time_set(double t) _ecore_time_loop_time = t; } -/** - * @} - */ - -/********************** Internal methods ********************************/ +/*-******************** Internal methods ********************************/ /* TODO: Documentation says "All implementations support the system-wide * real-time clock, which is identified by CLOCK_REALTIME. Check if the fallback diff --git a/src/lib/ecore/ecore_timer.c b/src/lib/ecore/ecore_timer.c index 0bcd97b28a..17ab04251a 100644 --- a/src/lib/ecore/ecore_timer.c +++ b/src/lib/ecore/ecore_timer.c @@ -65,17 +65,6 @@ static Ecore_Timer_Data *suspended = NULL; static double last_check = 0.0; static double precision = 10.0 / 1000000.0; -/** - * @addtogroup Ecore_Timer_Group - * - * @{ - */ - -/** - * Retrieves the current precision used by timer infrastructure. - * @return Current precision. - * @see ecore_timer_precision_set() - */ EAPI double ecore_timer_precision_get(void) { @@ -83,31 +72,6 @@ ecore_timer_precision_get(void) return precision; } -/** - * @brief Sets the precision to be used by timer infrastructure. - * - * @param value allowed introduced timeout delay, in seconds. - * - * This sets the precision for @b all timers. The precision determines how much - * of an difference from the requested interval is acceptable. One common reason - * to use this function is to @b increase the allowed timeout and thus @b - * decrease precision of the timers, this is because less precise the timers - * result in the system waking up less often and thus consuming less resources. - * - * Be aware that kernel may delay delivery even further, these delays - * are always possible due other tasks having higher priorities or - * other scheduler policies. - * - * Example: - * We have 2 timers, one that expires in a 2.0s and another that - * expires in 2.1s, if precision is 0.1s, then the Ecore will request - * for the next expire to happen in 2.1s and not 2.0s and another one - * of 0.1 as it would before. - * - * @note Ecore is smart enough to see if there are timers in the - * precision range, if it does not, in our example if no second timer - * in (T + precision) existed, then it would use the minimum timeout. - */ EAPI void ecore_timer_precision_set(double value) { @@ -125,24 +89,6 @@ unlock: _ecore_unlock(); } -/** - * Creates a timer to call the given function in the given period of time. - * @param in The interval in seconds. - * @param func The given function. If @p func returns 1, the timer is - * rescheduled for the next interval @p in. - * @param data Data to pass to @p func when it is called. - * @return A timer object on success. @c NULL on failure. - * - * This function adds a timer and returns its handle on success and NULL on - * failure. The function @p func will be called every @p in seconds. The - * function will be passed the @p data pointer as its parameter. - * - * When the timer @p func is called, it must return a value of either 1 - * (or ECORE_CALLBACK_RENEW) or 0 (or ECORE_CALLBACK_CANCEL). - * If it returns 1, it will be called again at the next tick, or if it returns - * 0 it will be deleted automatically making any references/handles for it - * invalid. - */ EAPI Ecore_Timer * ecore_timer_add(double in, Ecore_Task_Cb func, @@ -221,18 +167,6 @@ _ecore_timer_eo_base_constructor(Eo *obj, Ecore_Timer_Data *_pd EINA_UNUSED) ERR("only custom constructor can be used with '%s' class", MY_CLASS_NAME); } -/** - * Creates a timer to call the given function in the given period of time. - * @param in The interval in seconds from current loop time. - * @param func The given function. If @p func returns 1, the timer is - * rescheduled for the next interval @p in. - * @param data Data to pass to @p func when it is called. - * @return A timer object on success. @c NULL on failure. - * - * This is the same as ecore_timer_add(), but "now" is the time from - * ecore_loop_time_get() not ecore_time_get() as ecore_timer_add() uses. See - * ecore_timer_add() for more details. - */ EAPI Ecore_Timer * ecore_timer_loop_add(double in, Ecore_Task_Cb func, @@ -247,15 +181,6 @@ ecore_timer_loop_add(double in, return timer; } -/** - * Delete the specified timer from the timer list. - * @param timer The timer to delete. - * @return The data pointer set for the timer when @ref ecore_timer_add was - * called. @c NULL is returned if the function is unsuccessful. - * - * Note: @p timer must be a valid handle. If the timer function has already - * returned 0, the handle is no longer valid (and does not need to be delete). - */ EAPI void * ecore_timer_del(Ecore_Timer *timer) { @@ -271,13 +196,6 @@ ecore_timer_del(Ecore_Timer *timer) return data; } -/** - * Change the interval the timer ticks of. If set during - * a timer call, this will affect the next interval. - * - * @param timer The timer to change. - * @param in The interval in seconds. - */ EOLIAN static void _ecore_timer_interval_set(Eo *obj EINA_UNUSED, Ecore_Timer_Data *timer, double in) { @@ -289,12 +207,6 @@ _ecore_timer_interval_set(Eo *obj EINA_UNUSED, Ecore_Timer_Data *timer, double i _ecore_unlock(); } -/** - * Get the interval the timer ticks on. - * - * @param timer The timer to retrieve the interval from - * @return The interval on success. -1 on failure. - */ EOLIAN static double _ecore_timer_interval_get(Eo *obj EINA_UNUSED, Ecore_Timer_Data *timer) { @@ -308,13 +220,6 @@ _ecore_timer_interval_get(Eo *obj EINA_UNUSED, Ecore_Timer_Data *timer) return ret; } -/** - * Add some delay for the next occurrence of a timer. - * This doesn't affect the interval of a timer. - * - * @param timer The timer to change. - * @param add The delay to add to the next iteration. - */ EOLIAN static void _ecore_timer_delay(Eo *obj, Ecore_Timer_Data *_pd EINA_UNUSED, double add) { @@ -325,16 +230,6 @@ _ecore_timer_delay(Eo *obj, Ecore_Timer_Data *_pd EINA_UNUSED, double add) _ecore_unlock(); } -/** - * Reset a timer to its full interval - * This doesn't affect the interval of a timer - * @param timer The timer - * @since 1.2 - * @note This is equivalent to (but faster than) - * @code - * ecore_timer_delay(timer, ecore_timer_interval_get(timer) - ecore_timer_pending_get(timer)); - * @endcode - */ EOLIAN static void _ecore_timer_reset(Eo *obj, Ecore_Timer_Data *timer) { @@ -352,13 +247,6 @@ _ecore_timer_reset(Eo *obj, Ecore_Timer_Data *timer) _ecore_unlock(); } -/** - * Get the pending time regarding a timer. - * - * @param timer The timer to learn from. - * @return The pending time. - * @ingroup Ecore_Timer_Group - */ EOLIAN static double _ecore_timer_pending_get(Eo *obj EINA_UNUSED, Ecore_Timer_Data *timer) { @@ -380,20 +268,6 @@ _ecore_timer_pending_get(Eo *obj EINA_UNUSED, Ecore_Timer_Data *timer) return ret; } -/** - * Pauses a running timer. - * - * @param timer The timer to be paused. - * - * The timer callback won't be called while the timer is paused. The remaining - * time until the timer expires will be saved, so the timer can be resumed with - * that same remaining time to expire, instead of expiring instantly. Use - * ecore_timer_thaw() to resume it. - * - * @note Nothing happens if the timer was already paused. - * - * @see ecore_timer_thaw() - */ EAPI void ecore_timer_freeze(Ecore_Timer *timer) { @@ -443,19 +317,6 @@ _ecore_timer_eo_base_event_freeze_count_get(Eo *obj EINA_UNUSED, Ecore_Timer_Dat return timer->frozen; } -/** - * Resumes a frozen (paused) timer. - * - * @param timer The timer to be resumed. - * - * The timer will be resumed from its previous relative position in time. That - * means, if it had X seconds remaining until expire when it was paused, it will - * be started now with those same X seconds remaining to expire again. But - * notice that the interval time won't be touched by this call or by - * ecore_timer_freeze(). - * - * @see ecore_timer_freeze() - */ EAPI void ecore_timer_thaw(Ecore_Timer *timer) { @@ -540,10 +401,6 @@ ecore_timer_dump(void) #endif } -/** - * @} - */ - Ecore_Timer * _ecore_timer_loop_add(double in, Ecore_Task_Cb func, diff --git a/src/lib/ecore/ecore_timer.eo b/src/lib/ecore/ecore_timer.eo index 5e7f20aad1..b9db51aac9 100644 --- a/src/lib/ecore/ecore_timer.eo +++ b/src/lib/ecore/ecore_timer.eo @@ -29,7 +29,9 @@ class Ecore.Timer (Eo.Base) properties { interval { set { - /*@ Change the interval the timer ticks off. */ + /*@ Change the interval the timer ticks off. If set during + * a timer call, this will affect the next interval. + */ } get { /*@ Get the interval the timer ticks on. */ @@ -48,10 +50,18 @@ class Ecore.Timer (Eo.Base) methods { reset { /*@ Reset a timer to its full interval. This effectively makes - * the timer start ticking off from zero now. */ + * the timer start ticking off from zero now. + * @note This is equivalent to (but faster than) + * @code + * ecore_timer_delay(timer, ecore_timer_interval_get(timer) - ecore_timer_pending_get(timer)); + * @endcode + * @since 1.2 + */ } delay { - /*@ Add some delay for the next occurrence of a timer. */ + /*@ Add some delay for the next occurrence of a timer. + * This doesn't affect the interval of a timer. + */ params { @in double add; /*@ The amount of time to delay the timer by in seconds */ } @@ -61,7 +71,34 @@ class Ecore.Timer (Eo.Base) Eo.Base.constructor; Eo.Base.destructor; Eo.Base.event_freeze; + /* XXX: can't document overriden methods + * Pauses a running timer. + * + * @param timer The timer to be paused. + * + * The timer callback won't be called while the timer is paused. The remaining + * time until the timer expires will be saved, so the timer can be resumed with + * that same remaining time to expire, instead of expiring instantly. Use + * ecore_timer_thaw() to resume it. + * + * @note Nothing happens if the timer was already paused. + * + * @see ecore_timer_thaw() + */ Eo.Base.event_freeze_count.get; Eo.Base.event_thaw; - } + /* XXX: can't document overriden methods + * Resumes a frozen (paused) timer. + * + * @param timer The timer to be resumed. + * + * The timer will be resumed from its previous relative position in time. That + * means, if it had X seconds remaining until expire when it was paused, it will + * be started now with those same X seconds remaining to expire again. But + * notice that the interval time won't be touched by this call or by + * ecore_timer_freeze(). + * + * @see ecore_timer_freeze() + */ + } }