absolute_time 0.1.0

data/.gitignore

@@ -0,0 +1,10 @@
+*.gem
+*.bundle
+*.so
+*.o
+*.log
+*.tmproj
+Makefile
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in absolute_time.gemspec
+gemspec

data/README

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+AbsoluteTime
+
+This gem provides a monotonically increasing timer to permit safe measurement of time intervals.
+
+Using Time.now() for measuring intervals is not reliable—and sometimes unsafe—because the
+system clock may be stepped forwards or backwards between the two measurements, or may be
+running slower or faster than real time in order to effect clock synchronization with UTC.
+
+The module uses OS-specific functions such as mach_absolute_time() and clock_gettime() to
+access the system tick counter.  The time values returned by this module cannot be interpreted
+as real time clock values; they are only useful for comparison with another time value from
+this module.
+
+Also, please note that because the timer is dependent on the time since the system was
+booted, it is not meaningful to compare values of AbsoluteTime.now across reboots or between
+different machines.  It should, however, be safe to compare a timer value recorded by one process
+with a value recorded by a different process on the same machine.
+
+The resolution of the timer is system-dependent.
+
+
+Usage:
+
+# Is a monotonically increasing timer available on this system?
+>> AbsoluteTime.monotonic?
+=> true
+
+# Time an action by recording the start and end times.
+>> start_time = AbsoluteTime.now
+>> value = function_that_takes_a_long_time()
+>> end_time = AbsoluteTime.now
+>> puts "Function took #{end_time - start_time} seconds to complete."
+
+Function took 5.0002783499658108 seconds to complete.
+
+# Time an action using AbsoluteTime.measure, which acts like Benchmark.measure.
+>> AbsoluteTime.measure { function_that_takes_a_long_time() }
+=> 5.0002783499658108
+
+Supported platforms: Darwin (Mac OS X), FreeBSD, Linux
+
+If you can add support for another platform, please do so and send me a pull request on GitHub.  A Windows implementation using GetTickCount64() / GetTickCount() / QueryPerformanceCounter() would be much appreciated!

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/absolute_time.c

@@ -0,0 +1,135 @@
+/*
+    Copyright (C) 2011 Brian Buchanan. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+    ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+    SUCH DAMAGE.
+*/
+
+#include <ruby.h>
+#include <time.h>
+#ifdef HAVE_MACH_H
+#include <mach/mach.h>
+#endif
+#ifdef HAVE_MACH_MACH_TIME_H
+#include <mach/mach_time.h>
+#endif
+
+static double get_absolute_time(void);
+
+/*
+ * Document-module: AbsoluteTime
+ *
+ * Ruby interface to monotonically-increasing system timer.
+ */
+
+/*
+ * call-seq:
+ *   AbsoluteTime.now() -> time
+ *
+ * Returns the current value of the system timer as a floating-point number of seconds.
+ * Although the units of the return value are seconds, they cannot be safely
+ * interpreted as a wall clock time.  The return value is only useful when compared to
+ * the return value of a previous or subsequent call to AbsoluteTime.now().
+ *
+ * If a monotonically increasing system clock is not available, this function falls back
+ * to using the wall clock time.  You can check to see whether a monotonic clock is
+ * available using AbsoluteTime.monotonic?()
+ */
+static VALUE
+module_now(VALUE self_)
+{
+    return rb_float_new(get_absolute_time());
+}
+
+/*
+ * call-seq:
+ *   AbsoluteTime.realtime() { || ... } -> seconds
+ *
+ * Like Benchmark.realtime(), returns the elapsed time to execute the specified block,
+ * as a floating-point number of seconds.
+ */
+static VALUE
+module_realtime(VALUE self_)
+{
+    double start_time, end_time;
+    
+    start_time = get_absolute_time();
+    rb_yield(Qnil);
+    end_time = get_absolute_time();
+    
+    return rb_float_new(end_time - start_time);
+}
+
+/*
+ * call-seq:
+ *   AbsoluteTime.monotonic?() -> true | false
+ *
+ * Returns true if this module is able to use a guaranteed monotonically-increasing clock,
+ * false otherwise.
+ */
+static VALUE
+module_is_monotonic(VALUE self_)
+{
+#if defined(HAVE_CLOCK_GETTIME) && defined(CLOCK_MONOTONIC) || defined(HAVE_MACH_MACH_TIME_H)
+    return Qtrue;
+#else
+    return Qfalse;
+#endif
+}
+
+void
+Init_absolute_time(void)
+{
+    VALUE absolute_time_module = rb_define_module ("AbsoluteTime");
+    rb_define_singleton_method (absolute_time_module, "now", module_now, 0);
+    rb_define_singleton_method (absolute_time_module, "realtime", module_realtime, 0);
+    rb_define_singleton_method (absolute_time_module, "monotonic?", module_is_monotonic, 0);
+}
+
+static double
+get_absolute_time(void)
+{
+#if defined(HAVE_CLOCK_GETTIME) && defined(CLOCK_MONOTONIC)
+    struct timespec ts;
+    
+    if (clock_gettime(CLOCK_MONOTONIC, &ts) == -1) {
+        rb_sys_fail("clock_gettime");
+    }
+    return (double)ts.tv_sec + (double)ts.tv_nsec / 1e9;
+#else
+#  if defined(HAVE_MACH_MACH_TIME_H)
+    uint64_t t;
+    static mach_timebase_info_data_t timebase_info;
+    
+    /* If this is the first time we've run the function, then get the timebase info. */
+    if (timebase_info.denom == 0)
+        mach_timebase_info(&timebase_info);
+    
+    t = mach_absolute_time();
+    return (double)t * timebase_info.numer / timebase_info.denom / 1e9;
+#  else
+    struct timeval tv;
+    if (gettimeofday(&tv, 0) < 0)
+        rb_sys_fail("gettimeofday");
+    return (double)tv.tv_sec + (double)tv.tv_usec / 1e6;
+#  endif
+#endif
+}

