GBC Object Pool – Candlelight

Due to low interest, GBC Object Pool has been removed from the Solar2D Marketplace. If there is interest in the future, this product may be reinstated. The following is for reference only.

The GBC Object Pool plugin allows the Solar2D developer to easily and quickly implement object pooling within your application. Using two lines of code, you can create an object pool. GBC Object Pool optimizes the management of pooling, allowing for object reuse and eliminates garbage collection inherently found with traditional create/destroy functions.

Features

Eliminates the complexity of managing object pools.
Optimized for fast access to your pools.
Support for physics objects.
Reduces bottlenecks of traditional create and destroy methods.
Reduces / eliminates garbage collection since objects are reused.

Set Up

First thing is to activate the plugin within the Corona Marketplace.

In your application’s build.settings file, include the reference to the plugin:

plugins = {  
    ["plugin.GBCObjectPool"] = {
        publisherId = "com.gamesbycandlelight",
    },
}

Be sure to require the plugin in each module where you require pooling:

local GBCDataCabinet = require("plugin.GBCOPbjectPool")

ibrary

GBCObjectPool.init(createFunction, returnFunction)

createFunction: name of function where a single instance of your object is created.
returnFunction: (Optional) name of function that handles resetting returned objects.

Initializes a new pool.

createFunction is required and is a function that will create and return a single instance of the object you want to pool. See the sample code below, and the pooling example, for more details.

returnFunction is optional and is generally used to reset and changes to the object during its life. For example, if you change the scale size of an image, and then return it to the pool, it is good practice to reset the scale size so it is ready when the object is pulled from the pool in the future.

Returns a key to a pool. This key will be used in all future calls to this pool.

GBCObjectPool.create(key, count, autoExpandCount, isPhysicsEnabled, params)

key: The key of the pool. This value was returned from the init() call.
count: The number of objects to create in this pool.
autoExpandCount: (Optional, default = 0) The number of objects to create when the pool runs dry.
isPhysicsEnabled: (Optional, default = false) Do the objects in this pool have physics properties attached?
params: (Optional) A table of key/value pairs that can be passed into your create function.

GBCObjectPool.create() will create the objects (using the function that you specified in the init call) and will place them in the pool, so that you can use them in the future. count will specify how many objects to create, and all objects in the pool will be unused once created.

If autoExpandCount is a value greater than zero, GBC Object Pool will automatically create additional objects in this pool if needed.

If isPhysicsEnabled is true, GBC object Pool will assume that the objects have been created with physics properties (addBody, etc).

Optionally, you can pass a table of key/value pairs into your create function, which can be used for any purpose. This table of parameters will be saved with your object pool and can be later used when you autoexpand the pool, or return objects to the pool.

The primary reason for parameter passing would be to minimize the number of create functions needed to manage your pools. For more detail on using parameters, check out this blog entry (coming soon).

GBCObjectPool.get(key, delayDisplay, delayPhysics)

Gets a single unused object from the pool.

key: The key of the pool.
delayDisplay: (Optional, default = false) Do not enable object when returned.
delayPhysics: (Optional, default = false) Do not enable physics on this object when returned.

If delayDisplay is false (default), the object will be visible when returned. If delayDisplay is true, the object will not be displayed automatically. You can display the object using object.isVisible = true.

If delayPhysics is false (default), physics will be enabled on the object when returned (if isPhysicsEnabled was set when creating the pool). If delayPhysics is true, physics will not be enabled when returned. You can enabled physics with object.isBodyActive = true.

Note that objects that are returned with delayDisplay = false and delayPhysics = false will allow you to set properties (x and y location for example). These two features are useful if you wish to manually handle this in your game, for a variety of reasons.

Returns a single instance of an unused object from the pool, or nil if no unused objects exists (and autoExpandCount = 0)

GBCObjectPool.put(key, object)

key: The key to the pool.
object: The specific object to return to the pool

Makes the object available for reuse by placing back into the pool. Note GBCObjectPool.put() will attempt to clean up a bit:

any transitions are cancelled
physics will be disabled
object will be removed from screen

Any other changes, for example changing the objects scale or image, will need to be handled by you. GBCObjectPool.put() will call returnFunction you passed in the init() call, and this is where you would place code to reset the object.

Note that put will also pass any previously stored parameters to your return function. This will be useful in some instances where you wish to simplify the number of return functions needed to manage multiple pools. For more information, please check out this blog entry (coming soon).

GBCObjectPool.delete(key)

Removes all objects from a pool. The result is that the pool, along with all objects in this pool, will no longer exist.

key: Key to the pool.

GBCObjectPool.getStatus(key)

key: Key to the pool.

Returns the following information in a table:

“used” – Number of currently used objects in the pool.
“unused” – Number of currently unused objects in the pool.
“total” – Total number of objects in the pool.

GBCObjectPool.setDebugMode(enableDebug, enableVerbose)

Enables debug mode. Messages will be displayed in the console.

enableDebug: If true, messages will be displayed in the console.

enableVerbose: If true, and if enableDebug is also true, will also display messages when objects are taken from and placed into the pool.

Note: Displaying messages when objects are taken from (via get) and placed into (via put) the pool may significantly impact performance. Use enableVerbose with caution, and be sure to disable all debugging when compiling a production version of your app.

Sample Code

I have created an app that contains multiple examples using GBC Object Pool which is available here: GBC Object Pool Example Project.

Below is a few code examples on how to use GBC Object Pool.

To create a pool of objects, you need a function that create a single instance of the object, and pass that function into the initialization routine.

-- This creates a single red square
-- Make sure you return the object!
local function createObject()
    local obj = display.newRect(-100, -100, 32, 32)
    obj:setFillColor(1,0,0)
    return obj
end

-- Initialize a pool and create 10 objects
local objPool = GBCObjectPool.init(createObject)
GBCObjectPool.create(objPool, 10) 

-- objPool now contains 10 red squares

Using put and get:

local myObject = GBCObjectPool.get(objPool)

if myObject ~= nil then
    -- do some stuff with this object
end

-- later on...

GBCObjectPool.put(objPool, myObject)

References

Tricks and Tips

After using get() to request an object from a pool, be sure to check that the value returned is not nil before setting properties or referring to the object. You can see an example above.
Not everything you change on an object requires resetting in your reset function. For example if you change the color of an item every time you get() it, you can leave it that way when using put(). A good practice would be to reset everything you change, regardless.
Other more persistent changes, scaling an object, for example, will require a reset in your reset function. If not, object reuse will show unexpected results.