Last Modified
  2012-02-08 11:20:54 +0000
Requires
  - thread

## Description

# Multiton

## Synopsis

Multiton design pattern ensures only one object is allocated for a given state.

The 'multiton' pattern is similar to a singleton, but instead of only one instance, there are several similar instances. It is useful when you want to avoid constructing objects many times because of some huge expense (connecting to a database for example), require a set of similar but not identical objects, and cannot easily control how many times a contructor may be called.

    class SomeMultitonClass
      include Multiton
      attr :arg
      def initialize(arg)
        @arg = arg
      end
    end

    a = SomeMultitonClass.new(4)
    b = SomeMultitonClass.new(4)   # a and b are same object
    c = SomeMultitonClass.new(2)   # c is a different object

## Previous Behavior

In previous versions of Multiton the new method was made private and instance had to be used in its stay --just like Singleton. But this is less desirable for Multiton since Multitions can have multiple instances, not just one.

So instead Multiton now defines create as a private alias of the original new method (just in case it is needed) and then defines new to handle the multiton; instance is provided as an alias for it.

## How It Works

A pool of objects is searched for a previously cached object, if one is not found we construct one and cache it in the pool based on class and the args given to the contructor.

A limitation of this approach is that it is impossible to detect if different blocks were given to a contructor (if it takes a block). So it is the constructor arguments only which determine the uniqueness of an object. To workaround this, define the class method ::multiton_id.

    def SomeMultitonClass.multiton_id(*args, &block)
      # ...
    end

Which should return a hash key used to identify the object being constructed as (not) unique.

## Authors

- Christoph Rippel

- Thomas Sawyer

# Copying

Copyright (c) 2007 Christoph Rippel, Thomas Sawyer

Ruby License

This module is free software. You may use, modify, and/or redistribute this software under the same terms as Ruby.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.