data/absolute_time.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+Gem::Specification.new do |s|
+  s.name        = "absolute_time"
+  s.version     = '0.1.0'
+  s.authors     = ["Brian Buchanan"]
+  s.email       = ["brian@tiogalake.com"]
+  s.homepage    = ""
+  s.summary     = %q{Reliable monotonically increasing timer for measuring time intervals}
+  s.description = %q{This gem provides a monotonically increasing timer to permit safe measurement of time intervals.
+
+Using Time.now for measuring intervals is not reliable (and sometimes unsafe) because the
+system clock may be stepped forwards or backwards between the two measurements, or may be
+running slower or faster than real time in order to effect clock synchronization with UTC.
+
+The module uses OS-specific functions such as mach_absolute_time() and clock_gettime() to
+access the system tick counter.  The time values returned by this module cannot be interpreted
+as real time clock values; they are only useful for comparison with another time value from
+this module.
+}
+
+  s.rubyforge_project = "absolute_time"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.extensions    = 'extconf.rb'
+  s.has_rdoc      = true
+  s.extra_rdoc_files = `git ls-files -- *.c`.split("\n")
+end

data/extconf.rb

@@ -0,0 +1,31 @@
+# Copyright (C) 2011 Brian Buchanan. All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 
+# THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+# SUCH DAMAGE.
+
+require 'mkmf'
+dir_config('absolute_time')
+
+have_header('mach/mach.h')
+have_header('mach/mach_time.h')
+have_func('clock_gettime')
+
+create_makefile('absolute_time')

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: absolute_time
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Brian Buchanan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-09-17 00:00:00.000000000Z
+dependencies: []
+description: ! 'This gem provides a monotonically increasing timer to permit safe
+  measurement of time intervals.
+
+
+  Using Time.now for measuring intervals is not reliable (and sometimes unsafe) because
+  the
+
+  system clock may be stepped forwards or backwards between the two measurements,
+  or may be
+
+  running slower or faster than real time in order to effect clock synchronization
+  with UTC.
+
+
+  The module uses OS-specific functions such as mach_absolute_time() and clock_gettime()
+  to
+
+  access the system tick counter.  The time values returned by this module cannot
+  be interpreted
+
+  as real time clock values; they are only useful for comparison with another time
+  value from
+
+  this module.
+
+'
+email:
+- brian@tiogalake.com
+executables: []
+extensions:
+- extconf.rb
+extra_rdoc_files:
+- absolute_time.c
+files:
+- .gitignore
+- Gemfile
+- README
+- Rakefile
+- absolute_time.c
+- absolute_time.gemspec
+- extconf.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: absolute_time
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Reliable monotonically increasing timer for measuring time intervals
+test_files: []