# Timer (lv_timer) (/main-modules/timer)



LVGL has a built-in Timer system. You can register a function to have it
be called periodically. The Timers are handled and called in
<ApiLink name="lv_timer_handler" />, which needs to be called every few milliseconds.
See [Timer Handler](/integration/overview) for more information.

By default, LVGL itself uses Timers to:

* refresh each display --- during the creation of each Display, a Timer is
  created for that Display.  That Timer refreshes the display based on the configured
  value of <ApiLink name="LV_DEF_REFR_PERIOD" />, and also sends all display-related events,
  like <ApiLink name="LV_EVENT_REFR_START" />, <ApiLink name="LV_EVENT_REFR_READY" />,
  etc.
* read input devices --- during the creation of each [Input devices (lv\_indev)](/main-modules/indev), a Timer is
  created for that Input Device based on the configured value of
  <ApiLink name="LV_DEF_REFR_PERIOD" />.  That Timer causes that input device to be read and
  also sends all input-device-related events, like <ApiLink name="LV_EVENT_CLICKED" />,
  <ApiLink name="LV_EVENT_PRESSED" />, etc.
* update system-monitor values --- if <ApiLink name="LV_USE_SYSMON" /> is set to `1` in
  `lv_conf.h`, one or more timers are created to periodically compute and
  monitor system performance statistics and LVGL's memory usage.

Timers are non-preemptive, which means a Timer cannot interrupt another
Timer. Therefore, you can call any LVGL-related function in a Timer.

