Fast Date/DateTime classes for ruby :: Unmaintained, unnecessary on ruby 1.9.3+
Fast Date/DateTime classes for ruby :: Unmaintained, unnecessary on ruby 1.9.3+
= 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.
== Not necessary in 1.9.3+
Ruby 1.9.3+ replaced the old date library with one written in C, based partially on the design of home_run (but implemented differently). In most cases, if you are using Ruby 1.9.3+, you will not need to use home_run.
== 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:
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#> 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
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
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.
You can also just require the library:
require 'home_run'
This should only be used as a last resort. Because rubygems requires date, you can end up with situations where the Date instances created before the require use the standard library version of Date, while the Date instances created after the require use this library's version. However, in some cases (such as on Heroku), this is the only way to easily use this library. If you need to do this and you are using Rails 3, make sure you require home_run before rails/all in config/application.rb.
== Usage with bundler
Use the following in your Gemfile:
gem 'home_run', :require=>'date'
You need the :require option because otherwise it will require 'home_run', which can lead to problems.
== Running the specs
You can run the rubyspec based 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 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
Any other differences will either be documented here or considered bugs, so please report any other differences you find.
== Known incompatibilities
Some other libraries are known to be incompatible with this extension due to the above differences:
== 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:
== Compiling
To compile the library from a git checkout, after installing the requirements:
rake compile
== Testing
The default rake task runs the specs, so just run:
rake
You need to compile the library and install MSpec 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
=== Compiler Versions
=== Ruby Versions
If your platform, compiler version, or ruby version is not listed above, please test and send me a report including:
== Author
Jeremy Evans
No open issues yet, or sync has not completed.