Recurrent
Schedule and execute your recurring tasks
Installation
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 "HourlyReport.run"
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
Statistic.collect
end
Frequency
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
Name
The second argument is the name of the task
Options
The third (optional) argument is options. The options are:
:save
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).
:start_time
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.
Block
The code you want to execute whenever the task runs.
Configuration
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.
Logging
logger
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 |, log_level|
RAILS_DEFAULT_LOGGER.send(log_level, )
end
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.
save_task_schedule
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
end
load_task_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
end
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.
save_task_schedule
This method is passed an options hash.
configure.save_task_return_value do ||
# Code to save the return value
end
options
:name
The name of the task.
:return_value
The value returned by your block when the task was executed.
:executed_at
The time at which the task was executed.
:executed_by
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.
handle_slow_task
configure.handle_slow_task do |name, current_time, still_running_time|
# notification code etc here
end
name
The name of the task.
current_time
The time the task is scheduled to run at.
still_running_time
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.
wait_for_running_tasks_on_exit_for
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.