1# Timers
2
3LVGL has a built-in timer system. You can register a function to have it be called periodically. The timers are handled and called in `lv_timer_handler()`, which needs to be called every few milliseconds.
4See [Porting](/porting/timer-handler) for more information.
5
6Timers are non-preemptive, which means a timer cannot interrupt another timer. Therefore, you can call any LVGL related function in a timer.
7
8
9## Create a timer
10To create a new timer, use `lv_timer_create(timer_cb, period_ms, user_data)`. It will create an `lv_timer_t *` variable, which can be used later to modify the parameters of the timer.
11`lv_timer_create_basic()` can also be used. This allows you to create a new timer without specifying any parameters.
12
13A timer callback should have a `void (*lv_timer_cb_t)(lv_timer_t *);` prototype.
14
15For example:
16```c
17void my_timer(lv_timer_t * timer)
18{
19  /*Use the user_data*/
20  uint32_t * user_data = timer->user_data;
21  printf("my_timer called with user data: %d\n", *user_data);
22
23  /*Do something with LVGL*/
24  if(something_happened) {
25    something_happened = false;
26    lv_btn_create(lv_scr_act(), NULL);
27  }
28}
29
30...
31
32static uint32_t user_data = 10;
33lv_timer_t * timer = lv_timer_create(my_timer, 500,  &user_data);
34
35```
36
37## Ready and Reset
38
39`lv_timer_ready(timer)` makes a timer run on the next call of `lv_timer_handler()`.
40
41`lv_timer_reset(timer)` resets the period of a timer. It will be called again after the defined period of milliseconds has elapsed.
42
43
44## Set parameters
45You can modify some timer parameters later:
46- `lv_timer_set_cb(timer, new_cb)`
47- `lv_timer_set_period(timer, new_period)`
48
49## Repeat count
50
51You can make a timer repeat only a given number of times with `lv_timer_set_repeat_count(timer, count)`. The timer will automatically be deleted after it's called the defined number of times. Set the count to `-1` to repeat indefinitely.
52
53
54## Measure idle time
55
56You can get the idle percentage time of `lv_timer_handler` with `lv_timer_get_idle()`. Note that, it doesn't measure the idle time of the overall system, only `lv_timer_handler`.
57It can be misleading if you use an operating system and call `lv_timer_handler` in a timer, as it won't actually measure the time the OS spends in an idle thread.
58
59## Asynchronous calls
60
61In some cases, you can't perform an action immediately. For example, you can't delete an object because something else is still using it, or you don't want to block the execution now.
62For these cases, `lv_async_call(my_function, data_p)` can be used to call `my_function` on the next invocation of `lv_timer_handler`. `data_p` will be passed to the function when it's called.
63Note that only the data pointer is saved, so you need to ensure that the variable will be "alive" while the function is called. It can be *static*, global or dynamically allocated data.
64If you want to cancel an asynchronous call, call `lv_async_call_cancel(my_function, data_p)`, which will clear all asynchronous calls matching `my_function` and `data_p`.
65
66For example:
67```c
68void my_screen_clean_up(void * scr)
69{
70  /*Free some resources related to `scr`*/
71
72  /*Finally delete the screen*/
73  lv_obj_del(scr);
74}
75
76...
77
78/*Do something with the object on the current screen*/
79
80/*Delete screen on next call of `lv_timer_handler`, not right now.*/
81lv_async_call(my_screen_clean_up, lv_scr_act());
82
83/*The screen is still valid so you can do other things with it*/
84
85```
86
87If you just want to delete an object and don't need to clean anything up in `my_screen_cleanup` you could just use `lv_obj_del_async` which will delete the object on the next call to `lv_timer_handler`.
88
89## API
90
91```eval_rst
92
93.. doxygenfile:: lv_timer.h
94  :project: lvgl
95
96.. doxygenfile:: lv_async.h
97  :project: lvgl
98
99```
100