Re: ANN: home_run 0.9.1 Released

We are very appreciative of the extra effort to make sure home_run
works on JRuby's cext branch. We plan to ship JRuby 1.6 with support
for C extensions, at least at a beta/experimental level.

We also hope someone will step up to write a Java-based version of
this library, probably using JodaTime (which we ship with JRuby) as
the base. C extensions are part of JRuby's long-term plan, but they
have many limitations (such as inability to support multiple JRuby
runtimes or concurrent execution), and eventually apps will want a
Java version that does not have the same issues.

Thanks for a great library and for the JRuby support, Jeremy :)

- Charlie

On Wed, Sep 1, 2010 at 4:16 PM, Jeremy Evans <[e-mail]> wrote:
> =3D 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.
>
> =3D=3D Performance increase (microbenchmarks)
>
> The speedup you'll get depends mostly on your version of ruby, but
> also on your operating system, platform, and compiler. =C2=A0Here are
> some comparative results for common methods:
>
> =C2=A0# =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 | i386 =
=C2=A0| i386 =C2=A0| i386 =C2=A0| i386 =C2=A0| amd64 |
> =C2=A0# =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 |Windows|=
 Linux | Linux | Linux |OpenBSD|
> =C2=A0# =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 | 1.8.6 |=
 1.8.7 | 1.9.1 | 1.9.2 | 1.9.2 |