Creating a Timer [#creating-a-timer]

To create a new Timer, use
<ApiLink name="lv_timer_create" display="lv_timer_create(timer_cb, period_ms, user_data)" />. It returns an
<ApiLink name="lv_timer_t" /> `*` which can be used later to modify the
parameters of the Timer, pause it, or delete it when it is no longer needed.
<ApiLink name="lv_timer_create_basic" /> can also be used to create a new Timer without
specifying any parameters.

A Timer callback should have this prototype:  `void (*lv_timer_cb_t)(lv_timer_t *)`.

For example:

```c title=" " lineNumbers=1
void my_timer(lv_timer_t * timer)
{
  /* Use the user_data */
  uint32_t * user_data = lv_timer_get_user_data(timer);
  printf("my_timer called with user data: %d\n", *user_data);

  /* Do something with LVGL */
  if(something_happened) {
    something_happened = false;
    lv_button_create(lv_screen_active());
  }
}

...

static uint32_t user_data = 10;
lv_timer_t * timer = lv_timer_create(my_timer, 500,  &user_data);
```

Ready and Reset [#ready-and-reset]

<ApiLink name="lv_timer_ready" display="lv_timer_ready(timer)" /> makes a Timer run on the next call of
<ApiLink name="lv_timer_handler" />.

<ApiLink name="lv_timer_reset" display="lv_timer_reset(timer)" /> resets the period of a Timer. It will be
called again after its currently-set period (in milliseconds) has elapsed.

Setting Parameters [#setting-parameters]

You can modify these Timer parameters at any time during its life:

* <ApiLink name="lv_timer_set_cb" display="lv_timer_set_cb(timer, new_cb)" />
* <ApiLink name="lv_timer_set_period" display="lv_timer_set_period(timer, new_period_ms)" />
* <ApiLink name="lv_timer_set_user_data" display="lv_timer_set_user_data(timer, user_data)" />

Repeat Count [#repeat-count]

When a Timer is created, its repeat-count is set to `-1` to cause it to repeat
indefinitely.  You can make a Timer repeat only a given number of times with
<ApiLink name="lv_timer_set_repeat_count" display="lv_timer_set_repeat_count(timer, count)" />.  By default, once the Timer has
run `count` times, it will be automatically deleted.

You can use <ApiLink name="lv_timer_set_auto_delete" display="lv_timer_set_auto_delete(timer, false)" /> if you want the timer
to instead be paused after it has run `count` times.  This can be handy if you
reuse that timer repeatedly and want to avoid the CPU and <ApiLink name="lv_malloc" />
overhead of repeatedly creating and deleting a timer.  If you use this option, you
will need to set its repeat count (to either `-1` or a positive repeat count, since
it will have decremented to `0`) and [resume](/main-modules/timer) it to
make it active again.

Pause and Resume [#pause-and-resume]

<ApiLink name="lv_timer_pause" display="lv_timer_pause(timer)" /> pauses the specified Timer.

<ApiLink name="lv_timer_resume" display="lv_timer_resume(timer)" /> resumes the specified Timer.

Measuring Idle Time [#measuring-idle-time]

You can get the idle percentage time of <ApiLink name="lv_timer_handler" /> with
<ApiLink name="lv_timer_get_idle" />. Note that it does not measure the idle time of
the overall system, only of <ApiLink name="lv_timer_handler" />.  This can be misleading if
you are using an operating system and DMA and/or GPU are used during rendering, as it
does not actually measure the time the OS spends in an idle thread.

If you are using an OS and wish to get the time the CPU is spending in an idle
thread, one way of doing so is configuring <ApiLink name="LV_USE_SYSMON" /> and
<ApiLink name="LV_USE_PERF_MONITOR" /> to `1` in `lv_conf.h` (if they are not already),
and setting the macro <ApiLink name="LV_SYSMON_GET_IDLE" /> to the name of a function that
fetches the percent of CPU time spent in the OS's idle thread.  An example of such
a function is <ApiLink name="lv_os_get_idle_percent" /> in `lv_freertos.c`.  While the
configuration is set this way, some system performance statistics (including CPU
load) will appear on the display in a partially-transparent label whose location is
set by the <ApiLink name="LV_USE_PERF_MONITOR_POS" /> macro.

Enable and Disable [#enable-and-disable]

You can temporarily disable Timer handling with <ApiLink name="lv_timer_enable" display="lv_timer_enable(false)" />.
Be advised:  this also pauses handling of Timers that refresh Display(s) and read
from input devices, so don't forget to re-enable it with
<ApiLink name="lv_timer_enable" display="lv_timer_enable(true)" /> as soon as the need for the pause is over.

Timer Handler Resume Callback [#timer-handler-resume-callback]

When the Timer system has been disabled (causing <ApiLink name="lv_timer_handler" /> to
return early before it has processed any timers), if you want to take some action
when the Timer system is re-enabled again, set a resume callback using
<ApiLink name="lv_timer_handler_set_resume_cb" display="lv_timer_handler_set_resume_cb(cb, user_data)" />. The callback should have
this prototype:  `void (*lv_timer_handler_resume_cb_t)(void*)`.

Asynchronous calls [#asynchronous-calls]

There are several cases in which you may not want to perform an action immediately.
Some examples are:

* you cannot delete a Widget because something else is still using it,
* you don't want to block execution now, or
* you just want to defer the deletion for any reason

For these cases,
<ApiLink name="lv_async_call" display="lv_async_call(my_function, data_p)" /> can be used to call `my_function` on
the next invocation of <ApiLink name="lv_timer_handler" />.  As a side effect, this also
ensures it is called in a thread in which it is safe to make LVGL calls.
`data_p` will be passed to the function when it's called. Note that only the data's
pointer is saved, so whatever it is pointing to needs to remain valid until the
function is called, so it can point to `static`, global or dynamically allocated
data. If you want to cancel an asynchronous call, call
<ApiLink name="lv_async_call_cancel" display="lv_async_call_cancel(my_function, data_p)" />, which will remove all
asynchronous calls matching `my_function` and `data_p`.

Note that if <ApiLink name="lv_async_call" display="lv_async_call(my_function, data_p)" /> is called from a thread
other than the one that normally makes LVGL calls, you are still obligated to protect
the LVGL data structure using a MUTEX.

For example:

```c title=" " lineNumbers=1
void my_screen_clean_up(void * scr)
{
  /* Free some resources related to `scr`*/

  /* Finally delete the screen */
  lv_obj_delete(scr);
}

...

/* Do something with the Widget on the current screen */

/* Delete screen on next call of `lv_timer_handler`, not right now. */
lv_lock();
lv_async_call(my_screen_clean_up, lv_screen_active());
lv_unlock();

/* The screen is still valid so you can do other things with it */
```

If you just want to delete a Widget and don't need to clean anything up
in `my_screen_cleanup` you could just use <ApiLink name="lv_obj_delete_async" display="lv_obj_delete_async(widget)" /> which
will delete the Widget on the next call to <ApiLink name="lv_timer_handler" />.

API [#api]