Sidetiq

Recurring jobs for Sidekiq.

TABLE OF CONTENTS

• Overview
• Dependencies
• Installation
• Introduction
• Configuration
• API
• Polling
• Web Extension
• Contribute
• License
• Author

<a name='section_Overview>

OVERVIEW

Sidetiq provides a simple API for defining recurring workers for Sidekiq.

• Flexible DSL based on ice_cube

• High-resolution timer using clock_gettime(3) (or mach_absolute_time() on Apple Mac OS X), allowing for accurate sub-second clock ticks.

• Sidetiq uses a locking mechanism (based on setnx and pexpire) internally so Sidetiq clocks can run in each Sidekiq process without interfering with each other (tested with sub-second polling of scheduled jobs by Sidekiq and Sidetiq clock rates above 100hz).

<a name='section_Dependencies>

DEPENDENCIES

• Sidekiq
• ice_cube

<a name='section_Installation>

INSTALLATION

The best way to install Sidetiq is with RubyGems:

$ [sudo] gem install sidetiq

If you're installing from source, you can use Bundler to pick up all the gems (more info):

$ bundle install

<a name='section_Introduction>

INTRODUCTION

Defining recurring jobs is simple:

class MyWorker
  include Sidekiq::Worker
  include Sidetiq::Schedulable

  # Daily at midnight
  tiq { daily }
end

It also is possible to define multiple scheduling rules for a worker:

class MyWorker
  include Sidekiq::Worker
  include Sidetiq::Schedulable

  tiq do
    # Every third year in March
    yearly(3).month_of_year(:march)

    # Every second year in February
    yearly(2).month_of_year(:february)
  end
end

Or complex schedules:

class MyWorker
  include Sidekiq::Worker
  include Sidetiq::Schedulable

  # Every other month on the first monday and last tuesday at 12 o'clock.
  tiq { monthly(2).day_of_week(1 => [1], 2 => [-1]).hour_of_day(12) }
end

To start Sidetiq, simply call Sidetiq::Clock.start! in a server specific configuration block:

Sidekiq.configure_server do |config|
  Sidetiq::Clock.start!
end

Additionally, Sidetiq includes a middleware that will check if the clock thread is still alive and restart it if necessary.

<a name='section_Configuration>

CONFIGURATION

Sidetiq.configure do |config|
  # Thread priority of the clock thread (default: Thread.main.priority as
  # defined when Sidetiq is loaded).
  config.priority = 2

  # Clock tick resolution in seconds (default: 1).
  config.resolution = 0.5

  # Clock locking key expiration in ms (default: 1000).
  config.lock_expire = 100

  # When `true` uses UTC instead of local times (default: false)
  config.utc = false
end

<a name='section_API>

API

Sidetiq implements a simple API to support reflection of recurring jobs at runtime:

Sidetiq.schedules returns a Hash with the Sidekiq::Worker class as the key and the Sidetiq::Schedule object as the value:

Sidetiq.schedules
# => { MyWorker => #<Sidetiq::Schedule> }

Sidetiq.workers returns an Array of all workers currently tracked by Sidetiq (workers which include Sidetiq::Schedulable and a tiq call):

Sidetiq.workers
# => [MyWorker, AnotherWorker]

Sidetiq.scheduled returns an Array of currently scheduled Sidetiq jobs as Sidekiq::SortedEntry (Sidekiq::Job) objects. Optionally, it is possible to pass a block to which each job will be yielded:

Sidetiq.scheduled do |job|
  # do stuff ...
end

This list can further be filtered by passing the worker class to #scheduled, either as a String or the constant itself:

Sidetiq.scheduled(MyWorker) do |job|
  # do stuff ...
end

The same can be done for recurring jobs currently scheduled for retries (.retries wraps Sidekiq::RetrySet instead of Sidekiq::ScheduledSet):

Sidetiq.retries(MyWorker) do |job|
  # do stuff ...
end

<a name='section_Polling>

POLLING

By default Sidekiq uses a 15 second polling interval to check if scheduled jobs are due. If a recurring job has to run more often than that you should lower this value.

Sidekiq.options[:poll_interval] = 1

<a name='section_WebExtension>

WEB EXTENSION

Sidetiq includes an extension for Sidekiq's web interface. It will not be loaded by default, so it will have to be required manually:

require 'sidetiq/web'

SCREENSHOT

<a name='section_Contribute>

CONTRIBUTE

If you'd like to contribute to Sidetiq, start by forking my repo on GitHub:

http://github.com/tobiassvn/sidetiq

To get all of the dependencies, install the gem first. The best way to get your changes merged back into core is as follows:

1. Clone down your fork
2. Create a thoughtfully named topic branch to contain your change
3. Write some code
4. Add tests and make sure everything still passes by running rake
5. If you are adding new functionality, document it in the README
6. Do not change the version number, I will do that on my end
7. If necessary, rebase your commits into logical chunks, without errors
8. Push the branch up to GitHub
9. Send a pull request to the tobiassvn/sidetiq project.

<a name='section_License>

LICENSE

Sidetiq is released under the MIT License. See LICENSE for further details.

<a name='section_Author>

AUTHOR

Tobias Svensson, @tobiassvn, http://github.com/tobiassvn