namespace Chernobyl.DesignPatterns.Pool
{
    /// <summary>
    /// A storage container that consists of several objects 
    /// that are stored together for reuse. This class abstracts away
    /// how the pooled type is created, where it comes from, how it's 
    /// stored, and what happens to an object when it is returned to 
    /// the pool and retrieved from the pool.
    /// </summary>
    /// <typeparam name="PooledType">The type of object to pool.</typeparam>
    public interface IPool<PooledType>
    {
        /// <summary>
        /// Takes an object from the pool. If the pool has 
        /// no more objects to give or it does not want to 
        /// give an object out then null will be returned.
        /// </summary>
        /// <param name="objectToTake">The object to fill with
        /// the taken object.</param>
        /// <returns>True if there was an object that could be 
        /// taken from the pool and that object was assigned to 
        /// <paramref name="objectToTake"/>, false if otherwise.</returns>
        bool Take(out PooledType objectToTake);

        /// <summary>
        /// Returns a previously taken object to the pool.
        /// </summary>
        /// <param name="objectToReturn">The object to return
        /// to the pool.</param>
        void Return(PooledType objectToReturn);

        /// <summary>
        /// Adds an object to the pool.
        /// </summary>
        /// <param name="item">The item to add to the pool</param>
        void Add(PooledType item);

        /// <summary>
        /// Clears out the pool.
        /// </summary>
        void Clear();

        /// <summary>
        /// The number of objects in the pool.
        /// </summary>
        int Count { get; }

        /// <summary>
        /// Removes an item from the pool.
        /// </summary>
        /// <param name="item">The item to remove.</param>
        /// <returns>True if the item was removed, false if
        /// otherwise.</returns>
        bool Remove(PooledType item);
    }
}