== mongrel_light_cluster GemPlugin

mongrel_light_cluster is an add-on for mongrel_cluster, and will automatically
and transparently make your Mongrel instances use less memory.

It does so by preloading Ruby on Rails and your application during
initialization. It will then create several child processes, each which
share memory with each other. See
http://izumi.plan99.net/blog/index.php/category/optimizing-rails/
for more detailed information.

IMPORTANT NOTES:
- This only works on Unix, not on Windows.
- This will only have effect if you apply the Ruby copy-on-write-friendly
  garbage collector patch.
- Beware that there are some gotchas for your application, so please read on.


== Installation

Run the following commands:

  rake
  gem install pkg/mongrel_light_cluster-0.1.gem


== Usage

You don't have to enable it manually. You only have to start mongrel_cluster
as you normally would:

  mongrel_rails cluster::start

mongrel_light_cluster will kick in automatically. In case something goes
wrong because of mongrel_light_cluster, you can disable it by setting the
environment variable DISABLE_MONGREL_LIGHT_CLUSTER=1


== Configuration

By default, mongrel_light_cluster preloads all .rb files in app/ and lib/,
and will preload all init.rb files in vendor/plugins/.
You can tell mongrel_light_cluster not to preload some files by specifying
'dont_preload' in config/mongrel_cluster.yml. Conversely, you can also tell
mongrel_light_cluster to preload some files (in different directories) by
specifying 'preload'.

You can also disable mongrel_light_cluster entirely by setting
'disable_mongrel_light_cluster' to true.

Here's an example of mongrel_cluster.yml:

  ---
  log_file: log/mongrel.log
  address: 127.0.0.1
  port: 3860
  pid_file: tmp/pids/mongrel.pid
  servers: 3
  environment: production
  preload:
    - my_secret_folder/*.rb
    - some_other_folder/**/*.rb
  dont_preload:
    - app/controller/hello_world_controller.rb
    - lib/dont_load_this.rb
  disable_mongrel_light_cluster: true


== Gotchas

mongrel_light_cluster will preload files in your application, so make sure
that you don't initialize things twice.

Suppose your application is located in /home/mike/shopsite. And your
application.rb contains this line:

  require 'shopsite_init'

Your lib/shopsite_init.rb looks like this:

  SHOPSITE_NAME = "My amazing shopping website"

mongrel_light_cluster preloads lib/shopsite_init.rb by requiring it with its
full path, like this:

  require '/home/mike/shopsite/lib/shopsite_init.rb'

Though your application.rb requires shopsite_init as well, it specifies a
different filename (only the base name instead of a full path), so Ruby will
think that you're requiring two different files, and will load
shopsite_init.rb again. Because of that, you will get an ugly
'constant already defined' warning during startup. So make sure you check
whether you're already initialized:

  SHOPSITE_NAME = "My amazing shopping website" if !defined?(SHOPSITE_NAME)