/traderous

-- Class: Factory

-- A factory allows for simple object pooling; that is,

-- reusing object instances instead of creating them and deleting

-- them as needed. This approach saves CPU and memory.

--

-- Be careful of accidentally adding an instance to a view twice.

-- This will manifest itself as the sprite moving twice as fast, for

-- example, each time it is recycled. The easiest way to avoid this

-- problem is for the object to add itself to the view in its onNew

-- handler, since that will only be called once.

--

-- If you only want a certain number of instances of a class ever

-- created, first call preload() to create as many instances as you want,

-- then freeze() to prevent any new instances from being created.

-- If a factory is ever asked to make a new instance of a frozen class

-- but none are available for recycling, it returns nil.

--

-- Event: onReset

-- Called not on the factory, but the object is creates whenever

-- it is either initially created or recycled via create(). 

--

-- Extends:

--		<Class>

Factory = Class:extend{

	-- private property: objects ready to be recycled, stored by prototype

	_recycled = {},

	-- private property: tracks which pools cannot be added to, stored by prototype.

	_frozen = {},

	-- Method: create

	-- Creates a fresh object, either by reusing a previously

	-- recycled one or creating a new instance. If the object has

	-- a revive method, it calls it.

	--

	-- Arguments:

	--		prototype - <Class> object

	--		props - table of properties to mix into the class

	--

	-- Returns:

	-- 		fresh object

	create = function (self, prototype, props)

		local newObj

		if STRICT then

			assert(prototype.instanceOf and prototype:instanceOf(Class), 'asked to create something that isn\'t a class')

		end

		if self._recycled[prototype] and #self._recycled[prototype] > 0 then

			newObj = table.remove(self._recycled[prototype])

			if props then newObj:mixin(props) end

		else

			-- create a new instance if we're allowed to

			if not self._frozen[prototype] then

				newObj = prototype:new(props)

			else

				return nil

			end

		end

		if newObj.revive then newObj:revive() end

		if newObj.onReset then newObj:onReset() end

		return newObj

	end,

	-- Method: recycle

	-- Marks an object as ready to be recycled. If the object

	-- has a die method, then this function it.

	--

	-- Arguments:

	-- 		object - object to recycle

	--

	-- Returns:

	--		nothing

	recycle = function (self, object)

		if not self._recycled[object.prototype] then

			self._recycled[object.prototype] = {}

		end

		table.insert(self._recycled[object.prototype], object)

		if object.die then object:die() end

	end,

	-- Method: preload

	-- Preloads the factory with a certain number of instances of a class.

	--

	-- Arguments:

	--		prototype - class object

	--		count - number of objects to create

	--

	-- Returns:

	--		nothing

	preload = function (self, prototype, count)

		if not self._recycled[prototype] then

			self._recycled[prototype] = {}

		end

		local i

		for i = 1, count do

			table.insert(self._recycled[prototype], prototype:new())

		end

	end,

	-- Method: freeze

	-- Prevents any new instances of a class from being created via create().

	--

	-- Arguments:

	-- 		prototype - class object

	--

	-- Returns:

	--		nothing

	freeze = function (self, prototype)

		self._frozen[prototype] = true

	end,

	-- Method: unfreeze

	-- Allows new instances of a class to be created via create().

	--

	-- Arguments:

	--		prototype - class object

	--

	-- Returns:

	--		nothing

	unfreeze = function (self, prototype)

		self._frozen[prototype] = false

	end

}