8000 document Queue query state methods, Closes #455 · JavaScriptExpert/kue@e0c1294 · GitHub
[go: up one dir, main page]
Skip to content

Commit e0c1294

Browse files
behradbehrad
committed
document Queue query state methods, Closes Automattic#455 
1 parent 6147e0f commit e0c1294

File tree

3 files changed

+120
-18
lines changed

3 files changed

+120
-18
lines changed

‎History.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
* Upgrade to express 4.x, Closes #537
55
* Move `job.process` done callback to the last, Closes #387, Closes #385
6-
*
6+
* Document Javascript API to query queue state, Closes #455
77

88

99
0.8.12 / 2015-03-22

‎Readme.md

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -406,15 +406,61 @@ Kue will be refactored to fully atomic job state management from version 1.0 and
406406

407407
## Queue Maintenance
408408

409+
Queue object has two type of methods to tell you about the number of jobs in each state
410+
411+
```js
412+
queue.inactiveCount( function( err, total ) { // others are activeCount, completeCount, failedCount, delayedCount
413+
if( total > 100000 ) {
414+
console.log( 'We need some back pressure here' );
415+
}
416+
});
417+
```
418+
419+
you can also query on an specific job type:
420+
421+
```js
422+
queue.failedCount( 'my-critical-job', function( err, total ) {
423+
if( total > 10000 ) {
424+
console.log( 'This is tOoOo bad' );
425+
}
426+
});
427+
```
428+
429+
and iterating over job ids
430+
431+
```js
432+
queue.inactive( function( err, ids ) { // others are active, complete, failed, delayed
433+
// you may want to fetch each id to get the Job object out of it...
434+
});
435+
```
436+
437+
however the second one doesn't scale to large deployments, there you can use more specific `Job` static methods:
438+
439+
```js
440+
kue.Job.rangeByState( 'failed', 0, n, 'asc', function( err, jobs ) {
441+
// you have an array of maximum n Job objects here
442+
});
443+
```
444+
or
445+
446+
```js
447+
kue.Job.rangeByType( 'my-job-type', 'failed', 0, n, 'asc', function( err, jobs ) {
448+
// you have an array of maximum n Job objects here
449+
});
450+
```
451+
452+
**Note** *that the last two methods are subject to change in later Kue versions.*
453+
454+
409455
### Programmatic Job Management
410456

411-
If you did none of above or your process lost active jobs in any way, you can recover from them when your process is restarted. A blind logic would be to re-queue all stuck jobs:
457+
If you did none of above in [Error Handling](#error-handling) section or your process lost active jobs in any way, you can recover from them when your process is restarted. A blind logic would be to re-queue all stuck jobs:
412458

413459
```js
414460
queue.active( function( err, ids ) {
415461
ids.forEach( function( id ) {
416462
kue.Job.get( id, function( err, job ) {
417-
// if job is a stuck one
463+
// Your application should check if job is a stuck one
418464
job.inactive();
419465
});
420466
});

‎lib/kue.js

Lines changed: 71 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -403,6 +403,9 @@ Queue.prototype.card = function (state, fn) {
403403

404404
/**
405405
* Completed jobs.
406+
* @param {Function} fn
407+
* @return {Queue} for chaining
408+
* @api public
406409
*/
407410

408411
Queue.prototype.complete = function (fn) {
@@ -411,6 +414,9 @@ Queue.prototype.complete = function (fn) {
411414

412415
/**
413416
* Failed jobs.
417+
* @param {Function} fn
418+
* @return {Queue} for chaining
419+
* @api public
414420
*/
415421

416422
Queue.prototype.failed = function (fn) {
@@ -419,6 +425,9 @@ Queue.prototype.failed = function (fn) {
419425

420426
/**
421427
* Inactive jobs (queued).
428+
* @param {Function} fn
429+
* @return {Queue} for chaining
430+
* @api public
422431
*/
423432

424433
Queue.prototype.inactive = function (fn) {
@@ -427,6 +436,9 @@ Queue.prototype.inactive = function (fn) {
427436

428437
/**
429438
* Active jobs (mid-process).
439+
* @param {Function} fn
440+
* @return {Queue} for chaining
441+
* @api public
430442
*/
431443

432444
Queue.prototype.active = function (fn) {
@@ -435,48 +447,92 @@ Queue.prototype.active = function (fn) {
435447

436448
/**
437449
* Delayed jobs.
450+
* @param {Function} fn
451+
* @return {Queue} for chaining
452+
* @api public
438453
*/
439454

440455
Queue.prototype.delayed = function (fn) {
441456
return this.state('delayed', fn);
442457
};
443458

444459
/**
445-
* Completed jobs count.
460+
* Completed jobs of type `type` count.
461+
* @param {String} type is optional
462+
* @param {Function} fn
463+
* @return {Queue} for chaining
464+
* @api public
446465
*/
447466

448-
Queue.prototype.completeCount = function (fn) {
449-
return this.card('complete', fn);
467+
Queue.prototype.completeCount = function (type, fn) {
468+
if (1 == arguments.length) {
469+
fn = type;
470+
return this.card('complete', fn);
471+
}
472+
return this.cardByType(type, 'complete', fn);
450473
};
451474

475+
452476
/**
453-
* Failed jobs count.
477+
* Failed jobs of type `type` count.
478+
* @param {String} type is optional
479+
* @param {Function} fn
480+
* @return {Queue} for chaining
481+
* @api public
454482
*/
455483

456-
Queue.prototype.failedCount = function (fn) {
457-
return this.card('failed', fn);
484+
Queue.prototype.failedCount = function (type, fn) {
485+
if (1 == arguments.length) {
486+
fn = type;
487+
return this.card('failed', fn);
488+
}
489+
return this.cardByType(type, 'failed', fn);
458490
};
459491

460492
/**
461-
* Inactive jobs (queued) count.
493+
* Inactive jobs (queued) of type `type` count.
494+
* @param {String} type is optional
495+
* @param {Function} fn
496+
* @return {Queue} for chaining
497+
* @api public
462498
*/
463499

464-
Queue.prototype.inactiveCount = function (fn) {
465-
return this.card('inactive', fn);
500+
Queue.prototype.inactiveCount = function (type, fn) {
501+
if (1 == arguments.length) {
502+
fn = type;
503+
return this.card('inactive', fn);
504+
}
505+
return this.cardByType(type, 'inactive', fn);
466506
};
467507

468508
/**
469-
* Active jobs (mid-process).
509+
* Active jobs (mid-process) of type `type` count.
510+
* @param {String} type is optional
511+
* @param {Function} fn
512+
* @return {Queue} for chaining
513+
* @api public
470514
*/
471515

472-
Queue.prototype.activeCount = function (fn) {
473-
return this.card('active', fn);
516+
Queue.prototype.activeCount = function (type, fn) {
517+
if (1 == arguments.length) {
518+
fn = type;
519+
return this.card('active', fn);
520+
}
521+
return this.cardByType(type, 'active', fn);
474522
};
475523

476524
/**
477-
* Delayed jobs.
525+
* Delayed jobs of type `type` count.
526+
* @param {String} type is optional
527+
* @param {Function} fn
528+
* @return {Queue} for chaining
529+
* @api public
478530
*/
479531

480-
Queue.prototype.delayedCount = function (fn) {
481-
return this.card('delayed', fn);
532+
Queue.prototype.delayedCount = function (type, fn) {
533+
if (1 == arguments.length) {
534+
fn = type;
535+
return this.card('delayed', fn);
536+
}
537+
return this.cardByType(type, 'delayed', fn);
482538
};

0 commit comments

Comments
 (0)
0