Ecore Time functions
[Ecore - Main Loop and Job Functions.]

Functions that deal with time. More...

Functions

EAPI double ecore_time_get (void)
 Retrieves the current system time as a floating point value in seconds.
EAPI double ecore_time_unix_get (void)
 Retrieves the current UNIX time as a floating point value in seconds.
EAPI double ecore_loop_time_get (void)
 Retrieves the time at which the last loop stopped waiting for timeouts or events.
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.
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.
EAPI void * ecore_timer_del (Ecore_Timer *timer)
 Delete the specified timer from the timer list.
EAPI void ecore_timer_interval_set (Ecore_Timer *timer, double in)
 Change the interval the timer ticks of.
EAPI double ecore_timer_interval_get (Ecore_Timer *timer)
 Get the interval the timer ticks on.
EAPI void ecore_timer_delay (Ecore_Timer *timer, double add)
 Add some delay for the next occurrence of a timer.
EAPI double ecore_timer_pending_get (Ecore_Timer *timer)
 Get the pending time regarding a timer.
EAPI double ecore_timer_precision_get (void)
 Retrieves the current precision used by timer infrastructure.
EAPI void ecore_timer_precision_set (double value)
 Sets the precision to be used by timer infrastructure.

Detailed Description

Functions that deal with time.

These functions include those that simply retrieve it in a given format, and those that create events based on it.

The timer allows callbacks to be called at specific intervals.

Function Documentation

EAPI double ecore_loop_time_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.

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

Referenced by ecore_animator_add(), and ecore_timer_loop_add().

EAPI double ecore_time_get ( void   ) 

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 also:
ecore_loop_time_get().
ecore_time_unix_get().
Returns:
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).

References ecore_time_unix_get().

Referenced by ecore_thread_global_data_wait(), ecore_timer_add(), and ecore_timer_pending_get().

EAPI double ecore_time_unix_get ( void   ) 

Retrieves the current UNIX time as a floating point value in seconds.

See also:
ecore_time_get().
ecore_loop_time_get().
Returns:
The number of seconds since 12.00AM 1st January 1970.

Referenced by ecore_time_get().

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:
in The interval in seconds.
func The given function. If func returns 1, the timer is rescheduled for the next interval in.
data Data 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.

References ecore_time_get().

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

EAPI void * ecore_timer_del ( Ecore_Timer *  timer  ) 

Delete the specified timer from the timer list.

Parameters:
timer The 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).

Referenced by ecore_animator_frametime_set(), ecore_con_url_shutdown(), 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:
timer The timer to change.
add The dalay to add to the next iteration.

Referenced by ecore_animator_add().

EAPI double ecore_timer_interval_get ( Ecore_Timer *  timer  ) 

Get the interval the timer ticks on.

Parameters:
timer The timer to retrieve the interval from
Returns:
The interval on success. -1 on failure.
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:
timer The timer to change.
in The interval in seconds.
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:
in The interval in seconds from current loop time.
func The given function. If func returns 1, the timer is rescheduled for the next interval in.
data Data 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.

References ecore_loop_time_get().

Referenced by ecore_animator_add().

EAPI double ecore_timer_pending_get ( Ecore_Timer *  timer  ) 

Get the pending time regarding a timer.

Parameters:
timer The timer to learn from.

References ecore_time_get().

EAPI double ecore_timer_precision_get ( void   ) 

Retrieves the current precision used by timer infrastructure.

See also:
ecore_timer_precision_set()
EAPI void ecore_timer_precision_set ( double  value  ) 

Sets the precision to be used by timer infrastructure.

When system calculates time to expire the next timer we'll be able to delay the timer by the given amount so more timers will fit in the same dispatch, waking up the system less often and thus being able to save power.

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.
Parameters:
value allowed introduced timeout delay, in seconds.