Liking cljdoc? Tell your friends :D

cljobq.core


db-migrate!clj

(db-migrate!)
(db-migrate! {:keys [context] :or {context (clojure.core/deref global-ctx*)}})

Run cljobq database migrations to ensure the database schema is set up and up-to-date.

Options:

  • :context cljobq context created via cljobq.core/make-context. If not specified, the implicit cljobq.core/global-ctx* atom set using cljobq.core/set-context! is used instead.

Example:

(cljobq.core/db-migrate!)
Run cljobq database migrations to ensure the database schema is set up and
up-to-date.

Options:

- `:context`   cljobq context created via `cljobq.core/make-context`. If not
               specified, the implicit `cljobq.core/global-ctx*` atom set
               using `cljobq.core/set-context!` is used instead.

Example:

```clojure
(cljobq.core/db-migrate!)
```
sourceraw docstring

delete-jobclj

(delete-job {:keys [context queue job-name]
             :or {context (clojure.core/deref global-ctx*)}})

Delete a specific job job-name from the specified queue. Deleting a job by name only really makes sense for recurring jobs. Returns the number of jobs deleted.

Options:

  • :context cljobq context created via cljobq.core/make-context. If not specified, the implicit cljobq.core/global-ctx* atom set using cljobq.core/set-context! is used instead.
  • :job-name The name of the job to delete. Required.
  • :queue The name of the queue to delete the job from. Required.

Example:

(cljobq.core/delete-job {:queue "math", :job-name "algebra-on-wednesdays"})
Delete a specific job `job-name` from the specified queue. Deleting a job
by name only really makes sense for recurring jobs. Returns the number of
jobs deleted.

Options:

- `:context`   cljobq context created via `cljobq.core/make-context`. If not
               specified, the implicit `cljobq.core/global-ctx*` atom set
               using `cljobq.core/set-context!` is used instead.
- `:job-name`  The name of the job to delete. Required.
- `:queue`     The name of the queue to delete the job from. Required.

Example:

```clojure
(cljobq.core/delete-job {:queue "math", :job-name "algebra-on-wednesdays"})
```
sourceraw docstring

delete-queue-jobsclj

(delete-queue-jobs {:keys [context queue]
                    :or {context (clojure.core/deref global-ctx*)}})

Delete all jobs from the specified queue. Returns the number of jobs deleted.

Options:

  • :context cljobq context created via cljobq.core/make-context. If not specified, the implicit cljobq.core/global-ctx* atom set using cljobq.core/set-context! is used instead.
  • :queue The name of the queue. Required.

Example:

(cljobq.core/delete-queue-jobs {:queue "math"})
Delete all jobs from the specified queue. Returns the number of jobs
deleted.

Options:

- `:context`   cljobq context created via `cljobq.core/make-context`. If not
               specified, the implicit `cljobq.core/global-ctx*` atom set
               using `cljobq.core/set-context!` is used instead.
- `:queue`     The name of the queue. Required.

Example:

```clojure
(cljobq.core/delete-queue-jobs {:queue "math"})
```
sourceraw docstring

enqueueclj

(enqueue {:keys [context queue job-name run-at interval actor args]
          :or {context (clojure.core/deref global-ctx*)
               job-name (uuid/v1)
               run-at nil
               interval nil
               args []}})

Enqueue a job based on a job description with an optionally specfied explicit context. If a job with the given job-name for the specified queue already exists, the existing job will be updated instead. If no job-name is given, a uuid-based name will be assigned automatically. An interval string (unix cron format) can be specified to create a recurring job. Errors in the interval specification cause an exception to be thrown. Returns the newly inserted job.

Options:

  • :context cljobq context created via cljobq.core/make-context. If not specified, the implicit cljobq.core/global-ctx* atom set using cljobq.core/set-context! is used instead.
  • :job-name A name for the job. A job name is unique within a queue. If not specified, a UUID-based random name will be used instead.
  • :queue A queue name to enqueue the job to. Required.
  • :actor A var-quoted function to run as part of this job. Required.
  • :args A vector of arguments to pass to the job function.
  • :interval A string-based UNIX cron expression defining the interval at which to run a job. If specified, a recurring job is created. If omitted or nil, the job will only run once.
  • :run-at The date/time at which to run the job. If omitted, the job will be scheduled to run immediately if it is a one-off job, or at the next recurrence if an interval was specified.

