diff Implab/Components/ObjectPool.cs @ 154:2dcdee4c0810 v2

docs
author cin
date Fri, 12 Feb 2016 01:00:11 +0300
parents 240aa6994018
children 7c7e9ad6fe4a
line wrap: on
line diff
--- a/Implab/Components/ObjectPool.cs	Fri Feb 12 00:59:29 2016 +0300
+++ b/Implab/Components/ObjectPool.cs	Fri Feb 12 01:00:11 2016 +0300
@@ -4,18 +4,17 @@
 
 namespace Implab.Components {
     /// <summary>
-    /// Базовый класс для создания пулов объектов.
+    /// The base class for creating object pools.
     /// </summary>
     /// <remarks>
-    /// <para>Пул объектов позволяет многократно использовать один и тотже объект,
-    /// что актуально для объектов, создание которых требует существенных ресурсов.
-    /// Пул объектов использует слабые ссылки, чтобы не препятствовать освобождению
-    /// ресурсов и создает новые объекты при необходимости.</para>
+    /// <para>The objects pool is offers frequently requested objects to be reused, this gives
+    /// a gool speed improvement for the 'heavy' objects. To avoid memory overhead the pool uses
+    /// weak references allowing CG to do it's work. If there are no free objects in the pool
+    /// they are created on demand. </para>
     /// <para>
-    /// Наследники должны реализовывать метод <see cref="CreateInstance()"/> для создания
-    /// новых экземпляров.
+    /// Implementors need to defined a <see cref="CreateInstance()"/> method
     /// </para>
-    /// <para>Пул поддерживает обращения сразу из нескольких потоков.</para>
+    /// <para>The instances of this class are thred-safe.</para>
     /// </remarks>
     public abstract class ObjectPool<T> where T : class {
         readonly AsyncQueue<WeakReference> m_queue = new AsyncQueue<WeakReference>();
@@ -32,11 +31,22 @@
             m_size = size;
         }
 
+        /// <summary>
+        /// Creates the instance if there are no free ones in the pool.
+        /// </summary>
+        /// <returns>The new instance.</returns>
         protected abstract T CreateInstance();
 
+        /// <summary>
+        /// Cleanups the instance.
+        /// </summary>
+        /// <param name="instance">The instance to cleanup and prepare it for the next use.</param>
         protected virtual void CleanupInstance(T instance) {
         }
 
+        /// <summary>
+        /// Allocate free instance from the pool or reates a new one.
+        /// </summary>
         public T Allocate() {
             WeakReference reference;
             while (m_queue.TryDequeue(out reference)) {
@@ -49,6 +59,11 @@
             return CreateInstance();
         }
 
+        /// <summary>
+        /// Release the specified instance and returns it to the pool of free instances.
+        /// </summary>
+        /// <param name="instance">The instance to return to the pool.</param>
+        /// <remarks>Before the instance is returned to the pool the <see cref="CleanupInstance(T)"/> is called.</remarks>
         public void Release(T instance) {
             if (m_count < m_size && instance != null) {
                 Interlocked.Increment(ref m_count);