0
# Scheduler API
1

2
The Scheduler API provides a queue-based system for managing multiple workers and distributing OCR jobs across them for parallel processing. It's ideal for handling large batches of images or maintaining a pool of workers for high-throughput applications.
3

4
## Capabilities
5

6
### Scheduler Creation
7

8
Creates a new scheduler instance for managing worker pools and job queues.
9

10
```javascript { .api }
11
/**
12
 * Creates a new scheduler for managing multiple workers
13
 * @returns Scheduler instance
14
 */
15
function createScheduler(): Scheduler;
16
```
17

18
**Usage Examples:**
19

20
```javascript
21
import { createScheduler, createWorker } from 'tesseract.js';
22

23
const scheduler = createScheduler();
24
```
25

26
### Worker Management
27

28
Add workers to the scheduler pool for job distribution.
29

30
```javascript { .api }
31
/**
32
 * Adds a worker to the scheduler pool
33
 * @param worker - Worker instance to add
34
 * @returns Worker ID string for tracking
35
 */
36
addWorker(worker: Worker): string;
37

38
/**
39
 * Gets the current number of workers in the pool
40
 * @returns Number of workers
41
 */
42
getNumWorkers(): number;
43
```
44

45
**Usage Examples:**
46

47
```javascript
48
// Create and add workers to scheduler
49
const worker1 = await createWorker('eng');
50
const worker2 = await createWorker('eng');
51

52
const workerId1 = scheduler.addWorker(worker1);
53
const workerId2 = scheduler.addWorker(worker2);
54

55
console.log(scheduler.getNumWorkers()); // 2
56
```
57

58
### Job Queue Management
59

60
Queue jobs for execution across available workers.
61

62
```javascript { .api }
63
/**
64
 * Adds a recognition job to the queue
65
 * @param action - Job action type ('recognize' or 'detect')
66
 * @param args - Arguments for the specified action
67
 * @returns Promise resolving to job result
68
 */
69
addJob(action: 'recognize', ...args: Parameters<Worker['recognize']>): Promise<RecognizeResult>;
70
addJob(action: 'detect', ...args: Parameters<Worker['detect']>): Promise<DetectResult>;
71

72
/**
73
 * Gets the current job queue length
74
 * @returns Number of queued jobs
75
 */
76
getQueueLen(): number;
77
```
78

79
**Usage Examples:**
80

81
```javascript
82
// Queue recognition jobs
83
const results = await Promise.all([
84
  scheduler.addJob('recognize', 'image1.png'),
85
  scheduler.addJob('recognize', 'image2.png'),
86
  scheduler.addJob('recognize', 'image3.png')
87
]);
88

89
// Queue detection jobs
90
const detectionResult = await scheduler.addJob('detect', 'rotated-image.png');
91

92
// Check queue status
93
console.log(scheduler.getQueueLen()); // Number of pending jobs
94
```
95

96
### Advanced Job Queuing
97

98
Queue jobs with full parameter support for complex scenarios.
99

100
```javascript { .api }
101
// Recognition with options
102
const result = await scheduler.addJob('recognize', 'image.png', {
103
  rectangle: { left: 0, top: 0, width: 100, height: 100 }
104
}, {
105
  text: true,
106
  hocr: true
107
});
108

109
// Recognition with custom job ID
110
const resultWithId = await scheduler.addJob('recognize', 'image.png', {}, {}, 'custom-job-123');
111
```
112

113
### Scheduler Termination
114

115
Terminates all workers and clears the job queue.
116

117
```javascript { .api }
118
/**
119
 * Terminates all workers and clears the job queue
120
 * @returns Promise resolving when all workers are terminated
121
 */
122
terminate(): Promise<any>;
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
// Clean shutdown of scheduler and all workers
129
await scheduler.terminate();
130

131
// Use in finally block for guaranteed cleanup
132
try {
133
  // Process images
134
  const results = await Promise.all([
135
    scheduler.addJob('recognize', 'image1.png'),
136
    scheduler.addJob('recognize', 'image2.png')
137
  ]);
138
} finally {
139
  await scheduler.terminate();
140
}
141
```
142

143
## Complete Usage Patterns
144

145
### Basic Parallel Processing
146