Example:

(cljobq.core/enqueue
  {:actor #'*-and-log
   :args [9 6]
   :queue "math"})

Example return value:

{:args [9 6]
 :job-name "10189f80-81ab-11e8-9e30-698897b5b41d"
 :last-error nil
 :queue "math"
 :status "pending"
 :id 18
 :picked-at nil
 :interval nil
 :created-at #inst "2018-07-07T06:00:34.430781000-00:00"
 :run-at #inst "2018-07-07T06:00:34.424000000-00:00"
 :attempt 0
 :related-job-id nil
 :actor "user/*-and-log"}
Enqueue a job based on a job description with an optionally specfied
explicit `context`.
If a job with the given `job-name` for the specified `queue` already
exists, the existing job will be updated instead.
If no `job-name` is given, a uuid-based name will be assigned automatically.
An `interval` string (unix cron format) can be specified to create a
recurring job.
Errors in the interval specification cause an exception to be thrown.
Returns the newly inserted job.

Options:

- `:context`   cljobq context created via `cljobq.core/make-context`. If not
               specified, the implicit `cljobq.core/global-ctx*` atom set
               using `cljobq.core/set-context!` is used instead.
- `:job-name`  A name for the job. A job name is unique within a queue. If
               not specified, a UUID-based random name will be used instead.
- `:queue`     A queue name to enqueue the job to. Required.
- `:actor`     A var-quoted function to run as part of this job. Required.
- `:args`      A vector of arguments to pass to the job function.
- `:interval`  A string-based UNIX cron expression defining the interval
               at which to run a job. If specified, a recurring job is
               created. If omitted or nil, the job will only run once.
- `:run-at`    The date/time at which to run the job. If omitted, the job
               will be scheduled to run immediately if it is a one-off job,
               or at the next recurrence if an `interval` was specified.

Example:

```clojure
(cljobq.core/enqueue
  {:actor #'*-and-log
   :args [9 6]
   :queue "math"})
```

Example return value:

```clojure
{:args [9 6]
 :job-name "10189f80-81ab-11e8-9e30-698897b5b41d"
 :last-error nil
 :queue "math"
 :status "pending"
 :id 18
 :picked-at nil
 :interval nil
 :created-at #inst "2018-07-07T06:00:34.430781000-00:00"
 :run-at #inst "2018-07-07T06:00:34.424000000-00:00"
 :attempt 0
 :related-job-id nil
 :actor "user/*-and-log"}
```
sourceraw docstring

global-ctx*clj

source

list-failed-jobsclj

(list-failed-jobs)
(list-failed-jobs {:keys [context queue]
                   :or {context (clojure.core/deref global-ctx*) queue nil}})

List all failed jobs. If queue is specified, only jobs for that queue will be shown.

Options:

  • :context cljobq context created via cljobq.core/make-context. If not specified, the implicit cljobq.core/global-ctx* atom set using cljobq.core/set-context! is used instead.
  • :queue The name of the queue. If omitted, jobs from all queues will be shown.

Example:

(cljobq.core/list-failed-jobs {:queue "queue-c"})

Example return value:

({:args [14 :e]
  :job-name "929238f0-7e2b-11e8-9580-698897b5b41d"
  :last-error "Error from actor `user/*-and-log` payload `[14 :e]`: clojure.lang.Keyword cannot be cast to java.lang.Number\nclojure.lang.Numbers.multiply(Numbers.java:148)\nuser$_STAR__and_log.invokeStatic(form-init6140559550272751977.clj:2)\nuser$_STAR__and_log.invoke(form-init6140559550272751977.clj:1) ..."
  :queue "queue-c"
  :status nil
  :id 12
  :picked-at #inst "2018-07-04T20:43:12.000747000-00:00"
  :interval nil
  :created-at #inst "2018-07-02T19:10:24.264601000-00:00"
  :run-at nil
  :attempt 5
  :related-job-id nil
  :actor "user/*-and-log"})
List all failed jobs. If `queue` is specified, only jobs for that queue
will be shown.

Options:

- `:context`   cljobq context created via `cljobq.core/make-context`. If not
               specified, the implicit `cljobq.core/global-ctx*` atom set
               using `cljobq.core/set-context!` is used instead.
