It is interesting that there are not many good pooling tutorials available on the internet, This small tutorial will introduce one of the many methods of implementing a simple, general purpose object pool that is relatively fast.
My experience with Java is somewhat limited, I am still learning the ins and outs of doing things the java-way. Our team has been working on a Game Engine for the Android and the PC for the past 7-8 months and one of the problems we encountered in our early tests in the Android platform was the Garbage Collector. As objects were created and destroyed and re-created during every iteration of the game loop, made the Garbage Collector… lets just say, very unfriendly.
One way to combat this was the early concept of reusing objects as much as possible, during the development of the engine we had specific pools for specific objects, lets just say that things got a little bit “messy”. This tutorial is dedicated to the painful code cleanup that was performed in our engine to incorporate a general purpose “Pooling” solution that could not only provide pooling, but also work as a factory class to return platform-specific objects. Talk about killing two birds with one stone right? =]
This tutorial assumes some basic Java Programming concepts, it also assumes kowledge about Java Generics. By the end of this tutorial the user would have written a basic yet functional Generic Pool.
Now then, let us get started, we will start off by defining the interfaces
public interface Pool<Type> {
public void recycle(final Type data);
public Type get();
public void setFactory(final PoolObjectFactory<Type> factory);
public void reset();
public String debug();
}
public interface PoolObjectFactory<Type> {
public Type newObject();
}
Let us implement our Pool Interface. Our pool implementation is as follows.
public class ObjectPool<Type> implements Pool<Type> {
private final Stack<Type> freeObjects;
private PoolObjectFactory<Type> factory;
public ObjectPool() {
freeObjects = new Stack<Type>();
}
public void recycle(final Type data) {
freeObjects.push(data);
}
public Type get() {
if (freeObjects.isEmpty()) {
return factory.newObject();
}
return freeObjects.pop();
}
public void setFactory(final PoolObjectFactory<Type> factory) {
this.factory = factory;
}
public void reset() {
freeObjects.clear();
}
public String debug() {
return "Current Pool Size: " + freeObjects.size();
}
}
A fairly straightforward Pool Implementation, You grab objects from the pool via the get() function. The get() function checks to see if any objects are available, if not, it uses the factory to create one, if yes, then it simply returns an object in the stack.
So how do you use the Pool? Lets say you have a Vector, possibly one of the most used Objects in both Engine Envirnoment aswell as Game Programming Environment.
public class Vector {
public float x;
public float y;
public float z;
public Vector() {
x = 0.0f;
y = 0.0f;
z = 0.0f;
}
}
Not the greatest of Vector implementations, but for this example, it will do! First, we implement our Factory interface.
public class VectorFactory implements PoolObjectFactory<Vector> {
public Vector newObject() {
return new Vector();
}
}
And this small program shows how the Pool can be used.
public class TestPool {
public static void main(String[] args) {
Pool<Vector> vectorPool = new ObjectPool<Vector>();
vectorPool.setFactory(new VectorFactory());
// get a new Vector. This operation replaces the new operator
Vector vec = vectorPool.get();
// perform an operation on vec here
// once we are done, recycle this vector
vectorPool.recycle(vec);
// for safety reasons, point vec to null
vec = null;
}
}
So how does the pool work? All the magic happens during the get() method. The function first checks to see if there are any available free objects, if not, a new one is created from the Factory, otherwise a new object is returned from the Stack.
This simple yet effective pooling method was used in our engine for a very long time untill the relatively large code cleanup. Currently, when an object is removed from the pool, the pool no longer has a reference to that object which has both ups and downs. An upside is that control of the object is now passed onto the caller function and the object won’t be reused untill its passed into the pool via the recycle() function. The downside is that the object will constantly need to be removed and added to the stack at every get() and recycle() function call.
One solution would be to allow the Pool to keep a reference of the objects even after they are “removed” from the Pool and instead use the stack to keep values of free Object ID’s which represent the cell that the object is stored in the pool. This type of design will allow the creation of a “temporary object” pool, which instead can be reset at end of game loop. One example would be Vector objects, which are only used for Math operations and discarded afterwards. These Vectors can be grabbed from the Pool during the computation and automatically recycled at end of game loop. This also makes object storage more cache friendly, as it ensures they are created and stored closer together. This is the method currently used in our engine and one possible way to implement such a pool is below.
The PoolObjectFactory Interfaces remain the same, we now have a new Generic Interface called Poolable.
public interface Poolable<Type> {
public void setPoolID(final int id);
public int getPoolID();
public Type get();
public void clean();
}
The Pool interface now changes to accept Poolable objects instead.
public interface Pool<Type> {
public void recycle(final Poolable<Type> data);
public Type get();
public void setFactory(final PoolObjectFactory<Type> factory);
public void reset();
public String debug();
}
Below is the new implementation of the Vector Object.
public class Vector implements Poolable<Vector> {
public float x;
public float y;
public float z;
private int poolID;
public Vector() {
x = 0.0f;
y = 0.0f;
z = 0.0f;
}
public void setPoolID(int id) {
poolID = id;
}
public int getPoolID() {
return poolID;
}
public Vector get() {
return this;
}
public void clean() {
x = 0.0f;
y = 0.0f;
z = 0.0f;
}
}
The Implementation of the pool now becomes as follows
public class ObjectPool<Type> implements Pool<Type> {
private final Stack<Integer> freeObjectsID;
private final ArrayList<Poolable<Type>> objects;
private PoolObjectFactory<Type> factory;
public ObjectPool() {
freeObjectsID = new Stack<Integer>();
objects = new ArrayList<Poolable<Type>>();
}
public void recycle(final Poolable<Type> data) {
freeObjectsID.push(data.getPoolID());
}
@SuppressWarnings("unchecked")
public Type get() {
if (freeObjectsID.isEmpty()) {
final Poolable<Type> obj = (Poolable<Type>) factory.newObject();
obj.setPoolID(objects.size());
objects.add(obj);
return obj.get();
}
final Poolable<Type> obj = objects.get(freeObjectsID.pop());
obj.clean();
return obj.get();
}
public void setFactory(final PoolObjectFactory<Type> factory) {
this.factory = factory;
}
public void reset() {
freeObjectsID.clear();
final Iterator<Poolable<Type>> it = objects.iterator();
while (it.hasNext()) {
freeObjectsID.push(it.next().getPoolID());
}
}
public String debug() {
return "Current Pool Size: " + freeObjectsID.size();
}
}
So the new Pool has quite a bit more going on. The overall solution is not as optimised as it could be, for example, switching the ArrayList and Stack to custom-made containers designed specifically for the tasks the pool provides will give a small increase in performance and memory usage.
Overall, as mentioned before, the new Pool does not remove the objects from inside, this can be very dangerous. If the object is not recycled() it is essentially forever lost in the Pool, you can consider this a C++ equivalent of a memory leak, so ensure you recycle after use, although as mentioned before, if the pool is considered a “temporary object pool” it can always be reset at end of frame, which means that objects don’t need to be recycled.
For those of you wondering, Pooling is not meant to be easy to use, it is not meant to be used by your game programmers using your engine to make games, although some smarter interfaces can allow for such a thing. This is mainly there to help speedup the internals of the numerous engine components, such as the collision detectors, Maths libraries etc via reusing old objects which can and will get created in the packs of hundreds and thousands per frame (depending on game complexity).
This simple test program simulates a simple Game Loop.
public class TestPool {
public static void main(String[] args) {
Pool<Vector> vectorPool = new ObjectPool<Vector>();
vectorPool.setFactory(new VectorFactory());
// this loop will run 100,000 times, consider it a limited "fake" game loop
for (int i = 0; i < 100000; i++) {
// pool debug data after reset
System.out.println("Debug Data AFTER reset: " + vectorPool.debug());
for (int j = 0; j < 100; j++) {
// perform some long and tiresome Vector operation here
Vector vec1 = vectorPool.get();
Vector vec2 = vectorPool.get();
// do something silly..
vec1.x = i;
vec1.y = j;
vec2.x = j;
vec1.y = i;
Vector vec3 = vectorPool.get();
vec3.x = vec1.x + vec2.x;
vec3.y = vec1.y + vec2.y;
System.out.println("Some Silly Vector Math X: " + vec3.x + " Y: " + vec3.y);
}
// pool debug data before reset
System.out.println("Debug Data BEFORE reset: " + vectorPool.debug());
// reset the vectorPool, it is considered a temporary pool, all objects will become reusable
vectorPool.reset();
}
}
}
I would like to thank you for reading my very first somewhat technical java-tutorial and wish you good luck in your future engine-designing adventures! Any comments/suggestions are more than welcome!