Better documentation of monotonic clocks.

Author: jdantonio

lib/concurrent.rb

@@ -29,6 +29,24 @@
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
 
+# @!macro [new] monotonic_clock_warning
+# 
+#   @note Time calculations one all platforms and languages are sensitive to
+#     changes to the system clock. To alleviate the potential problems
+#     associated with changing the system clock while an application is running,
+#     most modern operating systems provide a monotonic clock that operates
+#     independently of the system clock. A monotonic clock cannot be used to
+#     determine human-friendly clock times. A monotonic clock is used exclusively
+#     for calculating time intervals. Not all Ruby platforms provide access to an
+#     operating system monotonic clock. On these platforms a pure-Ruby monotonic
+#     clock will be used as a fallback. An operating system monotonic clock is both
+#     faster and more reliable than the pure-Ruby implementation. The pure-Ruby
+#     implementation should be fast and reliable enough for most non-realtime
+#     operations. At this time the common Ruby platforms that provide access to an
+#     operating system monotonic clock are MRI 2.1 and above and JRuby (all versions).
+#
+#   @see http://linux.die.net/man/3/clock_gettime Linux clock_gettime(3)
+
 # Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
 # F#, C#, Java, and classic concurrency patterns.
 # 

lib/concurrent/atomic/condition.rb

@@ -43,6 +43,8 @@ def initialize
     # @param [Mutex] mutex the locked mutex guarding the wait
     # @param [Object] timeout nil means no timeout
     # @return [Result]
+    #
+    # @!macro monotonic_clock_warning
     def wait(mutex, timeout = nil)
       start_time = Concurrent.monotonic_time
       @condition.wait(mutex, timeout)

lib/concurrent/utility/monotonic_time.rb

@@ -1,14 +1,19 @@
 module Concurrent
 
+  # Clock that cannot be set and represents monotonic time since
+  # some unspecified starting point.
+  # @!visibility private
   GLOBAL_MONOTONIC_CLOCK = Class.new {
 
     if defined?(Process::CLOCK_MONOTONIC)
-      def get_time(other = 0.0)
-        Process.clock_gettime(Process::CLOCK_MONOTONIC) - other.to_f
+      # @!visibility private
+      def get_time(since = 0.0)
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - since.to_f
       end
     elsif RUBY_PLATFORM == 'java'
-      def get_time(other = 0.0)
-        (java.lang.System.nanoTime() / 1_000_000_000.0) - other.to_f
+      # @!visibility private
+      def get_time(since = 0.0)
+        (java.lang.System.nanoTime() / 1_000_000_000.0) - since.to_f
       end
     else
 
@@ -21,7 +26,8 @@ def initialize
         @last_time = Time.now.to_f
       end
 
-      def get_time(other = 0.0)
+      # @!visibility private
+      def get_time(since = 0.0)
         @mutex.synchronize {
           @correction ||= 0 # compensating any back time shifts
           now = Time.now.to_f
@@ -32,13 +38,26 @@ def get_time(other = 0.0)
             @correction += @last_time - corrected_now + 0.000_001
             @last_time = @correction + now
           end
-        } - other.to_f
+        } - since.to_f
       end
     end
   }.new
 
-  def monotonic_time(other = 0.0)
-    GLOBAL_MONOTONIC_CLOCK.get_time(other)
+  # @!macro [attach] monotonic_get_time
+  # 
+  #   Returns the current time a tracked by the application monotonic clock.
+  #   When no `since` time is given the return value will bet he current time.
+  #   When an `since` value is given the return value will be the monotonic time
+  #   interval which has been passed since the `since` time.
+  #
+  #   @param [Float] since the monotonic time from which to calculate
+  #     the time interval
+  #   @return [Float] The current monotonic time when `since` not given else
+  #     the elapsed monotonic time between `since` and the current time
+  #
+  #   @!macro monotonic_clock_warning
+  def monotonic_time(since = 0.0)
+    GLOBAL_MONOTONIC_CLOCK.get_time(since)
   end
   module_function :monotonic_time
 end
@@ -76,8 +95,8 @@ def get_time_native
     Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 
-  def get_interval_native(other)
-    Process.clock_gettime(Process::CLOCK_MONOTONIC) - other.to_f
+  def get_interval_native(since)
+    Process.clock_gettime(Process::CLOCK_MONOTONIC) - since.to_f
   end
 
   def get_time_ruby
@@ -94,8 +113,8 @@ def get_time_ruby
     end
   end
 
-  def get_interval_ruby(other)
-    get_time_ruby - other.to_f
+  def get_interval_ruby(since)
+    get_time_ruby - since.to_f
   end
 end
 

lib/concurrent/utility/timeout.rb

@@ -6,6 +6,8 @@
 module Concurrent
 
   # Wait the given number of seconds for the block operation to complete.
+  # Intended to be a simpler and more reliable replacement to the Ruby
+  # standard library `Timeout::timeout` method.
   #
   # @param [Integer] seconds The number of seconds to wait
   #
@@ -14,8 +16,9 @@ module Concurrent
   # @raise [Concurrent::TimeoutError] when the block operation does not complete
   #   in the allotted number of seconds.
   #
-  # @note This method is intended to be a simpler and more reliable replacement
-  # to the Ruby standard library `Timeout::timeout` method.
+  # @see http://ruby-doc.org/stdlib-2.2.0/libdoc/timeout/rdoc/Timeout.html Ruby Timeout::timeout
+  #
+  # @!macro monotonic_clock_warning
   def timeout(seconds)
 
     thread = Thread.new do

lib/concurrent/utility/timer.rb

@@ -10,6 +10,8 @@ module Concurrent
   # @yield the task to execute
   #
   # @return [Boolean] true
+  #
+  # @!macro monotonic_clock_warning
   def timer(seconds, *args, &block)
     raise ArgumentError.new('no block given') unless block_given?
     raise ArgumentError.new('interval must be greater than or equal to zero') if seconds < 0