0
# Schedulers
1

2
Control timing and concurrency of observable operations with different scheduling strategies.
3

4
## Capabilities
5

6
### Scheduler Types
7

8
Built-in schedulers for different execution contexts.
9

10
```javascript { .api }
11
/**
12
 * Immediate scheduler - executes work synchronously
13
 * @type {Scheduler}
14
 */
15
Rx.Scheduler.immediate;
16

17
/**
18
 * Current thread scheduler - executes work on current thread with trampoline
19
 * @type {Scheduler}
20
 */
21
Rx.Scheduler.currentThread;
22

23
/**
24
 * Default scheduler - executes work asynchronously (alias for async)
25
 * @type {Scheduler}
26
 */
27
Rx.Scheduler.default;
28

29
/**
30
 * Async scheduler - executes work asynchronously using setTimeout
31
 * @type {Scheduler}
32
 */
33
Rx.Scheduler.async;
34
```
35

36
### Scheduler Static Methods
37

38
Utility methods for working with schedulers.
39

40
```javascript { .api }
41
/**
42
 * Checks if an object is a scheduler
43
 * @param {*} obj - Object to test
44
 * @returns {boolean} True if object is a scheduler
45
 */
46
Rx.Scheduler.isScheduler = function(obj);
47

48
/**
49
 * Gets the current time
50
 * @returns {number} Current time in milliseconds
51
 */
52
Rx.Scheduler.now = function();
53

54
/**
55
 * Normalizes a time span value
56
 * @param {number} timeSpan - Time span to normalize
57
 * @returns {number} Normalized time span
58
 */
59
Rx.Scheduler.normalize = function(timeSpan);
60
```
61

62
### Scheduler Instance Methods
63

64
Core scheduling methods available on all scheduler instances.
65

66
```javascript { .api }
67
/**
68
 * Schedules work to be executed immediately
69
 * @param {*} state - Initial state passed to action
70
 * @param {function} action - Action to execute
71
 * @returns {Disposable} Disposable to cancel the scheduled work
72
 */
73
scheduler.schedule = function(state, action);
74

75
/**
76
 * Schedules work to be executed after a delay
77
 * @param {*} state - Initial state passed to action
78
 * @param {number} dueTime - Delay in milliseconds
79
 * @param {function} action - Action to execute
80
 * @returns {Disposable} Disposable to cancel the scheduled work
81
 */
82
scheduler.scheduleFuture = function(state, dueTime, action);
83

84
/**
85
 * Schedules recursive work
86
 * @param {*} state - Initial state passed to action
87
 * @param {function} action - Recursive action that can reschedule itself
88
 * @returns {Disposable} Disposable to cancel the scheduled work
89
 */
90
scheduler.scheduleRecursive = function(state, action);
91

92
/**
93
 * Schedules periodic work
94
 * @param {*} state - Initial state passed to action
95
 * @param {number} period - Period in milliseconds between executions
96
 * @param {function} action - Action to execute periodically
97
 * @returns {Disposable} Disposable to cancel the periodic work
98
 */
99
scheduler.schedulePeriodic = function(state, period, action);
100

101
/**
102
 * Gets the current time according to this scheduler
103
 * @returns {number} Current time in milliseconds
104
 */
105
scheduler.now = function();
106
```
107

108
### Using Schedulers with Observables
109

110
Schedulers can be specified for various operations:
111

112
```javascript { .api }
113
/**
114
 * Specifies the scheduler to use for subscription
115
 * @param {Scheduler} scheduler - Scheduler to use for subscription
116
 * @returns {Observable} Observable with specified subscription scheduler
117
 */
118
observable.subscribeOn = function(scheduler);
119

120
/**
121
 * Specifies the scheduler to use for observation
122
 * @param {Scheduler} scheduler - Scheduler to use for observation
123
 * @returns {Observable} Observable with specified observation scheduler
124
 */
125
observable.observeOn = function(scheduler);
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
// Execute subscription on current thread scheduler
132
var source = Rx.Observable.range(1, 5)
133
  .subscribeOn(Rx.Scheduler.currentThread);
134

135
// Observe results on async scheduler
136
var asyncSource = source.observeOn(Rx.Scheduler.async);
137

138
// Create observable with specific scheduler
139
var timerSource = Rx.Observable.timer(1000, Rx.Scheduler.async);
140
```
141

142
### Action Function Format
143

144
Action functions receive specific parameters for scheduling:
145

146
```javascript { .api }
147
/**
148
 * Action function for schedule method
149
 * @param {Scheduler} scheduler - The scheduler instance
150
 * @param {*} state - The state passed to schedule
151
 * @returns {Disposable} Optional disposable to cancel work
152
 */
153
function scheduleAction(scheduler, state) {
154
  // Perform work with state
155
  return optionalDisposable;
156
}
157

158
/**
159
 * Recursive action function for scheduleRecursive method
160
 * @param {*} state - The current state
161
 * @param {function} recurse - Function to call for recursion
162
 * @returns {Disposable} Optional disposable to cancel work
163
 */
164
function recursiveAction(state, recurse) {
165
  // Perform work with state
166
  if (shouldContinue) {
167
    recurse(newState); // Schedule next iteration
168
  }
169
  return optionalDisposable;
170
}
171

172
/**
173
 * Periodic action function for schedulePeriodic method
174
 * @param {*} state - The current state
175
 * @returns {*} New state for next iteration
176
 */
177
function periodicAction(state) {
178
  // Perform periodic work
179
  return newState; // State for next execution
180
}
181
```
182

183
### Custom Schedulers
184

185
Creating custom schedulers for specialized timing needs:
186

187
```javascript { .api }
188
/**
189
 * Base scheduler constructor for custom schedulers
190
 * @param {function} now - Function that returns current time
191
 * @param {function} schedule - Function to schedule immediate work
192
 * @param {function} scheduleFuture - Function to schedule delayed work
193
 * @param {function} scheduleRecursive - Function to schedule recursive work
194
 * @constructor
195
 */
196
function CustomScheduler(now, schedule, scheduleFuture, scheduleRecursive) {
197
  this.now = now;
198
  this.schedule = schedule;
199
  this.scheduleFuture = scheduleFuture;
200
  this.scheduleRecursive = scheduleRecursive;
201
}
202
```
203

204
### Scheduler Behavior Comparison
205

206
| Scheduler | Execution Context | Use Case |
207
|-----------|------------------|----------|
208
| `immediate` | Synchronous | Testing, immediate execution |
209
| `currentThread` | Current thread with trampoline | Avoiding stack overflow |
210
| `default`/`async` | Asynchronous with setTimeout | General async operations |
211
212
**Usage Example:**
213

214
```javascript
215
// Compare scheduler behaviors
216
var immediate = Rx.Observable.return(1, Rx.Scheduler.immediate);
217
var async = Rx.Observable.return(1, Rx.Scheduler.async);
218

219
console.log('Before subscribe');
220
immediate.subscribe(function(x) { console.log('Immediate: ' + x); });
221
async.subscribe(function(x) { console.log('Async: ' + x); });
222
console.log('After subscribe');
223

224
// Output:
225
// Before subscribe
226
// Immediate: 1
227
// After subscribe
228
// Async: 1
229
```