QueueAsyncProcessor: some comments translated to English

src/Qoollo.Turbo/Threading/QueueProcessing/QueueAsyncProcessor.cs

@@ -10,13 +10,13 @@
 namespace Qoollo.Turbo.Threading.QueueProcessing
 {
     /// <summary>
-    /// Асинхронный обработчик данных в несколько потоков с очередью
+    /// Asynchronous items processor with queue
     /// </summary>
-    /// <typeparam name="T">Тип обрабатываемого элемента</typeparam>
+    /// <typeparam name="T">Type of the elements processed by this <see cref="QueueAsyncProcessor{T}"/></typeparam>
     public abstract class QueueAsyncProcessor<T> : QueueAsyncProcessorBase<T>, IQueueAsyncProcessorStartStopHelper
     {
         /// <summary>
-        /// Контракты
+        /// Code contracts invariants
         /// </summary>
         [ContractInvariantMethod]
         private void Invariant()
@@ -47,15 +47,16 @@ private void Invariant()
         private volatile bool _letFinishProcess;
 
         /// <summary>
-        /// Конструктор QueueAsyncProcessor
+        /// QueueAsyncProcessor constructor
         /// </summary>
         /// <param name="threadCount">Число потоков обработки</param>
         /// <param name="maxQueueSize">Максимальный размер очереди</param>
         /// <param name="name">Имя, присваемое потокам</param>
         /// <param name="isBackground">Будут ли потоки работать в фоновом режиме</param>
         public QueueAsyncProcessor(int threadCount, int maxQueueSize, string name, bool isBackground)
         {
-            Contract.Requires(threadCount > 0);
+            if (threadCount <= 0)
+                throw new ArgumentOutOfRangeException(nameof(threadCount), "Number of threads should be positive");
 
             _isBackground = isBackground;
             _name = name ?? this.GetType().GetCSName();

src/Qoollo.Turbo/Threading/QueueProcessing/QueueAsyncProcessorBase.cs

@@ -9,53 +9,53 @@
 namespace Qoollo.Turbo.Threading.QueueProcessing
 {
     /// <summary>
-    /// Базовый класс для асинхронных обработчиков
+    /// Asynchronous items processor with queue (base methods)
     /// </summary>
-    /// <typeparam name="T">Тип обрабатываемого элемента</typeparam>
+    /// <typeparam name="T">Type of the elements processed by this <see cref="QueueAsyncProcessorBase{T}"/></typeparam>
     public abstract class QueueAsyncProcessorBase<T>: IConsumer<T>, IDisposable
     {
         /// <summary>
-        /// Добавить элемент на обработку
+        /// Attempts to add new item to processing queue
         /// </summary>
-        /// <param name="element">Элемент</param>
-        /// <param name="timeout">Таймаут добавления в миллисекундах</param>
-        /// <param name="token">Токен отмены</param>
-        /// <returns>Успешность (удалось ли добавить до истечения таймаута)</returns>
+        /// <param name="element">New item</param>
+        /// <param name="timeout">Adding timeout in milliseconds</param>
+        /// <param name="token">Cancellation token</param>
+        /// <returns>True if item was added, otherwise false</returns>
         public abstract bool Add(T element, int timeout, CancellationToken token);
         /// <summary>
-        /// Добавить элемент на обработку
+        /// Adds new item to processing queue (waits for space in processing queue)
         /// </summary>
-        /// <param name="element">Элемент</param>
+        /// <param name="element">New item</param>
         public void Add(T element)
         {
             bool result = Add(element, Timeout.Infinite, new CancellationToken());
             Debug.Assert(result);
         }
         /// <summary>
-        /// Добавить элемент на обработку
+        /// Adds new item to processing queue
         /// </summary>
-        /// <param name="element">Элемент</param>
-        /// <param name="token">Токен отмены</param>
+        /// <param name="element">New item</param>
+        /// <param name="token">Cancellation token</param>
         public void Add(T element, CancellationToken token)
         {
             bool result = Add(element, Timeout.Infinite, token);
             Debug.Assert(result);
         }
         /// <summary>
-        /// Добавить элемент на обработку
+        /// Attempts to add new item to processing queue
         /// </summary>
-        /// <param name="element">Элемент</param>
-        /// <param name="timeout">Таймаут добавления в миллисекундах</param>
-        /// <returns>Успешность (удалось ли добавить до истечения таймаута)</returns>
+        /// <param name="element">New item</param>
+        /// <param name="timeout">Adding timeout in milliseconds</param>
+        /// <returns>True if item was added, otherwise false</returns>
         public bool Add(T element, int timeout)
         {
             return Add(element, timeout, new CancellationToken());
         }
         /// <summary>
-        /// Попытаться добавить элемент на обработку
+        /// Attempts to add new item to processing queue
         /// </summary>
-        /// <param name="element">Элемент</param>
-        /// <returns>Удалось ли добавить</returns>
+        /// <param name="element">New item</param>
+        /// <returns>True if item was added, otherwise false</returns>
         public bool TryAdd(T element)
         {
             return Add(element, 0, new CancellationToken());
@@ -64,33 +64,33 @@ public bool TryAdd(T element)
 
 
         /// <summary>
-        /// Добавить элемент
+        /// Pushes new element to the consumer
         /// </summary>
-        /// <param name="item">Элемент</param>
+        /// <param name="item">Element</param>
         void IConsumer<T>.Add(T item)
         {
             this.Add(item);
         }
         /// <summary>
-        /// Попытаться добавить элемент
+        /// Attempts to push new element to the consumer
         /// </summary>
-        /// <param name="item">Элемент</param>
-        /// <returns>Успешность</returns>
+        /// <param name="item">Element</param>
+        /// <returns>True if the element was consumed successfully</returns>
         bool IConsumer<T>.TryAdd(T item)
         {
             return this.TryAdd(item);
         }
 
         /// <summary>
-        /// Основной код освобождения ресурсов
+        /// Cleans-up resources
         /// </summary>
-        /// <param name="isUserCall">Вызвано ли освобождение пользователем. False - деструктор</param>
+        /// <param name="isUserCall">Is it called explicitly by user (False - from finalizer)</param>
         protected virtual void Dispose(bool isUserCall)
         { 
         }
 
         /// <summary>
-        /// Освобождение ресурсов
+        /// Cleans-up resources
         /// </summary>
         public void Dispose()
         {

src/Qoollo.Turbo/Threading/QueueProcessing/QueueAsyncProcessorExtensions.cs

@@ -8,41 +8,42 @@
 namespace Qoollo.Turbo.Threading.QueueProcessing
 {
     /// <summary>
-    /// Интерфейс помошник для QueueAsyncProcessorExtension
+    /// Helper interface for <see cref="QueueAsyncProcessor{T}"/>
     /// </summary>
     public interface IQueueAsyncProcessorStartStopHelper: IDisposable
     {
         /// <summary>
-        /// Запустить QueueAsyncProcessor
+        /// Starts processing of items
         /// </summary>
         void Start();
         /// <summary>
-        /// Остановка и освобождение ресурсов
+        /// Stops processing of items
         /// </summary>
-        /// <param name="waitForStop">Ожидать остановки</param>
-        /// <param name="letFinishProcess">Позволить обработать всю очередь</param>
-        /// <param name="completeAdding">Запретить добавление новых элементов</param>
+        /// <param name="waitForStop">When True, waits until all processing threads are stopped</param>
+        /// <param name="letFinishProcess">True indicates that all items from inner queue should be processed before stopping</param>
+        /// <param name="completeAdding">When True, disallows adding new items to inner queue</param>
         void Stop(bool waitForStop, bool letFinishProcess, bool completeAdding);
         /// <summary>
-        /// Остановка и освобождение ресурсов
+        /// Stops processing of items
         /// </summary>
         void Stop();
     }
 
     /// <summary>
-    /// Расширения для QueueAsyncProcessor
+    /// <see cref="QueueAsyncProcessor{T}"/> extension methods
     /// </summary>
     public static class QueueAsyncProcessorExtensions
     {
         /// <summary>
         /// Fluent start
         /// </summary>
-        /// <typeparam name="TQueueProc">Тип QueueAsyncProcessor</typeparam>
-        /// <param name="proc">Сам обработчик</param>
-        /// <returns>Переданный обработчик</returns>
+        /// <typeparam name="TQueueProc">The type of <see cref="QueueAsyncProcessor{T}"/></typeparam>
+        /// <param name="proc"><see cref="QueueAsyncProcessor{T}"/> instance</param>
+        /// <returns>Same instance of the started <see cref="QueueAsyncProcessor{T}"/></returns>
         public static TQueueProc ThenStart<TQueueProc>(this TQueueProc proc) where TQueueProc : IQueueAsyncProcessorStartStopHelper
         {
-            Contract.Requires<ArgumentNullException>(proc != null);
+            if (proc == null)
+                throw new ArgumentNullException(nameof(proc));
 
             proc.Start();
             return proc;

src/Qoollo.Turbo/Threading/QueueProcessing/QueueAsyncProcessorState.cs

@@ -7,28 +7,28 @@
 namespace Qoollo.Turbo.Threading.QueueProcessing
 {
     /// <summary>
-    /// Состояние асинхронного обработчика
+    /// Defines possible states of the <see cref="QueueAsyncProcessor{T}"/>
     /// </summary>
     public enum QueueAsyncProcessorState : int
     {
         /// <summary>
-        /// Создан
+        /// Indicates that <see cref="QueueAsyncProcessor{T}"/> was created but not started
         /// </summary>
         Created = 0,
         /// <summary>
-        /// В процессе запуска
+        /// Indicates that <see cref="QueueAsyncProcessor{T}"/> is being transitioned from <see cref="Created"/> to <see cref="Running"/> state
         /// </summary>
         StartRequested = 1,
         /// <summary>
-        /// Работает
+        /// Indicates that <see cref="QueueAsyncProcessor{T}"/> is started and can process item
         /// </summary>
         Running = 2,
         /// <summary>
-        /// В процессе остановки
+        /// Indicates that <see cref="QueueAsyncProcessor{T}"/> is being transitioned from <see cref="Running"/> to <see cref="Stopped"/> state
         /// </summary>
         StopRequested = 3,
         /// <summary>
-        /// Остановлен
+        /// Indicates that <see cref="QueueAsyncProcessor{T}"/> is stopped
         /// </summary>
         Stopped = 4,
     }