Initial commit

.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

.travis.yml

@@ -0,0 +1 @@
+language: crystal

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.

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

shard.yml

@@ -0,0 +1,9 @@
+name: quartz
+version: 0.1.0
+
+authors:
+  - Andrew Hamon <[email protected]>
+
+crystal: 0.20.1
+
+license: MIT

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

spec/spec_helper.cr

@@ -0,0 +1,4 @@
+require "spec"
+require "../src/quartz"
+
+include Quartz

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

src/quartz.cr

@@ -0,0 +1 @@
+require "./quartz/*"

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

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

src/quartz/version.cr

@@ -0,0 +1,3 @@
+module Quartz
+  VERSION = "0.1.0"
+end