Proposed doc change to show with-timeout using :interrupt?

README.md

@@ -48,7 +48,8 @@ execution if the open condition triggered.
 
 A rate limiter protects your code block to run limited times per
 second. It will block or throw exception depends on your
-configuration.
+configuration. (:rate is a floating point number, and can be less than 1.0. 
+Example: 0.5 is once every two seconds.)
 
 ```clojure
 (require '[diehard.core :as dh])
@@ -80,7 +81,8 @@ Timeouts allow you to fail an execution with `TimeoutExceededException` if it ta
 ```clojure
 (require '[diehard.core :as dh])
 
-(dh/with-timeout {:timeout-ms 5000}
+(dh/with-timeout {:timeout-ms 5000
+                  :interrupt? true}
   (fly-me-to-the-moon))
 ```
 

src/diehard/spec.clj

@@ -135,7 +135,9 @@
                       :timeout/on-failure]))
 
 ;; rate limiter
-(s/def :rate-limiter/rate int?)
+; allow floating point numbers, so that we can pass numbers such as 0.5, to signify 1 req / 2 seconds
+;(s/def :rate-limiter/rate int?)
+(s/def :rate-limiter/rate number?)
 (s/def :rate-limiter/max-cached-tokens int?)
 
 (s/def :rate-limiter/rate-limiter-new

test/diehard/rate_limiter_test.clj

@@ -20,4 +20,23 @@
       (.shutdown pool)
       (t/is (< (Math/abs (- @counter (* rate time-secs)))
                ;; error tolerance 3%
-               (* 0.03 (* rate time-secs)))))))
+               (* 0.03 (* rate time-secs))))))
+
+  (t/testing "rate limits less than 1.0"
+    (let [rate 0.5
+          threads 1
+          pool (Executors/newFixedThreadPool threads)
+          rl (r/rate-limiter {:rate rate})
+          counter (atom 0)
+          time-secs 5]
+      (doseq [_ (range threads)]
+        (.submit pool (cast Runnable (fn []
+                                       (while true
+                                         (r/acquire! rl)
+                                         (swap! counter inc))))))
+      (Thread/sleep (* time-secs 1000))
+      (.shutdown pool)
+      (let [variance (Math/abs (- @counter (* rate time-secs)))]
+        (t/is (<= variance
+                ;; error tolerance: 0.5  -- larger, because we are dealing with slower ticks
+                0.5))))))