147
```javascript
148
import { createScheduler, createWorker } from 'tesseract.js';
149

150
(async () => {
151
  const scheduler = createScheduler();
152
  
153
  // Add multiple workers
154
  const worker1 = await createWorker('eng');
155
  const worker2 = await createWorker('eng');
156
  scheduler.addWorker(worker1);
157
  scheduler.addWorker(worker2);
158
  
159
  // Process multiple images in parallel
160
  const images = ['img1.png', 'img2.png', 'img3.png', 'img4.png'];
161
  const results = await Promise.all(
162
    images.map(img => scheduler.addJob('recognize', img))
163
  );
164
  
165
  // Extract text from all results
166
  const texts = results.map(result => result.data.text);
167
  console.log(texts);
168
  
169
  await scheduler.terminate();
170
})();
171
```
172

173
### Multi-Language Processing
174

175
```javascript
176
(async () => {
177
  const scheduler = createScheduler();
178
  
179
  // Create workers for different languages
180
  const englishWorker = await createWorker('eng');
181
  const frenchWorker = await createWorker('fra');
182
  const germanWorker = await createWorker('deu');
183
  
184
  scheduler.addWorker(englishWorker);
185
  scheduler.addWorker(frenchWorker);
186
  scheduler.addWorker(germanWorker);
187
  
188
  // Process images with different languages
189
  const results = await Promise.all([
190
    scheduler.addJob('recognize', 'english-doc.png'),
191
    scheduler.addJob('recognize', 'french-doc.png'),
192
    scheduler.addJob('recognize', 'german-doc.png')
193
  ]);
194
  
195
  await scheduler.terminate();
196
})();
197
```
198

199
### Batch Processing with Progress Tracking
200

201
```javascript
202
(async () => {
203
  const scheduler = createScheduler();
204
  
205
  // Add workers with progress logging
206
  const worker1 = await createWorker('eng', 1, {
207
    logger: m => console.log(`Worker 1: ${m.status} - ${m.progress}%`)
208
  });
209
  const worker2 = await createWorker('eng', 1, {
210
    logger: m => console.log(`Worker 2: ${m.status} - ${m.progress}%`)
211
  });
212
  
213
  scheduler.addWorker(worker1);
214
  scheduler.addWorker(worker2);
215
  
216
  // Process large batch
217
  const imageFiles = Array.from({length: 20}, (_, i) => `batch-${i}.png`);
218
  
219
  console.log(`Processing ${imageFiles.length} images with ${scheduler.getNumWorkers()} workers`);
220
  
221
  const results = [];
222
  for (const imageFile of imageFiles) {
223
    console.log(`Queue length: ${scheduler.getQueueLen()}`);
224
    results.push(scheduler.addJob('recognize', imageFile));
225
  }
226
  
227
  const allResults = await Promise.all(results);
228
  console.log(`Completed processing ${allResults.length} images`);
229
  
230
  await scheduler.terminate();
231
})();
232
```
233

234
### Error Handling with Scheduler
235

236
```javascript
237
(async () => {
238
  const scheduler = createScheduler();
239
  
240
  // Add worker with error handler
241
  const worker = await createWorker('eng', 1, {
242
    errorHandler: (error) => console.error('Worker error:', error)
243
  });
244
  scheduler.addWorker(worker);
245
  
246
  try {
247
    const results = await Promise.allSettled([
248
      scheduler.addJob('recognize', 'valid-image.png'),
249
      scheduler.addJob('recognize', 'invalid-image.png'),
250
      scheduler.addJob('recognize', 'another-image.png')
251
    ]);
252
    
253
    results.forEach((result, index) => {
254
      if (result.status === 'fulfilled') {
255
        console.log(`Image ${index}: ${result.value.data.text}`);
256
      } else {
257
        console.error(`Image ${index} failed:`, result.reason);
258
      }
259
    });
260
  } finally {
261
    await scheduler.terminate();
262
  }
263
})();
264
```
265

266
## Interface Definition
267

268
```javascript { .api }
269
interface Scheduler {
270
  addWorker(worker: Worker): string;
271
  addJob(action: 'recognize', ...args: Parameters<Worker['recognize']>): Promise<RecognizeResult>;
272
  addJob(action: 'detect', ...args: Parameters<Worker['detect']>): Promise<DetectResult>;
273
  terminate(): Promise<any>;
274
  getQueueLen(): number;
275
  getNumWorkers(): number;
276
}
277
```