TimeScheduler

Yet another library for single/periodical event scheduler.

Features

• A thread based scheduler that runs once or periodically at a specified datetime.

• The condition is specified by a format such as crontab or by keyword argument.

• Time can be specified in less than 1 second. However, the behavior depends on the environment.

• Suspend/resume function.

• Function to change the datetime conditions during execution.

• Runs only once within the specified timelimit.

Installation

Add this line to your application’s Gemfile:

gem 'time_scheduler'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install time_scheduler
or
$ gem install -l time_scheduler-x.x.x.gem

Usage

Example 1

require  "time_scheduler"

Scheduler  =  TimeScheduler.new

Signal.trap( :INT ) do
  exit
end

goal  =  Time.now + 5
while  time  =  Scheduler.wait( sec: "*" )
  p time
  break    if time > goal
end

goal  =  Time.now + 5
Scheduler.wait( :check, sec: "*" ) do |time|
  p time
  Scheduler.cancel( :check )    if time > goal
end

sleep  10

Example 2

require  "time_scheduler"

Scheduler  =  TimeScheduler.new

Signal.trap( :INT ) do
  exit
end

Scheduler.wait( sec: "*/5" ) do |time|
  p [time, :sec5]
end

Scheduler.wait( cron: "*/2 * * * *" ) do |time|
  p [time, :cron]
end

Scheduler.wait( at: Time.now + 30 ) do |time|
  p [time, :quit]
  exit
end

sleep

Example 3

require  "time_scheduler"

Scheduler  =  TimeScheduler.new

(0..4).each do
  p [Time.now.iso8601(3), :cycle]
  Scheduler.first_only( timeout: 10 ) do
    p [Time.now.iso8601(3), :first]
  end
  Scheduler.last_only( timeout: 10 ) do
    p [Time.now.iso8601(3), :last]
  end
  sleep 1
end

sleep

Reference

Create a new TimeScheduler.

TimeScheduler.new

• Result:

  • TimeScheduler object.

• Parameter:

  • None.

Schedule event.

TimeScheduler#wait( topic = Time.now.iso8601(6),
                    at: nil, cron: nil, year: nil, month: nil, day: nil, wday: nil,
                    hour: nil, min: nil, sec: 0, msec: nil,
                    &block )

• Result:

  • with block: (Non-blocing Mode)

    • topic: event identify topic for operation.

  • without block: (Blocking Mode)

    • time: event time. time object.

• Parameter:

  • topic: event identify topic for operation. (default: Time.now.iso8601(6))

  • at: time. Time or String object. (default: nil)

  • cron: set of min, hour, day, month, wday pattern. (default: nil)

  • year: year. unlimited range is denied. (default: nil)

  • month: month. 1..12, jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec. (default: nil)

  • day: day of month. 1..31. (default: nil)

  • wday: day of week. 0..7, sun, mon, tue, wed, thr, fri, sat. (default: nil)

  • hour: minute. 0..23. (default: nil)

  • min: minute. 0..59. (default: nil)

  • sec: second. 0..59. (default: 0)

  • msec: millisecond. 0..999. (default: nil), If msec is assigned, then other parameters are ignored. In detail, it can use "*" as wildcard.

  • block: Contents to be executed at a datetime that match the condition.

• Block Parameter:

  • time: event time. time object.

Get event topics.

TimeScheduler#topics

• Result:

  • topics: array of topics.

• Parameter:

  • none.

Cancel event.

TimeScheduler#cancel( *topics )

• Result:

  • nil.

• Parameter:

  • topic: topic for cancel operation.

Check activity.

TimeScheduler#active?

• Result:

  • false/true.

• Parameter:

  • none.

Suspend all events.

TimeScheduler#suspend

• Result:

  • nil.

• Parameter:

  • none.

Resume all events.

TimeScheduler#resume

• Result:

  • nil.

• Parameter:

  • none.

Invoke the block only once at the beginning, and ignoring recalls within the time limit.

TimeScheduler#first_only( ident = nil, timeout: 1, &block )

• Result:

  • nil.

• Parameter:

  • ident: Additional Identifier.

  • timeout: Monitoring time limit (sec).

• Block Parameter:

  • none.

When there is no recall within the time limit, invoke the block only once at the end.

TimeScheduler#last_only( ident = nil, timeout: 1, &block )

• Result:

  • nil.

• Parameter:

  • ident: Additional Identifier.

  • timeout: Monitoring time limit (sec).

• Block Parameter:

  • none.

Caution

Because it is calculated in local time, it does not work as expected when switching to daylight saving time.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/arimay/time_scheduler.

License

The gem is available as open source under the terms of the MIT License.

Copyright (c) ARIMA Yasuhiro <arima.yasuhiro@gmail.com>