0
# Scheduler
1
2
Scheduler is a cooperative scheduling library for browser environments that provides time-slicing capabilities for JavaScript applications. It implements a priority-based task scheduler that can yield control back to the browser's main thread to maintain responsiveness during intensive computations.
3
4
## Package Information
5
6
- **Package Name**: scheduler
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install scheduler`
10
11
## Core Imports
12
13
```javascript
14
import {
15
unstable_scheduleCallback,
16
unstable_cancelCallback,
17
unstable_runWithPriority,
18
unstable_ImmediatePriority,
19
unstable_UserBlockingPriority,
20
unstable_NormalPriority,
21
unstable_LowPriority,
22
unstable_IdlePriority
23
} from "scheduler";
24
```
25
26
For CommonJS:
27
28
```javascript
29
const {
30
unstable_scheduleCallback,
31
unstable_cancelCallback,
32
unstable_runWithPriority,
33
unstable_ImmediatePriority,
34
unstable_UserBlockingPriority,
35
unstable_NormalPriority,
36
unstable_LowPriority,
37
unstable_IdlePriority
38
} = require("scheduler");
39
```
40
41
For testing environments:
42
43
```javascript
44
import {
45
unstable_flushAll,
46
unstable_advanceTime,
47
reset
48
} from "scheduler/unstable_mock";
49
```
50
51
For PostTask API environments:
52
53
```javascript
54
import {
55
unstable_scheduleCallback,
56
unstable_cancelCallback,
57
unstable_runWithPriority,
58
unstable_getCurrentPriorityLevel,
59
unstable_next,
60
unstable_wrapCallback,
61
unstable_shouldYield,
62
unstable_requestPaint,
63
unstable_now,
64
unstable_forceFrameRate,
65
unstable_ImmediatePriority,
66
unstable_UserBlockingPriority,
67
unstable_NormalPriority,
68
unstable_LowPriority,
69
unstable_IdlePriority
70
} from "scheduler/unstable_post_task";
71
```
72
73
**Note**: The PostTask implementation uses the browser's native `scheduler.postTask()` API when available and provides a more limited feature set compared to the main scheduler implementation. Profiling is not available (`unstable_Profiling` is `null`).
74
75
For React Native environments (imports from `scheduler/index.native.js`):
76
77
```javascript
78
import {
79
unstable_scheduleCallback,
80
unstable_cancelCallback,
81
unstable_getCurrentPriorityLevel,
82
unstable_shouldYield,
83
unstable_requestPaint,
84
unstable_now,
85
unstable_ImmediatePriority,
86
unstable_UserBlockingPriority,
87
unstable_NormalPriority,
88
unstable_LowPriority,
89
unstable_IdlePriority
90
} from "scheduler";
91
```
92
93
**Note**: In React Native, the following functions throw "Not implemented" errors:
94
- `unstable_next()`
95
- `unstable_runWithPriority()`
96
- `unstable_wrapCallback()`
97
- `unstable_forceFrameRate()`
98
99
Additionally, `unstable_Profiling` is `null` in React Native environments.
100
101
## Basic Usage
102
103
```javascript
104
import {
105
unstable_scheduleCallback,
106
unstable_cancelCallback,
107
unstable_NormalPriority,
108
unstable_UserBlockingPriority
109
} from "scheduler";
110
111
// Schedule a task with normal priority
112
const task = unstable_scheduleCallback(unstable_NormalPriority, (didTimeout) => {
113
console.log("Task executed, timed out:", didTimeout);
114
// Return a continuation function if work is not complete
115
if (workRemaining) {
116
return (didTimeout) => {
117
// Continue work in next time slice
118
};
119
}
120
// Return null/undefined when work is complete
121
});
122
123
// Schedule high-priority task
124
const urgentTask = unstable_scheduleCallback(
125
unstable_UserBlockingPriority,
126
() => {
127
// Handle user interaction
128
updateUI();
129
}
130
);
131
132
// Cancel a task if needed
133
unstable_cancelCallback(task);
134
```
135
136
## Architecture
137
138
Scheduler is built around several key components:
139
140
- **Priority System**: Five priority levels from Immediate to Idle with different timeout behaviors
141
- **Task Queue**: Min-heap data structure for efficient priority-based scheduling
142
- **Time Slicing**: Yields control to browser after configurable time intervals (default 5ms)
143
- **Multiple Backends**: Different implementations for browser, React Native, testing, and PostTask API
144
- **Profiling Support**: Optional performance monitoring and event logging
145
146
## Capabilities
147
148
### Core Scheduling
149
150
Essential functions for scheduling and managing tasks with priority-based execution.
151
152
```javascript { .api }
153
function unstable_scheduleCallback(
154
priorityLevel: PriorityLevel,
155
callback: (didTimeout: boolean) => void | ((didTimeout: boolean) => void | null),
156
options?: { delay: number }
157
): Task;
158
159
function unstable_cancelCallback(task: Task): void;
160
161
function unstable_getCurrentPriorityLevel(): PriorityLevel;
162
```
163
164
[Core Scheduling](./core-scheduling.md)
165
166
### Priority Management
167
168
Functions for executing code with specific priority contexts and managing priority levels.
169
170
```javascript { .api }
171
function unstable_runWithPriority<T>(
172
priorityLevel: PriorityLevel,
173
eventHandler: () => T
174
): T;
175
176
function unstable_next<T>(eventHandler: () => T): T;
177
178
function unstable_wrapCallback<T>(callback: T): T;
179
```
180
181
[Priority Management](./priority-management.md)
182
183
### Timing and Yielding
184
185
Utilities for controlling when the scheduler yields control and managing frame rates.
186
187
```javascript { .api }
188
function unstable_shouldYield(): boolean;
189
function unstable_now(): number;
190
function unstable_requestPaint(): void;
191
function unstable_forceFrameRate(fps: number): void;
192
```
193
194
[Timing and Yielding](./timing-yielding.md)
195
196
### Testing Utilities
197
198
Mock scheduler functions specifically designed for testing environments and time control.
199
200
```javascript { .api }
201
function unstable_flushAll(): void;
202
function unstable_flushExpired(): void;
203
function unstable_advanceTime(ms: number): void;
204
function reset(): void;
205
```
206
207
[Testing Utilities](./testing-utilities.md)
208
209
### Profiling
210
211
Performance monitoring and event logging capabilities for development and debugging.
212
213
```javascript { .api }
214
const unstable_Profiling: {
215
startLoggingProfilingEvents(): void;
216
stopLoggingProfilingEvents(): ArrayBuffer | null;
217
} | null;
218
```
219
220
[Profiling](./profiling.md)
221
222
## Types
223
224
```javascript { .api }
225
type PriorityLevel = 0 | 1 | 2 | 3 | 4 | 5;
226
227
interface Task {
228
id: number;
229
callback: ((didTimeout: boolean) => void | ((didTimeout: boolean) => void | null)) | null;
230
priorityLevel: PriorityLevel;
231
startTime: number;
232
expirationTime: number;
233
sortIndex: number;
234
isQueued?: boolean;
235
}
236
237
type Callback = (didTimeout: boolean) => void | Callback | null;
238
```
239
240
## Priority Level Constants
241
242
```javascript { .api }
243
const unstable_ImmediatePriority: 1; // Times out immediately
244
const unstable_UserBlockingPriority: 2; // Times out in 250ms
245
const unstable_NormalPriority: 3; // Times out in 5000ms (default)
246
const unstable_LowPriority: 4; // Times out in 10000ms
247
const unstable_IdlePriority: 5; // Never times out
248
```