From ecd00255bac174ef33f9db60a91495c95ae099fd Mon Sep 17 00:00:00 2001 From: Andrew Hamon Date: Mon, 12 Dec 2016 00:06:48 -0500 Subject: [PATCH] Initial commit --- .gitignore | 9 +++++ .travis.yml | 1 + LICENSE | 21 ++++++++++++ README.md | 59 +++++++++++++++++++++++++++++++++ shard.yml | 9 +++++ spec/periodic_timer_spec.cr | 18 ++++++++++ spec/spec_helper.cr | 4 +++ spec/timer_spec.cr | 64 ++++++++++++++++++++++++++++++++++++ src/quartz.cr | 1 + src/quartz/periodic_timer.cr | 17 ++++++++++ src/quartz/timer.cr | 28 ++++++++++++++++ src/quartz/version.cr | 3 ++ 12 files changed, 234 insertions(+) create mode 100644 .gitignore create mode 100644 .travis.yml create mode 100644 LICENSE create mode 100644 README.md create mode 100644 shard.yml create mode 100644 spec/periodic_timer_spec.cr create mode 100644 spec/spec_helper.cr create mode 100644 spec/timer_spec.cr create mode 100644 src/quartz.cr create mode 100644 src/quartz/periodic_timer.cr create mode 100644 src/quartz/timer.cr create mode 100644 src/quartz/version.cr diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..14c9c84 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +/doc/ +/libs/ +/lib/ +/bin/ +/.shards/ + +# Libraries don't need dependency lock +# Dependencies will be locked in application that uses them +/shard.lock diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..ffc7b6a --- /dev/null +++ b/.travis.yml @@ -0,0 +1 @@ +language: crystal diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..933b44e --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2016 Andrew Hamon + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..34269bd --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ +# Quartz + +Dead simple timers in Crystal + +## Installation + +Add this to your application's `shard.yml`: + +```yaml +dependencies: + timer: + github: andrewhamon/quartz +``` + +## Usage + +```crystal +require "quartz" + +# Execute a block after 3 seconds +Quartz::Timer.new(3) do + puts "3 seconds" +end + +# Execute block every second +Quartz::PeriodicTimer.new(1) do + puts "tick" +end + +# Make sure you yield in some way so that the timers get scheduled +sleep(5) +``` + +## WARNING: Make sure you understand Crystal's concurrency model + +Crystal is concurrent, but not (yet) parallel. Crystal fibers don't run immediately after being spawned, the main fiber must yield control, either explicitly by sleeping or implicitly by doing blocking IO. + +See [the docs](https://crystal-lang.org/docs/guides/concurrency.html) for a more detailed explanation. + +This has a number of consequences for timers such as this library: + +- The countdown for a timer doesn't start when the timer is instantiated, only when the fiber it spawns runs. This could be an arbitrarily long time after the timer is instantiated. +- The block you pass your timer might never get called, if the main fiber terminates too early or if it never yields control. +- Different timers might fire in a different order than expected. A shorter timer could fire after a longer timer +- Timers are not precise. +- A shorter timer is not guaranteed to execute before a separate, longer timer. + + +## Contributing + +1. Fork it ( https://github.com/andrewhamon/quartz/fork ) +2. Create your feature branch (git checkout -b my-new-feature) +3. Commit your changes (git commit -am 'Add some feature') +4. Push to the branch (git push origin my-new-feature) +5. Create a new Pull Request + +## Contributors + +- [andrewhamon](https://github.com/andrewhamon) Andrew Hamon - creator, maintainer diff --git a/shard.yml b/shard.yml new file mode 100644 index 0000000..9727a7c --- /dev/null +++ b/shard.yml @@ -0,0 +1,9 @@ +name: quartz +version: 0.1.0 + +authors: + - Andrew Hamon + +crystal: 0.20.1 + +license: MIT diff --git a/spec/periodic_timer_spec.cr b/spec/periodic_timer_spec.cr new file mode 100644 index 0000000..efb1034 --- /dev/null +++ b/spec/periodic_timer_spec.cr @@ -0,0 +1,18 @@ +require "./spec_helper" + +period = 0.1 + +describe PeriodicTimer do + it "calls the block until canceled" do + call_count = 0 + + t = PeriodicTimer.new(period) do + call_count += 1 + end + + sleep(2.1 * period) + t.cancel + + call_count.should eq(2) + end +end diff --git a/spec/spec_helper.cr b/spec/spec_helper.cr new file mode 100644 index 0000000..b885c32 --- /dev/null +++ b/spec/spec_helper.cr @@ -0,0 +1,4 @@ +require "spec" +require "../src/quartz" + +include Quartz diff --git a/spec/timer_spec.cr b/spec/timer_spec.cr new file mode 100644 index 0000000..f3bd1b6 --- /dev/null +++ b/spec/timer_spec.cr @@ -0,0 +1,64 @@ +require "./spec_helper" + +short_duration = 0.1 +medium_duration = 0.2 +long_duration = 0.3 + +describe Timer do + it "should call the block passed once time has elapsed" do + block_called = false + + Timer.new(short_duration) do + block_called = true + end + + sleep(long_duration) + + block_called.should be_true + end + + it "should not have called the block before time has elapsed" do + block_called = false + + Timer.new(long_duration) do + block_called = true + end + + sleep(short_duration) + + block_called.should be_false + end + + it "should not call the block if canceled" do + block_called = false + + t = Timer.new(medium_duration) do + block_called = true + end + + sleep(short_duration) + t.cancel + + sleep(medium_duration) + + block_called.should be_false + end + + it "should not accept negative values" do + expect_raises ArgumentError do + block_called = false + + t = Timer.new(-1) do + block_called = true + end + end + end + + it "should accept a Time::Span" do + block_called = false + + t = Timer.new(Time::Span.new(1)) do + block_called = true + end + end +end diff --git a/src/quartz.cr b/src/quartz.cr new file mode 100644 index 0000000..51957b1 --- /dev/null +++ b/src/quartz.cr @@ -0,0 +1 @@ +require "./quartz/*" diff --git a/src/quartz/periodic_timer.cr b/src/quartz/periodic_timer.cr new file mode 100644 index 0000000..181f6ab --- /dev/null +++ b/src/quartz/periodic_timer.cr @@ -0,0 +1,17 @@ +require "./timer" + +module Quartz + class PeriodicTimer < Timer + def initialize(seconds : Number, &block) + @canceled = false + raise ArgumentError.new "sleep seconds must be positive" if seconds < 0 + spawn do + loop do + sleep(seconds) + break if @canceled + block.call + end + end + end + end +end diff --git a/src/quartz/timer.cr b/src/quartz/timer.cr new file mode 100644 index 0000000..d31625e --- /dev/null +++ b/src/quartz/timer.cr @@ -0,0 +1,28 @@ +# The Timer class is a convenience wrapper that uses `spawn` and +# `sleep` to call a block in the future + +module Quartz + class Timer + def initialize(seconds : Number, &block) + @canceled = false + raise ArgumentError.new "sleep seconds must be positive" if seconds < 0 + spawn do + sleep(seconds) + next if @canceled + block.call + end + end + + def initialize(time : Time::Span, &block) + initialize(time.total_seconds, &block) + end + + def canceled? + @canceled + end + + def cancel + @canceled = true + end + end +end diff --git a/src/quartz/version.cr b/src/quartz/version.cr new file mode 100644 index 0000000..09304b4 --- /dev/null +++ b/src/quartz/version.cr @@ -0,0 +1,3 @@ +module Quartz + VERSION = "0.1.0" +end