Manual about agents

docs/ru/agent.md

@@ -0,0 +1,76 @@
+# Агенты
+
+Тяжеловесные или отложенные операции на сайте удобно выполнять в фоновом режиме, иногда с определённой периодичностью, 
+иногда практически моментально. Помочь в этом может [система очередей](http://ruhighload.com/index.php/2009/05/15/%D0%BE%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C-%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B9-%D1%87%D1%82%D0%BE-%D1%8D%D1%82%D0%BE-%D0%B8-%D0%B7%D0%B0%D1%87%D0%B5%D0%BC/).
+Но в некоторых случаях, когда не требуется шардирование и отказоустойчивость подсистемы выполнения отложенных операций, 
+можно воспользоваться штатной технологией «Битрикса» — [агентами](http://dev.1c-bitrix.ru/learning/course/?COURSE_ID=43&LESSON_ID=3436). 
+К сожалению, эта технология имеет сырое API, но Console Jedi предоставляет свой API, покрывающий весь цикл работы с агентами.
+
+## Жизненный цикл
+
+### Настройка
+
+Переведите [выполнение агентов на cron](https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=2943&LESSON_PATH=3913.4776.4620.4978.2943), 
+если ещё не сделали этого. В Console Jedi этот процесс автоматизирован, поэтому, в отличии от официального руководства, 
+достаточно выполнить команду: 
+
+```bash
+vendor/bin/jedi agent:on-cron
+```
+
+### Создание
+
+PHP-класс агента либо должен наследовать класс `\Notamedia\ConsoleJedi\Agent\Agent`, либо подключать трейт 
+`\Notamedia\ConsoleJedi\Agent\AgentTrait`, позволяющие объекту класса работать в режиме агента.
+
+Вот и всё, больше не требуется никаких операций. И самое главное — не нужно создавать в классе статичные методы, как это 
+рекомендует официальная документация  «Битрикса», — Console Jedi умеет превращать объекты (с конструктором и публичными 
+нестатичными методами) в формат, ожидаемый «Битриксом».
+
+### Регистрация
+
+В момент, когда потребуется зарегистрировать в «Битриксе» новый агент, воспользуйтесь специальным строителем  
+`\Notamedia\ConsoleJedi\Agent\AgentTask`. 
+
+Давайте зарегистрируем агент модуля `vasya.tester`, при выполнении которого будет создаваться объект `TestAgent` с аргументами `arg1` 
+(строка) и `true` (булевый тип) и вызываться метод объекта `execute` с аргументом `100500` (строка):
+
+```php
+use Notamedia\ConsoleJedi\Agent\AgentTask;
+use Vendor\Module\TestAgent;
+
+AgentTask::builder()
+    ->setClass(TestAgent::class)
+    ->setConstructorArgs(['arg1', true])
+    ->setCallChain([
+        ['execute' => [100500]]
+    ]),
+    ->setModule('vasya.tester')
+    ->create();
+```
+
+> За подробным описанием методов строителя агентов обратитесь к PHPDoc-комментариям в классе `AgentTask`.
+
+### Выполнение
+
+Добавьте в `crontab` вызов команды, которая производит выполнение готовых к работе агентов:
+
+```bash
+vendor/bin/jedi agent:execute
+```
+
+## Продление жизни агента
+
+Если время выполнения агента превышает 10 минут, необходимо периодически в процессе его работы выполнять пинг, чтобы 
+«Битрикс» не считал его зависшим. Например:
+
+```php
+public function execute($param1)
+{
+    // Начало выполнения тяжёлых операций
+
+    $this->pingAgent(20, ['execute' => [$param1]]);
+
+    // Завершение выполнения
+}
+```

src/Agent/AgentTrait.php

@@ -77,7 +77,7 @@ public static function agent()
      * {
      *      // start a heavy (big) cycle
      *
-     *          $this->pingAgent(20, ['executeAgent => [$param1, $param2]]);
+     *          $this->pingAgent(20, ['executeAgent' => [$param1, $param2]]);
      *
      *      // end of cycle
      * }
@@ -119,7 +119,7 @@ protected function pingAgent($interval, array $callChain)
      * {
      *      // main logic
      *
-     *      return $this->getAgentName(['executeAgent => [$param1, $param2]]);
+     *      return $this->getAgentName(['executeAgent' => [$param1, $param2]]);
      * }
      * ```
      *