lowkiq 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '058eb93d910f0a3a8ebc243c6c05df173d9e03555dcabc2f554f05f40df11306'
-  data.tar.gz: 5a6437e5896ced972de4722b84066ef93b30b36a1be33eb01656559c50848383
+  metadata.gz: 12bf22fdbf98496119d373faa88915d5c6f7e25e9522ecaafb8f865c8a00b840
+  data.tar.gz: 95e857e0a27990987aeb9f8b17442888c5b39cfc346ce6f3f8bf0911758aaa21
 SHA512:
-  metadata.gz: 540ceb803a0bc1e811f28a0c15a00f6ded92bf58302bd791cb2539beafbe71f13a878792889fbb438f8dfe77820e6148278472884c4d071faa7440c98df46687
-  data.tar.gz: 02a7bb2ab6e80c2e223a9d515a760aeae41d8db75562612830077e2e5e9a8e79b6446814c03ea130751c338d771c1a3a4b20a2445ed6429450b0864e226aa55b
+  metadata.gz: 8c02521986c2ba633eead7c71811ca1f04377b1acb9080d86677a4f831621c789becbd7f5ed2d7255324f238187b4dab245d2bf1c22880e4f99d89675c5f2dc3
+  data.tar.gz: 6446af89cb40417500f250d81bae859e412b7a55eb5f1e4db7c43abf6815737ea433f94922c115eb5d6933f770e75b4c48c3a6e8974477dd84d2ec19d99eae06

data/Gemfile.lock

@@ -11,35 +11,35 @@ GEM
   specs:
     connection_pool (2.2.2)
     diff-lcs (1.3)
-    rack (2.0.5)
+    rack (2.2.2)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
-    rake (10.5.0)
+    rake (12.3.3)
     redis (4.1.3)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.0)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.1)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.1)
+      rspec-support (~> 3.9.1)
+    rspec-expectations (3.9.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.16)
+  bundler (~> 2.1.0)
   lowkiq!
   rack-test (~> 1.1)
-  rake (~> 10.0)
+  rake (~> 12.3.0)
   rspec (~> 3.0)
   rspec-mocks (~> 3.8)
 
 BUNDLED WITH
-   1.16.4
+   2.1.2

data/LICENSE.md

@@ -7,7 +7,7 @@ On granting a non-exclusive right to use open source software
 
 1.1. The Licensor provides the Licensee, in the manner and on the terms set forth in this Agreement, the right to use (license) **the Lowkiq open source software** (hereinafter - the "Software").
 
-1.2. The source code for the software is available on the website located in the Internet telecommunication network "Internet" at the address: https://github.com/bia-tech/lowkiq.
+1.2. The source code for the software is available on the website located in the Internet telecommunication network "Internet" at the address: https://github.com/bia-technologies/lowkiq.
 
 1.3. Software characteristics, that individualize it as a unique result of intellectual activity:
 
@@ -129,5 +129,5 @@ TIN/ 7810385714
 RRC/ 781001001
 
 Name and email address of the representative:<br>
-Pryalkin Andrey Yuryevich<br>
-Andrey.Pryalkin@bia-tech.ru<br>
+Mikhail Kuzmin<br>
+Mihail.Kuzmin@bia-tech.ru<br>

data/README.md

