Added an object Pool that can be used to recycle objects in order to avoid garbage buildup; wrote unit tests for the new pool class; added interface through which objects entering the pool can be instructed to revert their state

git-svn-id: file:///srv/devel/repo-conversion/nusu@192 d2e56fa2-650e-0410-a79f-9358c0239efd
This commit is contained in:
Markus Ewald 2010-03-15 19:08:10 +00:00
parent 2b94c316f6
commit b8dbf8f40d
6 changed files with 296 additions and 2 deletions

View File

@ -85,6 +85,7 @@
<DependentUpon>Deque.cs</DependentUpon>
</Compile>
<Compile Include="Source\Collections\IObservableCollection.cs" />
<Compile Include="Source\Collections\IRecyclable.cs" />
<Compile Include="Source\Collections\ItemEventArgs.cs" />
<Compile Include="Source\Collections\ItemEventArgs.Test.cs">
<DependentUpon>ItemEventArgs.cs</DependentUpon>
@ -109,6 +110,10 @@
<Compile Include="Source\Collections\ParentingCollection.Test.cs">
<DependentUpon>ParentingCollection.cs</DependentUpon>
</Compile>
<Compile Include="Source\Collections\Pool.cs" />
<Compile Include="Source\Collections\Pool.Test.cs">
<DependentUpon>Pool.cs</DependentUpon>
</Compile>
<Compile Include="Source\Collections\PriorityItemPair.cs" />
<Compile Include="Source\Collections\PriorityItemPair.Test.cs">
<DependentUpon>PriorityItemPair.cs</DependentUpon>

View File

@ -71,6 +71,7 @@
<DependentUpon>Deque.cs</DependentUpon>
</Compile>
<Compile Include="Source\Collections\IObservableCollection.cs" />
<Compile Include="Source\Collections\IRecyclable.cs" />
<Compile Include="Source\Collections\ItemEventArgs.cs" />
<Compile Include="Source\Collections\ItemEventArgs.Test.cs">
<DependentUpon>ItemEventArgs.cs</DependentUpon>
@ -95,6 +96,10 @@
<Compile Include="Source\Collections\ParentingCollection.Test.cs">
<DependentUpon>ParentingCollection.cs</DependentUpon>
</Compile>
<Compile Include="Source\Collections\Pool.cs" />
<Compile Include="Source\Collections\Pool.Test.cs">
<DependentUpon>Pool.cs</DependentUpon>
</Compile>
<Compile Include="Source\Collections\PriorityItemPair.cs" />
<Compile Include="Source\Collections\PriorityItemPair.Test.cs">
<DependentUpon>PriorityItemPair.cs</DependentUpon>

View File

@ -0,0 +1,45 @@
#region CPL License
/*
Nuclex Framework
Copyright (C) 2002-2009 Nuclex Development Labs
This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.
This library 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. See the
IBM Common Public License for more details.
You should have received a copy of the IBM Common Public
License along with this library
*/
#endregion
using System;
namespace Nuclex.Support.Collections {
/// <summary>Allows an object to be returned to its initial state</summary>
/// <remarks>
/// <para>
/// This interface is typically implemented by objects which can be recycled
/// in order to avoid the construction overhead of a heavyweight class and to
/// eliminate garbage by reusing instances.
/// </para>
/// <para>
/// Recyclable objects should have a parameterless constructor and calling
/// their Recycle() method should bring them back into the state they were
/// in right after they had been constructed.
/// </para>
/// </remarks>
public interface IRecyclable {
/// <summary>Returns the object to its initial state</summary>
void Recycle();
}
} // namespace Nuclex.Support.Collections

View File

@ -0,0 +1,108 @@
#region CPL License
/*
Nuclex Framework
Copyright (C) 2002-2009 Nuclex Development Labs
This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.
This library 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. See the
IBM Common Public License for more details.
You should have received a copy of the IBM Common Public
License along with this library
*/
#endregion
#if UNITTEST
using System;
using System.Collections.Generic;
using NUnit.Framework;
using NMock2;
namespace Nuclex.Support.Collections {
/// <summary>Unit tests for the Pool class</summary>
[TestFixture]
public class PoolTest {
#region class TestClass
/// <summary>Used to test the pool</summary>
private class TestClass : IRecyclable {
/// <summary>Returns the object to its initial state</summary>
public void Recycle() {
this.Recycled = true;
}
/// <summary>Whether the instance has been recycled</summary>
public bool Recycled;
}
#endregion // class TestClass
/// <summary>
/// Verifies that the pool can return newly constructed objects
/// </summary>
[Test]
public void TestGet() {
Pool<TestClass> pool = new Pool<TestClass>();
Assert.IsNotNull(pool.Get());
}
/// <summary>
/// Verifies that the pool will return a recycled object if one is available
/// </summary>
[Test]
public void TestGetRecycled() {
Pool<TestClass> pool = new Pool<TestClass>();
pool.Redeem(new TestClass());
TestClass test = pool.Get();
Assert.IsTrue(test.Recycled);
}
/// <summary>
/// Tests whether the pool can redeem objects that are no longer used
/// </summary>
[Test]
public void TestRedeem() {
Pool<TestClass> pool = new Pool<TestClass>();
pool.Redeem(new TestClass());
}
/// <summary>
/// Tests whether the Recycle() method is called at the appropriate time
/// </summary>
[Test]
public void TestRecycle() {
Pool<TestClass> pool = new Pool<TestClass>();
TestClass x = new TestClass();
Assert.IsFalse(x.Recycled);
pool.Redeem(x);
Assert.IsTrue(x.Recycled);
}
/// <summary>Verifies that the pool's Capacity is applied correctly</summary>
[Test]
public void TestPoolSize() {
Pool<TestClass> pool = new Pool<TestClass>(123);
Assert.AreEqual(123, pool.Capacity);
pool.Capacity = 321;
Assert.AreEqual(321, pool.Capacity);
}
}
} // namespace Nuclex.Support.Collections
#endif // UNITTEST

