0
# Core Scheduling
1

2
Essential functions for scheduling and managing tasks with priority-based execution in the scheduler library.
3

4
## Capabilities
5

6
### Schedule Callback
7

8
Schedules a task to be executed based on priority level with optional delay.
9

10
```javascript { .api }
11
/**
12
 * Schedule a callback to be executed based on priority level
13
 * @param priorityLevel - Priority level (1-5) determining execution order and timeout
14
 * @param callback - Function to execute, can return continuation function
15
 * @param options - Optional configuration object
16
 * @returns Task object that can be used to cancel the scheduled callback
17
 */
18
function unstable_scheduleCallback(
19
  priorityLevel: PriorityLevel,
20
  callback: (didTimeout: boolean) => void | ((didTimeout: boolean) => void | null),
21
  options?: { delay: number }
22
): Task;
23
```
24

25
The callback function receives a `didTimeout` parameter indicating whether the task exceeded its priority-based timeout. Tasks can return a continuation function to spread work across multiple time slices.
26

27
**Usage Examples:**
28

29
```javascript
30
import { 
31
  unstable_scheduleCallback, 
32
  unstable_NormalPriority,
33
  unstable_UserBlockingPriority 
34
} from "scheduler";
35

36
// Simple task
37
const task = unstable_scheduleCallback(unstable_NormalPriority, (didTimeout) => {
38
  console.log("Task executed, timed out:", didTimeout);
39
});
40

41
// Task with delay
42
const delayedTask = unstable_scheduleCallback(
43
  unstable_NormalPriority,
44
  (didTimeout) => {
45
    console.log("Delayed task executed");
46
  },
47
  { delay: 1000 } // Delay execution by 1 second
48
);
49

50
// Task with continuation (time slicing)
51
let workItems = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
52
const processWork = unstable_scheduleCallback(unstable_NormalPriority, function work(didTimeout) {
53
  // Process some work items
54
  const itemsToProcess = Math.min(3, workItems.length);
55
  for (let i = 0; i < itemsToProcess; i++) {
56
    const item = workItems.shift();
57
    console.log("Processing item:", item);
58
  }
59
  
60
  // If more work remains, return continuation
61
  if (workItems.length > 0) {
62
    return work; // Continue in next time slice
63
  }
64
  // Return null/undefined when work is complete
65
});
66
```
67

68
### Cancel Callback
69

70
Cancels a previously scheduled task.
71

72
```javascript { .api }
73
/**
74
 * Cancel a previously scheduled callback
75
 * @param task - Task object returned by unstable_scheduleCallback
76
 */
77
function unstable_cancelCallback(task: Task): void;
78
```
79

80
**Usage Examples:**
81

82
```javascript
83
import { unstable_scheduleCallback, unstable_cancelCallback, unstable_NormalPriority } from "scheduler";
84

85
const task = unstable_scheduleCallback(unstable_NormalPriority, () => {
86
  console.log("This will not execute");
87
});
88

89
// Cancel the task before it executes
90
unstable_cancelCallback(task);
91

92
// Conditional cancellation
93
const conditionalTask = unstable_scheduleCallback(unstable_NormalPriority, () => {
94
  console.log("Conditional task executed");
95
});
96

97
if (shouldCancel) {
98
  unstable_cancelCallback(conditionalTask);
99
}
100
```
101

102
### Get Current Priority Level
103

104
Returns the current priority level of the scheduler.
105

106
```javascript { .api }
107
/**
108
 * Get the current priority level
109
 * @returns Current priority level (1-5)
110
 */
111
function unstable_getCurrentPriorityLevel(): PriorityLevel;
112
```
113

114
**Usage Examples:**
115

116
```javascript
117
import { 
118
  unstable_getCurrentPriorityLevel,
119
  unstable_runWithPriority,
120
  unstable_UserBlockingPriority 
121
} from "scheduler";
122

123
// Check current priority
124
const currentPriority = unstable_getCurrentPriorityLevel();
125
console.log("Current priority:", currentPriority); // 3 (Normal priority)
126

127
// Priority changes within runWithPriority
128
unstable_runWithPriority(unstable_UserBlockingPriority, () => {
129
  const priority = unstable_getCurrentPriorityLevel();
130
  console.log("Priority inside:", priority); // 2 (UserBlocking priority)
131
});
132
```
133

134
## Priority Levels and Timeouts
135

136
Each priority level has different timeout behavior:
137

138
- **Immediate Priority (1)**: Times out immediately (-1ms)
139
- **UserBlocking Priority (2)**: Times out after 250ms  
140
- **Normal Priority (3)**: Times out after 5000ms
141
- **Low Priority (4)**: Times out after 10000ms
142
- **Idle Priority (5)**: Never times out
143

144
Tasks are executed in priority order, with higher priority (lower number) tasks executing first. When a task times out, the `didTimeout` parameter in the callback will be `true`.
145

146
## Task Object
147

148
```javascript { .api }
149
interface Task {
150
  /** Unique identifier for the task */
151
  id: number;
152
  /** Callback function or null if cancelled */
153
  callback: ((didTimeout: boolean) => void | ((didTimeout: boolean) => void | null)) | null;
154
  /** Priority level of the task */
155
  priorityLevel: PriorityLevel;
156
  /** When the task should start executing (milliseconds) */
157
  startTime: number;
158
  /** When the task expires based on priority timeout */
159
  expirationTime: number;
160
  /** Index used for heap sorting (either startTime or expirationTime) */
161
  sortIndex: number;
162
  /** Whether task is currently in the queue (profiling builds only) */
163
  isQueued?: boolean;
164
}
165
```