Ecore Timer functions

Macros | Typedefs | Functions
Ecore Timer functions
Ecore » Ecore main loop

Ecore provides very flexible timer functionality. More...

## Typedefs
typedef Eo | Ecore_Timer
| A handle for timers.

## Functions
double | ecore_timer_precision_get (void)
| Retrieves the current precision used by timer infrastructure. More...
void | ecore_timer_precision_set (double precision)
| Sets the precision to be used by timer infrastructure. More...
char * | ecore_timer_dump (void)
| This function returns a human readable text-based log for Ecore_Timer events. More...
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. More...
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. More...
void * | ecore_timer_del (Ecore_Timer *timer)
| Deletes the specified timer from the timer list. More...
void | ecore_timer_freeze (Ecore_Timer *timer)
| Pauses a running timer. More...
Eina_Bool | ecore_timer_freeze_get (Ecore_Timer *timer)
| Return whether the timer is freezing. More...
void | ecore_timer_thaw (Ecore_Timer *timer)
| Resumes a frozen (paused) timer. More...
void | ecore_timer_interval_set (Efl_Loop_Timer *obj, double in)
| Interval the timer ticks on. More...
double | ecore_timer_interval_get (const Efl_Loop_Timer *obj)
| Interval the timer ticks on. More...
double | ecore_timer_pending_get (const Efl_Loop_Timer *obj)
| Pending time regarding a timer. More...
void | ecore_timer_reset (Efl_Loop_Timer *obj)
| Resets a timer to its full interval. More...
void | ecore_timer_loop_reset (Efl_Loop_Timer *obj)
| This effectively resets a timer but based on the time when this iteration of the main loop started. More...
void | ecore_timer_delay (Efl_Loop_Timer *obj, double add)
| Adds a delay to the next occurrence of a timer. 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 ECORE_CALLBACK_RENEW;
}
ecore_timer_add(interval_in_seconds, my_func, data_given_to_function);
ECORE_CALLBACK_RENEW
#define ECORE_CALLBACK_RENEW
Return value to keep a callback.
Definition: Ecore_Common.h:153
ecore_timer_add
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.
Definition: ecore_timer.c:189
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition: eina_types.h:527

Note
  If the function was to be executed only once simply return `ECORE_CALLBACK_CANCEL` instead.

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

- ecore timers - Scheduled events

## Function Documentation

## ◆ ecore_timer_precision_get()

double ecore_timer_precision_get | ( | void |  | ) |

Retrieves the current precision used by timer infrastructure.

Returns
  Current precision.

See also
  ecore_timer_precision_set()

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ◆ ecore_timer_precision_set()

void ecore_timer_precision_set | ( | double | precision | ) |

Sets the precision to be used by timer infrastructure.

Parameters

  precision | Allowed 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.

References EINA_MAIN_LOOP_CHECK_RETURN.

## ◆ ecore_timer_dump()

char* ecore_timer_dump | ( | void |  | ) |

This function returns a human readable text-based log for Ecore_Timer events.

Returns
  A heap allocated string, or NULL. It MUST be freed manually by the caller using `free`.

It only contains an useful implementation if EFL is built in debug build profile, but it's safe to call it for any build profile.

## ◆ ecore_timer_add()

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.

Examples
  banshee.c, client.c, complex-types-client-eina-value.c, complex-types-server.c, complex-types.c, 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, ecore_timer_example.c, eina_tiler_01.c, evas-events.c, inwin_example.c, map_example_01.c, map_example_02.c, map_example_03.c, prefs_example_01.c, prefs_example_02.c, progressbar_example.c, server.c, test_growing_balls.c, and test_rotating_forever.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, and ERR.

Referenced by elm_transit_go_in().

## ◆ ecore_timer_loop_add()

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 EINA_MAIN_LOOP_CHECK_RETURN_VAL, and ERR.

## ◆ ecore_timer_del()

void* ecore_timer_del | ( | Ecore_Timer * | timer | ) |

Deletes 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).

Examples
  client.c, complex-types-server.c, ecore_fd_handler_example.c, ecore_idler_example.c, ecore_timer_example.c, evas-events.c, progressbar_example.c, test_growing_balls.c, and test_rotating_forever.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, EINA_TRUE, and ERR.

Referenced by ecore_avahi_del(), ecore_wl2_display_destroy(), ecore_wl_window_free(), elm_entry_file_set(), elm_transit_go(), and elm_transit_go_in().

## ◆ ecore_timer_freeze()

void ecore_timer_freeze | ( | Ecore_Timer * | timer | ) |

Pauses a running timer.

Parameters

  timer | The timer to be paused.

Remarks
  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.

## ◆ ecore_timer_freeze_get()

Eina_Bool ecore_timer_freeze_get | ( | Ecore_Timer * | timer | ) |

Return whether the timer is freezing.

Returns
  True if the timer object is freezed, false otherwise.

See also
  ecore_timer_freeze(), ecore_timer_thaw()

References EINA_FALSE, and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ◆ ecore_timer_thaw()

void ecore_timer_thaw | ( | Ecore_Timer * | timer | ) |

Resumes a frozen (paused) timer.

Remarks
  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().

Parameters

  [in] | timer | The timer to be resumed.

See also
  ecore_timer_freeze()

Examples
  ecore_timer_example.c.

## ◆ ecore_timer_interval_set()

void ecore_timer_interval_set | ( | Efl_Loop_Timer * | obj,
|  | double | in
| ) |  |

Interval the timer ticks on.

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

Parameters

  [in] | obj | The object.
  [in] | in | The new interval in seconds

Referenced by eio_monitoring_interval_set().

## ◆ ecore_timer_interval_get()

double ecore_timer_interval_get | ( | const Efl_Loop_Timer * | obj | ) |

Interval the timer ticks on.

Parameters

  [in] | obj | The object.

Returns
  The new interval in seconds

## ◆ ecore_timer_pending_get()

double ecore_timer_pending_get | ( | const Efl_Loop_Timer * | obj | ) |

Pending time regarding a timer.

Parameters

  [in] | obj | The object.

Returns
  Pending time

## ◆ ecore_timer_reset()

void ecore_timer_reset | ( | Efl_Loop_Timer * | obj | ) |

Resets a timer to its full interval.

This effectively makes the timer start ticking off from zero now.

This is equal to delaying the timer by the already passed time, since the timer started ticking

Parameters

  [in] | obj | The object.

Since
  1.2

## ◆ ecore_timer_loop_reset()

void ecore_timer_loop_reset | ( | Efl_Loop_Timer * | obj | ) |

This effectively resets a timer but based on the time when this iteration of the main loop started.

Since
  1.18

## ◆ ecore_timer_delay()

void ecore_timer_delay | ( | Efl_Loop_Timer * | obj,
|  | double | add
| ) |  |

Adds a delay to the next occurrence of a timer.

This doesn't affect the timer interval.

Parameters

  [in] | obj | The object.
  [in] | add | The amount of time by which to delay the timer in seconds