Awesome
Trapperkeeper Scheduler Service
A Trapperkeeper service that provides a simple API for scheduling background tasks.
Other Trapperkeeper services may specify a dependency on the Scheduler service, and then use its functions to schedule and cancel jobs to be run on background worker threads.
What Does This Service Do?
The SchedulerService
provides some simple API for scheduling (potentially
recurring) background tasks. The service manages the lifecycle of the underlying
scheduling subsystem so that other services don't need to (and avoids potential issues
around multiple services attempting to initialize the same scheduling subystem
in a single JVM process).
The functions that are currently available are as follows:
interspaced [interval-ms f]
: schedules a job that will callf
, block until that call completes, sleep forinterval-ms
milliseconds, and then repeat. Returns an identifier that can be used to reference this scheduled job (e.g., for cancellation) later.interspaced [interval-ms f group-id]
: schedules a job that will callf
, block until that call completes, sleep forinterval-ms
milliseconds, and then repeat. Returns an identifier that can be used to reference this scheduled job (e.g., for cancellation) later. A group identifiergroup-id
can be provided that allows jobs in the same group to be stopped at the same time.interval [interval-ms f]
: schedules a job that will callf
, block until that call completes, and then run again at the next logical interval based oninterval-ms
and the original start time. In other words,f
will get called everyinterval-ms
unless the execution time forf
exceedsinterval-ms
in which case that execution is skipped. Returns an identifier that can be used to reference this scheduled job (e.g., for cancellation) later.interval [interval-ms f group-id]
: schedules a job that will callf
, block until that call completes, and then run again at the next logical interval based oninterval-ms
and the original start time. In other words,f
will get called everyinterval-ms
unless the execution time forf
exceedsinterval-ms
in which case that execution is skipped. If there are insufficient threads in the thread pool to run the interval job at the time of execution, the job will be skipped. Returns an identifier that can be used to reference this scheduled job (e.g., for cancellation) later. A group identifiergroup-id
can be provided that allows jobs in the same group to be stopped at the same time.cron [cron-string f]
: schedules a job that will callf
in accordance with the cron schedule indicated by the 'cron-string'. Returns an identifier that can be used to reference this scheduled job (e.g. for cancellation) later. More information on a valid cron string can be found here.cron [cron-string f group-id]
: schedules a job that will callf
in accordance with the cron schedule indicated by the 'cron-string'. Returns an identifier that can be used to reference this scheduled job (e.g. for cancellation) later. A group identifiergroup-id
can be provided that allows jobs in the same group to be stopped at the same time. More information on a valid cron string can be found here.cron-next-valid-time [cron-string date]
: Given a cron specification and a date, returns a date that corresponds to the next execution of the timer based on that cron value.after [interval-ms f]
: schedules a job that will callf
a single time, after a delay ofinterval-ms
milliseconds. Returns an identifier that can be used to reference this scheduled job (e.g. for cancellation) later.after [interval-ms f group-id]
: schedules a job that will callf
a single time, after a delay ofinterval-ms
milliseconds. Returns an identifier that can be used to reference this scheduled job (e.g. for cancellation) later. A group identifiergroup-id
can be provided that allows jobs in the same group to be stopped at the same time.interval-after [initial-delay-ms interval-ms f]
: Similar tointerval
but delays initial execution untilinitial-delay-ms
has occurred.interval-after [initial-delay-ms interval-ms f group-id]
:Similar tointerval
but delays initial execution untilinitial-delay-ms
has occurred A group identifiergroup-id
can be provided that allows jobs in the same group to be stopped at the same time.stop-job [job-id]
: Given ajob-id
returned by one of the previous functions, cancels the job. If the job is currently executing it will be allowed to complete, but will not be invoked again afterward. Returnstrue
if the job was successfully stopped,false
otherwise.stop-jobs [group-id]
: Given agroup-id
identifier, cancel all the jobs associated with thatgroup-id
. If any of the jobs are currently executing they will be allowed to complete, but will not be invoked again afterward. Returns a sequence of maps, one for each job in the group, with each map containing thejob
and a booleanstopped?
key indiciating if the job was stopped successfully or not.count-jobs []
: Return a count of the total number of scheduled jobs known to to the scheduling service.after
jobs that have completed won't be included in the total.count-jobs [group-id]
: Return a count of the total number of scheduled jobs with the associatedgroup-id
known to to the scheduling service.after
jobs that have completed won't be included in the total.get-jobs []
: return a list of the current job identifiersget-jobs [group-id]
: return a list of the current job identifiers associated with the specified group identifier
Implementation Details
A configuration value is available under scheduler->thread-count that controls the number of threads used internally by the quartz library for job scheduling. If not specified, it defaults to 10, which is the quartz internal default.
The current implementation of the SchedulerService
is a wrapper around
the org.quartz-scheduler/quartz
library.
What's Next?
- Add additional scheduling API functions with more complicated recurring models.`.
- Add API for introspecting the state of currently scheduled jobs
#Support
Please log tickets and issues at our Jira Tracker.