1# Timer
2
3The Timer module provides basic timer capabilities. You can use the APIs of this module to execute functions at the specified time.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> When a timer is used on the UI, the timer triggering mechanism is controlled by the underlying principles of the UI. As such, when the UI transitions to the background, the timer will be frozen.
10
11## setTimeout
12
13setTimeout(handler: Function | string, delay?: number, ...arguments: any[]): number
14
15Sets a timer for the system to call a function after the timer goes off.
16
17The timer is automatically deleted after the callback is executed, and can be manually deleted by calling the **clearTimeout** API.
18
19**Atomic service API**: This API can be used in atomic services since API version 11.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23**Parameters**
24
25| Name| Type| Mandatory| Description|
26| -------- | -------- | -------- | -------- |
27| handler | Function \| string | Yes| Function to be called after the timer goes off. If the type is string, error information is printed and no other processing is performed.|
28| delay | number | No| Number of milliseconds delayed before the execution. It is recommended that an integer be passed in. A decimal will be rounded down.<br>If this parameter is not specified, the default value 0 is used, indicating that the function is executed immediately (in the next event loop).<br>NOTE<br>1. In either case, the actual delay may be longer than expected.<br>2. If a value less than 1 is passed, the default value 0 is used.|
29| ...arguments | any[] | No| Additional parameters to pass to the handler after the timer goes off.|
30
31**Return value**
32
33| Type| Description|
34| -------- | -------- |
35| number | ID of the timer. The timer ID is shared by processes and is an integer starting from 0 in ascending order.|
36
37**Example 1: carrying no parameters**
38
39  ```ts
40  setTimeout(() => {
41    console.info('delay 1s');
42  }, 1000);
43  ```
44
45**Example 2: carrying parameters**
46
47  ```ts
48  function myFunction(param1: string, param2: string) {
49    console.info(param1, param2);
50  }
51  setTimeout(myFunction, 1000, 'Hello', 'World');
52  ```
53
54## clearTimeout
55
56clearTimeout(timeoutID?: number): void
57
58Cancels a timer set via **setTimeout()**.
59
60The timer object is stored in the thread that creates the timer and must be deleted in that thread.
61
62**Atomic service API**: This API can be used in atomic services since API version 11.
63
64**System capability**: SystemCapability.ArkUI.ArkUI.Full
65
66**Parameters**
67
68| Name| Type| Mandatory| Description|
69| -------- | -------- | -------- | -------- |
70| timeoutID | number | No| ID of the timer to cancel, which is returned by **setTimeout()** If this parameter is omitted, no timer is canceled.|
71
72**Example**
73
74  ```js
75  let timeoutID = setTimeout(() => {
76    console.log('do after 1s delay.');
77  }, 1000);
78  clearTimeout(timeoutID);
79  ```
80
81
82## setInterval
83
84setInterval(handler: Function | string, delay: number, ...arguments: any[]): number
85
86Sets a repeating timer for the system to repeatedly call a function at a fixed interval.
87
88The timer can only be manually deleted by calling the **clearInterval** API.
89
90**Atomic service API**: This API can be used in atomic services since API version 11.
91
92**System capability**: SystemCapability.ArkUI.ArkUI.Full
93
94**Parameters**
95
96| Name| Type| Mandatory| Description|
97| -------- | -------- | -------- | -------- |
98| handler | Function \| string | Yes| Function to be called repeatedly. If the type is string, error information is printed and no other processing is performed.|
99| delay | number | Yes| Number of milliseconds delayed before the execution.|
100| ...arguments | any[] | No| Additional parameters to pass to the handler after the timer goes off.|
101
102**Return value**
103
104| Type| Description|
105| -------- | -------- |
106| number | ID of the timer. The timer ID is shared by processes and is an integer starting from 0 in ascending order.|
107
108**Example**
109
110  ```js
111  setInterval(() => {
112    console.log('do every 1s.');
113  }, 1000);
114  ```
115
116
117## clearInterval
118
119clearInterval(intervalID?: number): void
120
121Cancels the repeating timer set via **setInterval()**.
122
123The timer object is stored in the thread that creates the timer and must be deleted in that thread.
124
125**Atomic service API**: This API can be used in atomic services since API version 11.
126
127**System capability**: SystemCapability.ArkUI.ArkUI.Full
128
129**Parameters**
130
131| Name| Type| Mandatory| Description|
132| -------- | -------- | -------- | -------- |
133| intervalID | number | No| ID of the repeating timer to cancel, which is returned by **setInterval()**. If this parameter is omitted, no timer is canceled.|
134
135**Example**
136
137  ```js
138  let intervalID = setInterval(() => {
139    console.log('do every 1s.');
140  }, 1000);
141  clearInterval(intervalID);
142  ```
143
144## Other Description
145### Timeout Delay
146If the page is engaged in other operations, the timeout may be later than expected. The function or code snippet passed to **setTimeout** is executed in the next time period. Example:
147  ```ts
148  function foo() {
149    console.info('OH test foo is called')
150  }
151  setTimeout(foo, 0);
152  console.info('After OH test setTimeout')
153
154  // output
155  After OH test setTimeout
156  OH test foo is called
157  ```
158Although a 0 ms delay is specified for **setTimeout**, the task is not executed immediately. Instead, it is placed in the queue and waits for the next event loop. The functions in the queue can be executed only after the ongoing code execution is complete. As such, the final execution sequence may be different from that expected.
159
160### Maximum Delay
161The timer internally stores the delay as a 32-bit signed integer. If the delay is greater than 2147483647 ms (about 24.8 days), overflow occurs, and the timer is executed immediately.
162
163### Timer Suspension
164The timer triggering mechanism is controlled by the bottom-layer task scheduling. If an application is switched to the background, timers that have reached their set time will not be triggered. Once the application is restored to the foreground, the expired timers will be triggered in sequence. You can run the **trace** command to check whether a process is still scheduled. If the process is not scheduled, the timer is suspended.
165
166### Timer ID
167The **setTimeout()** and **setInterval()** APIs shares an ID pool, which means that, in theory, **clearTimeout()** and **clearInterval()** can be interchanged. However, to maintain clarity in coding practices, it is advised to avoid such intermixing.
168