• This repository has been archived on 24/Jun/2022
  • Stars
    star
    466
  • Rank 94,089 (Top 2 %)
  • Language
    Ruby
  • License
    Other
  • Created about 14 years ago
  • Updated over 11 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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:

#                 | 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 (using Sequel), 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¶ ↑

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 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 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.

Known incompatibilities¶ ↑

Some other libraries are known to be incompatible with this extension due to the above differences:

  • ActiveSupport 3.1 - DateTime#<=> broken because it relies on Date#<=> working for DateTimes.

  • Date::Performance - Date#<=> assumes @ajd instance variable (unnecessary anyway, as home_run is faster)

  • Runt - assumes @ajd instance variable

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

  • rake-compiler

  • 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.

  • Ragel 6.5+ if you want to modify the ragel parser.

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¶ ↑

  • 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)

Compiler Versions¶ ↑

  • gcc (3.3.5, 4.0.1, 4.2.1, 4.4.3, 4.5.0)

  • Sun Studio Compiler (5.9)

Ruby Versions¶ ↑

  • jruby cext branch (as of commit 1969c504229bfd6f2de1, 2010-08-23, compiles 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:

* 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

Author¶ ↑

Jeremy Evans <[email protected]>

More Repositories

1

sequel

Sequel: The Database Toolkit for Ruby
Ruby
4,818
star
2

rodauth

Ruby's Most Advanced Authentication Framework
Ruby
1,550
star
3

erubi

Small ERB Implementation
Ruby
373
star
4

forme

HTML forms library for ruby
Ruby
291
star
5

ruby-warning

Add custom processing for warnings
Ruby
281
star
6

roda-sequel-stack

Application Skeleton For Roda/Sequel stack
Ruby
262
star
7

sequel_pg

Faster SELECTs when using Sequel with pg
C
258
star
8

ruby-refrigerator

Freeze all core ruby classes
Ruby
198
star
9

ruby-american_date

American style month/day/year parsing for ruby 1.9+
Ruby
108
star
10

by

Ruby Library Preloader
Ruby
101
star
11

sequel_postgresql_triggers

Database enforced timestamps, immutable columns, and counter/sum caches
Ruby
97
star
12

minitest-hooks

Around and before_all/after_all/around_all hooks for Minitest
Ruby
89
star
13

rack-unreloader

Rack Application that reloads application files if changed, unloading constants first
Ruby
88
star
14

autoforme

Web Administrative Console for Roda/Sinatra/Rails and Sequel::Model
Ruby
62
star
15

scaffolding_extensions

Ruby Web Admin Front-End :: Unmaintained, use AutoForme instead
Ruby
57
star
16

zozo

Simple $LOAD_PATH management for ruby projects :: Unmaintained
Ruby
49
star
17

aqualung

Advanced music player
C
48
star
18

fixture_dependencies

Sequel/ActiveRecord fixture loader that handles dependency graphs
Ruby
45
star
19

third_base

A Fast and Easy Date/DateTime Class for Ruby :: Unmaintained, use home_run instead.
Ruby
39
star
20

giftsmas

Gift Tracking Website using Roda and Sequel
Ruby
36
star
21

simple_orm_benchmark

A small benchmark test for ruby ORMs.
Ruby
31
star
22

spam

Simple Personal Accounting Manager
Ruby
30
star
23

tilt

Generic interface to multiple Ruby template engines
Ruby
30
star
24

simple_ldap_authenticator

Simple authentication for Ruby using LDAP
Ruby
29
star
25

roda-route_list

List routes when using Roda
Ruby
27
star
26

ruby-pledge

Ruby Interface to OpenBSD pledge(2) system call
Ruby
26
star
27

kaeruera

Simple Error Tracker for Ruby
Ruby
24
star
28

roda-rails

Integration for using Roda as Rack middleware in a Rails app
Ruby
21
star
29

thamble

Create HTML Tables from Enumerables
Ruby
18
star
30

exception_notification

Gemified exception_notification rails plugin, compatible with Rails 2.3.5 with the RailsXss plugin :: Unmaintained
Ruby
17
star
31

roda-message_bus

MessageBus integration for Roda
Ruby
17
star
32

evilr

Do things you shouldn't ::Unmaintained
Ruby
13
star
33

rack-indifferent

Fast indifferent access to request params
Ruby
13
star
34

ruby-subset_sum

Simple Subset Sum Solver with C and Pure Ruby Versions
Ruby
12
star
35

ruby-style

Supervised TCPServer, Yielding Listeners Easily :: Unmaintained, switch to Unicorn or Rainbows!
Ruby
12
star
36

ape_tag_libs

Libaries for reading/writing APEv2 tags in many languages
C
11
star
37

gcit2ghi

Imports issues from Google Code Issue Tracker to GitHub Issues :: Unmaintained
Ruby
11
star
38

rack-deadline

Automatically clears sessions open too long
Ruby
11
star
39

minitest-parallel_fork

Fork-based parallelization for minitest
Ruby
11
star
40

ruby-deprecate_public

Warn when calling private methods via public interface
Ruby
11
star
41

cspvr

Content-Security-Policy Violation Recorder
Ruby
10
star
42

unicorn-lockdown

Helper library for running Unicorn on OpenBSD with chroot, privdrop, fork+exec, and pledge
Ruby
9
star
43

visibility_checker

Detect method visibility changes
Ruby
9
star
44

minitest-shared_description

Support for shared specs and shared spec subclasses for Minitest
Ruby
8
star
45

jpm

Password manager using openssl/signify
Ruby
8
star
46

sequel-mongo

Proof of Concept MongoDB Driver for Sequel (Do not use in production)
Ruby
7
star
47

quinto

Quinto server and client
Ruby
7
star
48

capybara-validate_html5

Validate HTML5 for each page accessed when testing with capybara
Ruby
7
star
49

minitest-global_expectations

Support minitest expectation methods for all objects
Ruby
6
star
50

simple_mailer

Simple email library with testing support
Ruby
6
star
51

roda-opal-example

Example of Using Roda with Opal
Ruby
6
star
52

rodauth-demo-rails

Rodauth's demo site ported to Rails, showing Rodauth/Rails integration
Ruby
5
star
53

enum_csv

Create CSV from Enumerables
Ruby
5
star
54

tilt-pipeline

Easily construct rendering pipelines using tilt
Ruby
5
star
55

lila_shell

Simple chat app using roda-message_bus
JavaScript
5
star
56

ruby-scgi

Simple support for using SCGI in ruby apps, such as Rails :: Unmaintained
Ruby
5
star
57

ruby-string-crypt

Backward compatible implementation of String#crypt
C
4
star
58

gg2ghd

Import Extract from Google Groups into GitHub Discussions
Ruby
4
star
59

tagged-ruby-bugs

Tagged Open Ruby Bugs
Ruby
3
star
60

openbsd-ruby-ports

Ports for Ruby Versions Removed from OpenBSD ports tree
Makefile
3
star
61

ruby-vorbis_comment

Ruby library for reading/writing vorbis comments
C
3
star
62

erubis

Git repository for http://www.kuwata-lab.com/erubis/
HTML
3
star
63

hs-SubsetSum

Subset sum problem solver for haskell
Haskell
3
star
64

tilt-rails_erb

Adds support for Rails' ERB templates to Tilt
Ruby
2
star
65

slab

Tutorial for building an OCR web application
Ruby
2
star
66

jeremyevans.github.com

Personal Website
HTML
2
star
67

sacruby

Various code related to the Sacramento Ruby Meetup
Ruby
2
star
68

sequel_validation_helpers_block

Allows easy determination of which validation rules apply to a given column, at the expense of increased verbosity
Ruby
2
star
69

sequel-impala

Support for Sequel to access the Impala database
1
star
70

mp3applygain

Apply gain information to mp3 audio data
C
1
star
71

openbsd-postgresql-ports

Ports for old PostgreSQL versions removed from the OpenBSD ports tree
Shell
1
star
72

faster_html_escape

Archive of old faster_html_escape gem
C
1
star
73

sequel-unsplit

Ruby code rewriter that replaces symbols containing embedded qualification/aliasing with equivalent Sequel code
Ruby
1
star
74

aqualung-scrobbler

last.fm scrobbler for Aqualung
Shell
1
star
75

rubyconflt2016-presentation

Presentation Source Code for my RubyConfLT 2016 presentation on Rodauth (runs on my showoff fork)
CSS
1
star
76

tilt-indirect

Adds indirection for tilt templates
Ruby
1
star
77

jeremyevans_github_hook_processor

Processor for GitHub webhooks for my repositories
Ruby
1
star
78

falcomcdcatalog

Falcom CD Catalog - English Edition
HTML
1
star
79

serverside

Ruby web framework from which Sequel was extracted
Ruby
1
star
80

tame_libs

programming language wrappers for OpenBSD's tame(2) system call
Ruby
1
star
81

capybara-restore_state

Restore capybara state after block execution
Ruby
1
star
82

openbsd-mariadb-ports

Ports for newer versions of MariaDB for OpenBSD
Makefile
1
star