Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



Schedule and execute your recurring tasks


gem install recurrent

Usage Examples

Command Line

Execute a command in the terminal

recurrent --every 5.seconds --system "say 'Recurrent says Hello'"

Run Ruby code

recurrent --every 1.hour --ruby ""

View command line options

recurrent --help

In your Rails app

Add gem "recurrent" to your Gemfile.

When recurrent is used from the root of your Rails application it will execute its tasks in the context of your environment and have access to your application's classes and methods.

Loading from a file

You can define tasks and configuration info in a file.

 recurrent --file config/recurrences.rb

The every method

Use the every method to create tasks.

every 30.seconds, :collect_usage_stats, :save => true do


The first argument is the frequency, it can be an integer in seconds, including ActiveSupport style 2.hours, 3.weeks etc, or an IceCube::Schedule


The second argument is the name of the task


The third (optional) argument is options. The options are:


Whether or not you want to save the return value of the task. Recurrent is data store agnostic, you must configure a method by which to save the return value (see below).


The time your task should start, can be in the future or the past. If not provided it will be set based on the frequency your task is executed.


The code you want to execute whenever the task runs.


Configuration options can be set via the configure method in a file passed to recurrent --file or elsewhere in your app, such as a Rails initializer, via Recurrent::Configuration.



Recurrent logs via puts, additionally you may use the logger of your choice by configuring Recurrent::Configuration.logger with two arguments and a block. The first argument is the message to be logged. The second is the log level, which will be one of :info, :debug, or :warn. An example using the Rails default logger:

  configure.logger do |message, log_level|
    RAILS_DEFAULT_LOGGER.send(log_level, message)

Keeping task execution times consistent

If you have a task that runs once an hour and you reboot your Recurrent worker 10 minutes before it was scheduled to execute you probably still want it to go off at the time it was scheduled. Letting Recurrent set your task start times partially solves this problem. For example when you create a task that runs every hour its start time is set to the beginning of the current day, and thus runs every hour on the hour. If your task runs every 5 seconds its start time will be set to the beginning of the current minute, and will execute at :00, :05, :10 etc.

Task frequencies that don't line up nicely like this will get out of sync. For example a task that is set to run every 23 hours with a start time of midnight will run at 11pm the first day, 10 pm the second day, 9pm the third day etc, but if your Recurrent worker is restarted it will start that process over. To avoid this you need to save your schedules so they can persist between reboots. Recurrent is datastore agnostic so you will need to configure the method by which you will save and load your tasks. If the following methods are configured Recurrent will keep your task execution times consistent.


This method is passed the name of the task being saved, and the schedule which is an instance of IceCube::Schedule. Note that the schedule has a to_yaml method. In the block you'll put the code that saves it to your datastore of choice, to later be retrieved by load_task_schedule.

 configure.save_task_schedule do |name, schedule|
   # Code to save the schedule


This method is passed the name of the task to be loaded and must return an instance of IceCube::Schedule. If you saved the schedule as yaml then IceCube::Schedule.from_yaml(schedule) may come in handy.

 configure.load_task_schedule do |name|
   # Code to load the schedule

Capturing the return value of your task

If you'd like to capture the return value of your task you'll need to configure the following method.


This method is passed an options hash.

  configure.save_task_return_value do |options|
    # Code to save the return value



The name of the task.


The value returned by your block when the task was executed.


The time at which the task was executed.


Information about the Recurrent worker that performed the task.

Handling a slow task

When a task is scheduled to occur Recurrent first checks to see if the task is still running from a previously scheduled execution. If it is still running then Recurrent does not initiate a new run. If you'd like to anything else, for example send yourself a notification that a task which is supposed to run every 30 seconds is taking longer than 30 seconds to execute, you can configure Recurrent::Configuration.handle_slow_task.


 configure.handle_slow_task do |name, current_time, still_running_time|
   # notification code etc here


The name of the task.


The time the task is scheduled to run at.


The time of the scheduled run that is still executing.

Dealing with running tasks when exiting the Recurrent worker

By default when attempting to exit the worker it will wait for all running tasks to finish before exiting.


How long to wait before killing tasks that are still running.

 configure.wait_for_running_tasks_on_exit_for = 10.seconds

Limiting the number of concurrent tasks

To limit the number of tasks that run simultaneously:

configure.maximum_concurrent_tasks = 5

This will run up to the above number of tasks simultaneously, if there are too many tasks running it will skip any extra tasks for that run. Tasks that run less frequently are prioritized. For example if you can run a maximum of 5 tasks, 4 of which are currently running, and you are now scheduled to run two tasks, one that runs once an hour, and one that runs once a minute, the hourly task will get the slot and the minutely task will not run until its next scheduled run.

Submitting an Issue

We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted. You can indicate support for an existing issuse by voting it up. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. Ideally, a bug report should include a pull request with failing specs.


Copyright (c) 2011 Zencoder See LICENSE for details.


Scheduled tasks.




No packages published


You can’t perform that action at this time.