Ecore Timer functions

Ecore provides very flexible timer functionality. More...

Typedefs

typedef struct _Ecore_Timer Ecore_Timer
 A handle for timers.
 

Functions

EAPI Ecore_Timerecore_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. More...
 
EAPI Ecore_Timerecore_timer_loop_add (double in, Ecore_Task_Cb func, const void *data)
 Creates a timer to call the given function in the given period of time. More...
 
EAPI void * ecore_timer_del (Ecore_Timer *timer)
 Delete the specified timer from the timer list. More...
 
EAPI void ecore_timer_interval_set (Ecore_Timer *timer, double in)
 Change the interval the timer ticks of. More...
 
EAPI double ecore_timer_interval_get (Ecore_Timer *timer)
 Get the interval the timer ticks on. More...
 
EAPI void ecore_timer_freeze (Ecore_Timer *timer)
 Pauses a running timer. More...
 
EAPI void ecore_timer_thaw (Ecore_Timer *timer)
 Resumes a frozen (paused) timer. More...
 
EAPI void ecore_timer_delay (Ecore_Timer *timer, double add)
 Add some delay for the next occurrence of a timer. More...
 
EAPI void ecore_timer_reset (Ecore_Timer *timer)
 Reset a timer to its full interval This doesn't affect the interval of a timer. More...
 
EAPI double ecore_timer_pending_get (Ecore_Timer *timer)
 Get the pending time regarding a timer. More...
 
EAPI double ecore_timer_precision_get (void)
 Retrieves the current precision used by timer infrastructure. More...
 
EAPI void ecore_timer_precision_set (double value)
 Sets the precision to be used by timer infrastructure. More...
 

Detailed Description

Ecore provides very flexible timer functionality.

The basic usage of timers, to call a certain function at a certain interval can be achieved with a single line:

* Eina_Bool my_func(void *data) {
* do_funky_stuff_with_data(data);
* return EINA_TRUE;
* }
* ecore_timer_add(interval_in_seconds, my_func, data_given_to_function);
*
Note
If the function was to be executed only once simply return EINA_FALSE instead.

An example that shows the usage of a lot of these:

Function Documentation

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.

Parameters
inThe interval in seconds.
funcThe given function. If func returns 1, the timer is rescheduled for the next interval in.
dataData to pass to func when it is called.
Returns
A timer object on success. NULL on failure.

This function adds a timer and returns its handle on success and NULL on failure. The function func will be called every in seconds. The function will be passed the data pointer as its parameter.

When the timer 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.

Examples:
ecore_animator_example.c, ecore_exe_example.c, ecore_fd_handler_example.c, ecore_idler_example.c, ecore_thread_example.c, ecore_time_functions_example.c, and ecore_timer_example.c.

References ecore_time_get().

Referenced by ecore_con_url_init(), ecore_con_url_timeout_set(), and ecore_exe_kill().

EAPI void * ecore_timer_del ( Ecore_Timer timer)

Delete the specified timer from the timer list.

Parameters
timerThe timer to delete.
Returns
The data pointer set for the timer when ecore_timer_add was called. NULL is returned if the function is unsuccessful.

Note: 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).

Examples:
ecore_fd_handler_example.c, ecore_idler_example.c, and ecore_timer_example.c.

Referenced by ecore_con_url_free(), ecore_con_url_shutdown(), ecore_con_url_timeout_set(), ecore_exe_free(), and ecore_exe_kill().

EAPI void ecore_timer_delay ( Ecore_Timer timer,
double  add 
)

Add some delay for the next occurrence of a timer.

This doesn't affect the interval of a timer.

Parameters
timerThe timer to change.
addThe delay to add to the next iteration.
Examples:
ecore_timer_example.c.
EAPI void ecore_timer_freeze ( Ecore_Timer timer)

Pauses a running timer.

Parameters
timerThe 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 Also
ecore_timer_thaw()
Examples:
ecore_timer_example.c.

References ecore_time_get().

Referenced by ecore_con_url_init().

EAPI double ecore_timer_interval_get ( Ecore_Timer timer)

Get the interval the timer ticks on.

Parameters
timerThe timer to retrieve the interval from
Returns
The interval on success. -1 on failure.
Examples:
ecore_timer_example.c.
EAPI void ecore_timer_interval_set ( Ecore_Timer timer,
double  in 
)

Change the interval the timer ticks of.

If set during a timer call, this will affect the next interval.

Parameters
timerThe timer to change.
inThe interval in seconds.
Examples:
ecore_timer_example.c.
EAPI Ecore_Timer * ecore_timer_loop_add ( double  in,
Ecore_Task_Cb  func,
const void *  data 
)

Creates a timer to call the given function in the given period of time.

Parameters
inThe interval in seconds from current loop time.
funcThe given function. If func returns 1, the timer is rescheduled for the next interval in.
dataData to pass to func when it is called.
Returns
A timer object on success. 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 double ecore_timer_pending_get ( Ecore_Timer timer)

Get the pending time regarding a timer.

Parameters
timerThe timer to learn from.
Returns
The pending time.
Examples:
ecore_timer_example.c.

References ecore_time_get().

EAPI double ecore_timer_precision_get ( void  )

Retrieves the current precision used by timer infrastructure.

Returns
Current precision.
See Also
ecore_timer_precision_set()
EAPI void ecore_timer_precision_set ( double  value)

Sets the precision to be used by timer infrastructure.

Parameters
valueallowed introduced timeout delay, in seconds.

This sets the precision for 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 increase the allowed timeout and thus 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.
Examples:
ecore_timer_example.c.
EAPI void ecore_timer_reset ( Ecore_Timer timer)

Reset a timer to its full interval This doesn't affect the interval of a timer.

Parameters
timerThe timer
Since
1.2
Note
This is equivalent to (but faster than)

References ecore_time_get().

EAPI void ecore_timer_thaw ( Ecore_Timer timer)

Resumes a frozen (paused) timer.

Parameters
timerThe 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 Also
ecore_timer_freeze()
Examples:
ecore_timer_example.c.

References ecore_time_get().