131
Source/Collections/Pool.cs Normal file
View File

@ -0,0 +1,131 @@
#region CPL License
/*
Nuclex Framework
Copyright (C) 2002-2009 Nuclex Development Labs
This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.
This library 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. See the
IBM Common Public License for more details.
You should have received a copy of the IBM Common Public
License along with this library
*/
#endregion
using System;
using System.Collections.Generic;
using System.Text;
namespace Nuclex.Support.Collections {
/// <summary>Pool that recycles objects in order to avoid garbage build-up</summary>
/// <typeparam name="ItemType">Type of objects being pooled</typeparam>
/// <remarks>
/// <para>
/// Use this class to recycle objects instead of letting them become garbage,
/// creating new instances each time. The Pool class is designed to either be
/// used on its own or as a building block for a static class that wraps it.
/// </para>
/// <para>
/// Special care has to be taken to revert the entire state of a recycled
/// object when it is returned to the pool. For example, events will need to
/// have their subscriber lists emptied to avoid sending out events to the
/// wrong subscribers and accumulating more and more subscribers each time
/// they are reused.
/// </para>
/// <para>
/// To simplify such cleanup, pooled objects can implement the IRecyclable
/// interface. When an object is returned to the pool, the pool will
/// automatically call its IRecyclable.Recycle() method.
/// </para>
/// </remarks>
public class Pool<ItemType> where ItemType : class, new() {
/// <summary>Default number of recyclable objects the pool will store</summary>
public const int DefaultPoolSize = 64;
/// <summary>Initializes a new pool using the default capacity</summary>
public Pool() : this(DefaultPoolSize) { }
/// <summary>Initializes a new pool using a user-specified capacity</summary>
/// <param name="capacity">Capacity of the pool</param>
public Pool(int capacity) {
Capacity = capacity;
}
/// <summary>
/// Returns a new or recycled instance of the types managed by the pool
/// </summary>
/// <returns>A new or recycled instance</returns>
public ItemType Get() {
lock(this) {
if(this.items.Count > 0) {
return this.items.Dequeue();
} else {
return new ItemType();
}
}
}
/// <summary>
/// Redeems an instance that is no longer used to be recycled by the pool
/// </summary>
/// <param name="item">The instance that will be redeemed</param>
public void Redeem(ItemType item) {
// Call Recycle() when the object is redeemed (instead of when it leaves
// the pool again) in order to eliminate any references the object may hold
// to other objects.
callRecycleIfSupported(item);
lock(this) {
if(this.items.Count < this.capacity) {
this.items.Enqueue(item);
}
}
}
/// <summary>Number of objects the pool can retain</summary>
/// <remarks>
/// Changing this value causes the pool to be emtpied. It is recommended that
/// you only read the pool's capacity, never change it.
/// </remarks>
public int Capacity {
get { return this.capacity; }
set {
this.capacity = value;
this.items = new Queue<ItemType>(value);
}
}
/// <summary>
/// Calls the Recycle() method on an objects if it implements
/// the IRecyclable interface
/// </summary>
/// <param name="item">
/// Object whose Recycle() method will be called if supported by the object
/// </param>
private static void callRecycleIfSupported(ItemType item) {
IRecyclable recycleable = item as IRecyclable;
if(recycleable != null) {
recycleable.Recycle();
}
}
/// <summary>Objects being retained for recycling</summary>
private Queue<ItemType> items;
/// <summary>Capacity of the pool</summary>
/// <remarks>
/// Required because the Queue class doesn't allow this value to be retrieved
/// </remarks>
private int capacity;
}
} // namespace Nuclex.Support.Collections

View File

@ -18,11 +18,11 @@ License along with this library
*/
#endregion
#if UNITTEST
using System;
using System.Collections.Generic;
#if UNITTEST
using NUnit.Framework;
using NMock2;