@@ -1,163 +1,194 @@
+[![Gem Version](https://badge.fury.io/rb/lowkiq.svg)](https://badge.fury.io/rb/lowkiq)
+
 # Lowkiq
 
-Упорядоченная обработка фоновых задач.
+Ordered background jobs processing
 
 ![dashboard](doc/dashboard.png)
 
+* [Rationale](#rationale)
+* [Description](#description)
+* [Sidekiq comparison](#sidekiq-comparison)
+* [Queue](#queue)
+  + [Calculation algorithm for `retry_count` and `perform_in`](#calculation-algorithm-for-retry_count-and-perform_in)
+  + [Job merging rules](#job-merging-rules)
+* [Install](#install)
+* [Api](#api)
+* [Ring app](#ring-app)
+* [Configuration](#configuration)
+* [Execution](#execution)
+* [Shutdown](#shutdown)
+* [Debug](#debug)
+* [Development](#development)
+* [Exceptions](#exceptions)
+* [Rails integration](#rails-integration)
+* [Splitter](#splitter)
+* [Scheduler](#scheduler)
+* [Recommendations on configuration](#recommendations-on-configuration)
+  + [`SomeWorker.shards_count`](#someworkershards_count)
+  + [`SomeWorker.max_retry_count`](#someworkermax_retry_count)
+
 ## Rationale
 
-При использовании Sidekiq мы столкнулись с проблемами при обработке сообщений от сторонней системы.
+We've faced some problems using Sidekiq while processing messages from a side system.
+For instance, the message is a data of an order in particular time.
+The side system will send a new data of an order on an every change.
+Orders are frequently updated and a queue containts some closely located messages of the same order.
 
-Sidekiq не гарантирует строгого порядка сообщений, т.к. очередь обрабатывается в несколько потоков.
-Например, пришло 2 сообщения: M1 и M2.
-Sidekiq обработчики начинают обрабатывать их параллельно,
-при этом M2 может обработаться раньше M1.
+Sidekiq doesn't guarantee a strict message order, because a queue is processed by multiple threads.
+For example, we've received 2 messages: M1 and M2.
+Sidekiq handlers begin to process them parallel,
+so M2 can be processed before M1.
 
-В очереди могут находиться сообщения касающиеся одной сущности.
-Параллельная обработка таких сообщений приводит к:
+Parallel processing of such kind of messages can result in:
 
 + dead locks
-+ затиранию новых данных старыми
++ overwriting new data with old one
 
-Lowkiq призван устранить эти проблемы, исключая параллельность обработки сообщений в рамках одной сущности.
+Lowkiq has been created to eliminate such problems by avoiding parallel task processing within one entity.
 
 ## Description
 
-Очереди надежны, т.е. задачи не теряются в случае внезапного падения процесса.
-Очереди хранятся в Redis и могут не успеть записаться на диск, в случае падения Redis.
+Lowkiq's queues are reliable i.e.,
+Lowkiq saves information about a job being processed
+and returns incompleted jobs back to the queue on startup.
+
+Jobs in queues are ordered by preassigned execution time, so they are not FIFO queues.
 
-Каждая задача имеет идентификатор. Очереди гарантируют, что не может быть ситуации,
-когда несколько потоков обрабатывают задачи с одинаковыми идентификаторами.
+Every job has it's own identifier. Lowkiq guarantees that jobs with equal id are processed by the same thread.
 
-Каждая очередь разбивается на постоянный набор шардов.
-На основе идентификатора задачи выбирается шард, в который попадет задача.
-Таким образом задачи с одним идентификатором всегда попадают в один и тот же шард.
-Задачи шарда всегда обрабатываются одним и тем же потоком.
-Это гарантирует порядок обработки задач с одинаковым идентификатором и исключает возможность блокировок.
+Every queue is divided into a permanent set of shards.
+A job is placed into particular shard based on an id of the job.
+So jobs with the same id are always placed into the same shard.
+All jobs of the shard are always processed with the same thread.
+This guarantees the sequently processing of jobs with the same ids and excludes the possibility of locks.
 
-Кроме идентификатора задача имеет полезную нагрузку или данные задачи (payload).
-Задачи в очереди группируются по идентификатору.
-Таким образом одновременно в обработку попадают все накопленные полезные нагрузки задачи.
+Besides the id, every job has a payload.
+Payloads are accumulated for jobs with the same id.
+So all accumulated payloads will be processed together.
+It's useful when you need to process only the last message and drop all previous ones.
 
-Если задачи содержат изменения сущности, то обработчик их все разом применит.
-Если задачи содержат снимки (версии) сущности, то обработчик может использовать только последнюю версию.
+A worker corresponds to a queue and contains a job processing logic.
 
-Каждой очереди соответствует воркер, содержащий логику обработки задачи.
-Для обработки задач используется фиксированное количество тредов,
-таким образом, добавление или удаление очереди/воркера не приводит к изменению числа тредов.
-Нет смысла задавать кол-во шардов одного воркера больше, чем общее кол-во тредов.
+Fixed amount of threads is used to process all job of all queues.
+Adding or removing queues or it's shards won't affect the amount of threads.
 
-## Аналоги
+## Sidekiq comparison
 
-Lowkiq можно рассматривать, в некотором смысле, как замену sidekiq, работающему с плагинами:
+If Sidekiq is good for your tasks you should use it.
+But if you use plugins like
+[sidekiq-grouping](https://github.com/gzigzigzeo/sidekiq-grouping),
+[sidekiq-unique-jobs](https://github.com/mhenrixon/sidekiq-unique-jobs),
+[sidekiq-merger](https://github.com/dtaniwaki/sidekiq-merger)
+or implement your own lock system, you should look at Lowkiq.
 
-+ [sidekiq-grouping](https://github.com/gzigzigzeo/sidekiq-grouping)
-+ [sidekiq-unique-jobs](https://github.com/mhenrixon/sidekiq-unique-jobs)
-+ [sidekiq-merger](https://github.com/dtaniwaki/sidekiq-merger)
+For example, sidekiq-grouping accumulates a batch of jobs than enqueues it and accumulates a next batch.
+With this approach queue can contains two batches with a data of the same order.
+These batches are parallel processed with different threads, so we come back to the initial problem.
 
-## Benchmark
+Lowkiq was designed to avoid any types of locking.
 
-5 threads, 100_000 blank jobs
+Furthermore, Lowkiq's queues are reliable. Only Sidekiq Pro or plugins can add such functionality.
 
-+ lowkiq: 214 sec
-+ sidekiq: 29 sec
+This [benchmark](examples/benchmark) shows overhead on redis usage.
+This is the results for 5 threads, 100,000 blank jobs:
 
-Этот [бенчмарк](examples/benchmark) показывает накладные расходы на взаимодействие с redis.
-В реальных задачах разница будет не так заметна.
++ lowkiq: 214 sec or 2.14 ms per job
++ sidekiq: 29 sec or 0.29 ms per job
 
-## Очередь
+This difference is related to different queues structure.
+Sidekiq uses one list for all workers and fetches the job entirely for O(1).
+Lowkiq uses several data structures, including sorted sets for storing ids of jobs.
+So fetching only an id of a job takes O(log(N)).
 
-Каждая задача в очереди имеет аттрибуты:
+## Queue
 
-+ `id` - идентификатор задачи (строка)
-+ `payloads` - сортированное множество payload'ов (объекты) по их score (вещественное число)
-+ `perform_in` - запланированное время начала иполнения задачи (unix timestamp, вещественное число)
-+ `retry_count` - количество совершённых повторов задачи (вещественное число)
+Please, look at [the presentation](https://docs.google.com/presentation/d/e/2PACX-1vRdwA2Ck22r26KV1DbY__XcYpj2FdlnR-2G05w1YULErnJLB_JL1itYbBC6_JbLSPOHwJ0nwvnIHH2A/pub?start=false&loop=false&delayms=3000).
 
-`id` может быть, например, идентификатором реплицируемой сущности
-`payloads` - множество,
-получаемое в результате группировки полезной нагрузки задачи по `id` и отсортированное по ее `score`.
-`payload` может быть объектом, т.к. сериализуется с помощью `Marshal.dump`.
-`score` может быть датой (unix timestamp) создания `payload`
-или ее монотонно увеличивающимся номером версии.
-По умолчанию - текущий unix timestamp.
-По умолчанию `perform_in` - текущий unix timestamp.
-`retry_count` для новой необработанной задачи равен `-1`, для упавшей один раз - `0`,
-т.е. считаются не совершённые, а запланированные повторы.
+Every job has following attributes:
 
-`score`, `perform_at` и `retry_count` вещественные из-за особенностей работы redis.
++ `id` is a job identifier with string type.
++ `payloads` is a sorted set of payloads ordered by it's score. Payload is an object. Score is a real number.
++ `perform_in` is planned execution time. It's unix timestamp with real number type.
++ `retry_count` is amount of retries. It's a real number.
 
-> Redis sorted sets use a double 64-bit floating point number to represent the score. In all the architectures we support, this is represented as an IEEE 754 floating point number, that is able to represent precisely integer numbers between -(2^53) and +(2^53) included. In more practical terms, all the integers between -9007199254740992 and 9007199254740992 are perfectly representable. Larger integers, or fractions, are internally represented in exponential form, so it is possible that you get only an approximation of the decimal number, or of the very big integer, that you set as score.
+For example, `id` can be an identifier of replicated entity.
+`payloads` is a sorted set ordered by score of payload and resulted by grouping a payload of job by it's `id`.
+`payload` can be a ruby object, because it is serialized by `Marshal.dump`.
+`score` can be `payload`'s creation date (unix timestamp) or it's incremental version number.
+By default `score` and `perform_in` are current unix timestamp.
+`retry_count` for new unprocessed job equals to `-1`,
+for one-time failed is `0`, so the planned retries are counted, not the performed ones.
 
-Выполнение задачи может закончиться неудачей.
-В этом случае ее `retry_count` инкрементируется и по заданной формуле вычисляется новый `perform_at`,
-и она ставится обратно в очередь.
+A job execution can be unsuccessful. In this case, its `retry_count` is incremented, new `perform_in` is calculated with determined formula and it moves back to a queue.
 
-В случае, когда `retry_count` становится `>=` `max_retry_count`
-элемент payloads с наименьшим(старейшим) score перемещается в морг,
-а оставшиеся элементы помещаются обратно в очередь, при этом
-`retry_count` и `perform_at` сбрасываются в `-1` и `now()` соответственно.
+In case of `retry_count` is getting `>=` `max_retry_count` an element of `payloads` with less (oldest) score is moved to a morgue,
+rest elements are moved back to the queue, wherein `retry_count` and `perform_in` are reset to `-1` and `now()` respectively.
 
-### Алгоритм расчета retry_count и perform_in
+### Calculation algorithm for `retry_count` and `perform_in`
 
-0. задача выполнилась и упала
+0. a job's been executed and failed
 1. `retry_count++`
-2. `perform_in = now + retry_in(try_count)`
-3. `if retry_count >= max_retry_count` задача перемещается в морг
+2. `perform_in = now + retry_in (try_count)`
+3. `if retry_count >= max_retry_count` the job will be moved to a morgue.
 
-| тип         | `retry_count` | `perform_in` |
-| ---         | ---           | ---          |
-| новая не выполнялась | -1 | задан или `now()` |
-| новая упала | 0 | `now() + retry_in(0)` |
-| повтор упал | 1 | `now() + retry_in(1)` |
+| type                      | `retry_count` | `perform_in`          |
+| ---                       | ---           | ---                   |
+| new haven't been executed | -1            | set or `now()`        |
+| new failed                | 0             | `now() + retry_in(0)` |
+| retry failed              | 1             | `now() + retry_in(1)` |
 
-Если `max_retry_count = 1`, то попытки прекращаются.
+If `max_retry_count = 1`, retries stop.
 
-### Правило слияния задач
+### Job merging rules
 
-Когда применяется:
+They are applied when:
 
-+ если в очереди была задача и добавляется еще одна с тем же id
-+ если при обработке возникла ошибка, а в очередь успели добавили задачу с тем же id
-+ если задачу из морга поставили в очередь, а в очереди уже есть задача с тем же id
++ a job had been in a queue and a new one with the same id was added
++ a job was failed, but a new one with the same id had been added
++ a job from morgue was moved back to queue, but queue had had a job with the same id
 
-Алгоритм:
+Algorithm:
 
-+ payloads объединяются, при этом выбирается минимальный score,
-  т.е. для одинаковых payload выигрывает самая старая
-+ если объединяется новая и задача из очереди,
-  то `perform_at` и `retry_count` берутся из задачи из очереди
-+ если объединяется упавшая задача и задача из очереди,
-  то `perform_at` и `retry_count` берутся из упавшей
-+ если объединяется задача из морга и задача из очереди,
-  то `perform_at = now()`, `retry_count = -1`
++ payloads is merged, minimal score is chosen for equal payloads
++ if a new job and queued job is merged, `perform_in` and `retry_count` is taken from the the job from the queue
++ if a failed job and queued job is merged, `perform_in` and `retry_count` is taken from the failed one
++ if morgue job and queued job is merged, `perform_in = now()`, `retry_count = -1`
 
-Пример:
+Example:
 
 ```
-# v1 - первая версия, v2 - вторая
-# #{"v1": 1} - сортированное множество одного элемента, payload - "v1", score - 1
+# v1 is the first version and v2 is the second
+# #{"v1": 1} is a sorted set of a single element, the payload is "v1", the score is 1
 
-# задача в очереди
-{ id: "1", payloads: #{"v1": 1, "v2": 2}, retry_count: 0, perform_at: 1536323288 }
-# добавляемая задача
-{ id: "1", payloads: #{"v2": 3, "v3": 4}, retry_count: -1, perform_at: 1536323290 }
+# a job is in a queue
+{ id: "1", payloads: #{"v1": 1, "v2": 2}, retry_count: 0, perform_in: 1536323288 }
+# a job which is being added
+{ id: "1", payloads: #{"v2": 3, "v3": 4}, retry_count: -1, perform_in: 1536323290 }
 
-# результат
-{ id: "1", payloads: #{"v1": 1, "v2": 3, "v3": 4}, retry_count: 0, perform_at: 1536323288 }
+# a resulted job in the queue
+{ id: "1", payloads: #{"v1": 1, "v2": 3, "v3": 4}, retry_count: 0, perform_in: 1536323288 }
 ```
 
-Морг - часть очереди. Задачи в морге не обрабатываются.
-Задача в морге имеет следующие атрибуты:
+Morgue is a part of the queue. Jobs in morgue are not processed.
+A job in morgue has following attributes:
 
-+ id - идентификатор задачи
-+ payloads - список
++ id is the job identifier
++ payloads
 
-Задачи в морге можно отсортировать по дате изменения или id.
+A job from morgue can be moved back to the queue, `retry_count` = 0 and `perform_in = now()` would be set.
 
-Задачу из морга можно переместить в очередь. При этом для нее `retry_count = 0`, `perform_at = now()`.
+## Install
 
-### Api
+```
+# Gemfile
+
+gem 'lowkiq'
+```
+
+Redis >= 3.2
+
+## Api
 
 ```ruby
 module ATestWorker
@@ -171,11 +202,10 @@ module ATestWorker
     10 * (count + 1) # (i.e. 10, 20, 30, 40, 50)
   end
 
-  def self.perform(paylods_by_id)
-    # payloads_by_id - хеш
+  def self.perform(payloads_by_id)
+    # payloads_by_id is a hash map
     payloads_by_id.each do |id, payloads|
-      # id - идентификатор задачи
-      # payloads отсортированы по score, от старых к новым (от минимальных к максимальным)
+      # payloads are sorted by score, from old to new (min to max)
       payloads.each do |payload|
         do_some_work(id, payload)
       end
@@ -184,7 +214,7 @@ module ATestWorker
 end
 ```
 
-Значения по умолчанию:
+Default values:
 
 ```ruby
 self.shards_count = 5
@@ -204,11 +234,11 @@ ATestWorker.perform_async [
   { id: 1, payload: { attr: 'v1' } },
   { id: 2, payload: { attr: 'v1' }, score: Time.now.to_i, perform_in: Time.now.to_i },
 ]
-# payload по умолчанию равен ""
-# score и perform_in по умолчанию равны Time.now.to_i
+# payload by default equals to ""
+# score and perform_in by default equals to Time.now.to_i
 ```
 
-Вы можете переопределить `perform_async` и вычислять `id`, `score` и `perform_in` в воркере:
+It is possible to redefine `perform_async` and calculate `id`, `score` и `perform_in` in a worker code:
 
 ```ruby
 module ATestWorker
@@ -229,56 +259,28 @@ end
 ATestWorker.perform_async 1000.times.map { |id| { payload: {id: id} } }
 ```
 
-### Max retry count
-
-Исходя из `retry_in` и `max_retry_count`,
-можно вычислить примерное время, которая задача проведет в очереди.
-
-Для `retry_in`, заданного по умолчанию получается следующая таблица:
-
-```ruby
-def retry_in(retry_count)
-  (retry_count ** 4) + 15 + (rand(30) * (retry_count + 1))
-end
-```
-
-| `max_retry_count` | кол-во дней жизни задачи |
-| --- | --- |
-| 14 | 1 |
-| 16 | 2 |
-| 18 | 3 |
-| 19 | 5 |
-| 20 | 6 |
-| 21 | 8 |
-| 22 | 10 |
-| 23 | 13 |
-| 24 | 16 |
-| 25 | 20 |
-
-`(0...25).map{ |c| retry_in c }.sum / 60 / 60 / 24`
-
 ## Ring app
 
-`Lowkiq::Web` - ring app.
+`Lowkiq::Web` - a ring app.
 
-+ `/` - dashboard
-+ `/api/v1/stats` - длина очереди, длина морга, лаг для каждого воркера и суммарно
++ `/` - a dashboard
++ `/api/v1/stats` - queue length, morgue length, lag for each worker and total result
 
-## Настройка
+## Configuration
 
-Опции и значения по умолчанию:
+Default options and values are:
 
-+ `Lowkiq.poll_interval = 1` - задержка в секундах между опросами очереди на предмет новых задач.
-  Используется только если на предыдущей итерации очередь оказалась пуста или случилась ошибка.
-+ `Lowkiq.threads_per_node = 5` - кол-во тредов для каждой ноды.
-+ `Lowkiq.redis = ->() { Redis.new url: ENV.fetch('REDIS_URL') }` - настройка redis.
-+ `Lowkiq.client_pool_size = 5` - размер пула редиса для постановки задач в очередь.
-+ `Lowkiq.pool_timeout = 5` - таймаут клиентского и серверного пула редиса
-+ `Lowkiq.server_middlewares = []` - список middleware, оборачивающих воркер.
-+ `Lowkiq.on_server_init = ->() {}` - выполнения кода при инициализации сервера.
-+ `Lowkiq.build_scheduler = ->() { Lowkiq.build_lag_scheduler }` - планировщик.
-+ `Lowkiq.build_splitter = ->() { Lowkiq.build_default_splitter }` - сплиттер.
-+ `Lowkiq.last_words = ->(ex) {}` - обработчик исключений, потомков `StandardError`, вызвавших остановку процесса.
++ `Lowkiq.poll_interval = 1` - delay in seconds between queue polling for new jobs.
+   Used only if the queue was empty at previous cycle or error was occured.
++ `Lowkiq.threads_per_node = 5` - threads per node.
++ `Lowkiq.redis = ->() { Redis.new url: ENV.fetch('REDIS_URL') }` - redis connection options
++ `Lowkiq.client_pool_size = 5` - redis pool size for queueing jobs
++ `Lowkiq.pool_timeout = 5` - client and server redis pool timeout
++ `Lowkiq.server_middlewares = []` - a middleware list, used for worker wrapping
++ `Lowkiq.on_server_init = ->() {}` - a lambda is being executed when server inits
++ `Lowkiq.build_scheduler = ->() { Lowkiq.build_lag_scheduler }` is a scheduler
++ `Lowkiq.build_splitter = ->() { Lowkiq.build_default_splitter }` is a splitter
++ `Lowkiq.last_words = ->(ex) {}` is an exception handler of descendants of `StandardError` caused the process stop
 
 ```ruby
 $logger = Logger.new(STDOUT)
@@ -299,184 +301,53 @@ Lowkiq.server_middlewares << -> (worker, batch, &block) do
 end
 ```
 
-## Splitter
-
-У каждого воркера есть несколько шардов:
-
-```
-# worker: shard ids
-worker A: 0, 1, 2
-worker B: 0, 1, 2, 3
-worker C: 0
-worker D: 0, 1
-```
-
-Lowkiq использует фиксированное кол-во тредов для обработки задач, следовательно нужно распределить шарды
-между тредами. Этим занимается Splitter.
-
-Чтобы определить набор шардов, которые будет обрабатывать тред, поместим их в один список:
-
-```
-A0, A1, A2, B0, B1, B2, B3, C0, D0, D1
-```
-
-Рассмотрим Default splitter, который равномерно распределяет шарды по тредам единственной ноды.
-
-Если `threads_per_node` установлено в 3, то распределение будет таким:
-
-```
-# thread id: shards
-t0: A0, B0, B3, D1
-t1: A1, B1, C0
-t2: A2, B2, D0
-```
-
-Помимо Default есть ByNode splitter. Он позволяет распределить нагрузку по нескольким процессам (нодам).
-
-
-```
-Lowkiq.build_splitter = -> () do
-  Lowkiq.build_by_node_splitter(
-    ENV.fetch('LOWKIQ_NUMBER_OF_NODES').to_i,
-    ENV.fetch('LOWKIQ_NODE_NUMBER').to_i
-  )
-end
-```
-
-Таким образом, вместо одного процесса нужно запустить несколько и указать переменные окружения:
-
-```
-# process 0
-LOWKIQ_NUMBER_OF_NODES=2 LOWKIQ_NODE_NUMBER=0 bundle exec lowkiq -r ./lib/app.rb
-
-# process 1
-LOWKIQ_NUMBER_OF_NODES=2 LOWKIQ_NODE_NUMBER=1 bundle exec lowkiq -r ./lib/app.rb
-```
-
-Отмечу, что общее количество тредов будет равно произведению `ENV.fetch('LOWKIQ_NUMBER_OF_NODES')` и  `Lowkiq.threads_per_node`.
+## Execution
 
-Вы можете написать свой сплиттер, если ваше приложение требует особого распределения шардов между тредами или нодами.
-
-## Scheduler
-
-Каждый тред обрабатывает набор шардов. За выбор шарда для обработки отвечает планировщик.
-Каждый поток имеет свой собственный экземпляр планировщика.
-
-Lowkiq имеет 2 планировщика на выбор.
-Первый, `Seq` - последовательно перебирает шарды.
-Второй, `Lag` - выбирает шард с самой старой задачей, т.е. стремится минимизировать лаг.
-Используется по умолчанию.
-
-Планировщик задается через настройки:
-
-```
-Lowkiq.build_scheduler = ->() { Lowkiq.build_seq_scheduler }
-# или
-Lowkiq.build_scheduler = ->() { Lowkiq.build_lag_scheduler }
-```
-
-## Исключения
-
-`StandardError` выброшенные воркером обрабатываются с помощью middleware.
-Такие исключения не приводят к остановке процесса.
-
-Все прочие исключения приводят к остановке процесса.
-При этом Lowkiq дожидается выполнения задач другими тредами.
-
-`StandardError` выброшенные вне воркера передаются в `Lowkiq.last_words`.
-Например это происходит при потере соединения к Redis или при ошибке в коде Lowkiq.
+`lowkiq -r ./path_to_app`
 
-## Изменение количества шардов воркера
+`path_to_app.rb` must load app. [Example](examples/dummy/lib/app.rb).
 
-Старайтесь не менять кол-во шардов.
+Lazy loading of workers modules is unacceptable.
+For preliminarily loading modules use
+`require`
+or [`require_dependency`](https://api.rubyonrails.org/classes/ActiveSupport/Dependencies/Loadable.html#method-i-require_dependency)
+for Ruby on Rails.
 
-Если вы можете отключить добавление новых заданий,
-то дождитесь опустошения очередей и выкатите новую версию кода с измененным кол-вом шардов.
+## Shutdown
 
-Если такой возможности нет, воспользуйтесь следующим сценарием.
+Send TERM or INT signal to process (Ctrl-C).
+Process will wait for executed jobs to finish.
 
-Например, есть воркер:
+Note that if queue is empty, process sleeps `poll_interval` seconds,
+therefore, the process will not stop until the `poll_interval` seconds have passed.
 
-```ruby
-module ATestWorker
-  extend Lowkiq::Worker
+## Debug
 
-  self.shards_count = 5
+To get trace of all threads of app:
 
-  def self.perform(payloads_by_id)
-    some_code
-  end
-end
 ```
-
-Теперь нужно указать новое кол-во шардов и задать новое имя очереди:
-
-```ruby
-module ATestWorker
-  extend Lowkiq::Worker
-
-  self.shards_count = 10
-  self.queue_name = "#{self.name}_V2"
-
-  def self.perform(payloads_by_id)
-    some_code
-  end
-end
-```
-
-И добавить воркер, перекладывающий задачи из старой очереди в новую:
-
-```ruby
-module ATestMigrationWorker
-  extend Lowkiq::Worker
-
-  self.shards_count = 5
-  self.queue_name = "ATestWorker"
-
-  def self.perform(payloads_by_id)
-    jobs = payloads_by_id.each_with_object([]) do |(id, payloads), acc|
-      payloads.each do |payload|
-        acc << { id: id, payload: payload }
-      end
-    end
-
-    ATestWorker.perform_async jobs
-  end
-end
+kill -TTIN <pid>
+cat /tmp/lowkiq_ttin.txt
 ```
 
-## Запуск
-
-`lowkiq -r ./path_to_app`
-
-`path_to_app.rb` должен загрузить приложение.
-Ленивая загрузка модулей воркеров недопустима.
-
-Redis версии >= 3.2.
-
-## Остановка
-
-Послать процессу TERM или INT(Ctrl-C).
-Процесс будет ждать завершения всех задач.
-Обратите внимание, если очередь пуста, то на время завершения влияет величина `poll_interval`.
-
 ## Development
 
 ```
 docker-compose run --rm --service-port app bash
-bundler
+bundle
 rspec
 cd examples/dummy ; bundle exec ../../exe/lowkiq -r ./lib/app.rb
 ```
 
-## Debug
+## Exceptions
 
-Получить trace всех тредов приложения:
+`StandardError` thrown by worker are handled with middleware. Such exceptions doesn't lead to process stop.
 
-```
-kill -TTIN <pid>
-cat /tmp/lowkiq_ttin.txt
-```
+All other exceptions cause the process to stop.
+Lowkiq will wait for job execution by other threads.
+
+`StandardError` thrown outside of worker are passed to `Lowkiq.last_words`.
+For example, it can happen when Redis connection is lost or when Lowkiq's code has a bug.
 
 ## Rails integration
 
@@ -493,10 +364,10 @@ end
 ```ruby
 # config/initializers/lowkiq.rb
 
-# загружаем все lowkiq воркеры
+# loading all lowkiq workers
 Dir["#{Rails.root}/app/lowkiq_workers/**/*.rb"].each { |file| require_dependency file }
 
-# конфигурация:
+# configuration:
 # Lowkiq.redis = -> { Redis.new url: ENV.fetch('LOWKIQ_REDIS_URL') }
 # Lowkiq.threads_per_node = ENV.fetch('LOWKIQ_THREADS_PER_NODE').to_i
 # Lowkiq.client_pool_size = ENV.fetch('LOWKIQ_CLIENT_POOL_SIZE').to_i
@@ -558,7 +429,7 @@ if defined? NewRelic
   Lowkiq.server_middlewares << NewRelicLowkiqMiddleware.new
 end
 
-# Rails reloader, в том числе отвечает за высвобождение ActiveRecord коннектов
+# Rails reloader, responsible for cleaning of ActiveRecord connections
 Lowkiq.server_middlewares << -> (worker, batch, &block) do
   Rails.application.reloader.wrap do
     block.call
@@ -574,4 +445,183 @@ Lowkiq.on_server_init = ->() do
 end
 ```
 
-Запуск: `bundle exec lowkiq -r ./config/environment.rb`
+Execution: `bundle exec lowkiq -r ./config/environment.rb`
+
+
+## Splitter
+
+Each worker has several shards:
+
+```
+# worker: shard ids
+worker A: 0, 1, 2
+worker B: 0, 1, 2, 3
+worker C: 0
+worker D: 0, 1
+```
+
+Lowkiq uses fixed amount of threads for job processing, therefore it is necessary to distribute shards between threads.
+Splitter does it.
+
+To define a set of shards, which is being processed by thread, lets move them to one list:
+
+```
+A0, A1, A2, B0, B1, B2, B3, C0, D0, D1
+```
+
+Default splitter evenly distributes shards by threads of a single node.
+
+If `threads_per_node` is set to 3, the distribution will be:
+
+```
+# thread id: shards
+t0: A0, B0, B3, D1
+t1: A1, B1, C0
+t2: A2, B2, D0
+```
+
+Besides Default Lowkiq has ByNode splitter. It allows to divide the load by several processes (nodes).
+
+```
+Lowkiq.build_splitter = -> () do
+  Lowkiq.build_by_node_splitter(
+    ENV.fetch('LOWKIQ_NUMBER_OF_NODES').to_i,
+    ENV.fetch('LOWKIQ_NODE_NUMBER').to_i
+  )
+end
+```
+
+So, instead of single process you need to execute multiple ones and to set environment variables up:
+
+```
+# process 0
+LOWKIQ_NUMBER_OF_NODES=2 LOWKIQ_NODE_NUMBER=0 bundle exec lowkiq -r ./lib/app.rb
+
+# process 1
+LOWKIQ_NUMBER_OF_NODES=2 LOWKIQ_NODE_NUMBER=1 bundle exec lowkiq -r ./lib/app.rb
+```
+
+Summary amount of threads are equal product of `ENV.fetch('LOWKIQ_NUMBER_OF_NODES')` and `Lowkiq.threads_per_node`.
+
+You can also write your own splitter if your app needs extra distribution of shards between threads or nodes.
+
+## Scheduler
+
+Every thread processes a set of shards. Scheduler select shard for processing.
+Every thread has it's own instance of scheduler.
+
+Lowkiq has 2 schedulers for your choice.
+`Seq` sequentally looks over shards.
+`Lag`  chooses shard with the oldest job minimizing the lag. It's used by default.
+
+Scheduler can be set up through settings:
+
+```
+Lowkiq.build_scheduler = ->() { Lowkiq.build_seq_scheduler }
+# or
+Lowkiq.build_scheduler = ->() { Lowkiq.build_lag_scheduler }
+```
+
+## Recommendations on configuration
+
+### `SomeWorker.shards_count`
+
+Sum of `shards_count` of all workers shouldn't be less than `Lowkiq.threads_per_node`
+otherwise threads will stay idle.
+
+Sum of `shards_count` of all workers can be equal to `Lowkiq.threads_per_node`.
+In this case thread processes a single shard. This makes sense only with uniform queue load.
+
+Sum of `shards_count` of all workers can be more than `Lowkiq.threads_per_node`.
+In this case `shards_count` can be counted as a priority.
+The larger it is, the more often the tasks of this queue will be processed.
+
+There is no reason to set `shards_count` of one worker more than `Lowkiq.threads_per_node`,
+because every thread will handle more than one shard from this queue, so it increases the overhead.
+
+### `SomeWorker.max_retry_count`
+
+From `retry_in` and `max_retry_count`, you can calculate approximate time that payload of job will be in a queue.
+After `max_retry_count` is reached the payload with a minimal score will be moved to a morgue.
+
+For default `retry_in` we receive the following table.
+
+```ruby
+def retry_in(retry_count)
+  (retry_count ** 4) + 15 + (rand(30) * (retry_count + 1))
+end
+```
+
+| `max_retry_count` | amount of days of job's life |
+| ---               | ---                          |
+| 14                | 1                            |
+| 16                | 2                            |
+| 18                | 3                            |
+| 19                | 5                            |
+| 20                | 6                            |
+| 21                | 8                            |
+| 22                | 10                           |
+| 23                | 13                           |
+| 24                | 16                           |
+| 25                | 20                           |
+
+`(0...25).map{ |c| retry_in c }.sum / 60 / 60 / 24`
+
+
+## Changing of worker's shards amount
+
+Try to count amount of shards right away and don't change it in future.
+
+If you can disable adding of new jobs, wait for queues to get empty and deploy the new version of code with changed amount of shards.
+
+If you can't do it, follow the next steps:
+
+A worker example:
+
+```ruby
+module ATestWorker
+  extend Lowkiq::Worker
+
+  self.shards_count = 5
+
+  def self.perform(payloads_by_id)
+    some_code
+  end
+end
+```
+
+Set the number of shards and new queue name:
+
+```ruby
+module ATestWorker
+  extend Lowkiq::Worker
+
+  self.shards_count = 10
+  self.queue_name = "#{self.name}_V2"
+
+  def self.perform(payloads_by_id)
+    some_code
+  end
+end
+```
+
+Add a worker moving jobs from the old queue to a new one:
+
+```ruby
+module ATestMigrationWorker
+  extend Lowkiq::Worker
+
+  self.shards_count = 5
+  self.queue_name = "ATestWorker"
+
+  def self.perform(payloads_by_id)
+    jobs = payloads_by_id.each_with_object([]) do |(id, payloads), acc|
+      payloads.each do |payload|
+        acc << { id: id, payload: payload }
+      end
+    end
+
+    ATestWorker.perform_async jobs
+  end
+end
+```