- `:queue`     The name of the queue. If omitted, jobs from all queues will
               be shown.

Example:

```clojure
(cljobq.core/list-failed-jobs {:queue "queue-c"})
```

Example return value:

```clojure
({:args [14 :e]
  :job-name "929238f0-7e2b-11e8-9580-698897b5b41d"
  :last-error "Error from actor `user/*-and-log` payload `[14 :e]`: clojure.lang.Keyword cannot be cast to java.lang.Number\nclojure.lang.Numbers.multiply(Numbers.java:148)\nuser$_STAR__and_log.invokeStatic(form-init6140559550272751977.clj:2)\nuser$_STAR__and_log.invoke(form-init6140559550272751977.clj:1) ..."
  :queue "queue-c"
  :status nil
  :id 12
  :picked-at #inst "2018-07-04T20:43:12.000747000-00:00"
  :interval nil
  :created-at #inst "2018-07-02T19:10:24.264601000-00:00"
  :run-at nil
  :attempt 5
  :related-job-id nil
  :actor "user/*-and-log"})
```
sourceraw docstring

list-jobsclj

(list-jobs)
(list-jobs {:keys [context queue]
            :or {context (clojure.core/deref global-ctx*) queue nil}})

List all non-failed jobs. If queue is specified, only jobs for that queue will be shown.

Options:

  • :context cljobq context created via cljobq.core/make-context. If not specified, the implicit cljobq.core/global-ctx* atom set using cljobq.core/set-context! is used instead.
  • :queue The name of the queue. If omitted, jobs from all queues will be shown.

Example:

(cljobq.core/list-jobs)

Example return value:

({:args [9 6]
  :job-name "10189f80-81ab-11e8-9e30-698897b5b41d"
  :last-error nil
  :queue "math"
  :status "pending"
  :id 18
  :picked-at nil
  :interval nil
  :created-at #inst "2018-07-07T06:00:34.430781000-00:00"
  :run-at #inst "2018-07-07T06:00:34.424000000-00:00"
  :attempt 0
  :related-job-id nil
  :actor "user/*-and-log"}
 {:args [:a 81]
  :job-name "regular-math-err"
  :last-error nil
  :queue "queue-c"
  :status "scheduled"
  :id 22
  :picked-at nil
  :interval "15 23 * * *"
  :created-at #inst "2018-07-07T06:56:35.294888000-00:00"
  :run-at #inst "2018-07-07T22:15:00.000000000-00:00"
  :attempt 0
  :related-job-id nil
  :actor "user/*-and-log"})
List all non-failed jobs. If `queue` is specified, only jobs for that queue
will be shown.

Options:

- `:context`   cljobq context created via `cljobq.core/make-context`. If not
               specified, the implicit `cljobq.core/global-ctx*` atom set
               using `cljobq.core/set-context!` is used instead.
- `:queue`     The name of the queue. If omitted, jobs from all queues will
               be shown.

Example:

```clojure
(cljobq.core/list-jobs)
```

Example return value:

```clojure
({:args [9 6]
  :job-name "10189f80-81ab-11e8-9e30-698897b5b41d"
  :last-error nil
  :queue "math"
  :status "pending"
  :id 18
  :picked-at nil
  :interval nil
  :created-at #inst "2018-07-07T06:00:34.430781000-00:00"
  :run-at #inst "2018-07-07T06:00:34.424000000-00:00"
  :attempt 0
  :related-job-id nil
  :actor "user/*-and-log"}
 {:args [:a 81]
  :job-name "regular-math-err"
  :last-error nil
  :queue "queue-c"
  :status "scheduled"
  :id 22
  :picked-at nil
  :interval "15 23 * * *"
  :created-at #inst "2018-07-07T06:56:35.294888000-00:00"
  :run-at #inst "2018-07-07T22:15:00.000000000-00:00"
  :attempt 0
  :related-job-id nil
  :actor "user/*-and-log"})
```
sourceraw docstring

list-recurring-jobsclj

(list-recurring-jobs)
(list-recurring-jobs {:keys [context queue]
                      :or {context (clojure.core/deref global-ctx*) queue nil}})

List all recurring jobs. If queue is specified, only jobs for that queue will be shown.

Options:

  • :context cljobq context created via cljobq.core/make-context. If not specified, the implicit cljobq.core/global-ctx* atom set using cljobq.core/set-context! is used instead.
  • :queue The name of the queue. If omitted, jobs from all queues will be shown.

Example:

(cljobq.core/list-recurring-jobs {:queue "math"})

Example return value:

({:args [:a 81]
  :job-name "regular-math-err"
  :last-error nil
  :queue "queue-c"
  :status "scheduled"
  :id 22
  :picked-at nil
  :interval "15 23 * * *"
  :created-at #inst "2018-07-07T06:56:35.294888000-00:00"
  :run-at #inst "2018-07-07T22:15:00.000000000-00:00"
  :attempt 0
  :related-job-id nil
  :actor "user/*-and-log"})
List all recurring jobs. If `queue` is specified, only jobs for that queue
will be shown.

Options:

- `:context`   cljobq context created via `cljobq.core/make-context`. If not
               specified, the implicit `cljobq.core/global-ctx*` atom set
               using `cljobq.core/set-context!` is used instead.
- `:queue`     The name of the queue. If omitted, jobs from all queues will
               be shown.

Example:

```clojure
(cljobq.core/list-recurring-jobs {:queue "math"})
```

Example return value:

```clojure
({:args [:a 81]
  :job-name "regular-math-err"
  :last-error nil
  :queue "queue-c"
  :status "scheduled"
  :id 22
  :picked-at nil
  :interval "15 23 * * *"
  :created-at #inst "2018-07-07T06:56:35.294888000-00:00"
  :run-at #inst "2018-07-07T22:15:00.000000000-00:00"
  :attempt 0
  :related-job-id nil
  :actor "user/*-and-log"})
```
sourceraw docstring

make-contextclj

(make-context {:keys [db default-timeout default-max-timeout
                      default-max-attempts default-num-threads]
               :or {default-timeout 1800
                    default-max-timeout (* default-timeout 10)
                    default-num-threads 1
                    default-max-attempts 3}
               :as context})

Return a new cljobq context based on the config hash passed in. cljobq does not use connection pooling internally, however, connection pooling can be enabled by using a db-spec with a data source set using hikari-cp or c3p0.

All options except for :db can be overriden per queue in the queue-defs passed to cljobq.core/start.

Options:

  • :db A clojure.java.jdbc db-spec map. Required.
  • :default-timeout The default job timeout, in seconds. Defaults to 1800 seconds.
  • :default-max-timeout The default maximum job timeout, including any backoff. Defaults to 10 times the default timeout.
  • :default-max-attempts The default maximum number of attempts/retries to try and run a job for before marking it as failed. Defaults to 3.
  • :default-num-threads The default number of worker threads for a queue. Defaults to 1.

Example:

(def jobq-context
  (cljobq.core/make-context
    {:db {:connection-uri "jdbc:postgresql://localhost:5432/jobqtest?user=test&password=test"}
     :default-timeout 180}))
Return a new cljobq context based on the config hash passed in.
cljobq does not use connection pooling internally, however, connection
pooling can be enabled by using a db-spec with a data source set using
hikari-cp or c3p0.

All options except for `:db` can be overriden per queue in the queue-defs
passed to `cljobq.core/start`.

Options:

- `:db`                   A `clojure.java.jdbc` db-spec map. Required.
- `:default-timeout`      The default job timeout, in seconds. Defaults to
                          1800 seconds.
- `:default-max-timeout`  The default maximum job timeout, including any
                          backoff. Defaults to 10 times the default timeout.
- `:default-max-attempts` The default maximum number of attempts/retries to
                          try and run a job for before marking it as failed.
                          Defaults to 3.
- `:default-num-threads`  The default number of worker threads for a queue.
                          Defaults to 1.

Example:

```clojure
(def jobq-context
  (cljobq.core/make-context
    {:db {:connection-uri "jdbc:postgresql://localhost:5432/jobqtest?user=test&password=test"}
     :default-timeout 180}))
```
sourceraw docstring

set-context!clj

(set-context! v)

Set the global context cljobq.core/global-ctx* based on the passed in config v. See cljobq.core/make-context for more information on the configuration options.

The global context serves as an implicit context to all other functions in the absence of an explicit context.

Example:

(cljobq.core/set-context!
  {:db {:connection-uri "jdbc:postgresql://localhost:5432/jobqtest?user=test&password=test"}
   :default-timeout 180})
Set the global context `cljobq.core/global-ctx*` based on the passed in
config `v`. See `cljobq.core/make-context` for more information on the
configuration options.

The global context serves as an implicit context to all other functions
in the absence of an explicit context.

Example:

```clojure
(cljobq.core/set-context!
  {:db {:connection-uri "jdbc:postgresql://localhost:5432/jobqtest?user=test&password=test"}
   :default-timeout 180})
```
sourceraw docstring

startclj

(start {:keys [context queues] :or {context (clojure.core/deref global-ctx*)}})

Given a set of queue definitions in queues, start the worker threads for each of the defined queues and start processing jobs. Returns a run-info which can be used to stop the threads (see cljobq.core/stop for more information.

Options:

  • :context cljobq context created via cljobq.core/make-context. If not specified, the implicit cljobq.core/global-ctx* atom set using cljobq.core/set-context! is used instead.
  • :queues A map of queue-name -> queue-def. A queue def can an empty map, in which case the defaults of the context will be used for all options.

Each queue-def is a map with the following options (defaults are taken from the context - see cljobq.core/make-context):

  • :num-threads The number of worker threads to start for this queue.
  • :max-attempts The maximum number of attempts/retries to try and run a job on this queue for before marking it as failed.
  • :timeout The job timeout, in seconds.
  • :max-timeout The maximum job timeout, including any backoff.
  • :backoff-factor The backoff factor to use when calculating when to retry a job. Calculated as: random() * timeout + min(max-timeout, timeout * backoff-factor ^ attempt-number). A backoff-factor of 1 defines a constant backoff, whilst a factor greater than 1 defines an exponential backoff.
  • :poll-interval The number of seconds the queue's workers will sleep for if no job is ready to run.

Example:

(def jobq-runinfo
  (cljobq.core/start
    {:queues
     {:default
      {}
      :math
      {:num-threads 4
       :max-attempts 1
       :poll-interval 5}
      :email
      {:num-threads 2
       :timeout 600
       :max-timeout 14400
       :backoff-factor 1.9}}}))
Given a set of queue definitions in `queues`, start the worker threads for
each of the defined queues and start processing jobs.
Returns a `run-info` which can be used to stop the threads (see
`cljobq.core/stop` for more information.

Options:

- `:context`   cljobq context created via `cljobq.core/make-context`. If not
               specified, the implicit `cljobq.core/global-ctx*` atom set
               using `cljobq.core/set-context!` is used instead.
- `:queues`    A map of queue-name -> queue-def. A queue def can an empty
               map, in which case the defaults of the `context` will be used
               for all options.

Each queue-def is a map with the following options (defaults are taken from
the context - see `cljobq.core/make-context`):

- `:num-threads`     The number of worker threads to start for this queue.
- `:max-attempts`    The maximum number of attempts/retries to try and run
                     a job on this queue for before marking it as failed.
- `:timeout`         The job timeout, in seconds.
- `:max-timeout`     The maximum job timeout, including any backoff.
- `:backoff-factor`  The backoff factor to use when calculating when to retry
                     a job. Calculated as: `random() * timeout + min(max-timeout, timeout * backoff-factor ^ attempt-number)`. A `backoff-factor` of 1 defines a constant backoff, whilst a factor greater than 1 defines an exponential backoff.
- `:poll-interval`   The number of seconds the queue's workers will sleep
                     for if no job is ready to run.

Example:

```clojure
(def jobq-runinfo
  (cljobq.core/start
    {:queues
     {:default
      {}
      :math
      {:num-threads 4
       :max-attempts 1
       :poll-interval 5}
      :email
      {:num-threads 2
       :timeout 600
       :max-timeout 14400
       :backoff-factor 1.9}}}))
```
sourceraw docstring

stopclj

(stop)
(stop run-info-or-ctx)

Stop all worker threads. Can be passed either a run-info returned by cljobq.core/start or a context. If passed a context, only the threads started by the last call to cljobq.core/start with that context will be stopped.

Example:

(cljobq.core/stop jobq-runinfo)
Stop all worker threads. Can be passed either a `run-info` returned by
`cljobq.core/start` or a context. If passed a context, only the threads
started by the last call to `cljobq.core/start` with that context will
be stopped.

Example:

```clojure
(cljobq.core/stop jobq-runinfo)
```
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close