> =C2=A0# =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 |-------+=
-------+-------+------ +-------|
> =C2=A0Date.civil =C2=A0 =C2=A0 =C2=A0 =C2=A0| =C2=A0 82x | =C2=A0 66x | =
=C2=A027x =C2=A0| =C2=A021x =C2=A0| =C2=A014x =C2=A0|
> =C2=A0Date.parse =C2=A0 =C2=A0 =C2=A0 =C2=A0| =C2=A0 56x | =C2=A0 56x | =
=C2=A033x =C2=A0| =C2=A030x =C2=A0| =C2=A025x =C2=A0|
> =C2=A0Date.today =C2=A0 =C2=A0 =C2=A0 =C2=A0| =C2=A0 17x | =C2=A0 =C2=A06=
x | =C2=A0 2x =C2=A0| =C2=A0 2x =C2=A0| =C2=A0 2x =C2=A0|
> =C2=A0Date.strptime =C2=A0 =C2=A0 | =C2=A0 43x | =C2=A0 62x | =C2=A063x =
=C2=A0| =C2=A037x =C2=A0| =C2=A023x =C2=A0|
> =C2=A0DateTime.civil =C2=A0 =C2=A0| =C2=A0252x | =C2=A0146x | =C2=A052x =
=C2=A0| =C2=A041x =C2=A0| =C2=A017x =C2=A0|
> =C2=A0DateTime.parse =C2=A0 =C2=A0| =C2=A0 52x | =C2=A0 54x | =C2=A032x =
=C2=A0| =C2=A027x =C2=A0| =C2=A020x =C2=A0|
> =C2=A0DateTime.now =C2=A0 =C2=A0 =C2=A0| =C2=A0 78x | =C2=A0 35x | =C2=A0=
11x =C2=A0| =C2=A0 8x =C2=A0| =C2=A0 4x =C2=A0|
> =C2=A0DateTime.strptime | =C2=A0 63x | =C2=A0 71x | =C2=A058x =C2=A0| =C2=
=A035x =C2=A0| =C2=A023x =C2=A0|
> =C2=A0Date#strftime =C2=A0 =C2=A0 | =C2=A0156x | =C2=A0104x | 110x =C2=A0=
| =C2=A070x =C2=A0| =C2=A062x =C2=A0|
> =C2=A0Date#+ =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| =C2=A0 34x | =C2=
=A0 32x | =C2=A0 5x =C2=A0| =C2=A0 5x =C2=A0| =C2=A0 4x =C2=A0|
> =C2=A0Date#<< =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 | =C2=A0177x | =C2=A0220=
x | =C2=A086x =C2=A0| =C2=A072x =C2=A0| =C2=A040x =C2=A0|
> =C2=A0Date#to_s =C2=A0 =C2=A0 =C2=A0 =C2=A0 | =C2=A0 15x | =C2=A0 =C2=A06=
x | =C2=A0 5x =C2=A0| =C2=A0 4x =C2=A0| =C2=A0 2x =C2=A0|
> =C2=A0DateTime#strftime | =C2=A0146x | =C2=A0107x | 114x =C2=A0| =C2=A071=
x =C2=A0| =C2=A060x =C2=A0|
> =C2=A0DateTime#+ =C2=A0 =C2=A0 =C2=A0 =C2=A0| =C2=A0 34x | =C2=A0 37x | =
=C2=A0 8x =C2=A0| =C2=A0 6x =C2=A0| =C2=A0 3x =C2=A0|
> =C2=A0DateTime#<< =C2=A0 =C2=A0 =C2=A0 | =C2=A0 88x | =C2=A0106x | =C2=A0=
40x =C2=A0| =C2=A033x =C2=A0| =C2=A016x =C2=A0|
> =C2=A0DateTime#to_s =C2=A0 =C2=A0 | =C2=A0144x | =C2=A0 47x | =C2=A054x =
=C2=A0| =C2=A029x =C2=A0| =C2=A024x =C2=A0|
>
> =3D=3D 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 (using Sequel), first without home_run,
> and then with home_run.
>
> =C2=A0$ script/console production
> =C2=A0Loading production environment (Rails 2.3.5)
> =C2=A0>> require 'benchmark'
> =C2=A0=3D> false
> =C2=A0>> puts Benchmark.measure{Employee.all}
> =C2=A0 =C2=A00.270000 =C2=A0 0.020000 =C2=A0 0.290000 ( =C2=A00.460604)
> =C2=A0=3D> nil
> =C2=A0>> puts Benchmark.measure{Notification.all}
> =C2=A0 =C2=A02.510000 =C2=A0 0.050000 =C2=A0 2.560000 ( =C2=A02.967896)
> =C2=A0=3D> nil
>
> =C2=A0$ home_run script/console production
> =C2=A0Loading production environment (Rails 2.3.5)
> =C2=A0>> require 'benchmark'
> =C2=A0=3D> false
> =C2=A0>> puts Benchmark.measure{Employee.all}
> =C2=A0 =C2=A00.100000 =C2=A0 0.000000 =C2=A0 0.100000 ( =C2=A00.114747)
> =C2=A0=3D> nil
> =C2=A0>> puts Benchmark.measure{Notification.all}
> =C2=A0 =C2=A00.860000 =C2=A0 0.010000 =C2=A0 0.870000 ( =C2=A00.939594)
>
> Without changing any application code, there's a 4x
> increase when retrieving all employees, and a 3x
> increase when retrieving all notifications. =C2=A0The
> main reason for the performance difference between
> these two models is that Employee has 5 date columns,
> while Notification only has 3.
>
> =3D=3D Installing the gem
>
> =C2=A0gem install home_run
>
> The standard gem requires compiling from source, so you need a working
> compiler toolchain. =C2=A0Since few Windows users have a working compiler
> toolchain, a windows binary gem is available that works on both 1.8
> and 1.9.
>
> =3D=3D 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:
>
> =C2=A0home_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:
>
> =C2=A0home_run --uninstall
>
> =3D=3D 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:
>
> =C2=A0home_run ruby ...
> =C2=A0home_run irb ...
> =C2=A0home_run unicorn ...
> =C2=A0home_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:
>
> =C2=A0require 'home_run'
>
> This should only be used as a last resort. =C2=A0Because rubygems require=
s
> 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.
>
> =3D=3D Running the specs
>
> You can run the rubyspec based specs after installing the gem, if
> you have MSpec installed (gem install mspec):
>
> =C2=A0home_run --spec
>
> If there are any failures, please report them as a bug.
>
> =3D=3D Running comparative benchmarks
>
> You can run the benchmarks after installing the gem:
>
> =C2=A0home_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:
>
> =C2=A0Date._parse,362562,10235,35.42
>
> means that:
>
> * The standard library's Date._parse averaged 362,562 nanoseconds
> =C2=A0per 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.
>
> =3D=3D Usage
>
> home_run aims to be compatible with the standard library, except
> for differences mentioned below. =C2=A0So you can use it the same way
> you use the standard library.
>
> =3D=3D Differences from standard library
>
> * Written in C (mostly) instead of ruby. =C2=A0Stores information in a
> =C2=A0C structure, and therefore has a range limitation. =C2=A0home_run
> =C2=A0cannot handle dates after 5874773-08-15 or before -5877752-05-08
> =C2=A0on 32-bit platforms (with larger limits for 64-bit platforms).
> * The Date class does not store fractional days (e.g. hours, minutes),
> =C2=A0or offsets. The DateTime class does handle fractional days and
> =C2=A0offsets.
> * The DateTime class stores fractional days as the number of
> =C2=A0nanoseconds since midnight, so it cannot deal with differences
> =C2=A0less than a nanosecond.
> * Neither Date nor DateTime uses rational. =C2=A0Places where the standar=
d
> =C2=A0library returns rationals, home_run returns integers or floats.
> * Because rational is not used, it is not required. =C2=A0This can break
> =C2=A0other libraries that use rational without directly requiring it.
> * There is no support for modifying the date of calendar reform, the
> =C2=A0sg arguments are ignored and the Gregorian calendar is always used.
> =C2=A0This 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
> =C2=A0does not support offsets with an absolute difference of more than
> =C2=A014 hours from UTC.
> * DateTime offsets are stored in minutes, so it will round offsets
> =C2=A0with fractional minutes to the nearest minute.
> * All public class and instance methods for both Date and DateTime
> =C2=A0are implemented, except that the allocate class method is not
> =C2=A0available and on 1.9, _dump and _load are used instead of
> =C2=A0marshal_dump and marshal_load.
> * Only the public API is compatible, the private methods in the
> =C2=A0standard library are not implemented.
> * The marshalling format differs from the one used by the standard
> =C2=A0library. =C2=A0Note that the 1.8 and 1.9 standard library date
> =C2=A0marshalling formats differ from each other.
> * Date#step treats the step value as an integer, so it cannot handle
> =C2=A0steps of fractional days. =C2=A0DateTime#step can handle fractional
> =C2=A0day steps, though.
> * When parsing the %Q modifier in _strptime, the hash returned
> =C2=A0includes an Integer :seconds value and a Float :sec_fraction
> =C2=A0value instead of a single rational :seconds value.
> * The string returned by #inspect has a different format, since it
> =C2=A0doesn't use rational.
> * The conversion of 2-digit years to 4-digit years in Date._parse
> =C2=A0is set to true by default. =C2=A0On ruby 1.8, the standard library
> =C2=A0has it set to false by default.
> * You can use the Date::Format::STYLE hash to change how to parse
> =C2=A0DD/DD/DD and DD.DD.DD date formats, allowing you to get ruby 1.9
> =C2=A0behavior on 1.8 or vice-versa. =C2=A0This is probably the only new
> =C2=A0feature 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.
>
> =3D=3D Known incompatibilities
>
> Some other libraries are known to be incompatible with this
> extension due to the above differences:
>
> * Date::Performance - Date#<=3D> assumes @ajd instance variable
> =C2=A0(unnecessary anyway, as home_run is faster)
> * ruby-ole - Depends on DateTime.allocate/#initialize
>
> =3D=3D Reporting issues/bugs
>
> home_run uses GitHub Issues for tracking issues/bugs:
>
> =C2=A0http://github.com/jeremyevans/home_run/issues
>
> =3D=3D Contributing
>
> The source code is on GitHub:
>
> =C2=A0http://github.com/jeremyevans/home_run
>
> To get a copy:
>
> =C2=A0git clone git://github.com/jeremyevans/home_run.git
>
> There are a few requirements:
>
> * rake
> * rake-compiler
> * MSpec (not RSpec) for running the specs. =C2=A0The specs are based on
> =C2=A0the rubyspec specs, which is why they use MSpec.
> * RDoc 2.5.10+ if you want to build the documentation.
> * Ragel 6.5+ if you want to modify the ragel parser.
>
> =3D=3D Compiling
>
> To compile the library from a git checkout, after installing the
> requirements:
>
> =C2=A0rake compile
>
> =3D=3D Testing
>
> The default rake task runs the specs, so just run:
>
> =C2=A0rake
>
> You need to compile the library and install MSpec before running the
> specs.
>
> =3D=3D Benchmarking
>
> To see the speedup that home_run gives you over the standard library:
>
> =C2=A0rake bench
>
> To see how much less memory home_run uses compared to the standard
> library:
>
> =C2=A0rake mem_bench
>
> To see how much less garbage is created when instantiating objects
> with home_run compared to the standard library:
>
> =C2=A0rake garbage_bench
>
> If you want to run all three benchmarks at once:
>
> =C2=A0rake bench_all
>
> =3D=3D Platforms Supported
>
> home_run has been tested on the following:
>
> =3D=3D=3D Operating Systems/Platforms
>
> * Linux (x86_64, i386)
> * Mac OS X 10.6 (x86_64, i386), 10.5 (i386)
> * OpenBSD (amd64, i386)
> * Solaris 10 (sparc)
> * Windows XP (i386)
> * Windows 7 (x64)
>
> =3D=3D=3D Compiler Versions
>
> * gcc (3.3.5, 4.0.1, 4.2.1, 4.4.3, 4.5.0)
> * Sun Studio Compiler (5.9)
>
> =3D=3D=3D Ruby Versions
>
> * jruby cext branch (as of commit 1969c504229bfd6f2de1, 2010-08-23,
> =C2=A0compiles and runs specs correctly, segfaults on benchmarks)
> * rbx head (as of commit 0e265b92727cf3536053, 2010-08-16)
> * ruby 1.8.6 (p0, p110, 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:
>
> =C2=A0* Your operating system and platform (e.g. i386, x86_64/amd64)
> =C2=A0* Your compiler
> =C2=A0* Your ruby version
> =C2=A0* The output of home_run --spec
> =C2=A0* The output of home_run --bench
>
> =3D=3D Author
>
> Jeremy Evans <[e-mail]>
> --
> Posted via http://www.ruby-forum.com/.
>
>