@@ -43,6 +43,11 @@ function random() {
43
43
* Base class for both: Resource & ResourceFaçade which implements interface for talking to Job / JobFaçade & Manager.
44
44
*/
45
45
class ResourceInterface extends EventEmitter {
46
+ /**
47
+ * Constructor
48
+ * @param {string } id - id of resource
49
+ * @param {string } name - name of the resource
50
+ **/
46
51
constructor ( id , name ) {
47
52
super ( ) ;
48
53
this . _online = false ;
@@ -52,38 +57,72 @@ class ResourceInterface extends EventEmitter {
52
57
this . _name = name ;
53
58
}
54
59
60
+ /**
61
+ * Check if resource is busy
62
+ * @returns {boolean } if resource is busy
63
+ **/
55
64
get isBusy ( ) {
56
65
return ! ! this . _job ;
57
66
}
58
67
68
+ /**
69
+ * Check if resource is open
70
+ * @returns {boolean } if resource is open
71
+ **/
59
72
get isOpen ( ) {
60
73
return ! ! this . _open ;
61
74
}
62
75
76
+ /**
77
+ * Get id of resource
78
+ * @returns {string } resource id
79
+ **/
63
80
get id ( ) {
64
81
return this . _id ;
65
82
}
66
83
84
+ /**
85
+ * Get name of resource
86
+ * @returns {string } resource name
87
+ **/
67
88
get name ( ) {
68
89
return this . _name ;
69
90
}
70
91
92
+ /**
93
+ * Get resource job
94
+ * @returns {Job } resource job
95
+ **/
71
96
get job ( ) {
72
97
return this . _job ;
73
98
}
74
99
100
+ /**
101
+ * Set resource job
102
+ * @param {Job } job - resource job
103
+ **/
75
104
set job ( job ) {
76
105
this . _job = job ;
77
106
}
78
107
108
+ /**
109
+ * Run job
110
+ **/
79
111
run ( /*job*/ ) {
80
112
throw new Error ( 'Resource.run must be overridden to return promise' ) ;
81
113
}
82
114
115
+ /**
116
+ * Abort job
117
+ **/
83
118
abort ( /*job*/ ) {
84
119
throw new Error ( 'Resource.run must be overridden to return promise' ) ;
85
120
}
86
121
122
+ /**
123
+ * Resolved returned promise, once resource is online
124
+ * @returns {Promise } promise
125
+ **/
87
126
onceOnline ( ) {
88
127
if ( this . _online ) {
89
128
return Promise . resolve ( ) ;
@@ -99,6 +138,10 @@ class ResourceInterface extends EventEmitter {
99
138
}
100
139
}
101
140
141
+ /**
142
+ * Resolved returned promise, once resource is opened
143
+ * @returns {Promise } promise
144
+ **/
102
145
onceOpened ( ) {
103
146
if ( this . _open ) {
104
147
return Promise . resolve ( ) ;
@@ -118,6 +161,10 @@ class ResourceInterface extends EventEmitter {
118
161
}
119
162
}
120
163
164
+ /**
165
+ * Resolved returned promise, once resource is closed
166
+ * @returns {Promise } promise
167
+ **/
121
168
onceClosed ( ) {
122
169
if ( ! this . _open ) {
123
170
return Promise . resolve ( ) ;
@@ -136,6 +183,11 @@ class ResourceInterface extends EventEmitter {
136
183
* Constructor requires actual job instance just to instantiate a resource from its createResource call, separate run call is required to start it.
137
184
*/
138
185
class ResourceFaçade extends ResourceInterface {
186
+ /**
187
+ * Constructor
188
+ * @param {Job } job for resource
189
+ * @param {string } file
190
+ **/
139
191
constructor ( job , file ) {
140
192
super ( 'res:' + job . resourceName ( ) + ':' + random ( ) , 'res:' + job . resourceName ( ) ) ;
141
193
this . _file = file ;
@@ -227,14 +279,27 @@ class ResourceFaçade extends ResourceInterface {
227
279
} ) ;
228
280
}
229
281
282
+ /**
283
+ * Check if resource is busy
284
+ * @returns {boolean } if resource is busy
285
+ **/
230
286
get isBusy ( ) {
231
287
return ! ! this . _job ;
232
288
}
233
289
290
+ /**
291
+ * Check if resource is ready
292
+ * @returns {boolean } if resource is ready
293
+ **/
234
294
get isReady ( ) {
235
295
return this . open === true || this . open === null ;
236
296
}
237
297
298
+ /**
299
+ * Run job
300
+ * @param {Job } job to run
301
+ * @returns {Promise } promise
302
+ **/
238
303
run ( job ) {
239
304
if ( this . isBusy ) {
240
305
log . w ( '[façade]: Resource façade %j is busy in %d: %j' , this . name , this . _worker . pid , this . id ) ;
@@ -254,6 +319,10 @@ class ResourceFaçade extends ResourceInterface {
254
319
} ) ;
255
320
}
256
321
322
+ /**
323
+ * Close resource
324
+ * @returns {Promise } promise
325
+ **/
257
326
close ( ) {
258
327
if ( this . isOpen ) {
259
328
log . w ( 'Closing underlying resource %s from façade' , this . id ) ;
@@ -272,6 +341,10 @@ class ResourceFaçade extends ResourceInterface {
272
341
}
273
342
}
274
343
344
+ /**
345
+ * Kill resource
346
+ * @returns {Promise } promise
347
+ **/
275
348
kill ( ) {
276
349
return new Promise ( ( resolve ) => {
277
350
this . _worker . kill ( ) ;
@@ -281,6 +354,10 @@ class ResourceFaçade extends ResourceInterface {
281
354
} ) ;
282
355
}
283
356
357
+ /**
358
+ * Open resource
359
+ * @returns {Promise } promise
360
+ **/
284
361
open ( ) {
285
362
if ( this . isOpen ) {
286
363
return Promise . resolve ( ) ;
@@ -299,6 +376,11 @@ class ResourceFaçade extends ResourceInterface {
299
376
}
300
377
}
301
378
379
+ /**
380
+ * Abort job
381
+ * @param {Job } job to abort
382
+ * @returns {Promise } promise
383
+ **/
302
384
abort ( job ) {
303
385
if ( ! this . job ) {
304
386
log . w ( '[façade]: Resource façade %j is not open in %d: %j' , this . name , this . _worker . pid , this . id ) ;
@@ -313,6 +395,9 @@ class ResourceFaçade extends ResourceInterface {
313
395
this . channel . send ( CMD . ABORT , job . _json ) ;
314
396
}
315
397
398
+ /**
399
+ * Resolve job
400
+ **/
316
401
resolve ( ) {
317
402
if ( this . _resolve ) {
318
403
log . w ( '[façade]: Resolving %s' , this . job . channel ) ;
@@ -331,6 +416,10 @@ class ResourceFaçade extends ResourceInterface {
331
416
}
332
417
}
333
418
419
+ /**
420
+ * Reject job
421
+ * @param {Error } error with which to reject
422
+ **/
334
423
reject ( error ) {
335
424
if ( this . _reject ) {
336
425
log . w ( '[façade]: Rejecting %s' , this . job . channel ) ;
@@ -350,14 +439,24 @@ class ResourceFaçade extends ResourceInterface {
350
439
}
351
440
}
352
441
442
+ /** Class for resource pool **/
353
443
class ResourcePool extends EventEmitter {
444
+ /**
445
+ * Constructor
446
+ * @param {function } construct - resource constructor
447
+ * @param {number } maxResources - maximal amount of resources
448
+ **/
354
449
constructor ( construct , maxResources ) {
355
450
super ( ) ;
356
451
this . construct = construct ;
357
452
this . maxResources = maxResources ;
358
453
this . pool = [ ] ;
359
454
}
360
455
456
+ /**
457
+ * Check if there are any resources in the pool available
458
+ * @returns {boolean } if any available
459
+ **/
361
460
canRun ( ) {
362
461
for ( let i = 0 ; i < this . pool . length ; i ++ ) {
363
462
if ( ! this . pool [ i ] . isBusy ) {
@@ -367,6 +466,10 @@ class ResourcePool extends EventEmitter {
367
466
return this . pool . length < this . maxResources ;
368
467
}
369
468
469
+ /**
470
+ * Get a free resource
471
+ * @returns {object } resource to use
472
+ **/
370
473
getResource ( ) {
371
474
for ( let i = 0 ; i < this . pool . length ; i ++ ) {
372
475
if ( ! this . pool [ i ] . isBusy ) {
@@ -393,12 +496,20 @@ class ResourcePool extends EventEmitter {
393
496
throw new Error ( 'ResourcePool should be checked with canRun() before calling getResource()' ) ;
394
497
}
395
498
499
+ /**
500
+ * Close resourse
501
+ * @returns {Promise } promise
502
+ **/
396
503
close ( ) {
397
504
return Promise . all ( this . pool . map ( r => r . close ( ) . catch ( e => log . w ( '[%d]: Error in .close() of pool for resource %s' , process . pid , r . id , e . stack || e ) ) ) ) . catch ( ( error ) => {
398
505
log . w ( 'Error while closing pooled resources' , error ) ;
399
506
} ) ;
400
507
}
401
508
509
+ /**
510
+ * Kill resourse
511
+ * @returns {Promise } promise
512
+ **/
402
513
kill ( ) {
403
514
return Promise . all ( this . pool . map ( r => r . kill ( ) ) ) . catch ( ( error ) => {
404
515
log . w ( 'Error while killing pooled resources' , error ) ;
@@ -410,12 +521,22 @@ class ResourcePool extends EventEmitter {
410
521
* Main class for custom resources to override.
411
522
*/
412
523
class Resource extends ResourceInterface {
524
+ /**
525
+ * Cosntructor
526
+ * @param {string } _id - resource id
527
+ * @param {string } name - resource name
528
+ * @param {number } checkInterval - resource ping interval in miliseconds
529
+ * @param {number } autoCloseTimeout - resource close timeout in miliseconds
530
+ **/
413
531
constructor ( _id , name , checkInterval , autoCloseTimeout ) {
414
532
super ( _id , name ) ;
415
533
this . _resourceCheckMillis = checkInterval || RESOURCE_PING_INTERVAL ;
416
534
this . _resourceAutoCloseMillis = autoCloseTimeout || RESOURCE_CLOSE_TIMEOUT ;
417
535
}
418
536
537
+ /**
538
+ * Called when resource opens
539
+ **/
419
540
opened ( ) {
420
541
this . _open = true ;
421
542
log . i ( '[%d]: Opened resource %j (%j)' , process . pid , this . name , this . id ) ;
@@ -436,6 +557,9 @@ class Resource extends ResourceInterface {
436
557
} , this . _resourceCheckMillis ) ;
437
558
}
438
559
560
+ /**
561
+ * Called when resource closes
562
+ **/
439
563
closed ( ) {
440
564
this . _open = false ;
441
565
clearInterval ( this . _checkInterval ) ;
@@ -449,22 +573,40 @@ class Resource extends ResourceInterface {
449
573
} , 1000 ) ;
450
574
}
451
575
576
+ /**
577
+ * Open resource
578
+ **/
452
579
open ( ) {
453
580
throw new Error ( 'Resource.open must be overridden to return a Promise which calls Resource.opened in case of success' ) ;
454
581
}
455
582
583
+ /**
584
+ * Close resource
585
+ **/
456
586
close ( ) {
457
587
throw new Error ( 'Resource.open must be overridden to return a Promise which calls Resource.closed in case of success' ) ;
458
588
}
459
589
590
+ /**
591
+ * Kill resource
592
+ **/
460
593
kill ( ) {
461
594
throw new Error ( 'Resource.kill should not be ever called' ) ;
462
595
}
463
596
597
+ /**
598
+ * Check if resource is active
599
+ **/
464
600
checkActive ( ) {
465
601
log . i ( '[%d]: Checking resource %j (%j)' , process . pid , this . name , this . id ) ;
466
602
}
467
603
604
+ /**
605
+ * Start channel communication
606
+ * @param {object } channel - channel to use
607
+ * @param {object } db - database connection
608
+ * @param {function } Constructor - cosntructor for job
609
+ **/
468
610
start ( channel , db , Constructor ) {
469
611
this . db = db ;
470
612
this . channel = channel ;
@@ -516,6 +658,11 @@ class Resource extends ResourceInterface {
516
658
log . d ( 'Resource is online' ) ;
517
659
}
518
660
661
+ /**
662
+ * Job done
663
+ * @param {Job } job that is completed
664
+ * @param {Error } error - error if any happened
665
+ **/
519
666
done ( job , error ) {
520
667
if ( error === JOB . ERROR . TIMEOUT ) {
521
668
log . w ( '[%d]: Timeout for job %s (%s) in resource %s' , process . pid , job . name , job . channel , this . id ) ;
0 commit comments