The garbage collector distributed with ruby tries to adapt memory
usage to the amount of memory used by the program, dynamically growing
or shrinking the allocated heap as it sees fit.

For long running server apps this doesn't really work very well. The
performance very much depends on the ratio heap size/program size. It
behaves somewhat erratic: adding code can actually make your program
run faster.

The supplied patch fixes this problem: it allows one to specify the
initial heap size to start with. Heap size will never drop below the
initial size. By carefully selecting the initial heap size one can
decrease startup time and increase throughput of server apps.

There are 4 patches for different versions of Ruby:
   rubygc184.patch     Ruby 1.8.4 (but will apply to 1.82 as well)
   rubygc185.patch     Ruby 1.8.5
   rubygc186.patch     Ruby 1.8.6
   rubygc19.patch      Ruby 1.9

Heap size and other options are controlled through environment
variables:

RUBY_HEAP_MIN_SLOTS
    - the initial heap size in number of slots used

RUBY_HEAP_SLOTS_INCREMENT
    - how many additional slots to allocate when Ruby allocates
      new heap slots

RUBY_HEAP_SLOTS_GROWTH_FACTOR
    - multiplicator used to increase heap block size for the next
      allocation.

RUBY_GC_MALLOC_LIMIT
    - the amount of C data structures which can be allocated
      without triggering a GC (if this is set too low, GC will be
      started even if there are empty slots available)

RUBY_HEAP_FREE_MIN
    - number of free slots that should be available after GC
      if fewer slots are available, additional heap will be allocated
      (Ruby >= 1.8.5 ensures the freelist has at least heapsize*0.2 entries)

The following values make the patched GC behave like the unpatched GC:

RUBY_HEAP_MIN_SLOTS=10000
RUBY_HEAP_SLOTS_INCREMENT=10000
RUBY_HEAP_SLOTS_GROWTH_FACTOR=1.8
RUBY_GC_MALLOC_LIMIT=8000000
RUBY_HEAP_FREE_MIN=4096

Try experimenting with these values. You can use perf_run_gc to find
out how many slots you need.

Memory usage of the ruby interpreter can be observed by setting
RUBY_GC_STATS=1, before you invoke any of the railsbench commands.

Per default, GC data gets written to stderr. You can change this
behavior by setting environment variable RUBY_GC_DATA_FILE.

Additionally, the Ruby module GC gets some new methods:

GC.enable_stats   - enable GC statistics collection
GC.disable_stats  - disable GC statistics collection
GC.clear_stats    - reset GC statistics
GC.collections    - number of collections since stats have been enabled
GC.time           - GC time used since stats have been enabled (miro seconds)
GC.dump           - dumps current heap topology to the GC log file
GC.log            - log given string to the GC log file

railsbench detects whether the patch has been applied and provides
GC statistics only in this case.
