home_run 0.9.0

data/CHANGELOG

@@ -0,0 +1,3 @@
+=== 0.9.0 (2010-08-20)
+
+* Initial Public Release

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Jeremy Evans
+
+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 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.
+

data/README.rdoc

@@ -0,0 +1,314 @@
+= home_run
+
+home_run is an implementation of ruby's Date/DateTime classes in C,
+with much better performance (20-200x) than the version in the
+standard library, while being almost completely compatible.
+
+== Performance increase (microbenchmarks)
+
+The speedup you'll get depends mostly on your version of ruby, but
+also on your operating system, platform, and compiler.  Here are
+some comparative results for common methods:
+
+  #                 | i386  | i386  | i386  | i386  | amd64 |
+  #                 |Windows| Linux | Linux | Linux |OpenBSD|
+  #                 | 1.8.6 | 1.8.7 | 1.9.1 | 1.9.2 | 1.9.2 |
+  #                 |-------+-------+-------+------ +-------|
+  Date.civil        |   82x |   66x |  27x  |  21x  |  14x  |
+  Date.parse        |   56x |   56x |  33x  |  30x  |  25x  |
+  Date.today        |   17x |    6x |   2x  |   2x  |   2x  |
+  Date.strptime     |   43x |   62x |  63x  |  37x  |  23x  |
+  DateTime.civil    |  252x |  146x |  52x  |  41x  |  17x  |
+  DateTime.parse    |   52x |   54x |  32x  |  27x  |  20x  |
+  DateTime.now      |   78x |   35x |  11x  |   8x  |   4x  |
+  DateTime.strptime |   63x |   71x |  58x  |  35x  |  23x  |
+  Date#strftime     |  156x |  104x | 110x  |  70x  |  62x  |
+  Date#+            |   34x |   32x |   5x  |   5x  |   4x  |
+  Date#<<           |  177x |  220x |  86x  |  72x  |  40x  |
+  Date#to_s         |   15x |    6x |   5x  |   4x  |   2x  |
+  DateTime#strftime |  146x |  107x | 114x  |  71x  |  60x  |
+  DateTime#+        |   34x |   37x |   8x  |   6x  |   3x  |
+  DateTime#<<       |   88x |  106x |  40x  |  33x  |  16x  |
+  DateTime#to_s     |  144x |   47x |  54x  |  29x  |  24x  |
+
+== Real world difference
+
+The standard library Date class is slow enough to be the
+bottleneck in much (if not most) of code that uses it.
+Here's a real world benchmark showing the retrieval of
+data from a database, first without home_run, and then
+with home_run.
+
+  $ script/console production
+  Loading production environment (Rails 2.3.5)
+  >> require 'benchmark'
+  => false
+  >> puts Benchmark.measure{Employee.all}
+    0.270000   0.020000   0.290000 (  0.460604)
+  => nil
+  >> puts Benchmark.measure{Notification.all}
+    2.510000   0.050000   2.560000 (  2.967896)
+  => nil
+
+  $ home_run script/console production
+  Loading production environment (Rails 2.3.5)
+  >> require 'benchmark'
+  => false
+  >> puts Benchmark.measure{Employee.all}
+    0.100000   0.000000   0.100000 (  0.114747)
+  => nil
+  >> puts Benchmark.measure{Notification.all}
+    0.860000   0.010000   0.870000 (  0.939594)
+
+Without changing any application code, there's a 4x
+increase when retrieving all employees, and a 3x
+increase when retrieving all notifications.  The
+main reason for the performance difference between
+these two models is that Employee has 5 date columns,
+while Notification only has 3.
+
+== Installing the gem
+
+  gem install home_run
+
+The standard gem requires compiling from source, so you need a working
+compiler toolchain.  Since few Windows users have a working compiler
+toolchain, a windows binary gem is available that works on both 1.8
+and 1.9.
+
+== Installing into site_ruby
+
+This is only necessary on ruby 1.8, as on ruby 1.9, gem directories
+come before the standard library directories in the load path.
+
+After installing the gem:
+
+  home_run --install
+
+Installing into site_ruby means that ruby will always use home_run's
+Date/DateTime classes instead of the ones in the standard library.
+
+If you ever want to uninstall from site_ruby:
+
+  home_run --uninstall
+
+== Running without installing into site_ruby
+
+Just like installing into site_ruby, this should only be necessary
+on ruby 1.8.
+
+If you don't want to install into site_ruby, you can use home_run's
+Date/DateTime classes for specific programs by running your script
+using home_run:
+
+  home_run ruby ...
+  home_run irb ...
+  home_run unicorn ...
+  home_run rake ...
+
+This manipulates the RUBYLIB and RUBYOPT environment variables so
+that home_run's Date/DateTime classes will be used.
+
+== Running the specs
+
+You can run the specs after installing the gem, if you have MSpec
+installed (gem install mspec):
+
+  home_run --spec
+
+If there are any failures, please report them as a bug.
+
+== Running comparative benchmarks
+
+You can run the benchmarks after installing the gem:
+
+  home_run --bench
+
+The benchmarks compare home_run's Date/DateTime classes to the
+standard library ones, showing you the amount of time an average
+call to each method takes for both the standard library and
+home_run, and the number of times home_run is faster or slower.
+Output is in CSV, so an entry like this:
+
+  Date._parse,362562,10235,35.42
+
+means that:
+
+* The standard library's Date._parse averaged 362,562 nanoseconds
+  per call.
+* home_run's Date._parse averaged 10,235 nanoseconds per call.
+* Therefore, home_run's Date._parse method is 35.42 times faster
+
+The bench task tries to be fair by ensuring that it runs the
+benchmark for at least two seconds for both the standard
+library and home_run's versions.
+
+== Usage
+
+home_run aims to be compatible with the standard library, except
+for differences mentioned below.  So you can use it the same way
+you use the standard library.
+
+== Differences from standard library
+
+* Written in C (mostly) instead of ruby.  Stores information in a
+  C structure, and therefore has a range limitation.  home_run
+  cannot handle dates after 5874773-08-15 or before -5877752-05-08
+  on 32-bit platforms (with larger limits for 64-bit platforms).
+* The Date class does not store fractional days (e.g. hours, minutes),
+  or offsets. The DateTime class does handle fractional days and
+  offsets.
+* The DateTime class stores fractional days as the number of
+  nanoseconds since midnight, so it cannot deal with differences
+  less than a nanosecond.
+* Neither Date nor DateTime uses rational.  Places where the standard
+  library returns rationals, home_run returns integers or floats.
+* Because rational is not used, it is not required.  This can break
+  other libraries that use rational without directly requiring it.
+* There is no support for modifying the date of calendar reform, the
+  sg arguments are ignored and the Gregorian calendar is always used.
+  This means that julian day 0 is -4173-11-24, instead of -4712-01-01.
+* The undocumented Date#strftime format modifiers are not supported.
+* The DateTime offset is checked for reasonableness. home_run
+  does not support offsets with an absolute difference of more than
+  14 hours from UTC.
+* DateTime offsets are stored in minutes, so it will round offsets
+  with fractional minutes to the nearest minute.
+* All public class and instance methods for both Date and DateTime
+  are implemented, except that the allocate class method is not
+  available and on 1.9, _dump and _load are used instead of
+  marshal_dump and marshal_load.
+* Only the public API is compatible, the private methods in the
+  standard library are not implemented.
+* The marshalling format differs from the one used by the standard
+  library.  Note that the 1.8 and 1.9 standard library date
+  marshalling formats differ from each other.
+* Date#step treats the step value as an integer, so it cannot handle
+  steps of fractional days.  DateTime#step can handle fractional
+  day steps, though.
+* When parsing the %Q modifier in _strptime, the hash returned
+  includes an Integer :seconds value and a Float :sec_fraction
+  value instead of a single rational :seconds value.
+* The string returned by #inspect has a different format, since it
+  doesn't use rational.
+* The conversion of 2-digit years to 4-digit years in Date._parse
+  is set to true by default.  On ruby 1.8, the standard library
+  has it set to false by default.
+* You can use the Date::Format::STYLE hash to change how to parse
+  DD/DD/DD and DD.DD.DD date formats, allowing you to get ruby 1.9
+  behavior on 1.8 or vice-versa.  This is probably the only new
+  feature in that isn't in the standard library.
+
+Any other differences will either be documented here or considered
+bugs, so please report any other differences you find.
+
+== Reporting issues/bugs
+
+home_run uses GitHub Issues for tracking issues/bugs:
+
+  http://github.com/jeremyevans/home_run/issues
+
+== Contributing
+
+The source code is on GitHub:
+
+  http://github.com/jeremyevans/home_run
+
+To get a copy:
+
+  git clone git://github.com/jeremyevans/home_run.git
+
+There are a few requirements:
+
+* Rake
+* Ragel 6.5+ for building the ragel parser.  The compiled C file is
+  included in the gem, so people installing the gem don't need
+  Ragel.  The compiled C file is not checked into git, so you need
+  Ragel if you are working with a git checkout.
+* MSpec (not RSpec) for running the specs.  The specs are based on
+  the rubyspec specs, which is why they use MSpec.
+* RDoc 2.5.10+ if you want to build the documentation.
+
+The directory layout is slightly unusual in that there is no
+lib directory and there are .rb files in the ext directory. This may
+change in a future version.
+
+== Building
+
+To build the library from a git checkout, after installing the
+requirements:
+
+  rake parser build
+
+== Testing
+
+The default rake task runs the specs, so just run:
+
+  rake
+
+You need to build the library before running the specs.
+
+== Benchmarking
+
+To see the speedup that home_run gives you over the standard library:
+
+  rake bench
+
+To see how much less memory home_run uses compared to the standard
+library:
+
+  rake mem_bench
+
+To see how much less garbage is created when instantiating objects
+with home_run compared to the standard library:
+
+  rake garbage_bench
+
+If you want to run all three benchmarks at once:
+
+  rake bench_all
+
+== Platforms Supported
+
+home_run has been tested on the following:
+
+=== Operating Systems/Platforms
+
+* Linux (x86_64, i386)
+* Mac OS X 10.6 (x86_64, i386)
+* OpenBSD (amd64, i386)
+* Windows XP (i386)
+
+=== Compiler Versions
+
+* gcc (3.3.5, 4.2.1, 4.4.3, 4.5.0)
+
+=== Ruby Versions
+
+* rbx head (as of commit 0e265b92727cf3536053, 2010-08-16)
+* ruby 1.8.6 (p0, p398, p399)
+* ruby 1.8.7 (p174, p248, p299, p302)
+* ruby 1.9.1 (p243, p378, p429, p430)
+* ruby 1.9.2 (p0)
+* ruby head
+
+If your platform, compiler version, or ruby version is not listed
+above, please test and send me a report including:
+
+* Your operating system and platform (e.g. i386, x86_64/amd64)
+* Your compiler
+* Your ruby version
+* The output of home_run --spec
+* The output of home_run --bench
+
+== Todo
+
+* Get it working on jruby with the cext branch
+* Add more specs for greater code coverage and to test
+  boundry conditions
+* Expand main ragel parser to handle more formats
+* Add ragel versions of the 1.9 date parsing functions
+
+== Author
+
+Jeremy Evans <code@jeremyevans.net>

