mirror of https://gitee.com/bigwinds/arangodb
276 lines
9.0 KiB
Plaintext
276 lines
9.0 KiB
Plaintext
!CHAPTER Foxx Job Queues
|
|
|
|
Foxx allows defining job queues that let you perform slow or expensive actions asynchronously. These queues can be used to send e-mails, call external APIs or perform other actions that you do not want to perform directly or want to retry on failure.
|
|
|
|
For the low-level functionality see the section *Task Management* in the chapter *JavaScript Modules*.
|
|
|
|
*Examples*
|
|
|
|
The following Foxx route handler will enqueue a job whenever the *"/log"* route is accessed that prints "Hello World!" to the server log.
|
|
|
|
```js
|
|
var Foxx = require("org/arangodb/foxx");
|
|
var ctrl = new Foxx.Controller(applicationContext);
|
|
var queue = Foxx.queues.create("my-queue");
|
|
|
|
Foxx.queues.registerJobType("log", function (data) {
|
|
print(data);
|
|
});
|
|
|
|
ctrl.get("/log", function () {
|
|
queue.push("log", "Hello World!");
|
|
});
|
|
```
|
|
|
|
!SECTION Creating or updating a queue
|
|
|
|
Creates a queue with the given name and maximum number of workers.
|
|
|
|
`Foxx.queues.create(name, [maxWorkers])`
|
|
|
|
Returns the *Queue* instance for the given *name*. If the queue does not exist, a new queue with the given *name* will be created. If a queue with the given *name* already exists and *maxWorkers* is set, the queue's maximum number of workers will be updated.
|
|
|
|
*Parameter*
|
|
|
|
* *name*: the name of the queue to create.
|
|
* *maxWorkers* (optional): the maximum number of workers. Default: *1*.
|
|
|
|
*Examples*
|
|
|
|
```js
|
|
// Create a queue with the default number of workers (i.e. one)
|
|
var queue1 = Foxx.queues.create("my-queue");
|
|
// Create a queue with a given number of workers
|
|
var queue2 = Foxx.queues.create("another-queue", 2);
|
|
// Update the number of workers of an existing queue
|
|
var queue3 = Foxx.queues.create("my-queue", 10);
|
|
// queue1 and queue3 refer to the same queue
|
|
assertEqual(queue1, queue3);
|
|
```
|
|
|
|
!SECTION Fetching an existing queue
|
|
|
|
Fetches a queue with the given name.
|
|
|
|
`Foxx.queues.get(name)`
|
|
|
|
Returns the *Queue* instance for the given *name*. If the queue does not exist, an exception is thrown instead.
|
|
|
|
*Parameter*
|
|
|
|
* *name*: the name of the queue to fetch.
|
|
|
|
*Examples*
|
|
|
|
If the queue does not yet exist, an exception is thrown:
|
|
|
|
```js
|
|
Foxx.queues.get("some-queue");
|
|
// Error: Queue does not exist: some-queue
|
|
// at ...
|
|
```
|
|
|
|
Otherwise, the *Queue* instance will be returned:
|
|
|
|
```js
|
|
var queue1 = Foxx.queues.create("some-queue");
|
|
var queue2 = Foxx.queues.get("some-queue");
|
|
assertEqual(queue1, queue2);
|
|
```
|
|
|
|
!SECTION Deleting a queue
|
|
|
|
Deletes the queue with the given name from the database.
|
|
|
|
`Foxx.queues.delete(name)`
|
|
|
|
Returns *true* if the queue was deleted successfully. If the queue did not exist, it returns *false* instead.
|
|
|
|
When a queue is deleted, jobs on that queue will no longer be executed.
|
|
|
|
Deleting a queue will not delete any jobs on that queue.
|
|
|
|
*Parameter*
|
|
|
|
* *name*: the name of the queue to delete.
|
|
|
|
*Examples*
|
|
|
|
```js
|
|
var queue = Foxx.queues.create("my-queue");
|
|
Foxx.queues.delete("my-queue"); // true
|
|
Foxx.queues.delete("my-queue"); // false
|
|
```
|
|
|
|
!SECTION Registering a job type
|
|
|
|
Registers a job type with the queue manager.
|
|
|
|
`Foxx.queues.registerJobType(name, opts)`
|
|
|
|
If *opts* is a function, it will be treated as the *execute* function.
|
|
|
|
*Parameter*
|
|
|
|
* *name*: the name of the job type to register.
|
|
* *opts*: an object with the following properties:
|
|
* *execute*: a function to pass the job data to when a job is executed.
|
|
* *maxFailures* (optional): the number of times a job will be re-tried before it is marked as *"failed"*. A negative value or *Infinity* means that the job will be re-tried on failure indefinitely. Default: *0*.
|
|
* *schema* (optional): a [Joi](https://github.com/hapijs/joi) schema to validate a job's data against before accepting it.
|
|
* *preprocess* (optional): a function to pre-process a job's (validated) data before serializing it in the queue.
|
|
* *backOff* (optional): either a function that takes the number of times the job has failed before as input and returns the number of milliseconds to wait before trying the job again, or the delay to be used to calculate an [exponential back-off](https://en.wikipedia.org/wiki/Exponential_backoff), or *0* for no delay. Default: *1000*.
|
|
|
|
*Examples*
|
|
|
|
```js
|
|
var Foxx = require("org/arangodb/foxx");
|
|
Foxx.queues.registerJobType("log", function (data) {
|
|
print(data);
|
|
});
|
|
```
|
|
|
|
!SECTION Adding a job to a queue
|
|
|
|
Adds a job of the given type to the given queue.
|
|
|
|
`Queue::push(name, data, [opts])`
|
|
|
|
Returns the job id.
|
|
|
|
*Parameter*
|
|
|
|
* *name*: the name of the job's job type.
|
|
* *data*: the job data of the job; must be serializable to JSON.
|
|
* *opts* (optional): an object with any of the following properties:
|
|
* *success* (optional): a function to be called after the job has been completed successfully.
|
|
* *failure* (optional): a function to be called after the job has failed too many times.
|
|
* *delayUntil* (optional): a timestamp in milliseconds until which the execution of the job should be delayed. Default: *Date.now()*.
|
|
* *backOff* (optional): either a function that takes the number of times the job has failed before as input and returns the number of milliseconds to wait before trying the job again, or the delay to be used to calculate an [exponential back-off](https://en.wikipedia.org/wiki/Exponential_backoff), or *0* for no delay. See [Registering a job type](#registering-a-job-type).
|
|
* *allowUnknown* (optional): whether the job should be queued even if the job type name does not match a currently registered job type. Default: *false*.
|
|
* *maxFailures* (optional): the number of times the job will be re-tried before it is marked as *"failed"*. A negative value or *Infinity* means that the job will be re-tried on failure indefinitely. See [Registering a job type](#registering-a-job-type).
|
|
Note that if you pass a function for the *backOff* calculation, *success* callback or *failure* callback options the function must not rely on any external scope or external variables.
|
|
|
|
*Examples*
|
|
|
|
Basic usage example:
|
|
|
|
```js
|
|
var Foxx = require("org/arangodb/foxx");
|
|
var queue = Foxx.queues.create("my-queue");
|
|
queue.push("log", "Hello World!");
|
|
```
|
|
|
|
This will **not** work, because *console* was defined outside the callback function:
|
|
|
|
```js
|
|
var Foxx = require("org/arangodb/foxx");
|
|
var queue = Foxx.queues.create("my-queue");
|
|
var console = require("console"); // outside the callback's function scope
|
|
queue.push("log", "Hello World!", {
|
|
success: function () {
|
|
console.log("Yay!"); // throws "console is not defined"
|
|
}
|
|
});
|
|
```
|
|
|
|
!SECTION Fetching a job from the queue
|
|
|
|
Creates a proxy object representing a job with the given job id.
|
|
|
|
`Queue::get(jobId)`
|
|
|
|
Returns the *Job* instance for the given *jobId*. Properties of the job object will be fetched whenever they are referenced and can not be modified.
|
|
|
|
*Parameter*
|
|
|
|
* *jobId*: the id of the job to create a proxy object for.
|
|
|
|
*Examples*
|
|
```js
|
|
var jobId = queue.push("log", "Hello World!");
|
|
var job = queue.get(jobId);
|
|
assertEqual(job.id, jobId);
|
|
```
|
|
|
|
!SECTION Deleting a job from the queue
|
|
|
|
Deletes a job with the given job id.
|
|
|
|
`Queue::delete(jobId)`
|
|
|
|
Returns *true* if the job was deleted successfully. If the job did not exist, it returns *false* instead.
|
|
|
|
!SECTION Fetching a list of jobs in a queue
|
|
|
|
*Examples*
|
|
|
|
```js
|
|
queue.push("log", "Hello World!", {delayUntil: Date.now() + 50});
|
|
assertEqual(queue.pending("log").length, 1);
|
|
// 50 ms later...
|
|
assertEqual(queue.pending("log").length, 0);
|
|
assertEqual(queue.progress("log").length, 1);
|
|
// even later...
|
|
assertEqual(queue.progress("log").length, 0);
|
|
assertEqual(queue.complete("log").length, 1);
|
|
```
|
|
|
|
!SUBSECTION Fetching a list of pending jobs in a queue
|
|
|
|
`Queue::pending([type])`
|
|
|
|
Returns an array of job ids of jobs in the given queue with the status *"pending"*, optionally filtered by the given job type.
|
|
|
|
*Parameter*
|
|
|
|
* *type* (optional): the name of the job type to filter the results.
|
|
|
|
!SUBSECTION Fetching a list of jobs that are currently in progress
|
|
|
|
`Queue::progress([type])`
|
|
|
|
Returns an array of job ids of jobs in the given queue with the status *"progress"*, optionally filtered by the given job type.
|
|
|
|
*Parameter*
|
|
|
|
* *type* (optional): the name of the job type to filter the results.
|
|
|
|
!SUBSECTION Fetching a list of completed jobs in a queue
|
|
|
|
`Queue::complete([type])`
|
|
|
|
Returns an array of job ids of jobs in the given queue with the status *"complete"*, optionally filtered by the given job type.
|
|
|
|
*Parameter*
|
|
|
|
* *type* (optional): the name of the job type to filter the results.
|
|
|
|
!SUBSECTION Fetching a list of failed jobs in a queue
|
|
|
|
`Queue::failed([type])`
|
|
|
|
Returns an array of job ids of jobs in the given queue with the status *"failed"*, optionally filtered by the given job type.
|
|
|
|
*Parameter*
|
|
|
|
* *type* (optional): the name of the job type to filter the results.
|
|
|
|
!SUBSECTION Fetching a list of all jobs in a queue
|
|
|
|
`Queue::all([type])`
|
|
|
|
Returns an array of job ids of all jobs in the given queue, optionally filtered by the given job type.
|
|
|
|
*Parameter*
|
|
|
|
* *type* (optional): the name of the job type to filter the results.
|
|
|
|
!SECTION Aborting a job
|
|
|
|
Aborts a non-completed job.
|
|
|
|
`Job::abort()`
|
|
|
|
Sets a job's status to *"failed"* if it is not already *"complete"*, without calling the job's *onFailure* callback.
|
|
|