data/Rakefile

@@ -0,0 +1,140 @@
+require "rake"
+require "rake/clean"
+require 'rbconfig'
+
+CLEAN.include %w'ext/Makefile ext/date_ext.*o **/*.rbc *.core rdoc' 
+RUBY=ENV['RUBY'] || File.join(RbConfig::CONFIG['bindir'], RbConfig::CONFIG['ruby_install_name'])
+
+begin
+  gem 'rdoc'
+  require 'rdoc/rdoc'
+  require "rake/rdoctask"
+  Rake::RDocTask.new do |rdoc|
+    rdoc.rdoc_dir = "rdoc"
+    rdoc.options += ["--quiet", "--line-numbers", "--inline-source", '--title',
+      'home_run: Fast Date/DateTime classes for ruby', '--main', 'README.rdoc']
+    rdoc.rdoc_files.add %w"README.rdoc CHANGELOG LICENSE ext/**/*.rb ext/*.c"
+  end
+rescue LoadError
+end
+
+desc "Run the specs with mspec"
+task :default => :spec
+task :spec do
+  ENV['RUBY'] ||= RUBY
+  sh %{mspec}
+end
+
+desc "Build the gem"
+task :gem => [:clean, :parser] do
+  sh %{gem build home_run.gemspec}
+end
+
+desc "Try to clean up everything"
+task :distclean  do
+  CLEAN.concat(%w'pkg home_run-*.gem ext/1.* tmp rdoc ext/date_parser.c')
+  Rake::Task[:clean].invoke
+end
+
+if RUBY_PLATFORM !~ /win|w32/ and File.directory?(File.join(File.expand_path(ENV['HOME']), '.rake-compiler'))
+begin
+  require "rake/extensiontask"
+  ENV['RUBY_CC_VERSION'] = '1.8.6:1.9.1'
+  load('home_run.gemspec')
+  desc "Internal--cross compile the windows binary gem"
+  Rake::ExtensionTask.new('date_ext', HOME_RUN_GEMSPEC) do |ext|
+    ext.name = 'date_ext'
+    ext.ext_dir = 'ext' 
+    ext.lib_dir = 'ext' 
+    ext.cross_compile = true
+    ext.cross_platform = 'i386-mswin32'
+    ext.source_pattern = '*.c'
+  end
+
+  # FIXME: Incredibly hacky, should figure out how to get
+  # rake compiler to do this correctly
+  desc "Build the cross compiled windows binary gem"
+  task :windows_gem => :clean do
+    sh %{rm -rf tmp pkg home_run-*.gem ext/1.*}
+    system %{rake cross native gem}
+    unless File.directory?('pkg')
+      sh %{cp ext/*.c tmp/i386-mswin32/date_ext/1.8.6}
+      system %{rake cross native gem}
+      sh %{cp ext/*.c tmp/i386-mswin32/date_ext/1.9.1}
+      system %{rake cross native gem}
+      sh %{rake cross native gem}
+    end
+    sh %{rm -rf home_run-*.gem tmp ext/1.*}
+    sh %{mv pkg/home_run-*.gem .}
+    sh %{rmdir pkg}
+  end
+
+  desc "Build the cross compiled windows binary gem"
+  task :windows_gem_clean do
+    sh %{rm -rf tmp ext/1.{8,9}}
+  end
+rescue LoadError
+end
+end
+
+desc "Build the ragel parser"
+task :parser do
+  sh %{cd ext && ragel date_parser.rl}
+end
+
+desc "Build the extension"
+task :build=>[:clean] do
+  sh %{cd ext && #{RUBY} extconf.rb && make}
+end
+
+desc "Build debug version of extension"
+task :build_debug=>[:clean] do
+  ENV['DEBUG'] = '1'
+  sh %{cd ext && #{RUBY} extconf.rb && make}
+end
+
+desc "Start an IRB shell using the extension"
+task :irb do
+  irb = ENV['IRB'] || File.join(RbConfig::CONFIG['bindir'], File.basename(RUBY).sub('ruby', 'irb'))
+  sh %{#{irb} -I ext -r date}
+end
+
+desc "Run comparative benchmarks"
+task :bench do
+  sh %{#{RUBY} bench/cpu_bench.rb}
+end
+
+desc "Run all benchmarks"
+task :bench_all => [:bench, :mem_bench, :garbage_bench]
+
+desc "Run comparative memory benchmarks"
+task :mem_bench do
+  if RUBY_PLATFORM =~ /win|w32/
+    puts "Memory benchmarks not supported on Windows"
+    next
+  end
+
+  stdlib = `#{RUBY} -I #{RbConfig::CONFIG['rubylibdir']} bench/mem_bench.rb`.to_i
+  home_run = `#{RUBY} -I ext bench/mem_bench.rb`.to_i
+  puts "Date memory use,#{stdlib}KB,#{home_run}KB,#{sprintf('%0.1f', stdlib/home_run.to_f)}"
+
+  stdlib = `#{RUBY} -I #{RbConfig::CONFIG['rubylibdir']} bench/dt_mem_bench.rb`.to_i
+  home_run = `#{RUBY} -I ext bench/dt_mem_bench.rb`.to_i
+  puts "DateTime memory use,#{stdlib}KB,#{home_run}KB,#{sprintf('%0.1f', stdlib/home_run.to_f)}"
+end
+
+desc "Run comparative garbage creation benchmarks"
+task :garbage_bench do
+  if RUBY_PLATFORM =~ /win|w32/
+    puts "Garbage creation benchmarks not supported on Windows"
+    next
+  end
+
+  stdlib = `#{RUBY} -I #{RbConfig::CONFIG['rubylibdir']} bench/garbage_bench.rb`.to_i
+  home_run = `#{RUBY} -I ext bench/garbage_bench.rb`.to_i
+  puts "Date garbage created,#{stdlib}KB,#{home_run}KB,#{sprintf('%0.1f', stdlib/home_run.to_f)}"
+
+  stdlib = `#{RUBY} -I #{RbConfig::CONFIG['rubylibdir']} bench/dt_garbage_bench.rb`.to_i
+  home_run = `#{RUBY} -I ext bench/dt_garbage_bench.rb`.to_i
+  puts "DateTime garbage created,#{stdlib}KB,#{home_run}KB,#{sprintf('%0.1f', stdlib/home_run.to_f)}"
+end